# yandex-eats-mcp

MCP server for the [Yandex Eats Vendor Management API](https://yandex.ru/dev/eda-vendor/doc/en/ref/Vendor-Management-Integration-API/).

Lets AI agents (Cursor, Claude Desktop, and other MCP hosts) manage partner operations: orders history/details, busy mode, place blocks, menu import, courier code validation, and feedback replies.

> This wraps the **push** Vendor Management API (`https://dc-partner.eda.yandex.net`). It is **not** a consumer ordering API.

## Install / run

### Cursor / Claude Desktop (recommended)

```json
{
  "mcpServers": {
    "yandex-eats": {
      "command": "npx",
      "args": ["-y", "yandex-eats-mcp"],
      "env": {
        "YANDEX_EATS_CLIENT_ID": "your-client-id",
        "YANDEX_EATS_CLIENT_SECRET": "your-client-secret",
        "YANDEX_EATS_PARTNER_NAME": "your-partner-name"
      }
    }
  }
}
```

Pin a version: `"args": ["-y", "yandex-eats-mcp@0.1.0"]`.

### Local development

```bash
npm install
npm run build
npm start
```

MCP config pointing at a local build:

```json
{
  "mcpServers": {
    "yandex-eats": {
      "command": "node",
      "args": ["/absolute/path/to/yandex-eats-mcp/dist/index.js"],
      "env": {
        "YANDEX_EATS_CLIENT_ID": "...",
        "YANDEX_EATS_CLIENT_SECRET": "...",
        "YANDEX_EATS_PARTNER_NAME": "..."
      }
    }
  }
}
```

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `YANDEX_EATS_CLIENT_ID` | yes | OAuth client id |
| `YANDEX_EATS_CLIENT_SECRET` | yes | OAuth client secret |
| `YANDEX_EATS_PARTNER_NAME` | for several write tools | Sent as `Partner-Name` header |
| `YANDEX_EATS_BASE_URL` | no | Default `https://dc-partner.eda.yandex.net` |
| `YANDEX_EATS_TIMEOUT_MS` | no | Default `30000` |
| `YANDEX_EATS_DRY_RUN` | no | If `true`, tools do not call the API |

Credentials are never accepted as tool arguments. Access tokens are never returned to the agent.

## Tools

| Tool | Description |
|------|-------------|
| `yandex_eats_auth_status` | Credential / token cache status (no token value) |
| `yandex_eats_refresh_token` | Force OAuth refresh |
| `yandex_eats_orders_history` | Order history (max 1000; 180 days) |
| `yandex_eats_orders_details` | Details by `eats_ids` (max 100) |
| `yandex_eats_busy_mode_status` | High-demand places |
| `yandex_eats_block_status` | Current blocks |
| `yandex_eats_block_places` | Block places (`confirm: true` required) |
| `yandex_eats_unblock_places` | Unblock places (`confirm: true` required) |
| `yandex_eats_menu_import` | Force menu / stop-list import |
| `yandex_eats_validate_courier_code` | Validate courier pickup code |
| `yandex_eats_feedback_answer` | Reply to feedback (may need subscription) |

## Resources

- `yandex-eats://docs/overview`
- `yandex-eats://config/status`

## Prompts

- `yandex_eats_investigate_order`
- `yandex_eats_resync_menu`

## Tests

```bash
# Unit + MCP integration (mocked Vendor API, in-memory transport)
npm test

# E2E: spawn dist/index.js over stdio (builds first). Live API smoke only if
# YANDEX_EATS_LIVE_E2E=1 and real CLIENT_ID/SECRET are set.
npm run test:e2e

npm run test:all
```

| Suite | Path | Network |
|-------|------|---------|
| Unit | `tests/*.test.ts` | mocked `fetch` |
| Integration | `tests/integration/` | mocked Vendor API + real MCP protocol (in-memory) |
| E2E stdio | `tests/e2e/stdio.e2e.test.ts` | dry-run MCP child process |
| E2E live | `tests/e2e/live.e2e.test.ts` | real Yandex (opt-in) |

## Publish to npm

```bash
npm test && npm run build
npm pack --dry-run
npm publish
```

Requires an npm account with publish rights for `yandex-eats-mcp`.

## Docs

- [docs/YANDEX_EATS_API.md](./docs/YANDEX_EATS_API.md) — API research
- [docs/MCP_SERVER_PLAN.md](./docs/MCP_SERVER_PLAN.md) — implementation plan

## License

MIT