Command Executor

Um servidor Model Context Protocol para executar comandos pré-aprovados com segurança.

🎥 Demonstração

https://github.com/user-attachments/assets/ed763a12-b685-4e0b-b9a5-bc948a590f51

✨ Recursos

• Execução segura de comandos com lista de comandos pré-aprovados
• Comandos permitidos configuráveis por meio de variáveis de ambiente
• Construído com TypeScript e MCP SDK
• Comunicação via stdio para integração perfeita
• Tratamento de erros e validações de segurança
• Transmissão de saída de comandos em tempo real

🚀 Instalação

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

⚙️ Configuração

🔒 Comandos Permitidos

Por padrão, os seguintes comandos são permitidos:

• git
• ls
• mkdir
• cd
• npm
• npx
• python

Você pode personalizar os comandos permitidos definindo a variável de ambiente ALLOWED_COMMANDS:

export ALLOWED_COMMANDS=git,ls,mkdir,python

🔌 Integração com Claude Desktop

Para usar com Claude Desktop, adicione a configuração do servidor:

No MacOS:

~/Library/Application Support/Claude/claude_desktop_config.json

No Windows:

%APPDATA%/Claude/claude_desktop_config.json

Exemplo de configuração:

{
  "mcpServers": {
    "command-executor": {
      "command": "/path/to/command-executor/build/index.js"
    }
  }
}

🛡️ Considerações de Segurança

O servidor command-executor implementa várias medidas de segurança:

1. Lista de Comandos Pré-aprovados

   • Somente comandos explicitamente permitidos podem ser executados
   • A lista padrão é restritiva e focada em segurança
   • Os comandos são validados por prefixo para prevenir injeção

2. Validação de Comandos

   • A validação de prefixo de comando previne injeção de comandos
   • Sem execução de shell para maior segurança
   • As variáveis de ambiente são devidamente sanitizadas

3. Tratamento de Erros

   • Tratamento abrangente de erros para comandos não autorizados
   • Mensagens de erro claras para depuração
   • Comandos com falha não derrubam o servidor

4. Isolamento de Ambiente

   • O servidor executa em seu próprio ambiente
   • As variáveis de ambiente podem ser controladas
   • Acesso limitado ao sistema

💻 Desenvolvimento

📁 Estrutura do Projeto

command-executor/
├─ src/
│  └─ index.ts      # Main server implementation
├─ build/
│  └─ index.js      # Compiled JavaScript
├─ assets/
│  └─ header.svg    # Project header image
└─ package.json     # Project configuration

🐛 Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector:

npm run inspector

O Inspector fornecerá uma URL para acessar ferramentas de depuração no seu navegador.

🛠️ API de Ferramentas

O servidor fornece uma única ferramenta:

execute_command

Executa um comando pré-aprovado.

Parâmetros:

• command (string, obrigatório): O comando a ser executado

Exemplo de Requisição:

{
  "name": "execute_command",
  "arguments": {
    "command": "git status"
  }
}

Exemplo de Resposta:

{
  "content": [
    {
      "type": "text",
      "text": "On branch main\nNothing to commit, working tree clean"
    }
  ]
}

Resposta de Erro:

{
  "content": [
    {
      "type": "text",
      "text": "Command execution failed: Command not allowed"
    }
  ],
  "isError": true
}

❌ Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para vários cenários:

1. Comandos Não Autorizados

   {
     "code": "InvalidParams",
     "message": "Command not allowed: [command]. Allowed commands: git, ls, mkdir, cd, npm, npx, python"
   }
   

2. Falhas de Execução

   {
     "content": [
       {
         "type": "text",
         "text": "Command execution failed: [error message]"
       }
     ],
     "isError": true
   }
   

🤝 Contribuindo

1. Faça um fork do repositório
2. Crie sua branch de funcionalidade
3. Faça commit das suas alterações
4. Envie para a branch
5. Crie um novo Pull Request

📄 Licença

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