Техническое задание: MCP сервер для Яндекс.Трекер

Общие сведения

Проект: MCP (Model Context Protocol) сервер для интеграции с Яндекс.Трекер Платформа: Node.js Режим работы: stdio, HTTP/HTTPS API версия: Яндекс.Трекер REST API v 2

Режимы работы

1. STDIO режим (для VS Code, Claude Desktop и т.д.)

npm run compile
npm run run

2. HTTP/HTTPS режим (для ChatGPT)

Сервер также может работать как HTTP/HTTPS API для подключения к ChatGPT через OpenAI Actions.

# Компиляция
npm run compile

# Запуск HTTP сервера
npm run start:http

# Для HTTPS настройте SSL_KEY_PATH и SSL_CERT_PATH в .env

Доступные эндпоинты:

• GET / - Информация о сервере

• GET /.well-known/ai-plugin.json - Манифест плагина для ChatGPT

• GET /openapi.json - OpenAPI спецификация

• GET /tools - Список всех инструментов

• POST /execute/:operationId - Выполнение инструмента

📚 Подробная документация: HTTP_SERVER.md

Цель проекта

Создание MCP сервера, обеспечивающего взаимодействие AI-ассистентов с системой управления задачами Яндекс.Трекер через стандартизированный протокол MCP.

Ключевые возможности

✨ Полное управление задачами:

• Создание, редактирование, удаление задач

• Поиск задач по различным критериям

• Управление связями между задачами

• Изменение очереди задач - перенос между очередями с сохранением данных

📎 Работа с вложениями:

• Прикрепление файлов и изображений к задачам

• Загрузка файлов на Wiki страницы

• Получение списка вложений

• Удаление вложений

📋 Управление очередями и Wiki:

• Получение информации об очередях

• Создание и редактирование Wiki страниц

• Добавление контента к страницам

💬 Комментарии и коммуникация:

• Добавление комментариев к задачам

• Упоминание пользователей (@mention)

📚 Подробная документация:

• ATTACHMENTS.md - Работа с вложениями файлов

• QUEUE_MANAGEMENT.md - Управление очередями задач

• HTTP_SERVER.md - HTTP/HTTPS режим для ChatGPT

Архитектура и технические требования

Основные компоненты

1. MCP Server Core Реализация протокола MCP версии 2024 - 11 - 05 Обработка stdio коммуникации Управление жизненным циклом соединения

2. Yandex Tracker API Client HTTP клиент для взаимодействия с API Яндекс.Трекер Аутентификация через OAuth токен Обработка rate limiting и ошибок

3. Data Models Типизированные модели для объектов Трекера (задачи, проекты, пользователи) Валидация входящих и исходящих данных

Технологический стек

Runtime: Node.js 18+
Язык: TypeScript
HTTP клиент: axios
MCP SDK: @modelcontextprotocol/sdk
Валидация: zod
Логирование: pino

Функциональные требования

Обязательные инструменты (tools)

1. Управление задачами

create_issue

Создание новой задачи
Параметры: summary, description, queue, type, priority, assignee, components, labels
Возврат: объект созданной задачи с ключом

get_issue

Получение информации о задаче по ключу
Параметры: issueKey
Возврат: полная информация о задаче

update_issue

Обновление существующей задачи
Параметры: issueKey, поля для обновления
Возврат: обновленный объект задачи

search_issues

Поиск задач по критериям
Параметры: query (язык запросов Трекера), sort, limit, offset
Возврат: список найденных задач

transition_issue

Изменение статуса задачи
Параметры: issueKey, transition, comment
Возврат: обновленная задача

2. Комментарии

add_comment

Добавление комментария к задаче
Параметры: issueKey, text, summonees
Возврат: объект созданного комментария

get_comments

Получение комментариев задачи

Параметры: issueKey, limit, offset
Возврат: список комментариев

3. Управление проектами

get_queues

Получение списка очередей
Параметры: expand, filter
Возврат: список доступных очередей

get_queue

Получение информации об очереди
Параметры: queueKey, expand
Возврат: детальная информация об очереди

4. Пользователи и права

get_myself

Получение информации о текущем пользователе
Возврат: профиль пользователя

search_users

Поиск пользователей
Параметры: query, limit
Возврат: список найденных пользователей

Ресурсы (resources)

1. Конфигурация

config://yandex-tracker/settings

Текущие настройки подключения
Информация об авторизации (без токена)
Базовый URL API

2. Схемы и метаданные

schema://yandex-tracker/issue-types

Доступные типы задач в организации

schema://yandex-tracker/priorities

Список приоритетов задач

schema://yandex-tracker/statuses

Доступные статусы задач

