Command Executor

Un servidor de Model Context Protocol para ejecutar comandos preaprobados de forma segura.

🎥 Demo

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

✨ Características

• Ejecución segura de comandos con lista de comandos preaprobados
• Comandos permitidos configurables mediante variables de entorno
• Construido con TypeScript y MCP SDK
• Comunicación a través de stdio para una integración perfecta
• Manejo de errores y validaciones de seguridad
• Transmisión de salida de comandos en tiempo real

🚀 Instalación

Instalar dependencias:

npm install

Compilar el servidor:

npm run build

Para desarrollo con reconstrucción automática:

npm run watch

⚙️ Configuración

🔒 Comandos Permitidos

Por defecto, se permiten los siguientes comandos:

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

Puedes personalizar los comandos permitidos estableciendo la variable de entorno ALLOWED_COMMANDS:

export ALLOWED_COMMANDS=git,ls,mkdir,python

🔌 Integración con Claude Desktop

Para usar con Claude Desktop, añade la configuración del servidor:

En MacOS:

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

En Windows:

%APPDATA%/Claude/claude_desktop_config.json

Ejemplo de configuración:

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

🛡️ Consideraciones de Seguridad

El servidor command-executor implementa varias medidas de seguridad:

1. Lista de Comandos Preaprobados

   • Solo se pueden ejecutar comandos explícitamente permitidos
   • La lista predeterminada es restrictiva y centrada en la seguridad
   • Los comandos se validan por prefijo para prevenir inyecciones

2. Validación de Comandos

   • La validación del prefijo del comando previene la inyección de comandos
   • Sin ejecución de shell para mayor seguridad
   • Las variables de entorno se sanean adecuadamente

3. Manejo de Errores

   • Manejo integral de errores para comandos no autorizados
   • Mensajes de error claros para depuración
   • Los comandos fallidos no bloquean el servidor

4. Aislamiento del Entorno

   • El servidor se ejecuta en su propio entorno
   • Las variables de entorno se pueden controlar
   • Acceso limitado al sistema

💻 Desarrollo

📁 Estructura del Proyecto

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

🐛 Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser desafiante. Recomendamos usar el MCP Inspector:

npm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en tu navegador.

🛠️ API de Herramientas

El servidor proporciona una única herramienta:

execute_command

Ejecuta un comando preaprobado.

Parámetros:

• command (string, obligatorio): El comando a ejecutar

Ejemplo de Solicitud:

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

Ejemplo de Respuesta:

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

Respuesta de Error:

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

❌ Manejo de Errores

El servidor proporciona mensajes de error detallados para varios escenarios:

1. Comandos No Autorizados

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

2. Fallos de Ejecución

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

🤝 Contribuciones

1. Haz un fork del repositorio
2. Crea tu rama de características
3. Haz commit de tus cambios
4. Haz push a la rama
5. Crea una nueva Pull Request

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.