# Yandex Tracker MCP Server

Local [Model Context Protocol](https://modelcontextprotocol.io/) server (Node.js + TypeScript) that exposes the [Yandex Tracker REST API v3](https://yandex.ru/support/tracker/en/api-ref/about-api) as tools for LLM clients. Transport is **stdio** only (the host spawns the process; there is no HTTP port).

## Prerequisites

- Node.js **18+**
- A Tracker OAuth token and organisation ID (see below)

## Install and run

```bash
npm install
npm run build    # compile to dist/
npm run start    # run compiled server (used by MCP hosts)
```

Other scripts:

| Script | Purpose |
|--------|---------|
| `npm run clean` | Remove the `dist/` directory |
| `npm run dev` | Run `src/index.ts` with [tsx](https://github.com/privatenumber/tsx) (handy for quick local checks; MCP hosts normally use `start`) |

After `clean`, run `build` again before `start`.

## Configuration

1. Copy `.env.example` to `.env` and fill in values (do not commit `.env`).

2. Required variables:

   - `TRACKER_TOKEN` — OAuth token (see below)
   - `TRACKER_ORG_ID` — Organisation ID from [Tracker administration → Organisations](https://tracker.yandex.com/admin/orgs)

   Optional:

   - `TRACKER_ORG_HEADER` — `X-Org-ID` (Yandex 360, default) or `X-Cloud-Org-ID` (Yandex Cloud)
   - `TRACKER_BASE_URL` — default `https://api.tracker.yandex.net/v3`; change for self-hosted
   - `TRACKER_AUTH_SCHEME` — `OAuth` (default) or `Bearer` (e.g. IAM)

## Getting a Tracker OAuth token

1. **Create an OAuth app** at [https://oauth.yandex.ru/](https://oauth.yandex.ru/) (choose API access / debugging, add scopes **`tracker:read`** and **`tracker:write`**, note the **Client ID**).

2. **Authorize in the browser** (implicit flow). Open (replace `YOUR_CLIENT_ID`):

   [https://oauth.yandex.com/authorize?response_type=token&client_id=YOUR_CLIENT_ID](https://oauth.yandex.com/authorize?response_type=token&client_id=YOUR_CLIENT_ID)

3. After you approve access, the redirect URL will contain `access_token=...`. Copy that value into `TRACKER_TOKEN`.

4. **Smoke test** (optional):

   ```bash
   curl -sS 'https://api.tracker.yandex.net/v3/myself' \
     -H 'Authorization: OAuth YOUR_TOKEN' \
     -H 'X-Org-ID: YOUR_ORG_ID'
   ```

   `401` usually means a bad token; `403` often means a wrong org header or ID.

## Using with Cursor

1. Build the project and note the **absolute path** to `dist/index.js`.

2. Edit your MCP config (e.g. `~/.cursor/mcp.json`) and add a server entry. Example:

   ```json
   {
     "mcpServers": {
       "tracker-custom": {
         "command": "node",
         "args": ["/absolute/path/to/tracker-mcp-server/dist/index.js"],
         "env": {
           "TRACKER_TOKEN": "your_oauth_token",
           "TRACKER_ORG_ID": "your_org_id",
           "TRACKER_ORG_HEADER": "X-Org-ID",
           "TRACKER_BASE_URL": "https://api.tracker.yandex.net/v3",
           "TRACKER_AUTH_SCHEME": "OAuth"
         }
       }
     }
   }
   ```

   You can rely on a `.env` file **only** if your host loads it; many setups pass `env` explicitly as above.

3. Restart Cursor. In chat, try: use the Tracker MCP to call **`get_myself`** to verify auth.

## Using with Claude Desktop

1. Build the project and note the **absolute path** to `dist/index.js`.

2. Edit the Claude Desktop config file:

   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

3. Under `mcpServers`, add the same shape as in the Cursor example (`command`, `args`, `env`).

4. Fully quit and reopen Claude Desktop, then use a task that invokes Tracker tools (e.g. **get_myself**).

## Project layout (high level)

- `src/index.ts` — MCP entry, registers tools, stdio transport
- `src/tracker-client.ts` — HTTP client for Tracker API
- `src/tools/*.ts` — tool implementations (read, write, validate, checklist, sync)
- `convention.json` — validation rules for `validate_issue` / `audit_queue`
- `sync-map.json` — optional Tracker ↔ Miro id map for agent-driven sync

## License

Private / use as you prefer unless you add a formal license file.