MCP Script Runner

Ejecuta scripts bash definidos por el desarrollador en un entorno Dockerizado para agentes de codificación.

Documentación

MCP Script Runner

Un servidor de Model Context Protocol (MCP) que proporciona a los agentes de codificación una interfaz genérica para ejecutar scripts bash definidos por el desarrollador dentro de un entorno Dockerizado.

🚀 Inicio Rápido

Opción 1: Docker (Recomendado)

# Clone and run with Docker
git clone <repository-url>
cd devmcp
docker compose up --build -d

# Check logs
docker compose logs -f

Opción 2: Instalación Local

# Clone repository
git clone <repository-url>
cd devmcp

# Install dependencies
pip install -r requirements.txt

# Run the server
python -m mcp_script_runner.server

📋 Descripción General

El servidor MCP Script Runner permite a los agentes de IA:

Ejecutar scripts bash predefinidos con argumentos configurables
Gestionar directorios de trabajo para diferentes contextos de proyecto
Obtener información de scripts incluyendo descripciones y argumentos disponibles
Listar scripts disponibles dinámicamente
Manejar tiempos de espera de scripts y condiciones de error de manera elegante

🐳 Soporte Docker

El proyecto incluye soporte Docker completo para ejecución en contenedores:

🔧 Contenedores listos para usar con todas las dependencias
🛡️ Entorno de ejecución aislado
📦 Implementación fácil con Docker Compose
🔍 Capacidades de depuración con acceso interactivo a shell

Consulte DOCKER.md para la guía completa de uso de Docker.

Comandos Docker Rápidos

# Start the MCP server
docker compose up --build -d

# Interactive development shell
docker compose --profile debug up shell

# Test script execution
docker compose exec mcp-script-runner bash scripts/hello.sh

🛠️ Instalación

Requisitos Previos

Python 3.11+
Docker (para ejecución en contenedores)
Shell compatible con Bash

Configuración Local

# Install Python dependencies
pip install -r requirements.txt

# Verify installation
python -c "from src.mcp_script_runner.server import main; print('✅ Installation OK')"

Configuración Docker

# Build container
docker build -t mcp-script-runner .

# Or use Docker Compose
docker compose up --build

⚙️ Configuración

Archivo de Configuración: `.mcp-config.json`

{
  "working_directory": ".",
  "scripts": {
    "hello": {
      "path": "scripts/hello.sh",
      "description": "Simple hello world script",
      "arguments": [],
      "timeout": 30
    },
    "list_files": {
      "path": "scripts/list_files.sh",
      "description": "List files in directory with options",
      "arguments": ["directory", "options"],
      "timeout": 10
    }
  }
}

Estructura del Directorio de Scripts

project/
├── .mcp-config.json
├── scripts/
│   ├── hello.sh
│   ├── list_files.sh
│   └── system_info.sh
└── src/
    └── mcp_script_runner/

🔧 Herramientas MCP Disponibles

Herramienta	Descripción	Argumentos
`run_script`	Ejecutar un script configurado	`script_name`, `arguments[]`
`list_scripts`	Listar todos los scripts disponibles	Ninguno
`get_script_info`	Obtener detalles del script	`script_name`
`get_working_directory`	Obtener el directorio de trabajo actual	Ninguno
`set_working_directory`	Establecer el directorio de trabajo	`path`
`reload_config`	Recargar el archivo de configuración	Ninguno

Ejemplo de Uso de Herramientas

{
  "tool": "run_script",
  "arguments": {
    "script_name": "hello",
    "arguments": []
  }
}

🏃‍♂️ Ejecutando el Servidor

Ejecución Local

# Start MCP server (listens on stdio)
python -m mcp_script_runner.server

# Or with explicit path
PYTHONPATH=src python -m mcp_script_runner.server

Ejecución Docker

# Background service
docker compose up -d

# Interactive mode
docker compose run --rm mcp-script-runner

# Debug shell
docker compose --profile debug up shell

📝 Scripts de Ejemplo

Script Básico de Saludo (`scripts/hello.sh`)

#!/bin/bash
echo "Hello from MCP Script Runner!"
echo "Current directory: $(pwd)"
echo "Script arguments: $@"
echo "Date: $(date)"

Script de Listado de Archivos (`scripts/list_files.sh`)

#!/bin/bash
DIRECTORY=${1:-.}
OPTIONS=${2:-"-la"}
echo "Listing files in: $DIRECTORY"
ls $OPTIONS "$DIRECTORY"

Script de Información del Sistema (`scripts/system_info.sh`)

#!/bin/bash
echo "=== System Information ==="
echo "OS: $(uname -s)"
echo "Kernel: $(uname -r)"
echo "Architecture: $(uname -m)"
echo "Uptime: $(uptime)"
echo "Disk Usage:"
df -h

