mcp-cli-catalog

mcp-cli-catalog

Um servidor MCP que publica as ferramentas de CLI da sua máquina. Agentes de codificação já têm acesso ao shell e são ótimos em gerar comandos complexos com pipes e filtros. Isso apenas informa a eles o que está disponível para que possam usar as ferramentas MCP de forma mais eficiente.

Por quê

• Agentes de codificação com LLM podem efetivamente encadear comandos de shell com pipes para filtrar e reformatar dados complexos.
• Declarar ferramentas de CLI como ferramentas MCP as torna descobríveis para o LLM.

Como Funciona

• Este servidor expõe suas ferramentas de CLI como definições de ferramentas MCP para que o LLM saiba o que está disponível.
• As ferramentas MCP definidas no catálogo apenas instruem o LLM a usar o shell; elas não executam nenhuma ferramenta por conta própria.
• O acesso ao shell é necessário para que o agente realmente execute os comandos.

Instalação

Adicione o servidor à sua configuração MCP (ex.: para Claude Code):

{
  "mcpServers": {
    "cli-catalog": {
      "command": "npx",
      "args": ["mcp-cli-catalog"]
    }
  }
}

Ou com um caminho de catálogo personalizado:

{
  "mcpServers": {
    "cli-catalog": {
      "command": "npx",
      "args": ["mcp-cli-catalog", "--config", "./tools.json"]
    }
  }
}

Configurar Ferramentas

Adicione um arquivo de catálogo JSON (padrão: ~/.mcp-cli-catalog.json) com as ferramentas de CLI que você deseja tornar descobríveis:

{
  // JSON Comments are allowed.
  "tools": [
    {
      "name": "knowledge-base-search",
      "description": "Search full text across the knowledge base",
      "usage": "knowledge-base-search 'pattern' | head"
    },
    {
      "name": "knowledge-base-get",
      "description": "Get a knowledge base file",
      "usage": "knowledge-base-get path/to/file.md | sed -n '100,200p'\nknowledge-base-get path/to/file.md | rg 'TODO'"
    }
  ]
}

• name e description são obrigatórios.
• usage (opcional) aparece como uma dica nas respostas.
• command (opcional) é a string exata a ser executada. Se você pular, a ferramenta name é usada.
• Aponte para um catálogo diferente com --config <path> ou MCP_CLI_CATALOG_FILE=<path>.

Teste

Teste sua configuração do servidor com o MCP Inspector:

npx @modelcontextprotocol/inspector npx mcp-cli-catalog

Ou com um catálogo personalizado:

npx @modelcontextprotocol/inspector npx mcp-cli-catalog --config ./tools.json

Desenvolvimento

• npm run dev: execute diretamente de src/index.js
• npm run build: compile para dist/index.js e corrija as permissões
• npm start: execute o servidor compilado a partir de dist/index.js

Abordagens alternativas

O "Code Mode" da Cloudflare¹ e o post sobre execução de código com MCP da Anthropic² exploram uma maneira diferente de resolver desafios de ferramentas MCP. A abordagem deles fornece ferramentas MCP por meio de um SDK para o LLM, que escreve código para chamar e processar essas ferramentas. Este projeto segue um caminho mais simples: construir ferramentas de CLI e torná-las descobríveis por meio do catálogo de ferramentas MCP.

---

1. Cloudflare, "Code Mode," 2025.
2. Anthropic, "Code execution with MCP," 2025.