Yandex Tracker

Se integra con Yandex Tracker, permitiendo que un asistente de IA interactúe con su sistema de gestión de tareas a través del protocolo MCP.

GitHub
3

Documentación

Especificación Técnica: Servidor MCP para Yandex Tracker

Información General

Proyecto: Servidor MCP (Model Context Protocol) para integración con Yandex Tracker Plataforma: Node.js Modo de operación: stdio Versión de API: Yandex Tracker REST API v 2

Objetivo del Proyecto

Crear un servidor MCP que permita la interacción de asistentes de IA con el sistema de gestión de tareas Yandex Tracker a través del protocolo estandarizado MCP.

Arquitectura y Requisitos Técnicos

Componentes Principales

  1. Núcleo del Servidor MCP Implementación del protocolo MCP versión 2024 - 11 - 05 Manejo de comunicación stdio Gestión del ciclo de vida de la conexión
  2. Cliente API de Yandex Tracker Cliente HTTP para interactuar con la API de Yandex Tracker Autenticación mediante token OAuth Manejo de límites de tasa y errores
  3. Modelos de Datos Modelos tipados para objetos de Tracker (tareas, proyectos, usuarios) Validación de datos entrantes y salientes

Stack Tecnológico

Runtime: Node.js 18+
Lenguaje: TypeScript
Cliente HTTP: axios
SDK MCP: @modelcontextprotocol/sdk
Validación: zod
Registro de logs: pino

Requisitos Funcionales

Herramientas Obligatorias (tools)

  1. Gestión de tareas

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
Возврат: обновленная задача
  1. Comentarios

add_comment

Добавление комментария к задаче
Параметры: issueKey, text, summonees
Возврат: объект созданного комментария

get_comments

Получение комментариев задачи

Параметры: issueKey, limit, offset
Возврат: список комментариев
  1. Gestión de proyectos

get_queues

Получение списка очередей
Параметры: expand, filter
Возврат: список доступных очередей

get_queue

Получение информации об очереди
Параметры: queueKey, expand
Возврат: детальная информация об очереди
  1. Usuarios y permisos

get_myself

Получение информации о текущем пользователе
Возврат: профиль пользователя

search_users

Поиск пользователей
Параметры: query, limit
Возврат: список найденных пользователей

Recursos (resources)

  1. Configuración

config://yandex-tracker/settings

Текущие настройки подключения
Информация об авторизации (без токена)
Базовый URL API
  1. Esquemas y metadatos

schema://yandex-tracker/issue-types

Доступные типы задач в организации

schema://yandex-tracker/priorities

Список приоритетов задач

schema://yandex-tracker/statuses

Доступные статусы задач

Prompts

  1. Análisis de tareas

analyze_sprint

Анализ спринта или группы задач
Аргументы: sprintId или query для поиска задач
Контекст: статистика, проблемы, рекомендации

task_summary

Краткое изложение задачи
Аргументы: issueKey
Контекст: суть задачи, статус, исполнители
  1. Creación de contenido

daily_report

Генерация отчета о ежедневной работе
Аргументы: assignee, date
Контекст: выполненные задачи, планы

Configuración y Autenticación

Variables de Entorno

Autenticación

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
Обработка истечения токена с информативными сообщениями

Manejo de Errores

Tipos de Errores

  1. Autenticación 401 Unauthorized - token no válido 403 Forbidden - permisos insuficientes
  2. Errores de cliente 400 Bad Request - parámetros incorrectos 404 Not Found - tarea no encontrada 409 Conflict - conflicto al actualizar
  3. Errores de servidor 500 Internal Server Error 503 Service Unavailable
  4. Errores de red Tiempos de espera agotados Pérdida de conexión

Estrategias de Manejo

Reintentos automáticos para errores 5 xx (retroceso exponencial) Límite de tasa con espera Mensajes de error detallados para el usuario Registro de todos los errores para depuración

Rendimiento y Limitaciones

Límite de Tasa

Cumplimiento de los límites de la API de Yandex Tracker Cola de solicitudes con priorización Almacenamiento en caché de datos solicitados con frecuencia

Optimización

  1. Operaciones por lotes cuando sea posible
  2. Carga diferida de datos
  3. Compresión de respuestas

Pruebas

Pruebas Unitarias

Cobertura de todos los métodos públicos Simulación de solicitudes HTTP Validación de datos de entrada y salida

Pruebas de Integración

Pruebas con API real (entorno de desarrollo) Verificación de todas las herramientas MCP Pruebas de manejo de errores

Pruebas E 2 E

Ciclo completo de interacción a través de MCP Pruebas en Claude Desktop u otro cliente MCP

Documentación

README.md

Instrucciones de instalación y configuración Ejemplos de uso Configuración para clientes MCP populares

Documentación de API

Descripción de todas las herramientas, recursos y prompts Ejemplos de solicitudes y respuestas Esquemas de datos

Guía de Solución de Problemas

Problemas comunes y sus soluciones Depuración de conexión Problemas de autenticación

Despliegue y Distribución

Paquete NPM

Publicación en el registro npm Versionado semántico Lanzamientos automáticos mediante GitHub Actions

Contenedor Docker (opcional)

Dockerfile para contenerización Docker Compose para desarrollo local

Instalación

Configuración en clientes MCP

Monitoreo y Registro de Logs

Métricas

Número de solicitudes a la API Tiempo de respuesta Número de errores por tipo Uso del límite de tasa

Registro de Logs

Logs estructurados en formato 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"
            }
        }
    }
}

Различные уровни логирования
Ротация логов
Безопасность - исключение токенов из логов

Seguridad

Protección de Tokens

  1. Tokens solo mediante variables de entorno
  2. Enmascaramiento de tokens en logs
  3. Almacenamiento seguro de configuración

Validación de Datos

  1. Verificación de todos los parámetros entrantes
  2. Saneamiento de entrada del usuario
  3. Protección contra ataques de inyección

Compatibilidad

Versiones de MCP

  1. Soporte del Protocolo MCP 2024 - 11 - 05
  2. Compatibilidad inversa con versiones anteriores

Versiones de Node.js

Versión mínima: Node.js 18 Pruebas en versiones LTS Soporte de módulos ES

Planes de Desarrollo

Fase 1 (MVP)

Operaciones básicas con tareas Búsqueda y filtrado Gestión de comentarios

Fase 2

Trabajo con proyectos y tableros Analítica avanzada Integración con calendario

Fase 3

Automatización de procesos Integración con otros sistemas Informes ampliados

Criterios de Aceptación

  1. Todas las herramientas obligatorias implementadas y probadas
  2. Integración exitosa con clientes MCP populares
  3. Cobertura de pruebas de al menos 80 %
  4. Documentación completa y actualizada
  5. Rendimiento acorde a los requisitos de la API
  6. Manejo seguro de datos de autenticación