MCP Script Runner

Execute scripts bash definidos pelo desenvolvedor em um ambiente Dockerizado para agentes de codificação.

Documentação

MCP Script Runner

Um servidor Model Context Protocol (MCP) que fornece aos agentes de codificação uma interface genérica para executar scripts bash definidos pelo desenvolvedor em um ambiente Dockerizado.

🚀 Início Rápido

Opção 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

Opção 2: Instalação 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

📋 Visão Geral

O servidor MCP Script Runner permite que agentes de IA:

Executar scripts bash predefinidos com argumentos configuráveis
Gerenciar diretórios de trabalho para diferentes contextos de projeto
Obter informações de scripts incluindo descrições e argumentos disponíveis
Listar scripts disponíveis dinamicamente
Lidar com timeouts de scripts e condições de erro de forma elegante

🐳 Suporte a Docker

O projeto inclui suporte completo a Docker para execução em contêineres:

🔧 Contêineres prontos para uso com todas as dependências
🛡️ Ambiente de execução isolado
📦 Implantação fácil com Docker Compose
🔍 Capacidades de depuração com acesso interativo ao shell

Consulte DOCKER.md para o guia completo de uso do Docker.

Comandos Rápidos do Docker

# 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

🛠️ Instalação

Pré-requisitos

Python 3.11+
Docker (para execução em contêineres)
Shell compatível com Bash

Configuração Local

# Install Python dependencies
pip install -r requirements.txt

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

Configuração Docker

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

# Or use Docker Compose
docker compose up --build

⚙️ Configuração

Arquivo de Configuração: `.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
    }
  }
}

Estrutura do Diretório de Scripts

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

🔧 Ferramentas MCP Disponíveis

Ferramenta	Descrição	Argumentos
`run_script`	Executar um script configurado	`script_name`, `arguments[]`
`list_scripts`	Listar todos os scripts disponíveis	Nenhum
`get_script_info`	Obter detalhes do script	`script_name`
`get_working_directory`	Obter diretório de trabalho atual	Nenhum
`set_working_directory`	Definir diretório de trabalho	`path`
`reload_config`	Recarregar arquivo de configuração	Nenhum

Exemplo de Uso da Ferramenta

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

🏃‍♂️ Executando o Servidor

Execução 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

Execução Docker

# Background service
docker compose up -d

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

# Debug shell
docker compose --profile debug up shell

📝 Exemplos de Scripts

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

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

Script de Listagem de Arquivos (`scripts/list_files.sh`)

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

Script de Informações do 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

🧪 Testes

Testes Unitários

# Run tests locally
python -m pytest tests/

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

Testes Manuais

# 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())
"

🔐 Considerações de Segurança

🛡️ Execução em contêiner isola a execução de scripts
👤 Usuário não-root dentro dos contêineres (mcpuser)
📁 Acesso limitado a arquivos por meio de montagens de volume
⏱️ Timeouts de scripts previnem processos descontrolados
🚫 Sem injeção de shell - argumentos passados com segurança

🎯 Casos de Uso

Automação de Desenvolvimento

Comandos de build e teste
Scripts de geração de código
Configuração do ambiente de desenvolvimento

Administração de Sistemas

Scripts de monitoramento de sistema
Tarefas de backup e manutenção
Gerenciamento de configuração

Integração CI/CD

Scripts de implantação
Validação de ambiente
Fluxos de trabalho de testes automatizados

Gerenciamento de Projetos

Automação de tarefas
Geração de relatórios
Gerenciamento de recursos

🐛 Solução de Problemas

Problemas Comuns

O Servidor MCP Não 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')"

A Execução do Script Falha

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

# Test script directly
bash scripts/hello.sh

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

Problemas com 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 Depuração

# 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

📚 Desenvolvimento

Estrutura do Projeto

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

Adicionando Novos Scripts

Crie o script no diretório scripts/
Torne-o executável: chmod +x scripts/myscript.sh
Adicione ao .mcp-config.json:

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

Recarregue a configuração: Use a ferramenta reload_config

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Adicione testes para a nova funcionalidade
Teste com Docker: docker compose up --build
Envie um pull request

🚀 Implantação

Implantação em Produção

# 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/

Integração com Clientes MCP

Configuração do Claude Desktop

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

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🤝 Suporte

📖 Documentação: Consulte DOCKER.md para uso do Docker
🐛 Problemas: Crie uma issue no GitHub
💬 Discussões: GitHub Discussions
📧 Contato: Consulte os contribuidores do repositório

Pronto para começar?

🐳 Usuários Docker: docker compose up --build 🐍 Usuários locais: pip install -r requirements.txt && python -m mcp_script_runner.server

MCP Script Runner

Documentação