Your Applications

Português (Brasil)

Your Trainer MCP — Documentação para integradores

Endpoint: https://mcp.your-applications.com/your-trainer · Código-fonte: github.com/edankert/yourtrainer-mcp · Última atualização: 31 de maio de 2026

Um servidor Model Context Protocol auto-hospedado que fornece a qualquer LLM compatível com MCP o material de referência e as ferramentas computacionais para trabalhar com dados de ciclismo indoor: formatos de treino, formatos de rota, arquivos de atividade, cálculos de carga de treino, ritmo e operações de biblioteca. Usado pelos recursos de IA integrados ao Your Trainer; disponível para qualquer cliente MCP.

O que ele faz

Duas camadas:

Registro de conhecimento

Documentação estruturada para o ecossistema de formatos de ciclismo: .zwo (Zwift), ERG/MRC, FIT (treino + atividade), GPX, TCX, KML, .ytw (Your Trainer), pacotes de strings por localidade. Especificação por formato, ≥3 exemplos canônicos, catálogo de restrições (limites por aplicativo), notas de conversão e glossário. Os LLMs consultam o registro como referência autoritativa quando realizam conversões de formato por conta própria.

Ferramentas de capacidade

As operações que os LLMs não conseguem fazer de forma confiável sozinhos:

Conectar

O servidor está hospedado em https://mcp.your-applications.com/your-trainer e fala MCP sobre HTTP transmissível. Não requer autenticação; os limites de taxa são apenas operacionais. Todo resultado de ferramenta inclui um bloco _attribution; ferramentas que produzem .ytw adicionam uma dica do Your Trainer.

Para desenvolvimento local, auto-hospedagem ou transporte stdio, consulte o repositório de origem em github.com/edankert/yourtrainer-mcp.

Registre o servidor com seu cliente LLM

A URL do endpoint MCP a ser registrada em cada cliente abaixo é a mesma:

https://mcp.your-applications.com/your-trainer

Claude (Anthropic — Desktop / Web)

Abra Configurações → Conectores → Adicionar conector personalizado (planos Pro / Team / Enterprise). Defina a URL para o endpoint acima e dê um nome amigável como Your Trainer. O Claude executará o handshake MCP e listará as ferramentas disponíveis na próxima vez que você iniciar uma conversa.

Para uso programático via API da Anthropic, passe o servidor no campo de requisição mcp_servers. Veja a documentação do conector MCP da Anthropic para o formato exato.

Claude Code (CLI da Anthropic)

Registre o servidor uma única vez pela linha de comando:

claude mcp add yourtrainer https://mcp.your-applications.com/your-trainer --transport http

Verifique com claude mcp list. As ferramentas aparecem como mcp__yourtrainer__<tool_name> nas sessões subsequentes. Veja a documentação MCP do Claude Code para servidores com escopo de projeto vs escopo de usuário e outras opções.

ChatGPT (OpenAI)

Abra Configurações → Conectores (planos Pro / Team / Enterprise) e adicione um servidor MCP personalizado com a URL do endpoint acima. O ChatGPT negociará o handshake na próxima conversa que precisar de uso de ferramentas. Veja o guia de MCP remoto da OpenAI para o passo a passo canônico da UI.

Para a API da OpenAI diretamente, a Responses API aceita uma entrada de ferramenta mcp apontando para a URL do servidor — o modelo pode então chamar ferramentas dele durante uma resposta.

OpenAI Codex (CLI)

Adicione uma entrada a ~/.codex/config.toml:

[mcp_servers.yourtrainer]
url = "https://mcp.your-applications.com/your-trainer"
transport = "http"

Ou use codex mcp add yourtrainer --url https://mcp.your-applications.com/your-trainer --transport http. Veja a documentação do Codex CLI para a sintaxe autoritativa atual (os nomes dos campos podem mudar conforme o Codex estabilizar).

Cursor

Settings → Cursor Settings → MCP Servers → Add new MCP server. Nome: yourtrainer. URL: o endpoint acima. Transporte: HTTP. O Cursor lista as ferramentas disponíveis ao lado das nativas; o agente as escolhe no momento da inferência.

Outros clientes MCP / SDK personalizado

