AgentExecMCP

Un servidor seguro basado en Docker que proporciona capacidades de ejecución centrales para agentes de IA.

Documentación

AgentExecMCP

Un servidor FastMCP que proporciona capacidades de ejecución centrales para agentes de IA, empaquetado en Docker para una implementación segura y sencilla.

⚡ Inicio Rápido

Ponte en marcha en 2 minutos: consulta QUICKSTART.md.

📋 Tabla de Contenidos

Inicio Rápido
Características
Comandos Make
Integración con Claude Desktop
Integración con Cursor
- Configuración Manual
Herramientas MCP
Ejemplos de Conexión de Clientes
Características de Seguridad
Entorno
Soporte del Protocolo MCP
Desarrollo
Pruebas
Requisitos
Casos de Uso
Licencia

🚀 Características

Ejecución de Shell: Ejecuta comandos bash con controles de tiempo de espera y seguridad
Ejecución de Código en Múltiples Lenguajes: Soporte para Python, Node.js y Go con ejecución optimizada
Gestión de Paquetes: Instala paquetes mediante pip, npm y módulos de Go
Múltiples Transportes: stdio y SSE
Implementación con Docker: Contenerizado para un entorno de ejecución consistente
Protocolo MCP: Protocolo de Contexto de Modelo conforme a estándares
Controles de Seguridad: Ejecución sin privilegios de root, tiempos de espera, límites de concurrencia
Integración con Claude Desktop: Funciona perfectamente con Claude Desktop mediante transporte SSE
Optimización de Go: Ejecución de código Go con CGO_ENABLED=0 para una mejor compatibilidad

🛠️ Comandos Make

AgentExecMCP incluye un Makefile completo que facilita enormemente la configuración y gestión. Todos los comandos están diseñados para ser fáciles de usar tanto para usuarios técnicos como no técnicos.

Comandos de Inicio Rápido

make help                # Show all available commands with descriptions
make quick-start         # Build and run with SSE transport (recommended)

Comandos Principales

make build              # Build the Docker container
make run                # Run with STDIO transport (interactive)
make run-sse            # Run with SSE transport (for Claude Desktop)

Comandos de Gestión

make status             # Show container status
make logs               # Show container logs (follows log output)
make health             # Check if server is responding
make stop               # Stop all running containers
make shell              # Open shell in running container

Comandos de Desarrollo

make lint               # Run ruff linter and formatter

Comandos de Mantenimiento

make test               # Test basic functionality
make clean              # Remove containers and images
make workspace          # Create workspace directory

Flujo de Trabajo de Ejemplo

# First time setup
make quick-start                    # Builds and starts everything
make install-claude-config          # Sets up Claude Desktop

# Daily usage
make status                         # Check if running
make logs                          # View output
make stop                          # Stop when done

# Troubleshooting
make clean                         # Clean everything
make quick-start                   # Fresh start

🖥️ Integración con Claude Desktop

AgentExecMCP funciona perfectamente con Claude Desktop utilizando el transporte SSE. Esto es ideal para el desarrollo y las pruebas locales.

Configuración Fácil con Make (Recomendado)

Configuración súper sencilla en 3 pasos:

Inicia AgentExecMCP:
```
make quick-start
```
Instala la configuración de Claude Desktop:
```
make install-claude-config
```
Reinicia Claude Desktop y busca el icono de herramientas MCP. ¡🎉

Configuración Manual (si lo prefieres)

Inicia el servidor SSE:

docker run -d --name AgentExecMCP-claude -p 8000:8000 -e MCP_TRANSPORT=sse AgentExecMCP

Configura Claude Desktop:

Abre tu archivo de configuración de Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Añade la siguiente configuración:
```
{
  "mcpServers": {
    "AgentExecMCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/sse"
      ]
    }
  }
}
```
Reinicia Claude Desktop y busca el icono de herramientas MCP

Probar la Integración

Prueba estos comandos en Claude Desktop:

"Ejecuta un comando de shell para listar archivos"
"Ejecuta código Python para calcular 2+2"
"Instala el paquete requests usando pip"

Solución de Problemas

Comprueba el estado del servidor: make status
Ver registros: make logs
Reinicia el servidor: make stop && make quick-start

Requisitos Previos para Claude Desktop

Node.js y npm instalados en tu sistema
Docker en ejecución con el contenedor de AgentExecMCP
Claude Desktop en su última versión

El paquete mcp-remote se instalará automáticamente mediante npx en el primer uso.

🖥️ Integración con Cursor

AgentExecMCP funciona perfectamente con el IDE Cursor utilizando el mismo transporte SSE y configuración que Claude Desktop.

Configuración Manual (para Cursor)

Inicia el servidor SSE:
```
make quick-start
```

Configura Cursor:

Abre tu archivo de configuración mcp de Cursor (por ejemplo, ~/.cursor/mcp.json) y añade lo siguiente:

{
  "mcpServers": {
    "AgentExecMCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/sse"
      ]
    }
  }
}

