MCPShell

MCPShell

MCPShell es una herramienta que permite a los LLMs ejecutar de forma segura herramientas de línea de comandos a través del Protocolo de Contexto de Modelo (MCP). Proporciona un puente seguro entre los LLMs y los comandos del sistema operativo.

Características

• Ejecución flexible de comandos: Ejecuta cualquier comando de shell como herramientas MCP, con sustitución de parámetros mediante plantillas.
• Definiciones de herramientas basadas en configuración: Define herramientas en YAML con parámetros, restricciones y formato de salida.
• Seguridad mediante restricciones: Valida los parámetros de las herramientas usando expresiones CEL antes de la ejecución, así como entornos sandbox opcionales para ejecutar comandos.
• Prototipado rápido de herramientas MCP: solo añade algo de código shell y úsalo como herramienta MCP en tu LLM.
• Integración sencilla: Funciona con cualquier cliente LLM que soporte el protocolo MCP (por ejemplo, Cursor, VSCode, Witsy...)

Inicio Rápido

Imagina que quieres que Cursor (o algún otro cliente MCP) te ayude con tus problemas de espacio en tu disco duro.

1. Crea un archivo de configuración /my/example.yaml que defina tus herramientas:

   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):
   

   Echa un vistazo al directorio de ejemplos para ver ejemplos más sofisticados y útiles. ¿Quizás prefieres que el LLM conozca tu clúster de Kubernetes con kubectl? ¿O que ejecute algunos comandos de AWS CLI?

2. Configura el servidor MCP en Cursor (o en cualquier otro cliente LLM con soporte para MCP)

   Por ejemplo, para Cursor, crea .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"
               ]
           }
       }
   }
   

   También puedes usar rutas relativas y omitir la extensión .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"
               ]
           }
       }
   }
   

   Esto buscará example.yaml en el directorio de herramientas (~/.mcpshell/tools/ por defecto).

   Consulta más detalles sobre cómo configurar Cursor o Visual Studio Code. Otros LLMs con soporte para MCPs deberían configurarse de manera similar.

3. Asegúrate de que tu cliente MCP esté actualizado (Cursor debería reconocerlo automáticamente la primera vez, pero cualquier cambio en el archivo de configuración requerirá una actualización).

4. Haz a tu LLM algunas preguntas que debería poder responder con la nueva herramienta. Por ejemplo: "Me estoy quedando sin espacio en mi disco duro. ¿Podrías ayudarme a encontrar el problema?".

Uso y Configuración

Echa un vistazo a todos los comandos en este documento.

Los archivos de configuración usan un formato YAML definido aquí. Consulta este directorio para ver algunos ejemplos.

Para desplegar MCPShell en contenedores y Kubernetes, consulta la Guía de Despliegue en Contenedores.

Modo Agente

Para funcionalidad de agente de IA que conecta LLMs directamente a herramientas, consulta el proyecto Don. Don proporciona:

• Conectividad directa con LLMs sin requerir un cliente MCP separado
• Soporte RAG (Generación Aumentada por Recuperación)
• Arquitectura multi-agente
• Usa el formato de configuración de herramientas de MCPShell

Consideraciones de Seguridad

Así que probablemente pensarás "esta IA me ha ayudado a encontrar todos esos archivos grandes. ¿Qué tal si creo otra herramienta para eliminar archivos?". ¡No hagas eso!.

• Limita el alcance de estas herramientas a acciones de solo lectura, no le des al LLM el poder de cambiar cosas.
• Usa restricciones para limitar la ejecución de comandos a parámetros seguros
• Considera usar un entorno sandbox para ejecutar comandos.
• Revisa todas las plantillas de comandos para detectar posibles vulnerabilidades de inyección
• Solo expón herramientas que sean seguras para uso externo
• ¡Todo lo anterior!

Por favor, lee el documento de Consideraciones de Seguridad antes de usar este software.

Contribuciones

¡Las contribuciones son bienvenidas! Echa un vistazo a la guía de desarrollo. Por favor, abre un issue o envía un pull request en GitHub.

Licencia

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