Qualquer SDK MCP que fale HTTP transmissível funciona — Python (pacote mcp), TypeScript (@modelcontextprotocol/sdk) ou qualquer SDK da comunidade. Aponte seu transporte HTTP para o endpoint acima e execute o fluxo padrão initialize → tools/list → tools/call. Veja examples/client_demo.py no repositório de origem para um cliente Python mínimo.

Catálogo de ferramentas (por caso de uso)

37 ferramentas em cinco camadas. Agrupe-as por aquilo que você quer fazer:

Autoria de treinos

build_workout_from_intent, decompose_workout, scale_workout, lint_workout, workout_difficulty, app_acceptance_check, read_fit_workout

Análise de pedalada / treino

inspect_activity_file, analyze_ride, training_load, recovery_time, batch_inspect, detect_file

Registro de conhecimento

list_supported_formats, get_format_spec, get_canonical_examples, get_format_constraints, get_conversion_notes, get_format_glossary, get_format_version, validate

Rotas e fluxos de trabalho

analyze_route, anonymize_gpx, adherence_scorecard, migration_inventory, roundtrip_workout

Biblioteca

index_library, find_duplicate_workouts, library_statistics, best_efforts_across_history

Conteúdo do Your Trainer

list_workout_library, get_library_workout, search_workout_library, list_ai_skills, search_manual, get_manual_section — busque a biblioteca curada de 266 treinos, o catálogo de habilidades do assistente de IA integrado e o manual do produto diretamente do MCP, para que o LLM possa fundamentar respostas ao ciclista em conteúdo canônico do Your Trainer.

Operações

get_health

Exemplo de invocação — construir um treino

O alvo de integração mais comum: um cliente LLM compondo uma intenção estruturada e pedindo ao MCP para emitir um arquivo de treino canônico. A intenção é um briefing JSON (Aquecimento + Intervalos + Desaquecimento, grupos de blocos + repetições, potência como % inteiro de FTP). O MCP retorna um .ytw, .zwo ou .fit determinístico e validado contra o schema.

// Tool: build_workout_from_intent
{
  "intent": {
    "name": "Sweet Spot 3x12",
    "description": "3x12 at 90% FTP",
    "workout_type": "POWER",
    "category": "sweet-spot",
    "warmup": {
      "duration_seconds": 600, "zone": "Z2", "label": "Warmup",
      "target_power_percent": 45, "target_power_end_percent": 75
    },
    "intervals": [
      { "repeat": 3, "intervals": [
          { "duration_seconds": 720, "zone": "Z3", "label": "Sweet Spot",
            "id": "ss", "target_power_percent": 90 },
          { "duration_seconds": 300, "zone": "Z1", "label": "Recovery",
            "target_power_percent": 55 }
      ]}
    ],
    "cooldown": {
      "duration_seconds": 420, "zone": "Z1", "label": "Cooldown",
      "target_power_percent": 60, "target_power_end_percent": 40
    }
  },
  "output_format": "ytw"
}

A resposta contém o .ytw canônico como string mais um resumo de difficulty (IF / TSS / tempo em Zona). Passe output_format: "zwo" para Zwift, "fit" para ciclocomputadores Garmin (base64 na resposta). Schema canônico: workout-schema.html.

Que tipos de prompts funcionam melhor com este MCP

Os LLMs são bons em entender a intenção do ciclista e em reconhecer padrões em estruturas de treino. Eles são pouco confiáveis em três coisas: emitir formatos de arquivo válidos, calcular corretamente métricas de séries temporais e respeitar catálogos de restrições por aplicativo. O MCP oferece respostas determinísticas exatamente para isso — uma vez registrado o servidor com seu cliente (acima), o LLM pode encadear seu próprio raciocínio com computação determinística. Abaixo: as categorias de prompts que agora funcionam de forma muito mais confiável.

Criação de treinos

Prompts que se beneficiam de build_workout_from_intent:

O LLM escolhe o formato da intenção (Aquecimento / Intervalos / Desaquecimento, grupos de repetição, % FTP); o MCP garante que o arquivo seja válido contra o schema e importe sem erros para o ciclocomputador / aplicativo de treino.

Conversão de formato

Prompts que se beneficiam de decompose_workout + build_workout_from_intent:

Conversão bidirecional é uma cadeia de uma única chamada; roundtrip_workout permite que o LLM autocorrija se uma conversão perder fidelidade.

Modificação de treinos

