kit-one-tool-mcp

Modelo de clone-e-renomeação para um servidor MCP de ferramenta única: uma ferramenta com um esquema de entrada descrito, além de 15 testes offline cobrindo os caminhos de falha (chave ausente, 401, 403, 429, 503, falha de DNS, corpo não-JSON, resultado vazio). Executa sem chave de API e sem rede.

GitHubExperimente este MCPPatrocinado

Documentação

kit-one-tool-mcp

license MIT tests 15 offline api key not needed listed on glama 8 more servers wired $49

A maioria dos exemplos de MCP mostra o caminho feliz e depois falha no notebook de alguém com erro 401. Este é o oposto: uma ferramenta, um schema descrito e 15 testes que são, em sua maioria, os caminhos infelizes — chave ausente, 401, 403, 429, 503, falha de DNS, corpo não-JSON, resultado vazio.

Clone, renomeie THING, e você tem a forma de um servidor MCP funcional. É uma amostra do que um MCP Basic construído com Kit parece quando é entregue.

Se você veio aqui procurando um exemplo de MCP com uma ferramenta, um exemplo de servidor MCP em TypeScript, ou uma maneira de testar uma ferramenta MCP sem chave de API e sem rede, é isto aqui.

É deliberadamente uma ferramenta. Uma segunda ferramenta, ou um Cloudflare Worker, é um Build Packet, não uma versão maior disto.

Quer seu repositório configurado para Claude Code primeiro?

Este repositório é MIT e completo — pegue e use. Se você quiser um CLAUDE.md, uma lista de permissões de ferramentas e uma skill configurada para seu repositório:

Comprar Setup Lite — $29 · ~24h, devolvido como um PR.

Detalhes: kit.sdvsignal.com/#setup-lite · a mesma forma que este repositório, construída contra sua API, é MCP Basic $199.

Início em 60 segundos — sem chave de API, sem rede, sem Claude

git clone https://github.com/sdvsignal/kit-one-tool-mcp
cd kit-one-tool-mcp && npm install && npm test

Sem git? A mesma árvore versionada é enviada como um único arquivo em cada release: última release. Descompacte e depois o mesmo npm install && npm test.

15 testes, todos offline. Três deles levantam um cliente MCP real contra o servidor real por um transporte em memória e chamam a ferramenta, então a conexão é testada, não apenas a função. Se esses passarem, o servidor funciona — você ainda não precisou de uma chave.

Adicione ao Claude Code

Hoje, este é o que funciona. Clone primeiro, depois aponte o Claude Code para o arquivo local:

git clone https://github.com/sdvsignal/kit-one-tool-mcp
cd kit-one-tool-mcp && npm install
export THING_API_KEY=...
claude mcp add kit-one-tool -- node "$PWD/src/index.js"

Ou manualmente em .mcp.json, usando o caminho absoluto para onde você clonou:

{
  "mcpServers": {
    "kit-one-tool": {
      "command": "node",
      "args": ["/absolute/path/to/kit-one-tool-mcp/src/index.js"],
      "env": { "THING_API_KEY": "..." }
    }
  }
}

Quando estiver no npm

@sdvsignal/kit-one-tool-mcp ainda não foi publicado, então os dois comandos abaixo falharão com um 404 se você tentar hoje. Eles estão aqui para você saber como a instalação ficará, não para executar agora:

claude mcp add kit-one-tool-mcp -- npx -y @sdvsignal/kit-one-tool-mcp

{ "mcpServers": { "kit-one-tool-mcp": { "command": "npx", "args": ["-y", "@sdvsignal/kit-one-tool-mcp"] } } }

Nome do registro: io.github.sdvsignal/kit-one-tool-mcp (veja server.json).

Claude Desktop em vez disso: adicione isto ao arquivo de configuração e reinicie o aplicativo.

{
  "mcpServers": {
    "one-tool": {
      "command": "node",
      "args": ["/absolute/path/to/one-tool-mcp/src/index.js"],
      "env": { "THING_API_KEY": "..." }
    }
  }
}

Sua chave vive no seu ambiente. Não está neste repositório, e não há valor padrão que funcione silenciosamente.

Execute em um contêiner

A mesma ferramenta, o mesmo stdio, nada escutando em uma porta:

docker build -t one-tool-mcp .
docker run --rm -i -e THING_API_KEY=... one-tool-mcp

-i importa — o servidor fala por stdin/stdout, então sem ele não há nada com o que falar. Para apontar o Claude Desktop para a imagem em vez de para o node, use "command": "docker" com "args": ["run", "--rm", "-i", "-e", "THING_API_KEY", "one-tool-mcp"].

Prompt de teste rápido

Digite isto para o Claude. Este é o teste de que está realmente conectado:

