My Next Adventure

npx add-mcp 'https://mcp.mynextadventure.cloud/mcp'

Servidor MCP MyNextAdventure

Um servidor remoto Model Context Protocol que permite a um assistente de IA planejar viagens no MyNextAdventure — criar uma viagem, montar o itinerário, propor voos e hotéis, adicionar atividades e compartilhar o resultado.

Ele roda como um Cloudflare Worker sem estado e é um proxy autenticado e enxuto na frente da API pública do MyNextAdventure: não armazena dados de viagem próprios e encaminha cada chamada para a API usando a chave de API do próprio chamador.

• Produção: https://mcp.mynextadventure.cloud/mcp (HTTP Streamable)
• API upstream: https://api.mynextadventure.cloud (API pública v1)

Autenticação

Toda requisição precisa de uma chave de API do MyNextAdventure. Crie uma no aplicativo em Configurações → Chaves de API e envie-a de uma das seguintes formas:

• Authorization: Bearer <api-key> — o que a maioria dos clientes MCP envia, e o que mcp-remote faz, ou
• X-API-Key: <api-key> — para clientes que só permitem definir cabeçalhos personalizados.

O worker a encaminha para a API como X-API-Key. Requisições sem chave recebem um 401. Tudo o que a chave pode fazer, o assistente pode fazer: as chaves são por usuário, então o assistente só vê as viagens daquele usuário.

Onde sua chave fica. O servidor não tem estado: sua chave é lida dos cabeçalhos de cada requisição, usada para fazer aquela única chamada à API do MyNextAdventure e nunca é armazenada — não há armazenamento de sessão nem Durable Object retendo-a entre requisições. Ela nunca é registrada em logs e não é compartilhada entre requisições ou usuários. Revogue uma chave a qualquer momento no aplicativo em Configurações → Chaves de API.

Ferramentas

24 ferramentas, cobrindo as operações que o planejamento conversacional realmente precisa. Cada uma é uma visão selecionada de uma operação da API do MyNextAdventure — veja Regenerando as ferramentas.

Ferramenta	O que faz
whoami	Qual conta a chave de API pertence (útil para verificar a conexão).
list_trips	Lista as viagens do usuário; filtra por status (planning, ready, finished, cancelled).
get_trip	Uma viagem completa — variantes, destinos, opções, eventos. Necessário antes de qualquer edição.
create_trip	Cria uma nova viagem vazia.
update_trip	Renomeia, define uma foto de capa ou move a viagem pelo seu ciclo de vida.
create_trip_share_link	Cria/atualiza um link público de compartilhamento somente leitura.
create_variant	Adiciona um plano alternativo (as datas ficam aqui: exatas ou flexíveis).
duplicate_variant	Copia uma variante com tudo o que ela contém.
update_variant	Renomeia uma variante, altera suas datas ou notas.
select_variant	Marca uma variante como o plano escolhido.
add_destination	Adiciona uma parada a uma variante, na ordem do itinerário.
update_destination	Altera o nome do lugar, as datas ou as notas de uma parada.
reorder_destinations	Reordena as paradas em uma variante.
add_accommodation_option	Propõe um lugar para ficar em um destino.
add_transport_option	Propõe uma forma de chegar a um destino.
add_getting_around_option	Propõe mobilidade local (transporte público, carro alugado, …).
update_destination_option	Edita uma opção existente de qualquer um dos três tipos.
select_destination_option	Seleciona — ou, sem um optionId, desmarca — uma opção.
add_event	Adiciona uma atividade (museu, show, restaurante, passeio) a uma variante.
update_event	Edita uma atividade.
toggle_event	Alterna uma atividade entre confirmada e "apenas uma ideia".
delete_trip_item	Exclui permanentemente uma variante, destino, opção ou evento. Excluir uma variante inteira adicionalmente requer confirm: true.
list_goals	Lista as metas de viagem / lista de desejos do usuário.
add_goal	Adiciona uma meta a partir de um nome ou URL.

O servidor também inclui instructions do MCP descrevendo o modelo de dados (trip → variants → destinations → options, com eventos na variante) e a ordem usual de operações, para que um cliente não precise adivinhar o fluxo de trabalho.

