# @cododel/yandex-wordstat-mcp

Bun/TypeScript MCP server for the official Yandex Wordstat v2 API. It provides the same practical Wordstat surface as the upstream `yandex-wordstat-mcp` package and adds a shared typed architecture, local stdio and stateless Streamable HTTP transports, remote BYOK credentials, explicit server-owned credential opt-in, Docker packaging, cost metadata, and generic agent installation guidance.

## Commands

```bash
# Local MCP child process; requires Yandex credentials in ENV
bun src/cli.ts stdio

# Remote stateless Streamable HTTP; BYOK headers required by default
bun src/cli.ts serve --host 127.0.0.1 --port 3000
```

See [INSTALL.md](INSTALL.md) for MCP client, Docker, authentication, and upgrade instructions.

## Tools

| Tool | Wordstat method | Billing |
|---|---|---:|
| `get-regions-tree` | `GetRegionsTree` | free |
| `get-region-children` | cached `GetRegionsTree` | free |
| `top-requests` | `GetTop` | ~0.02 RUB/call |
| `dynamics` | `GetDynamics` | ~0.02 RUB/call |
| `regions` | `GetRegionsDistribution` | ~0.05 RUB/call |

Pricing is informational and can change. Source: [Yandex Search API pricing](https://yandex.cloud/ru/docs/search-api/pricing).

## Local credentials

Accepted aliases, in priority order:

```text
YANDEX_WORDSTAT_API_KEY or YANDEX_SEARCH_API_KEY
YANDEX_WORDSTAT_FOLDER_ID or YANDEX_CLOUD_FOLDER_ID or YANDEX_FOLDER_ID
```

## Remote credential policy

Default `serve` behavior:

- server ENV Yandex credentials are ignored;
- every MCP request needs `X-Yandex-API-Key` and `X-Yandex-Folder-Id`;
- keys are transport headers and are absent from tool schemas;
- loopback BYOK may omit `MCP_ACCESS_TOKEN`, but non-loopback HTTP requires it;
- `--allow-server-credentials` always requires a non-empty `MCP_ACCESS_TOKEN`;
- browser Origin and Host checks run before credential handling;
- server credentials become available only with `--allow-server-credentials`.

Serve behind HTTPS. The built-in server intentionally does not terminate TLS.

## Billing safety and exact counts

- `top-requests`, `dynamics`, and `regions` are at-most-once billed operations. Clients must not retry them automatically after errors or unknown outcomes.
- Set `WORDSTAT_MAX_COST_RUB_PER_HOUR` and `WORDSTAT_MAX_COST_RUB_PER_DAY` together to enable a persistent SQLite budget guard. Amounts are parsed to integer kopecks; every dispatched paid attempt counts conservatively.
- `WORDSTAT_LEDGER_PATH` defaults to `./data/wordstat.sqlite`; Docker uses the persistent `/data/wordstat.sqlite` volume.
- Wordstat int64 count fields are returned as exact decimal strings, not JSON numbers.

## Development

```bash
bun install --frozen-lockfile
bun test
bun run typecheck
```

The project uses native Bun TypeScript. There is no emitted `dist/` directory.

## Attribution

This project uses the MIT-licensed [`packages/yandex-wordstat-mcp`](https://github.com/altrr2/yandex-tools-mcp/tree/main/packages/yandex-wordstat-mcp) implementation by Alternex as its functional baseline. See [UPSTREAM.md](UPSTREAM.md) and [LICENSE](LICENSE).