# Техническое задание: MCP сервер для Яндекс.Трекер ## Общие сведения Проект: MCP (Model Context Protocol) сервер для интеграции с Яндекс.Трекер Платформа: Node.js Режим работы: stdio API версия: Яндекс.Трекер REST API v 2 ## Цель проекта Создание MCP сервера, обеспечивающего взаимодействие AI-ассистентов с системой управления задачами Яндекс.Трекер через стандартизированный протокол MCP. ## Архитектура и технические требования ### Основные компоненты 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= YANDEX_TRACKER_CLOUD_ORG_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 формате ``` bash npm install -g yandex-tracker-mcp-server ``` ``` json { "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. Безопасная обработка аутентификационных данных