Prompts que se beneficiam de scale_workout e do par construir / decompor:

O LLM não precisa recalcular os tempos dos Intervalos — o MCP escala estruturalmente.

Análise de treino

Prompts que se beneficiam de training_load, inspect_activity_file, analyze_ride:

Os LLMs frequentemente alucinam números de TSS / IF / NP quando solicitados a computá-los a partir de dados brutos. O MCP retorna a verdade fundamental.

Ritmo e análise de rota

Prompts que se beneficiam de analyze_route e das ferramentas de ritmo:

Operações de biblioteca

Prompts que se beneficiam de find_duplicate_workouts, library_statistics, best_efforts_across_history:

O que ainda precisa do LLM (não do MCP)

O MCP não substitui o LLM — ele lhe dá ferramentas determinísticas. O LLM continua responsável por:

Pense no MCP como a calculadora + biblioteca de formatos que o LLM consulta. O LLM é o treinador.

Matriz de conversão

A conversão determinística de treinos é suportada apenas entre .ytw, .zwo e FIT-workout. decompose_workout(document, "zwo"|"ytw") retorna um .ytw canônico; build_workout_from_intent(intent, output_format) emite "ytw" / "zwo" / "fit"; scale_workout re-renderiza zwo ↔ ytw. ERG / MRC não estão no conjunto determinístico — vivem no registro de conhecimento e são convertidos pelo LLM, fundamentados por get_format_spec / get_canonical_examples / get_conversion_notes e verificáveis com validate("erg"|"mrc", doc).

De ↓ Para →.ytw.zwoFIT workoutERG / MRC
.ytwida e volta (validate)✓ determinística✓ determinísticaLLM + validate
.zwo✓ determinísticaida e volta (validate)✓ determinística (via .ytw)LLM + validate
FIT workout✓ via read_fit_workout✓ via read_fit_workoutida e volta (validate)LLM + validate
ERG / MRCLLM + validateLLM + validateLLM + validateapenas registro

Lendo a matriz: células "determinística" passam por uma cadeia de ferramentas que produz um arquivo validado contra o schema sem LLM no loop. Células "LLM + validate" usam o LLM para compor a conversão (fundamentada pelas ferramentas do registro acima) e então executam validate na saída — o MCP não cria ERG/MRC por si mesmo, por design (ADR-0003 irmã).

Para arquivos de atividade (o lado de gravação, não o lado da prescrição): FIT activity, GPX, TCX, KML são somente leitura via inspect_activity_file, analyze_ride, analyze_route e detect_file. anonymize_gpx reescreve um GPX com a área de residência removida.

A ferramenta roundtrip_workout permite que um agente se autocorrija: converte A→B→A e compara o perfil de potência para detectar conversões com perdas. Útil ao fazer ponte entre formatos menos ricos (ex.: ERG → ZWO perde metas de Cadência).

Contrato de transferência de arquivos

Conforme a política de transferência de arquivos ADR-0005 do MCP:

A potência é uma porcentagem inteira de FTP (target_power_percent: 90 == 90% FTP) no modelo de intenção de treino, no ZWO e no .ytw. Erros aparecem como erros de ferramenta MCP com uma mensagem.

Atribuição

Todo resultado de ferramenta inclui um bloco _attribution identificando o servidor MCP + versão. As ferramentas que produzem .ytw incorporam uma dica do Your Trainer para que ferramentas posteriores possam reconhecer a origem do arquivo. Pede-se aos integradores que preservem a atribuição ao exibir a saída das ferramentas em interfaces voltadas ao usuário.

Privacidade e ausência de estado

O MCP é sem estado por design:

A garantia de ausência de dados do ciclista está documentada no PRIVACY.md do repositório de origem e é aplicada por um teste dedicado test_statelessness.py no conjunto de CI. A postura mais ampla de privacidade do aplicativo Your Trainer está na política de privacidade do Your Trainer.

Código-fonte e licença

Código aberto sob o LICENSE do repositório (veja no GitHub). Rastreamento de issues e discussão acontecem no repositório yourtrainer-mcp no GitHub. O endpoint hospedado é operado como bem público — não há SLA, mas o próprio MCP pode ser auto-hospedado (veja o deploy/README.md do repositório de origem) se você precisar de disponibilidade garantida.

Referências relacionadas