🧪 Pruebas

Pruebas Unitarias

# Run tests locally
python -m pytest tests/

# Run tests in Docker
docker compose run --rm mcp-script-runner python -m pytest tests/

Pruebas Manuales

# Test script execution
python -c "
import asyncio
from src.mcp_script_runner.executor import ScriptExecutor
from src.mcp_script_runner.config import ConfigManager

async def test():
    cm = ConfigManager()
    ex = ScriptExecutor(cm)
    result = await ex.execute_script('hello')
    print(f'Exit code: {result.exit_code}')
    print(result.stdout)

asyncio.run(test())
"

🔐 Consideraciones de Seguridad

🛡️ Ejecución en contenedores aísla la ejecución de scripts
👤 Usuario no root dentro de los contenedores (mcpuser)
📁 Acceso limitado a archivos mediante montajes de volúmenes
⏱️ Tiempos de espera de scripts previenen procesos descontrolados
🚫 Sin inyección de shell - argumentos pasados de forma segura

🎯 Casos de Uso

Automatización de Desarrollo

Comandos de compilación y prueba
Scripts de generación de código
Configuración del entorno de desarrollo

Administración de Sistemas

Scripts de monitoreo del sistema
Tareas de respaldo y mantenimiento
Gestión de configuración

Integración CI/CD

Scripts de implementación
Validación de entorno
Flujos de trabajo de pruebas automatizadas

Gestión de Proyectos

Automatización de tareas
Generación de informes
Gestión de recursos

🐛 Solución de Problemas

Problemas Comunes

El Servidor MCP No Se Inicia

# Check Python path
export PYTHONPATH=src

# Verify dependencies
pip install -r requirements.txt

# Check configuration
python -c "from src.mcp_script_runner.config import ConfigManager; cm = ConfigManager(); print('Config OK')"

La Ejecución del Script Falla

# Check script permissions
chmod +x scripts/*.sh

# Test script directly
bash scripts/hello.sh

# Check Docker logs
docker compose logs mcp-script-runner

Problemas con Docker

# Rebuild container
docker compose up --build

# Check container status
docker compose ps

# Interactive debugging
docker compose run --rm mcp-script-runner bash

Modo de Depuración

# Local debug
PYTHONPATH=src python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from mcp_script_runner.server import main
import asyncio
asyncio.run(main())
"

# Docker debug
docker compose --profile debug up shell

📚 Desarrollo

Estructura del Proyecto

devmcp/
├── 📄 README.md              # This file
├── 🐳 DOCKER.md              # Docker usage guide
├── 📋 TASKS.md               # Development tasks
├── ⚙️ .mcp-config.json       # Configuration
├── 🐳 Dockerfile             # Container definition
├── 🐳 docker-compose.yml     # Container orchestration
├── 📦 requirements.txt       # Python dependencies
├── 📦 pyproject.toml         # Python project config
├── 🔧 scripts/               # Example scripts
├── 🐍 src/mcp_script_runner/ # Python source code
└── 🧪 tests/                 # Unit tests

Agregar Nuevos Scripts

Cree el script en el directorio scripts/
Hágalo ejecutable: chmod +x scripts/myscript.sh
Agréguelo a .mcp-config.json:

{
  "scripts": {
    "myscript": {
      "path": "scripts/myscript.sh",
      "description": "My custom script",
      "arguments": ["arg1", "arg2"],
      "timeout": 30
    }
  }
}

Recargue la configuración: Use la herramienta reload_config

Contribuciones

Haga un fork del repositorio
Cree una rama de características
Agregue pruebas para la nueva funcionalidad
Pruebe con Docker: docker compose up --build
Envíe una solicitud de extracción (pull request)

🚀 Implementación

Implementación en Producción

# Using Docker Compose
docker compose up -d

# Using Docker Swarm
docker stack deploy -c docker-compose.yml mcp-stack

# Using Kubernetes
kubectl apply -f k8s/

Integración con Clientes MCP

Configuración de Claude Desktop

{
  "mcpServers": {
    "script-runner": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/devmcp/docker-compose.yml", "run", "--rm", "mcp-script-runner"]
    }
  }
}

📄 Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.

🤝 Soporte

📖 Documentación: Consulte DOCKER.md para el uso de Docker
🐛 Problemas: Cree un issue en GitHub
💬 Discusiones: Discusiones de GitHub
📧 Contacto: Consulte los contribuyentes del repositorio

¿Listo para comenzar?

🐳 Usuarios de Docker: docker compose up --build 🐍 Usuarios locales: pip install -r requirements.txt && python -m mcp_script_runner.server

MCP Script Runner

Documentación