O servidor embutido
mycli mcp conecta um McpServer ao transporte stdio. A partir daí, stdout
pertence ao JSON-RPC e qualquer diagnóstico vai para stderr. O processo só
termina quando o cliente fecha o transporte.
Configuração em um cliente:
{ "mcpServers": { "mycli": { "command": "mycli", "args": ["mcp"] } } }No Claude Code: claude mcp add mycli -- mycli mcp. Em desenvolvimento,
sem compilar: "command": "bun", "args": ["run", "src/main.ts", "mcp"].
O que o starter kit expõe
| Tipo | Nome | Função |
|---|---|---|
| tool | doctor |
{ checks, ok } do diagnóstico, sem gravar arquivos |
| tool | about |
identidade, runtime, plataforma, pasta de dados, créditos |
| tool | exit_codes |
tabela de códigos de saída |
| tool | skill |
documentação embutida, inteira ou por tópico |
| tool | config_list |
chaves de settings.json em vigor e o esquema |
| tool | config_get |
valor de uma chave |
| tool | credentials_status |
arquivo, origem da chave mestra, quantidade e nomes |
| resource | mycli://about |
identidade em JSON |
| resource | mycli://exit-codes |
códigos em JSON |
| resource | mycli://skill |
documentação completa |
| resource | mycli://skill/{topic} |
uma seção, o template lista os tópicos |
| prompt | operate |
instrui o agente a ler skill cli e cumprir uma tarefa pelo CLI com --json |
Nenhuma tool devolve o valor de uma credencial e nenhuma grava. Escrita
continua no CLI. A confirmação depende do comando: credentials clear
pede confirmação, enquanto config set e credentials rotate-key não.
mycli mcp --list enumera tudo sem abrir o transporte. O servidor mantém um
catálogo durante o registro, então a lista e o que o cliente vê são
iguais.
Regras para tools
- Nome em
snake_case,<grupo>_<acao>. title,descriptionque diz quando usar e o que devolve,inputSchemaem Zod com.describe()em cada campo.- Para saída estruturada, use
contentem texto estructuredContentcom o mesmo objeto. A toolskilldevolve apenas texto Markdown. Falha prevista devolveisError: truecom a ação sugerida. - Tools que gravam ou chamam rede dizem isso na descrição.
- Respostas curtas. Paginação por
limitecursorquando a lista cresce. - Tools que consomem APIs leem o token com
getCredential(name)internamente.
Economia de tokens
O OpenMCP, padrão para converter APIs web em servidores MCP, formaliza algo
que vale para qualquer servidor: o agente lê todas as descrições de tool a
cada conversa, então cada palavra a mais custa em todas as chamadas. O
Termfy aplica isso com uma tool de descoberta (skill) em vez de dezenas de
tools de documentação, descrições de duas frases e resources para consultar
conteúdo sem executar ações.
Adicionar uma tool
- Copie
template/tool/example.tsparasrc/mcp/tools/<grupo>.ts. - Implemente reutilizando funções de
src/config/e coletores do CLI. - Acrescente ao
catalog.toolse registre emregisterAll(src/mcp/server.ts). - Teste em
tests/mcp.test.ts, que sobe o binário e conversa peloClientdo SDK. Para testar à mão, usenpx @modelcontextprotocol/inspector bun run src/main.ts mcp. - Atualize a tabela em
docs/mcp.md.
A skill termfy-mcp traz o contrato de tool, o guia de testes e a
documentação do SDK e da especificação MCP em references/.