AgentExecMCP

Um servidor seguro baseado em Docker que fornece capacidades essenciais de execução para agentes de IA.

GitHub
2

Documentação

AgentExecMCP

License

Um servidor FastMCP que fornece capacidades essenciais de execução para agentes de IA, empacotado em Docker para implantação segura e fácil.

⚡ Início Rápido

Comece a usar em 2 minutos: veja QUICKSTART.md.

📋 Sumário

🚀 Recursos

  • Execução de Shell: Execute comandos bash com controle de tempo limite e segurança
  • Execução de Código em Múltiplas Linguagens: Suporte a Python, Node.js e Go com execução otimizada
  • Gerenciamento de Pacotes: Instale pacotes via pip, npm e módulos Go
  • Múltiplos Transportes: stdio e SSE
  • Implantação Docker: Containerizado para ambiente de execução consistente
  • Protocolo MCP: Model Context Protocol em conformidade com padrões
  • Controles de Segurança: Execução sem root, limites de tempo, limites de concorrência
  • Integração com Claude Desktop: Funciona perfeitamente com Claude Desktop via transporte SSE
  • Otimização Go: Execução de código Go com CGO_ENABLED=0 para melhor compatibilidade

🛠️ Comandos Make

O AgentExecMCP inclui um Makefile abrangente que torna a configuração e o gerenciamento muito fáceis. Todos os comandos são projetados para serem amigáveis tanto para usuários técnicos quanto não técnicos.

Comandos de Início Rápido

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

Comandos Principais

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 Gerenciamento

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 Desenvolvimento

make lint               # Run ruff linter and formatter

Comandos de Manutenção

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

Exemplo de Fluxo de Trabalho

# 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

🖥️ Integração com Claude Desktop

O AgentExecMCP funciona perfeitamente com Claude Desktop usando transporte SSE. Isso é perfeito para desenvolvimento e testes locais.

Configuração Fácil com Make (Recomendado)

Configuração super simples em 3 etapas:

  1. Inicie o AgentExecMCP:

    make quick-start

  2. Instale a configuração do Claude Desktop:

    make install-claude-config

  3. Reinicie o Claude Desktop e procure o ícone de ferramentas MCP! 🎉

Configuração Manual (se preferir)

  1. Inicie o servidor SSE:

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

  2. Configure o Claude Desktop:

    Abra o arquivo de configuração do Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    Adicione a seguinte configuração:

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

  3. Reinicie o Claude Desktop e procure o ícone de ferramentas MCP

Testar a Integração

Experimente estes comandos no Claude Desktop:

  • "Execute um comando shell para listar arquivos"
  • "Execute algum código Python para calcular 2+2"
  • "Instale o pacote requests usando pip"

Solução de Problemas

  • Verifique o status do servidor: make status
  • Veja os logs: make logs
  • Reinicie o servidor: make stop && make quick-start

Pré-requisitos para Claude Desktop

  • Node.js e npm instalados no seu sistema
  • Docker em execução com o container AgentExecMCP
  • Claude Desktop versão mais recente

O pacote mcp-remote será instalado automaticamente pelo npx no primeiro uso.

🖥️ Integração com Cursor

O AgentExecMCP funciona perfeitamente com o IDE Cursor usando o mesmo transporte SSE e configuração do Claude Desktop.

Configuração Manual (para Cursor)

  1. Inicie o servidor SSE:

    make quick-start

  2. Configure o Cursor:

    Abra o arquivo de configuração mcp do Cursor (por exemplo, ~/.cursor/mcp.json) e adicione o seguinte:

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

🔧 Ferramentas MCP

1. Ferramenta Shell

Execute comandos shell com controles de segurança.

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

2. Ferramenta de Execução de Código

Execute trechos de código em Python, Node.js ou Go com execução otimizada.

{
  "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
      }
    }
  }
}

Exemplo 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
      }
    }
  }
}

Recursos:

  • Python: Ambiente Python 3.x completo com biblioteca padrão
  • Node.js: Runtime Node.js com pacotes npm
  • Go: Execução otimizada com CGO_ENABLED=0 para melhor compatibilidade
  • Limpeza automática: Arquivos temporários são criados e limpos automaticamente
  • Tratamento de erros: Erros de compilação e execução são capturados adequadamente

3. Ferramenta de Instalação de Pacotes

Instale pacotes usando vários gerenciadores de pacotes.

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

🌐 Exemplos de Conexão de Cliente

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

🔒 Recursos de Segurança

  • Execução sem root: Executa como usuário agent (UID 10001)
  • Espaço de trabalho isolado: Todas as operações no diretório /workspace
  • Controles de tempo limite: Limites de tempo configuráveis (padrão 60s, máximo 300s)
  • Limites de concorrência: Máximo de 4 processos simultâneos
  • Validação de entrada: Limites de tamanho e validação de parâmetros
  • Limpeza de processos: Limpeza automática de processos em execução

🌍 Ambiente

O container inclui:

  • Imagem base Ubuntu 22.04
  • Python 3.13.3 com gerenciador de pacotes pip
  • Node.js 20.19.2 com npm
  • Go 1.23.4 com módulos
  • Ferramentas de desenvolvimento: git, curl, wget, build-essential
  • Utilitários: jq, ripgrep, fd-find, htop

📡 Suporte ao Protocolo MCP

O servidor implementa a especificação Model Context Protocol (MCP) 2024-11-05 com múltiplas opções de transporte:

  • STDIO: Transporte padrão para ferramentas locais e uso em linha de comando
  • SSE: Transporte Server-Sent Events para implantação HTTP e Claude Desktop

🛠️ Desenvolvimento

Desenvolvimento 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

Testes

O servidor foi testado com:

  • ✅ Conformidade com o protocolo MCP em todos os transportes
  • ✅ Todas as três ferramentas (shell, execute_code, install_package)
  • ✅ Execução de código em múltiplas linguagens com importação de pacotes
  • ✅ Instalação e verificação de pacotes
  • ✅ Implantação em container Docker
  • ✅ Integração com Claude Desktop via transporte SSE
  • ✅ Controles de segurança e tempo limite

📋 Requisitos

  • Docker (para implantação em container)
  • Python 3.12+ (para desenvolvimento local)
  • Gerenciador de pacotes UV (para gerenciamento de dependências)
  • Node.js e npm (para integração com Claude Desktop)

🎯 Casos de Uso

  • Integração com Claude Desktop: Forneça capacidades de execução diretamente no Claude Desktop
  • Execução de Agentes de IA: Forneça ambiente de execução seguro para agentes de IA
  • Sandbox de Código: Execute código não confiável em container isolado
  • Desenvolvimento Multi-linguagem: Suporte a fluxos de trabalho em Python, Node.js e Go
  • Gerenciamento de Pacotes: Instale e teste pacotes em diferentes ecossistemas
  • Automação de Shell: Execute comandos do sistema com controles adequados
  • Implantação Kubernetes: Escale capacidades de execução em ambientes de nuvem

📄 Licença

Este projeto é licenciado sob a Apache License 2.0 - veja o arquivo LICENSE para detalhes.

Este projeto segue os princípios orientadores de ser rápido para construir, reproduzível, seguro por padrão e extensível.