@mmtr-tech/yandex-tracker-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @mmtr-tech/yandex-tracker-mcp
+
+MCP server for the [Yandex Tracker](https://yandex.ru/support/tracker/en/api-ref/access) API (OAuth + Yandex 360 organization).
+
+[Русская версия](README.ru.md)
+
+## Install / run in Cursor
+
+```json
+{
+  "mcpServers": {
+    "yandex-tracker": {
+      "command": "npx",
+      "args": ["-y", "@mmtr-tech/yandex-tracker-mcp"],
+      "env": {
+        "API_TOKEN": "your-oauth-token",
+        "X_ORG_ID": "your-org-id"
+      }
+    }
+  }
+}
+```
+
+Optional: `"API_BASE_URL": "https://api.tracker.yandex.net/v3"` (this is the default).
+
+After changing the config, **Restart Cursor** (toggling MCP is often not enough).
+
+### Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `API_TOKEN` | yes | OAuth token (`Authorization: OAuth …`) |
+| `X_ORG_ID` | yes | Yandex 360 organization id (`X-Org-ID`) |
+| `API_BASE_URL` | no | Defaults to `https://api.tracker.yandex.net/v3` |
+
+## Getting an OAuth token and X_ORG_ID
+
+You need a Tracker user **OAuth token** and a Yandex 360 **organization id**.
+
+### 1. Register an app in Yandex OAuth
+
+App types: [Register an application](https://yandex.ru/dev/id/doc/en/register-client).
+
+For this MCP, choose **“For API access or debugging”** (not “for user authorization”). The type cannot be changed later.
+
+1. Open [oauth.yandex.ru](https://oauth.yandex.ru) → **Create**.
+2. Select **For API access or debugging**.
+3. Set a name and contact email.
+4. Add scopes:
+   - `tracker:read` — read only;
+   - `tracker:write` — create/update/comments/transitions (required for write tools).
+5. Create the app and copy the **ClientID**.
+
+Tracker guide: [API access → OAuth](https://yandex.ru/support/tracker/en/api-ref/access).
+
+### 2. Issue a token
+
+```text
+https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>
+```
+
+Open the link while signed in as the Tracker user that should call the API. The string shown is your `API_TOKEN`.
+
+The token acts with that user’s permissions. Access can be revoked in Yandex ID settings.
+
+### 3. Find X_ORG_ID
+
+In Tracker: **Administration → Organizations** → copy the organization id (`X-Org-ID`).
+
+### 4. Verify access
+
+```bash
+curl -X GET 'https://api.tracker.yandex.net/v3/myself' \
+  -H "Authorization: OAuth $API_TOKEN" \
+  -H "X-Org-ID: $X_ORG_ID"
+```
+
+Expect `200` and JSON with `login` / `display`. `401` means a bad token, scopes, or org id.
+
+## Tools
+
+### Read
+
+| Tool | API |
+|------|-----|
+| `get_myself` | `GET /myself` |
+| `get_user` | `GET /users/{id}` |
+| `list_users` | `GET /users` |
+| `list_queues` | `GET /queues/` |
+| `get_queue` | `GET /queues/{id}` |
+| `list_queue_versions` | `GET /queues/{id}/versions` |
+| `list_queue_components` | `GET /queues/{id}?expand=components` |
+| `get_issue` | `GET /issues/{id}` |
+| `search_issues` | `POST /issues/_search` |
+| `count_issues` | `POST /issues/_count` |
+| `get_issue_comments` | `GET /issues/{id}/comments` |
+| `get_issue_links` | `GET /issues/{id}/links` |
+| `get_issue_transitions` | `GET /issues/{id}/transitions` |
+| `get_issue_changelog` | `GET /issues/{id}/changelog` |
+| `get_issue_attachments` | attachment metadata only |
+| `get_issue_worklog` | `GET /issues/{id}/worklog` |
+| `get_issue_checklist` | `GET /issues/{id}/checklistItems` |
+| `list_boards` | `GET /boards/` |
+| `list_board_sprints` | `GET /boards/{id}/sprints` |
+
+For `search_issues` / `count_issues`, provide **exactly one** mode (`query` or `filter`; search also supports `keys` / `queue`).
+
+Example queries: `Queue: TEST`, `Queue: TEST Assignee: me() Sort by: Updated DESC`, `Key: TEST-1`.
+
+### Write (side effects)
+
+| Tool | API |
+|------|-----|
+| `create_issue` | `POST /issues/` (optional `fields`) |
+| `update_issue` | `PATCH /issues/{id}` (`fields` / operators) |
+| `add_issue_comment` | `POST /issues/{id}/comments` |
+| `execute_transition` | status transition |
+| `create_issue_link` / `delete_issue_link` | issue links |
+| `add_issue_followers` / `remove_issue_followers` | watchers |
+| `add_issue_worklog` | time tracking |
+| `update_checklist_item` | checklist |
+| `upload_issue_attachment` | upload from local `filePath` |
+
+Status changes only via `execute_transition` (call `get_issue_transitions` first). Requires OAuth scope `tracker:write`.
+
+## Local development
+
+```bash
+git clone <repo>
+cd yandex-tracker
+cp .env.example .env
+npm install
+npm run test:unit
+npm run typecheck
+npm run dev
+```
+
+Or point `mcp.json` at `src/index.ts` with `npx tsx` (see the repository).
+
+## License
+
+MIT

package/README.ru.md

@@ -0,0 +1,142 @@
+# @mmtr-tech/yandex-tracker-mcp
+
+MCP-сервер для API [Яндекс Трекера](https://yandex.ru/support/tracker/ru/api-ref/access) (OAuth + организация Яндекс 360).
+
+[English version](README.md)
+
+## Установка / запуск в Cursor
+
+```json
+{
+  "mcpServers": {
+    "yandex-tracker": {
+      "command": "npx",
+      "args": ["-y", "@mmtr-tech/yandex-tracker-mcp"],
+      "env": {
+        "API_TOKEN": "your-oauth-token",
+        "X_ORG_ID": "your-org-id"
+      }
+    }
+  }
+}
+```
+
+Опционально: `"API_BASE_URL": "https://api.tracker.yandex.net/v3"` (это значение по умолчанию).
+
+После изменения конфига — **Restart Cursor** (toggle MCP часто недостаточен).
+
+### Env
+
+| Переменная | Обязательно | Описание |
+|------------|-------------|----------|
+| `API_TOKEN` | да | OAuth-токен (`Authorization: OAuth …`) |
+| `X_ORG_ID` | да | Id организации Яндекс 360 (`X-Org-ID`) |
+| `API_BASE_URL` | нет | По умолчанию `https://api.tracker.yandex.net/v3` |
+
+## Как получить OAuth-токен и X_ORG_ID
+
+Нужны **OAuth-токен** пользователя Трекера и **id организации** Яндекс 360.
+
+### 1. Зарегистрировать приложение в Яндекс OAuth
+
+Инструкция по типам приложений: [Регистрация приложения](https://yandex.ru/dev/id/doc/ru/register-client#access).
+
+Для этого MCP выбирайте тип **«Для доступа к API или отладки»** (не «для авторизации пользователей»). Тип после создания не меняется.
+
+1. Откройте [oauth.yandex.ru](https://oauth.yandex.ru) → **Создать**.
+2. Выберите **Для доступа к API или отладки**.
+3. Укажите название и почту.
+4. В поле доступов добавьте:
+   - `tracker:read` — только чтение;
+   - `tracker:write` — создание/правка/комменты/переходы (нужен для write-tools).
+5. Создайте приложение и скопируйте **ClientID**.
+
+Подробнее по Трекеру: [Доступ к API → OAuth](https://yandex.ru/support/tracker/ru/api-ref/access).
+
+### 2. Выпустить токен
+
+```text
+https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>
+```
+
+Откройте ссылку под аккаунтом, от имени которого будете ходить в Трекер. Появившаяся строка — это `API_TOKEN`.
+
+Токен действует с правами этого пользователя. Отозвать доступ можно в настройках Яндекс ID.
+
+### 3. Узнать X_ORG_ID
+
+В Трекере: **Администрирование → Организации** → скопируйте идентификатор (`X-Org-ID`).
+
+### 4. Проверить доступ
+
+```bash
+curl -X GET 'https://api.tracker.yandex.net/v3/myself' \
+  -H "Authorization: OAuth $API_TOKEN" \
+  -H "X-Org-ID: $X_ORG_ID"
+```
+
+Ожидается `200` и JSON с `login` / `display`. `401` — неверный токен, scopes или org id.
+
+## Tools
+
+### Чтение
+
+| Tool | API |
+|------|-----|
+| `get_myself` | `GET /myself` |
+| `get_user` | `GET /users/{id}` |
+| `list_users` | `GET /users` |
+| `list_queues` | `GET /queues/` |
+| `get_queue` | `GET /queues/{id}` |
+| `list_queue_versions` | `GET /queues/{id}/versions` |
+| `list_queue_components` | `GET /queues/{id}?expand=components` |
+| `get_issue` | `GET /issues/{id}` |
+| `search_issues` | `POST /issues/_search` |
+| `count_issues` | `POST /issues/_count` |
+| `get_issue_comments` | `GET /issues/{id}/comments` |
+| `get_issue_links` | `GET /issues/{id}/links` |
+| `get_issue_transitions` | `GET /issues/{id}/transitions` |
+| `get_issue_changelog` | `GET /issues/{id}/changelog` |
+| `get_issue_attachments` | метаданные вложений |
+| `get_issue_worklog` | `GET /issues/{id}/worklog` |
+| `get_issue_checklist` | `GET /issues/{id}/checklistItems` |
+| `list_boards` | `GET /boards/` |
+| `list_board_sprints` | `GET /boards/{id}/sprints` |
+
+`search_issues` / `count_issues`: укажите **ровно один** режим (`query` или `filter`; у search ещё `keys` / `queue`).
+
+Примеры `query`: `Queue: TEST`, `Queue: TEST Assignee: me() Sort by: Updated DESC`, `Key: TEST-1`.
+
+### Запись (побочные эффекты)
+
+| Tool | API |
+|------|-----|
+| `create_issue` | `POST /issues/` (+ опц. `fields`) |
+| `update_issue` | `PATCH /issues/{id}` (+ `fields` / операторы) |
+| `add_issue_comment` | `POST /issues/{id}/comments` |
+| `execute_transition` | переход статуса |
+| `create_issue_link` / `delete_issue_link` | связи |
+| `add_issue_followers` / `remove_issue_followers` | наблюдатели |
+| `add_issue_worklog` | списание времени |
+| `update_checklist_item` | чеклист |
+| `upload_issue_attachment` | загрузка файла с локального `filePath` |
+
+Статус меняется только через `execute_transition` (сначала `get_issue_transitions`). Нужен OAuth scope `tracker:write`.
+
+## Локальная разработка
+
+```bash
+git clone <repo>
+cd yandex-tracker
+cp .env.example .env
+npm install
+npm run test:unit
+npm run typecheck
+npm run dev
+```
+
+Либо в `mcp.json` укажите путь к `src/index.ts` через `npx tsx` (см. репозиторий).
+
+## License
+
+MIT

package/dist/client/tracker-client.d.ts

@@ -0,0 +1,185 @@
+export interface TrackerClientConfig {
+    baseUrl: string;
+    token: string;
+    orgId: string;
+    sslVerify?: boolean;
+    timeoutMs?: number;
+}
+export interface ListQueuesParams {
+    perPage?: number;
+    page?: number;
+    expand?: string;
+}
+export interface GetQueueParams {
+    queueId: string;
+    expand?: string;
+}
+export interface GetIssueParams {
+    issueId: string;
+    expand?: string;
+    fields?: string;
+}
+export interface SearchIssuesParams {
+    query?: string;
+    filter?: Record<string, unknown>;
+    keys?: string | string[];
+    queue?: string;
+    order?: string;
+    perPage?: number;
+    page?: number;
+    expand?: string;
+    fields?: string;
+}
+export interface ListCommentsParams {
+    issueId: string;
+    perPage?: number;
+    expand?: string;
+    /** Comment id after which the next page starts. */
+    afterId?: number;
+}
+export interface CreateIssueParams {
+    queue: string;
+    summary: string;
+    description?: string;
+    type?: string;
+    priority?: string;
+    assignee?: string;
+    parent?: string;
+    tags?: string[];
+    markupType?: string;
+    /** Extra / custom fields merged into the request body. */
+    fields?: Record<string, unknown>;
+}
+export interface UpdateIssueParams {
+    issueId: string;
+    summary?: string;
+    description?: string;
+    type?: string;
+    priority?: string;
+    assignee?: string | null;
+    parent?: string | null;
+    tags?: string[];
+    markupType?: string;
+    version?: number;
+    /** Extra / custom fields merged into the PATCH body (supports Tracker operators). */
+    fields?: Record<string, unknown>;
+}
+export interface AddCommentParams {
+    issueId: string;
+    text: string;
+    markupType?: string;
+    summonees?: string[];
+}
+export interface ExecuteTransitionParams {
+    issueId: string;
+    transitionId: string;
+    comment?: string;
+    resolution?: string;
+    fields?: Record<string, unknown>;
+}
+export interface GetIssueChangelogParams {
+    issueId: string;
+    perPage?: number;
+    /** Changelog entry id after which the next page starts. */
+    afterId?: string;
+    field?: string;
+    type?: string;
+}
+export interface GetUserParams {
+    userId: string;
+    expand?: string;
+}
+export interface ListUsersParams {
+    perPage?: number;
+    /** User uid cursor — start listing after this id. */
+    id?: number;
+    email?: string;
+    expand?: string;
+}
+export interface CreateIssueLinkParams {
+    issueId: string;
+    relationship: string;
+    linkedIssueId: string;
+}
+export interface DeleteIssueLinkParams {
+    issueId: string;
+    linkId: string | number;
+}
+export interface FollowersParams {
+    issueId: string;
+    users: string[];
+    version?: number;
+}
+export interface IssueWorklogListParams {
+    issueId: string;
+    perPage?: number;
+    afterId?: number;
+}
+export interface AddIssueWorklogParams {
+    issueId: string;
+    duration: string;
+    start?: string;
+    comment?: string;
+}
+export interface CountIssuesParams {
+    query?: string;
+    filter?: Record<string, unknown>;
+}
+export interface UpdateChecklistItemParams {
+    issueId: string;
+    itemId: string;
+    checked?: boolean;
+    text?: string;
+}
+export interface UploadAttachmentParams {
+    issueId: string;
+    filePath: string;
+    filename?: string;
+}
+export interface ListBoardSprintsParams {
+    boardId: string | number;
+}
+/**
+ * HTTP client for Yandex Tracker API v3 (OAuth + X-Org-ID / Yandex 360).
+ */
+export declare class TrackerClient {
+    private http;
+    private config;
+    constructor(config: TrackerClientConfig);
+    getMyself(): Promise<unknown>;
+    listQueues(params?: ListQueuesParams): Promise<unknown>;
+    getQueue(params: GetQueueParams): Promise<unknown>;
+    getIssue(params: GetIssueParams): Promise<unknown>;
+    searchIssues(params: SearchIssuesParams): Promise<unknown>;
+    getIssueComments(params: ListCommentsParams): Promise<unknown>;
+    getIssueLinks(issueId: string): Promise<unknown>;
+    getIssueTransitions(issueId: string): Promise<unknown>;
+    getIssueChangelog(params: GetIssueChangelogParams): Promise<unknown>;
+    getIssueAttachments(issueId: string): Promise<unknown>;
+    getUser(params: GetUserParams): Promise<unknown>;
+    listUsers(params?: ListUsersParams): Promise<unknown>;
+    createIssue(params: CreateIssueParams): Promise<unknown>;
+    updateIssue(params: UpdateIssueParams): Promise<unknown>;
+    createIssueLink(params: CreateIssueLinkParams): Promise<unknown>;
+    deleteIssueLink(params: DeleteIssueLinkParams): Promise<unknown>;
+    addIssueFollowers(params: FollowersParams): Promise<unknown>;
+    removeIssueFollowers(params: FollowersParams): Promise<unknown>;
+    getIssueWorklog(params: IssueWorklogListParams): Promise<unknown>;
+    addIssueWorklog(params: AddIssueWorklogParams): Promise<unknown>;
+    getQueueVersions(queueId: string): Promise<unknown>;
+    getQueueComponents(queueId: string): Promise<unknown>;
+    countIssues(params: CountIssuesParams): Promise<unknown>;
+    getIssueChecklist(issueId: string): Promise<unknown>;
+    updateChecklistItem(params: UpdateChecklistItemParams): Promise<unknown>;
+    listBoards(params?: {
+        perPage?: number;
+        page?: number;
+    }): Promise<unknown>;
+    listBoardSprints(params: ListBoardSprintsParams): Promise<unknown>;
+    uploadIssueAttachment(params: UploadAttachmentParams): Promise<unknown>;
+    addIssueComment(params: AddCommentParams): Promise<unknown>;
+    executeTransition(params: ExecuteTransitionParams): Promise<unknown>;
+    private wrapError;
+}
+export declare function createTrackerClient(): TrackerClient;
+//# sourceMappingURL=tracker-client.d.ts.map