create-connector

Criar um conector MCP remoto

Constrói um servidor MCP Streamable-HTTP stateless (TypeScript, @modelcontextprotocol/sdk) que funciona como um conector personalizado do claude.ai, opcionalmente com cartões visuais inline (MCP Apps), e o implanta na Vercel. Comprovado em um projeto real com mais de 30 ferramentas.

Os templates estão em templates/ ao lado deste arquivo. Notas mais detalhadas estão em references/; leia-as apenas quando a etapa precisar:

• references/mcp-apps-cards.md — cartões inline: recurso ui://, protocolo postMessage, CSP, listas clicáveis
• references/deploy-vercel.md — configuração da Vercel, implantação, readição do conector no claude.ai
• references/gotchas.md — armadilhas que custam tempo real (leia antes de depurar)

Fluxo de Trabalho

1. Esclareça (pergunte apenas o que não puder inferir): quais dados/API, somente leitura ou gravação, precisa de autenticação ou não, quer cartões ou apenas texto. Padrão: dados públicos, somente leitura, sem autenticação, texto + cartões.
2. Teste cada API upstream antes de escrever código. Use curl em cada endpoint: status, formato da resposta, formatos de data, limites de taxa, timeouts, redirecionamentos (um 301 significa que a URL mudou, por exemplo, api.frankfurter.dev, não .app). Endpoints públicos SPARQL/busca podem ser lentos: meça o tempo, mantenha as consultas simples, filtre no código.
3. Gere o esqueleto a partir de templates/ (copie package.json, tsconfig.json, vercel.json, api/, src/, scripts/), renomeie my-connector, execute npm install.
4. Escreva as ferramentas em src/server.ts (um registerTool para cada uma). Regras abaixo.
5. Adicione cada ferramenta a scripts/test-client.ts. O executor falha em ferramentas não testadas, saída vazia e isError.
6. Verifique localmente: npm run typecheck, inicie PORT=<porta nova> npm run dev, confirme que o log mostra "listening" (não EADDRINUSE), depois npm test -- http://localhost:<porta>/mcp. Objetivo: Untested tools: none. Problems: 0.
7. Documente: tabela de ferramentas no README (uma linha por ferramenta), CONTRIBUTING, LICENSE.
8. Faça commit, push e implante apenas com a autorização do usuário (consulte references/deploy-vercel.md), depois execute o teste contra a URL ativa.
9. Diga ao usuário para remover e readicionar o conector no claude.ai (ele armazena em cache a lista de ferramentas) e forneça de 3 a 5 prompts de teste curtos.

Regras de design de ferramentas

• Poucas ferramentas, que realmente funcionem. Nomes são verbos em snake_case: search_x, get_x, list_x.
• Esquema Zod com limites em cada entrada (min/max, default); descreva cada campo com um exemplo.
• A descrição diz o que ela retorna e quando usá-la, em uma ou duas frases. O modelo a lê para escolher a ferramenta.
• Anotações: readOnlyHint: true, idempotentHint: true, destructiveHint: false, mais openWorldHint: true para APIs externas.
• Envolva cada manipulador em safe(...): falhas upstream tornam-se resultados isError com uma mensagem legível, nunca uma falha.
• Nomeie a fonte de dados em cada resultado. Informe quando os dados são editados pela comunidade ou provisórios.
• Nunca falhe em campos ausentes; recorra a "desconhecido".
• Tolerância a erros de digitação: em caso de nenhuma correspondência, retorne sugestões "você quis dizer" em vez de um resultado vazio.
• Armazene em cache chamadas upstream (o template getJson/getText possui TTL, deduplicação em andamento, cache curto para falhas, timeout). Use TTLs curtos (minutos) para dados ativos, horas para dados estáticos. Seja gentil com APIs gratuitas.
• Retorne tanto texto (para o modelo) quanto structuredContent (para o cartão) por meio de um auxiliar como card(texto, dados).
• Sem segredos no repositório. Se uma chave for necessária, leia-a de process.env e documente-a.
• Filtre trabalho pesado no código, não na consulta upstream, quando o upstream for lento.

Servidor Stateless (amigável à Vercel)

Um novo McpServer e transporte são criados por requisição (src/handler.ts); sem sessões, sem memória entre requisições. O único estado é o cache em memória, que é de melhor esforço. CORS e um limite de tamanho de corpo estão no manipulador. api/mcp.ts exporta { fetch } e maxDuration: 30; vercel.json reescreve /mcp para /api/mcp.

Cartões (MCP Apps), versão resumida

Registre um recurso HTML ui://… (mimeType: text/html;profile=mcp-app), então dê a cada ferramenta _meta: { ui: { resourceUri }, "ui/resourceUri": resourceUri } e retorne structuredContent com um campo kind. O HTML é um único arquivo autocontido que renderiza por kind. Consulte references/mcp-apps-cards.md e templates/src/view.ts.

Saída para o usuário

Seja conciso. Relate: o que foi construído (lista de ferramentas), resultado do teste, URL e as etapas exatas para atualizar o conector. Declare as ressalvas honestamente (caminhos de UI não verificados, upstreams lentos, dados da comunidade).