Ainda não expostas, embora a API as suporte: gerenciamento de acesso de colaboradores e convites, votação, coleções, tokens de convite, vinculação meta↔viagem, gerenciamento de chaves de API e exclusão de viagens.

Conectando

Claude Desktop

Configurações → Desenvolvedor → Editar configuração e adicione:

{
  "mcpServers": {
    "mynextadventure": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.mynextadventure.cloud/mcp",
        "--header",
        "Authorization: Bearer ${MNA_API_KEY}"
      ],
      "env": { "MNA_API_KEY": "your-api-key" }
    }
  }
}

Reinicie o Claude Desktop; as ferramentas aparecem no conector.

claude.ai / Claude Code

Adicione um conector personalizado apontando para https://mcp.mynextadventure.cloud/mcp e defina o cabeçalho Authorization: Bearer <api-key>. Pelo Claude Code:

claude mcp add --transport http mynextadventure https://mcp.mynextadventure.cloud/mcp \
  --header "Authorization: Bearer <api-key>"

ChatGPT

Configurações → Conectores → Adicionar conector personalizado, URL do servidor MCP https://mcp.mynextadventure.cloud/mcp, autenticação "cabeçalho personalizado" com X-API-Key: <api-key> (ou Authorization: Bearer <api-key>).

Qualquer outro cliente MCP

HTTP Streamable em /mcp. GET / retorna um pequeno documento JSON de saúde com o endpoint e a contagem de ferramentas.

Desenvolvimento

npm install
npm run dev              # wrangler dev on http://localhost:8787
npm test                 # vitest: request building, schemas, generator freshness
npm run type-check       # tsc --noEmit
npm run generate:tools   # regenerate src/generated/tools.ts from the OpenAPI spec
npx tsx scripts/smoke.ts # drive the MCP protocol against localhost:8787

scripts/smoke.ts realiza um handshake real (initialize → tools/list → um tools/call), lendo a chave de API de $MNA_API_KEY ou ~/.config/mna/credentials. Ele se recusa a chamar ferramentas de mutação a menos que --force seja passado. Para exercitar ferramentas de escrita sem tocar em dados reais, aponte o worker para um mock local:

npx wrangler dev --var MNA_API_BASE_URL:http://localhost:8899

Regenerando as ferramentas

Os esquemas das ferramentas são gerados, não escritos à mão:

apps/server/openapi-v1.json   (the API's OpenAPI snapshot, kept fresh by server CI)
        +
scripts/tool-manifest.ts      (which operations become tools, their names and descriptions)
        ↓  scripts/generator.ts
src/generated/tools.ts        (committed; zod input schemas + request builders)

Para adicionar ou alterar uma ferramenta, edite scripts/tool-manifest.ts e execute npm run generate:tools. Nunca edite src/generated/tools.ts manualmente — um teste falha se ele se desviar da especificação.

Uma entrada de manifesto nomeia uma operação da API ou agrupa várias operações sem corpo atrás de um argumento discriminador (delete_trip_item's target, select_destination_option's action) para manter o número de ferramentas baixo. Parâmetros de caminho podem ser renomeados (id → tripId), parâmetros de consulta podem ser restritos a enums e descrições podem ser substituídas — todo o resto, incluindo os esquemas do corpo da requisição, vem da especificação.

Implantação

npm run deploy (wrangler) — somente produção, então é restrito a um mantenedor; CI nunca implanta este worker.

Desenvolvimento

npm ci
npm run type-check
npm test        # includes a drift test: src/generated/tools.ts must match the generator output
npm run dev     # wrangler dev

As ferramentas são geradas a partir do snapshot OpenAPI fornecido em spec/openapi-v1.json (especificação canônica ao vivo: https://api.mynextadventure.cloud/api/v1/openapi.json) via scripts/generate-tools.ts. Regere após atualizar o snapshot.

Este repositório é a fonte implantável para mcp.mynextadventure.cloud. O desenvolvimento também acontece no monorepo My Next Adventure e é sincronizado aqui no lançamento. Issues e PRs são bem-vindos.

Licença

MIT