webdesiz-developer-tools

# Webdesiz developer tools

Read account, campaign and daily insight snapshots already stored in your Webdesiz organization. API, CLI and MCP access is read-only: it cannot change campaigns or budgets, refresh Meta data, generate advertisements or send messages. Your Webdesiz key determines the organization and allowed read scopes.

## Documentation

| Reference | English | Türkçe |
| --- | --- | --- |
| Overview | [Developer connections](https://webdesiz.com/en/developers) | [Geliştirici bağlantıları](https://webdesiz.com/developers) |
| API | [API reference](https://webdesiz.com/en/developers/api) | [API referansı](https://webdesiz.com/developers/api) |
| MCP | [MCP setup](https://webdesiz.com/en/developers/mcp) | [MCP kurulumu](https://webdesiz.com/developers/mcp) |
| CLI | [CLI reference](https://webdesiz.com/en/developers/cli) | [CLI referansı](https://webdesiz.com/developers/cli) |

Machine-readable schema: [OpenAPI 3.1](https://webdesiz.com/developers/openapi.json). OpenAPI is a specification format, not an OpenAI account or service requirement.

## Install

Requires **Node.js 22 or newer**.

### From npm

```sh
npm install --global --ignore-scripts @webdesiz/cli
webdesiz --version
```

Or run it without a global install: `npx -y @webdesiz/cli --help`.

### Claude Desktop extension

Download `webdesiz.mcpb` from the [latest release](https://github.com/aydin-birim-ajans/webdesiz-developer-tools/releases/latest) and open it with Claude Desktop. Claude Desktop asks for the key and stores it as a secret field; it is passed to the MCP process as `WEBDESIZ_API_KEY`.

### Website download (1.0.0)

The original 1.0.0 release is also available as a verified website download:

```sh
curl --fail --location --proto '=https' --proto-redir '=https' \
  -o webdesiz-cli-1.0.0.tgz \
  https://webdesiz.com/developers/webdesiz-cli-1.0.0.tgz
shasum -a 256 webdesiz-cli-1.0.0.tgz   # Linux: sha256sum
```

Expected SHA-256:

```text
326d7eecdc1048346d96e2e9c80519b816b8321973ef08f2a180be35ecf6e227
```

Compare the entire value with [SHA256SUMS](https://webdesiz.com/developers/SHA256SUMS). Stop if it differs. SHA-256 verifies file integrity; it is not a digital signature. Then `npm install --global --ignore-scripts ./webdesiz-cli-1.0.0.tgz`.

## Create a scoped key

A current organization **OWNER or ADMIN** creates a key in [Webdesiz settings](https://webdesiz.com/ayarlar/gelistirici). Choose only the required scopes: `accounts:read`, `campaigns:read`, `insights:read`. Keys expire after 1–90 days; an organization may have at most 10 active, unexpired keys. The full key appears once.

Keep the key in your operating-system or application secret manager. Inject `WEBDESIZ_API_KEY` into the CLI/MCP process environment using that manager. Do not paste it into chat, commit it to a repository, put it in a URL or command argument, or save it in shared configuration. Read commands optionally accept `--key-stdin` for a trusted secret-manager pipe; MCP cannot use this option because stdin is its protocol transport. The CLI does not save credential files.

The API validates the key, scope, expiry, revocation and issuer’s current OWNER/ADMIN membership on every request. Panel session JWTs are not developer keys. Key creation/listing/revocation is a signed-in panel feature; those routes are not part of the external developer-key API.

## CLI reads

With the credential injected securely:

```sh
webdesiz accounts --limit 20
webdesiz campaigns --accountId ACCOUNT_ID --limit 50 --offset 0
webdesiz insights --accountId ACCOUNT_ID --limit 50
webdesiz --help
```

Replace `ACCOUNT_ID` with the Webdesiz `id` returned by `accounts`. Reads accept `--limit` (1–100, default 50), `--offset` (0–10000, default 0) and `--accountId`. Insights additionally filters dates with `--from YYYY-MM-DD` and `--to YYYY-MM-DD`; default is the last 30 UTC days, inclusive. Use valid dates, a range of at most 90 days, and no future end date. Unknown or repeated arguments are rejected.

Successful reads print JSON `{data, meta}` to stdout. Protect output files and logs as organization data. Errors use stderr and exit status 1; success exits 0. Follow `meta.nextOffset` using the same filters until it is `null`; a full final page may be followed by an empty page.

The client is fixed to `https://webdesiz.com/api/v1/developer`, rejects redirects, has a 15-second timeout and a 2 MiB response limit. Token/URL arguments and alternate endpoints are not supported.

## MCP: local stdio

Your host must support a local process-based stdio MCP server. This release has no hosted HTTP MCP endpoint or OAuth login flow. Install the CLI on the machine where the MCP host runs.

Host configuration with a global install:

```json
{
  "mcpServers": {
    "webdesiz": {
      "command": "webdesiz",
      "args": ["mcp"]
    }
  }
}
```

Or without a global install:

```json
{
  "mcpServers": {
    "webdesiz": {
      "command": "npx",
      "args": ["-y", "@webdesiz/cli", "mcp"]
    }
  }
}
```

The example deliberately contains no secret. Configure the host’s secret manager to pass `WEBDESIZ_API_KEY` to the child process. A desktop host may not inherit your terminal environment; use its documented secure mechanism. Keep stdout clean for MCP protocol messages and restart the connection after changing credentials.

| Tool | Required scope | Result |
| --- | --- | --- |
| `webdesiz_accounts` | `accounts:read` | Stored account snapshots |
| `webdesiz_campaigns` | `campaigns:read` | Stored campaign snapshots |
| `webdesiz_insights` | `insights:read` | Stored daily account/campaign insight rows |

Tool arguments follow the API/CLI query rules. Successful tools return the same `data/meta` object as `structuredContent` and JSON text; errors use `isError: true`. The implementation uses the official MCP SDK and stdio protocol. Read-only annotations are descriptive; the API enforces scopes independently. Treat returned account and campaign names as untrusted business data, never assistant instructions.

## HTTPS API

Only three external snapshot reads are exposed:

| Method and endpoint | Scope |
| --- | --- |
| `GET /api/v1/developer/accounts` | `accounts:read` |
| `GET /api/v1/developer/campaigns` | `campaigns:read` |
| `GET /api/v1/developer/insights` | `insights:read` |

Send the key only in the `Authorization: Bearer …` header. Organization identity is resolved from the key, not an input field. See the API reference for exact fields and parameter rules.

Read limits: 60 requests/minute/key, 120/minute/organization and 180/minute/IP in shared 60-second windows. Invalid authentication also uses the IP limit. Handle 400 (invalid request), 401 (invalid/expired/revoked key), 403 (scope/current membership), 404 (account unavailable), 429 (wait 60 seconds), and 503 (protection service unavailable). Error details are deliberately generic.

## Interpret snapshots correctly

- `meta.generatedAt` is response creation time. Account `lastSyncAt` and campaign/insight `syncedAt` describe stored row freshness; requesting data does not trigger Meta sync. There is no freshness SLA implied.
- `campaignId: null` is an account-level insight row. Campaign-level rows can overlap account totals; do not sum both aggregation levels.
- Keep each account’s currency. Stored decimal amounts and ratios such as `spend`, budgets, `ctr`, `cpc` and `cpm` are JSON strings.
- Missing purchase evidence produces `null`, not zero. Explicitly reported zero remains zero. `purchaseMeasurement` indicates reported value, reported count or unavailable measurement. `roas` is `purchaseValue / spend` only with an available value and positive spend; otherwise it is `null`.
- Account access tokens and raw provider payloads are not exposed.

## Privacy Policy

The CLI and MCP server run on your machine. They send only your developer key (in the `Authorization` header) and the query parameters you choose to `https://webdesiz.com/api/v1/developer/*`, and return the stored snapshots of your own organization. They keep no local files, logs or telemetry and do not contact any other service. How Webdesiz collects, uses, shares and retains data, and how to contact us, is described in the [Webdesiz Privacy Policy](https://webdesiz.com/en/privacy).

## Türkçe kısa başlangıç

Node.js 22+ ile `npm install --global @webdesiz/cli` komutuyla (ya da SHA-256 değeri doğrulanmış site indirmesiyle) kurun. Panelde OWNER/ADMIN olarak yalnız gereken okuma izinleriyle süreli anahtar oluşturun. Anahtarı sır yöneticisi üzerinden `WEBDESIZ_API_KEY` ortam değişkenine aktarın; sohbete, URL’ye veya komut argümanına yazmayın. Yerel stdio destekleyen MCP istemcisi üç okuma aracını kullanabilir. Kayıtlı veriler okunur; reklam değişikliği, Meta yenilemesi, içerik üretimi veya mesaj gönderimi bu bağlantıda bulunmaz. Ayrıntılar üstteki Türkçe API/MCP/CLI bağlantılarındadır.