Техническое задание: 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 формате

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