🔧 Herramientas MCP

1. Herramienta Shell

Ejecuta comandos de shell con controles de seguridad.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "shell",
    "arguments": {
      "request": {
        "command": "echo 'Hello World!'",
        "timeout": 60,
        "cwd": "/workspace"
      }
    }
  }
}

2. Herramienta de Ejecución de Código

Ejecuta fragmentos de código en Python, Node.js o Go con ejecución optimizada.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "request": {
        "language": "python",
        "code": "print('Hello from Python!')\nprint(2 + 2)",
        "timeout": 60
      }
    }
  }
}

Ejemplo de Código Go:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "request": {
        "language": "go",
        "code": "package main\nimport \"fmt\"\nfunc main() {\n    fmt.Println(\"Hello from Go!\")\n}",
        "timeout": 60
      }
    }
  }
}

Características:

Python: Entorno completo de Python 3.x con biblioteca estándar
Node.js: Entorno de ejecución de Node.js con paquetes npm
Go: Ejecución optimizada con CGO_ENABLED=0 para una mejor compatibilidad
Limpieza automática: Los archivos temporales se crean y limpian automáticamente
Manejo de errores: Los errores de compilación y ejecución se capturan correctamente

3. Herramienta de Instalación de Paquetes

Instala paquetes utilizando varios gestores de paquetes.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "install_package",
    "arguments": {
      "request": {
        "package_manager": "pip",
        "package": "requests",
        "version": "2.32.0"
      }
    }
  }
}

🌐 Ejemplos de Conexión de Clientes

Cliente FastMCP (Python)

from fastmcp import Client
import asyncio

async def main():
    # Connect via stdio to local container
    async with Client("docker run -i --rm AgentExecMCP") as client:
        result = await client.call_tool("shell", {"request": {"command": "echo 'Hello!'"}})
        print(result[0].text)
    
    # Connect via SSE to HTTP server
    async with Client("http://localhost:8000/sse") as client:
        tools = await client.list_tools()
        print(f"Available tools: {[tool.name for tool in tools]}")

asyncio.run(main())

🔒 Características de Seguridad

Ejecución sin privilegios de root: Se ejecuta como usuario agent (UID 10001)
Espacio de trabajo aislado: Todas las operaciones en el directorio /workspace
Controles de tiempo de espera: Tiempos de espera configurables (60s por defecto, máximo 300s)
Límites de concurrencia: Máximo de 4 procesos concurrentes
Validación de entrada: Límites de tamaño y validación de parámetros
Limpieza de procesos: Limpieza automática de procesos en ejecución

🌍 Entorno

El contenedor incluye:

Imagen base Ubuntu 22.04
Python 3.13.3 con gestor de paquetes pip
Node.js 20.19.2 con npm
Go 1.23.4 con módulos
Herramientas de desarrollo: git, curl, wget, build-essential
Utilidades: jq, ripgrep, fd-find, htop

📡 Soporte del Protocolo MCP

El servidor implementa la especificación del Protocolo de Contexto de Modelo (MCP) 2024-11-05 con múltiples opciones de transporte:

STDIO: Transporte predeterminado para herramientas locales y uso desde línea de comandos
SSE: Transporte de Eventos Enviados por el Servidor para implementación HTTP y Claude Desktop

🛠️ Desarrollo

Desarrollo Local

# Install dependencies
uv sync

# Run server locally (stdio)
uv run python -m app.main

# Run server with SSE transport
MCP_TRANSPORT=sse uv run python -m app.main

Pruebas

El servidor ha sido probado con:

✅ Cumplimiento del protocolo MCP en todos los transportes
✅ Las tres herramientas (shell, execute_code, install_package)
✅ Ejecución de código en múltiples lenguajes con importación de paquetes
✅ Instalación y verificación de paquetes
✅ Implementación del contenedor Docker
✅ Integración con Claude Desktop mediante transporte SSE
✅ Controles de seguridad y tiempo de espera

📋 Requisitos

Docker (para implementación contenerizada)
Python 3.12+ (para desarrollo local)
Gestor de paquetes UV (para gestión de dependencias)
Node.js y npm (para integración con Claude Desktop)

🎯 Casos de Uso

Integración con Claude Desktop: Proporciona capacidades de ejecución directamente en Claude Desktop
Ejecución de Agentes de IA: Proporciona un entorno de ejecución seguro para agentes de IA
Aislamiento de Código: Ejecuta código no confiable en un contenedor aislado
Desarrollo Multilenguaje: Soporta flujos de trabajo en Python, Node.js y Go
Gestión de Paquetes: Instala y prueba paquetes en diferentes ecosistemas
Automatización de Shell: Ejecuta comandos del sistema con controles adecuados
Implementación en Kubernetes: Escala las capacidades de ejecución en entornos de nube

📄 Licencia

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

Este proyecto sigue los principios rectores de ser rápido de construir, reproducible, seguro por defecto y extensible.