Pesquise THING por "onboarding" e mostre-me os 3 principais.

Você deve obter até 3 resultados com nomes e ids. Se nada corresponder, você recebe No THINGs matched "onboarding", o que é correto e não uma falha. Dizer ao modelo que um resultado vazio é vazio é a maior parte do motivo pelo qual ele para de tentar novamente.

O que há aqui

ArquivoO que é
src/search-things.jsA ferramenta única. Recebe suas dependências como argumento, por isso é testável sem chave.
src/server.jsConexão do servidor. Registra exatamente uma ferramenta.
src/index.jsO ponto de entrada. Conecta stdio e nada mais.
test/Os 15 testes acima.
DockerfileConstrói a imagem acima. Copia o lockfile e src/, executa npm ci --omit=dev.

Erros que você pode ver

MensagemSignificado
THING_API_KEY is not setvariável de ambiente ausente, ou o Claude não foi reiniciado depois que você a definiu
THING rejected the key (401/403)chave errada ou revogada
THING rate limit hit (429)espere e tente novamente
THING returned 503problema do lado deles, não seu
Could not reach https://...rede, ou THING_BASE_URL está errado
THING returned something that was not JSONgeralmente uma página de erro HTML de um proxy

Nenhum deles retorna um stack trace. Uma ferramenta que lança erros brutos ao modelo faz com que ele adivinhe.

Remova

claude mcp remove one-tool

Claude Desktop: exclua o bloco one-tool e reinicie. O servidor não mantém estado, então nada fica para trás.

Tornando seu

  1. Renomeie search_things para o que realmente faz, do ponto de vista do chamador.
  2. Escreva o schema de entrada antes da implementação. Cada campo descrito, obrigatório vs opcional explícito.
  3. Mantenha a descrição voltada ao modelo: diga quando usar a ferramenta, não apenas o que ela é.
  4. Aponte THING_BASE_URL e o cabeçalho de autenticação para a API real.
  5. Execute npm test, depois execute o prompt de teste rápido no Claude. Um teste que passa não é prova de que a ferramenta funciona contra a API real.

Você não queria construir um, queria oito conectados

Metade das pessoas que chegam aqui de um diretório MCP não está construindo um servidor — elas querem os comuns conectados, e esbarram na mesma parede toda vez, que é o JSON em vez do servidor.

MCP Config Pack — $49 são oito configurações prontas (filesystem, GitHub, Postgres, context7 e mais quatro), cada uma com o prompt de teste rápido e a condição de aprovação que diz que está realmente conectado, em vez de apenas listado. Offline, sem telemetria, download instantâneo. Duas das oito não precisam de token algum, então você pode provar a conexão antes de chegar perto de uma credencial.

Detalhes e a lista completa: kit.sdvsignal.com/#mcp-config-pack. Se você preferir que elas sejam conectadas no seu repositório junto com hooks e skills, isso é Setup Sprint $99, não isto.

Grátis aqui vs. pago

Este repositório é MIT e completo — a ferramenta, os testes, a tabela de erros, o caminho de remoção. Nada é retido. Se você está construindo seu próprio servidor MCP, pegue e use.

Pago é a mesma forma construída contra sua API e testada contra ela antes da entrega, que é a parte que os testes offline acima deliberadamente não conseguem fazer: MCP Basic $199 — uma ferramenta, o schema, notas de entrega, um prompt de teste rápido e o caminho de ativar/desativar. Precisa de mais de uma ferramenta, ou um Worker? Build Packet $399. Só quer o repositório configurado para Claude Code primeiro? Setup Lite $29 (de volta como um PR em 24h) ou Setup Sprint $99 (48h). Só quer os servidores de outras pessoas conectados? MCP Config Pack $49, acima.

Enviando um aplicativo iOS por cima? Preview Pack $149 é um vídeo de preview da App Store no padrão da Apple, 5 imagens estáticas e 2 rodadas de revisão, em 72 horas.

→ Escopo e pedido: kit.sdvsignal.com

Usamos ferramentas de IA incluindo Claude; uma pessoa revisa cada entrega antes de ser enviada. Projeto independente, não afiliado à Anthropic.

Perguntas

Escrevendo sua primeira descrição de ferramenta, ou quer uma segunda leitura de uma? Cole em Discussions. Respostas reais, sem cadastro.

Relacionados

  • kit-claude-code-starter — a configuração completa do Claude Code (CLAUDE.md, allowlist, 3 skills), grátis
  • kit-plugins — as mesmas skills como plugins instaláveis do Claude Code
  • kit-ios-worker-template — verificação StoreKit 2 em um Cloudflare Worker, com registro de falhas

Licença

Licenciado sob MIT. Use para seu próprio trabalho, sem necessidade de atribuição.