Техническое задание: MCP сервер для Яндекс.Трекер
Общие сведения
Проект: MCP (Model Context Protocol) сервер для интеграции с Яндекс.Трекер Платформа: Node.js Режим работы: stdio API версия: Яндекс.Трекер REST API v 2
Цель проекта
Создание MCP сервера, обеспечивающего взаимодействие AI-ассистентов с системой управления задачами Яндекс.Трекер через стандартизированный протокол MCP.
Архитектура и технические требования
Основные компоненты
- MCP Server Core Реализация протокола MCP версии 2024 - 11 - 05 Обработка stdio коммуникации Управление жизненным циклом соединения
- Yandex Tracker API Client HTTP клиент для взаимодействия с API Яндекс.Трекер Аутентификация через OAuth токен Обработка rate limiting и ошибок
- Data Models Типизированные модели для объектов Трекера (задачи, проекты, пользователи) Валидация входящих и исходящих данных
Технологический стек
Runtime: Node.js 18+
Язык: TypeScript
HTTP клиент: axios
MCP SDK: @modelcontextprotocol/sdk
Валидация: zod
Логирование: pino
Функциональные требования
Обязательные инструменты (tools)
- Управление задачами
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
Возврат: обновленная задача
- Комментарии
add_comment
Добавление комментария к задаче
Параметры: issueKey, text, summonees
Возврат: объект созданного комментария
get_comments
Получение комментариев задачи
Параметры: issueKey, limit, offset
Возврат: список комментариев
- Управление проектами
get_queues
Получение списка очередей
Параметры: expand, filter
Возврат: список доступных очередей
get_queue
Получение информации об очереди
Параметры: queueKey, expand
Возврат: детальная информация об очереди
- Пользователи и права
get_myself
Получение информации о текущем пользователе
Возврат: профиль пользователя
search_users
Поиск пользователей
Параметры: query, limit
Возврат: список найденных пользователей
Ресурсы (resources)
- Конфигурация
config://yandex-tracker/settings
Текущие настройки подключения
Информация об авторизации (без токена)
Базовый URL API
- Схемы и метаданные
schema://yandex-tracker/issue-types
Доступные типы задач в организации
schema://yandex-tracker/priorities
Список приоритетов задач
schema://yandex-tracker/statuses
Доступные статусы задач
Промпты (prompts)
- Анализ задач
analyze_sprint
Анализ спринта или группы задач
Аргументы: sprintId или query для поиска задач
Контекст: статистика, проблемы, рекомендации
task_summary
Краткое изложение задачи
Аргументы: issueKey
Контекст: суть задачи, статус, исполнители
- Создание контента
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
Обработка истечения токена с информативными сообщениями
Обработка ошибок
Типы ошибок
- Аутентификация 401 Unauthorized - невалидный токен 403 Forbidden - недостаточно прав
- Клиентские ошибки 400 Bad Request - некорректные параметры 404 Not Found - задача не найдена 409 Conflict - конфликт при обновлении
- Серверные ошибки 500 Internal Server Error 503 Service Unavailable
- Сетевые ошибки Таймауты Потеря соединения
Стратегии обработки
Автоматические повторы для 5 xx ошибок (exponential backoff) Rate limiting с ожиданием Детальные сообщения об ошибках для пользователя Логирование всех ошибок для отладки
Производительность и ограничения
Rate Limiting
Соблюдение лимитов API Яндекс.Трекер Очередь запросов с приоритизацией Кэширование часто запрашиваемых данных
Оптимизация
- Пакетные операции где возможно
- Ленивая загрузка данных
- Сжатие ответов
Тестирование
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"
}
}
}
}
Различные уровни логирования
Ротация логов
Безопасность - исключение токенов из логов
Безопасность
Защита токенов
- Токены только через переменные окружения
- Маскирование токенов в логах
- Безопасное хранение конфигурации
Валидация данных
- Проверка всех входящих параметров
- Санитизация пользовательского ввода
- Защита от injection атак
Совместимость
MCP версии
- Поддержка MCP Protocol 2024 - 11 - 05
- Обратная совместимость с предыдущими версиями
Node.js версии
Минимальная версия: Node.js 18 Тестирование на LTS версиях Поддержка ES modules
Планы развития
Фаза 1 (MVP)
Базовые операции с задачами Поиск и фильтрация Управление комментариями
Фаза 2
Работа с проектами и досками Продвинутая аналитика Интеграция с календарем
Фаза 3
Автоматизация процессов Интеграция с другими системами Расширенные отчеты
Критерии приемки
- Все обязательные инструменты реализованы и протестированы
- Успешная интеграция с популярными MCP клиентами
- Покрытие тестами не менее 80 %
- Документация полная и актуальная
- Производительность соответствует требованиям API
- Безопасная обработка аутентификационных данных