Промпты (prompts)

1. Анализ задач

analyze_sprint

Анализ спринта или группы задач
Аргументы: sprintId или query для поиска задач
Контекст: статистика, проблемы, рекомендации

task_summary

Краткое изложение задачи
Аргументы: issueKey
Контекст: суть задачи, статус, исполнители

2. Создание контента

daily_report

Генерация отчета о ежедневной работе
Аргументы: assignee, date
Контекст: выполненные задачи, планы

Конфигурация и аутентификация

Переменные окружения

Аутентификация

YANDEX_TRACKER_TOKEN=<OAuth токен>
YANDEX_TRACKER_CLOUD_ORG_ID=<ID огранизации>
YANDEX_TRACKER_BASE_URL=https://api.tracker.yandex.net/v2
LOG_LEVEL=info
REQUEST_TIMEOUT=30000
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60000

OAuth 2. 0 токен через заголовок Authorization
Передача ID организации в заголовке X-Cloud-Org-Id
Обработка истечения токена с информативными сообщениями

Обработка ошибок

Типы ошибок

1. Аутентификация 401 Unauthorized - невалидный токен 403 Forbidden - недостаточно прав

2. Клиентские ошибки 400 Bad Request - некорректные параметры 404 Not Found - задача не найдена 409 Conflict - конфликт при обновлении

3. Серверные ошибки 500 Internal Server Error 503 Service Unavailable

4. Сетевые ошибки Таймауты Потеря соединения

Стратегии обработки

Автоматические повторы для 5 xx ошибок (exponential backoff) Rate limiting с ожиданием Детальные сообщения об ошибках для пользователя Логирование всех ошибок для отладки

Производительность и ограничения

Rate Limiting

Соблюдение лимитов API Яндекс.Трекер Очередь запросов с приоритизацией Кэширование часто запрашиваемых данных

Оптимизация

1. Пакетные операции где возможно

2. Ленивая загрузка данных

3. Сжатие ответов

Тестирование

Unit тесты

Покрытие всех публичных методов Мокирование HTTP запросов Валидация входных и выходных данных

Интеграционные тесты

Тестирование с реальным API (dev окружение) Проверка всех инструментов MCP Тестирование обработки ошибок

E 2 E тесты

Полный цикл взаимодействия через MCP Тестирование в Claude Desktop или другом MCP клиенте

Документация

README.md

Инструкции по установке и настройке Примеры использования Конфигурация для популярных MCP клиентов

API Documentation

Описание всех инструментов, ресурсов и промптов Примеры запросов и ответов Схемы данных

Troubleshooting Guide

Частые проблемы и их решения Отладка соединения Проблемы с аутентификацией

Развертывание и распространение

NPM пакет

Публикация в npm registry Семантическое версионирование Автоматические релизы через GitHub Actions

Docker контейнер (опционально)

Dockerfile для контейнеризации Docker Compose для локальной разработки

Установка

Конфигурация в MCP клиентах

Мониторинг и логирование

Метрики

Количество запросов к API Время ответа Количество ошибок по типам Использование rate limit

Логирование

Структурированные логи в JSON формате

npm install -g yandex-tracker-mcp-server

{
"mcpServers": {
    "yandex-tracker": {
        "command": "yandex-tracker-mcp-server",
        "env": {
        "YANDEX_TRACKER_TOKEN": "your_token_here",
        "YANDEX_TRACKER_CLOUD_ORG_ID": "your_org_id"
            }
        }
    }
}

Различные уровни логирования
Ротация логов
Безопасность - исключение токенов из логов

Безопасность

Защита токенов

1. Токены только через переменные окружения

2. Маскирование токенов в логах

3. Безопасное хранение конфигурации

Валидация данных

1. Проверка всех входящих параметров

2. Санитизация пользовательского ввода

3. Защита от injection атак

Совместимость

MCP версии

1. Поддержка MCP Protocol 2024 - 11 - 05

2. Обратная совместимость с предыдущими версиями

Node.js версии

Минимальная версия: Node.js 18 Тестирование на LTS версиях Поддержка ES modules

Планы развития

Фаза 1 (MVP)

Базовые операции с задачами Поиск и фильтрация Управление комментариями

Фаза 2

Работа с проектами и досками Продвинутая аналитика Интеграция с календарем

Фаза 3

Автоматизация процессов Интеграция с другими системами Расширенные отчеты

Критерии приемки

1. Все обязательные инструменты реализованы и протестированы

2. Успешная интеграция с популярными MCP клиентами

3. Покрытие тестами не менее 80 %

4. Документация полная и актуальная

5. Производительность соответствует требованиям API

6. Безопасная обработка аутентификационных данных