MCPShell

MCPShell

O MCPShell é uma ferramenta que permite que LLMs executem com segurança ferramentas de linha de comando através do Model Context Protocol (MCP). Ele fornece uma ponte segura entre LLMs e comandos do sistema operacional.

Recursos

• Execução flexível de comandos: Execute quaisquer comandos shell como ferramentas MCP, com substituição de parâmetros por meio de templates.
• Definições de ferramentas baseadas em configuração: Defina ferramentas em YAML com parâmetros, restrições e formatação de saída.
• Segurança por meio de restrições: Valide os parâmetros das ferramentas usando expressões CEL antes da execução, bem como ambientes isolados (sandbox) opcionais para executar comandos.
• Prototipagem rápida de ferramentas MCP: basta adicionar algum código shell e usá-lo como uma ferramenta MCP no seu LLM.
• Integração simples: Funciona com qualquer cliente LLM que suporte o protocolo MCP (ex.: Cursor, VSCode, Witsy...)

Início Rápido

Imagine que você quer que o Cursor (ou algum outro cliente MCP) ajude você com seus problemas de espaço no seu disco rígido.

1. Crie um arquivo de configuração /my/example.yaml definindo suas ferramentas:

   mcp:
     description: |
       Tool for analyzing disk usage to help identify what's consuming space.
     run:
       shell: bash
     tools:
       - name: "disk_usage"
         description: "Check disk usage for a directory"
         params:
           directory:
             type: string
             description: "Directory to analyze"
             required: true
           max_depth:
             type: number
             description: "Maximum depth to analyze (1-3)"
             default: 2
         constraints:
           - "directory.startsWith('/')"  # Must be absolute path
           - "!directory.contains('..')"  # Prevent directory traversal
           - "max_depth >= 1 && max_depth <= 3"  # Limit recursion depth
           - "directory.matches('^[\\w\\s./\\-_]+$')"  # Only allow safe path characters, prevent command injection
         run:
           command: |
             du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
         output:
           prefix: |
             Disk Usage Analysis (Top 20 largest directories):
   

   Dê uma olhada no diretório de exemplos para exemplos mais sofisticados e úteis. Talvez você prefira deixar o LLM conhecer seu cluster Kubernetes com o kubectl? Ou deixá-lo executar alguns comandos do AWS CLI?

2. Configure o servidor MCP no Cursor (ou em qualquer outro cliente LLM com suporte a MCP)

   Por exemplo, para o Cursor, crie .cursor/mcp.json:

   {
       // you need the "go" command available
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/MCPShell@v0.1.8",
                  "mcp", "--tools", "/my/example.yaml",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   Você também pode usar caminhos relativos e omitir a extensão .yaml:

   {
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/MCPShell@v0.1.8",
                  "mcp", "--tools", "example",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   Isso procurará por example.yaml no diretório de ferramentas (~/.mcpshell/tools/ por padrão).

   Veja mais detalhes sobre como configurar o Cursor ou o Visual Studio Code. Outros LLMs com suporte a MCPs devem ser configurados de maneira semelhante.

3. Certifique-se de que seu cliente MCP foi atualizado (o Cursor deve reconhecê-lo automaticamente na primeira vez, mas qualquer alteração no arquivo de configuração exigirá uma atualização).

4. Faça ao seu LLM algumas perguntas que ele deve ser capaz de responder com a nova ferramenta. Por exemplo: "Estou ficando sem espaço no meu disco rígido. Você poderia me ajudar a encontrar o problema?".

Uso e Configuração

Veja todos os comandos neste documento.

Os arquivos de configuração usam um formato YAML definido aqui. Veja este diretório para alguns exemplos.

Para implantar o MCPShell em contêineres e Kubernetes, consulte o Guia de Implantação em Contêineres.

Modo Agente

Para funcionalidade de agente de IA que conecta LLMs diretamente às ferramentas, consulte o projeto Don. O Don oferece:

• Conectividade direta com LLMs sem exigir um cliente MCP separado
• Suporte a RAG (Geração Aumentada por Recuperação)
• Arquitetura multiagente
• Usa o formato de configuração de ferramentas do MCPShell

Considerações de Segurança

Então você provavelmente vai pensar "essa IA me ajudou a encontrar todos aqueles arquivos grandes. E se eu criar outra ferramenta para remover arquivos?". Não faça isso!.

• Limite o escopo dessas ferramentas a ações somente leitura, não dê ao LLM o poder de alterar coisas.
• Use restrições para limitar a execução de comandos a parâmetros seguros.
• Considere usar um ambiente isolado (sandbox) para executar comandos.
• Revise todos os templates de comandos em busca de possíveis vulnerabilidades de injeção.
• Exponha apenas ferramentas que sejam seguras para uso externo.
• Tudo isso e mais!

Leia o documento de Considerações de Segurança antes de usar este software.

Contribuindo

Contribuições são bem-vindas! Consulte o guia de desenvolvimento. Abra uma issue ou envie um pull request no GitHub.

Licença

Este projeto está licenciado sob a Licença MIT — consulte o arquivo LICENSE para mais detalhes.