Техническое задание: 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=<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. Безопасная обработка аутентификационных данных