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

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

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

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

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

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

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

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

• 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

get_issue

update_issue

search_issues

transition_issue

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

add_comment

get_comments

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

get_queues

get_queue

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

get_myself

search_users

Ресурсы (resources)

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

config://yandex-tracker/settings

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

schema://yandex-tracker/issue-types

schema://yandex-tracker/priorities

schema://yandex-tracker/statuses

Промпты (prompts)

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

analyze_sprint

task_summary

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

daily_report

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

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

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

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

Типы ошибок

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 формате

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

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

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