Yandex Tracker

Integra-se ao Yandex Tracker, permitindo que um assistente de IA interaja com seu sistema de gerenciamento de tarefas por meio do protocolo MCP.

GitHub
3

Documentação

Especificação Técnica: Servidor MCP para Yandex Tracker

Informações Gerais

Projeto: Servidor MCP (Model Context Protocol) para integração com Yandex Tracker Plataforma: Node.js Modo de operação: stdio Versão da API: Yandex Tracker REST API v 2

Objetivo do Projeto

Criar um servidor MCP que permita a interação de assistentes de IA com o sistema de gerenciamento de tarefas Yandex Tracker por meio do protocolo padronizado MCP.

Arquitetura e Requisitos Técnicos

Componentes Principais

  1. MCP Server Core Implementação do protocolo MCP versão 2024 - 11 - 05 Tratamento da comunicação stdio Gerenciamento do ciclo de vida da conexão
  2. Yandex Tracker API Client Cliente HTTP para interação com a API do Yandex Tracker Autenticação via token OAuth Tratamento de rate limiting e erros
  3. Data Models Modelos tipados para objetos do Tracker (tarefas, projetos, usuários) Validação de dados de entrada e saída

Stack Tecnológico

Runtime: Node.js 18+
Linguagem: TypeScript
Cliente HTTP: axios
MCP SDK: @modelcontextprotocol/sdk
Validação: zod
Logging: pino

Requisitos Funcionais

Ferramentas Obrigatórias (tools)

  1. Gerenciamento de tarefas

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. Comentários

add_comment

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

get_comments

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

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

get_queues

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

get_queue

Получение информации об очереди
Параметры: queueKey, expand
Возврат: детальная информация об очереди
  1. Usuários e permissões

get_myself

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

search_users

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

Recursos (resources)

  1. Configuração

config://yandex-tracker/settings

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

schema://yandex-tracker/issue-types

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

schema://yandex-tracker/priorities

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

schema://yandex-tracker/statuses

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

Prompts

  1. Análise de tarefas

analyze_sprint

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

task_summary

Краткое изложение задачи
Аргументы: issueKey
Контекст: суть задачи, статус, исполнители
  1. Criação de conteúdo

daily_report

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

Configuração e Autenticação

Variáveis de Ambiente

Autenticação

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

Tratamento de Erros

Tipos de Erros

  1. Autenticação 401 Unauthorized - token inválido 403 Forbidden - permissões insuficientes
  2. Erros do cliente 400 Bad Request - parâmetros incorretos 404 Not Found - tarefa não encontrada 409 Conflict - conflito na atualização
  3. Erros do servidor 500 Internal Server Error 503 Service Unavailable
  4. Erros de rede Timeouts Perda de conexão

Estratégias de Tratamento

Repetições automáticas para erros 5 xx (exponential backoff) Rate limiting com espera Mensagens de erro detalhadas para o usuário Registro de todos os erros para depuração

Desempenho e Limitações

Rate Limiting

Respeito aos limites da API do Yandex Tracker Fila de requisições com priorização Cache de dados frequentemente solicitados

Otimização

  1. Operações em lote quando possível
  2. Carregamento preguiçoso de dados
  3. Compressão de respostas

Testes

Testes Unitários

Cobertura de todos os métodos públicos Mock de requisições HTTP Validação de dados de entrada e saída

Testes de Integração

Testes com API real (ambiente de desenvolvimento) Verificação de todas as ferramentas MCP Testes de tratamento de erros

Testes E 2 E

Ciclo completo de interação via MCP Testes no Claude Desktop ou outro cliente MCP

Documentação

README.md

Instruções de instalação e configuração Exemplos de uso Configuração para clientes MCP populares

Documentação da API

Descrição de todas as ferramentas, recursos e prompts Exemplos de requisições e respostas Esquemas de dados

Guia de Solução de Problemas

Problemas comuns e suas soluções Depuração de conexão Problemas de autenticação

Implantação e Distribuição

Pacote NPM

Publicação no registro npm Versionamento semântico Lançamentos automáticos via GitHub Actions

Contêiner Docker (opcional)

Dockerfile para conteinerização Docker Compose para desenvolvimento local

Instalação

Configuração em clientes MCP

Monitoramento e Logging

Métricas

Número de requisições à API Tempo de resposta Número de erros por tipo Uso do rate limit

Logging

Logs estruturados em 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"
            }
        }
    }
}

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

Segurança

Proteção de Tokens

  1. Tokens apenas por variáveis de ambiente
  2. Mascaramento de tokens nos logs
  3. Armazenamento seguro da configuração

Validação de Dados

  1. Verificação de todos os parâmetros de entrada
  2. Sanitização da entrada do usuário
  3. Proteção contra ataques de injeção

Compatibilidade

Versões MCP

  1. Suporte ao MCP Protocol 2024 - 11 - 05
  2. Compatibilidade retroativa com versões anteriores

Versões do Node.js

Versão mínima: Node.js 18 Testes nas versões LTS Suporte a ES modules

Planos de Desenvolvimento

Fase 1 (MVP)

Operações básicas com tarefas Busca e filtragem Gerenciamento de comentários

Fase 2

Trabalho com projetos e quadros Análise avançada Integração com calendário

Fase 3

Automação de processos Integração com outros sistemas Relatórios avançados

Critérios de Aceite

  1. Todas as ferramentas obrigatórias implementadas e testadas
  2. Integração bem-sucedida com clientes MCP populares
  3. Cobertura de testes de pelo menos 80 %
  4. Documentação completa e atualizada
  5. Desempenho em conformidade com os requisitos da API
  6. Tratamento seguro de dados de autenticação