MCP Code Sandbox Server

Execute código com segurança em ambientes de sandbox isolados usando a API E2B.

GitHub
17
Experimente este MCPPatrocinado

Documentação

Servidor MCP Code Sandbox

Um servidor extensível de Protocolo de Comunicação de Mensagens (MCP) que fornece capacidades seguras de execução de código em ambientes de sandbox isolados. Este servidor segue o padrão MCP, tornando-o compatível com Claude for Desktop e outros clientes MCP.

Recursos

  • Crie ambientes de sandbox isolados para execução de código
  • Execute código Python com segurança
  • Realize operações de arquivos (listar, ler, escrever)
  • Instale pacotes Python no sandbox
  • Arquitetura extensível com interface de interpretador de código abstraída
  • Design modular com separação clara de responsabilidades

Arquitetura

O servidor é construído com uma arquitetura modular e extensível:

Componentes Principais

  • Interface Abstrata de Interpretador: Permite que diferentes backends de execução de código sejam integrados
  • Administração de Sandbox: Ferramentas para criar e gerenciar ambientes de sandbox
  • Execução de Código: Ferramentas para executar código e instalar pacotes
  • Operações de Arquivos: Ferramentas para gerenciar arquivos dentro dos sandboxes

Estrutura do Projeto

├── src/
│   └── sandbox/
│       ├── __pycache__/
│       ├── e2b/
│       │   ├── __pycache__/
│       │   ├── __init__.py
│       │   ├── e2b_file_interface.py
│       │   └── e2b_interpreter.py
│       ├── __init__.py
│       ├── code_interpreter.py
│       ├── file_interface.py
│       └── interpreter_factory.py
├── tools/
│   ├── __pycache__/
│   ├── __init__.py
│   ├── code_execution_tools.py
│   ├── file_tools.py
│   └── sandbox_tools.py
├── main.py
├── .env
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── uv.lock

Pré-requisitos

  • Python 3.10 ou superior
  • Chave de API E2B (para o interpretador E2B padrão)

Instalação

  1. Clone este repositório:

    git clone https://github.com/yourusername/mcp-code-sandbox.git
cd mcp-code-sandbox

  2. Configure um ambiente virtual:

    # Using venv
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Or using uv (recommended)
uv init
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Instale os pacotes necessários:

    # Using pip
pip install fastmcp python-dotenv e2b-code-interpreter

# Or using uv
uv add fastmcp python-dotenv e2b-code-interpreter

  4. Configure as variáveis de ambiente:

    # Create a .env file with the following variables
E2B_API_KEY=your_e2b_api_key_here
INTERPRETER_TYPE=e2b  # Default, can be changed to other implemented interpreters

Uso

Executando o Servidor de Forma Independente

Você pode executar o servidor diretamente pela linha de comando:

python main.py

Isso iniciará o servidor usando o transporte stdio, tornando-o compatível com Claude for Desktop.

Usando com Claude for Desktop

  1. Certifique-se de ter a versão mais recente do Claude for Desktop instalada

  2. Abra o arquivo de configuração do Claude for Desktop:

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

  3. Adicione a configuração do seu servidor de sandbox de código:

    {
  "mcpServers": {
    "code-sandbox": {
      "command": "python",
      "args": [
        "/ABSOLUTE/PATH/TO/main.py"
      ]
    }
  }
}

    Ou se você estiver usando uv:

    {
  "mcpServers": {
    "code-sandbox": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PROJECT_DIRECTORY",
        "run",
        "main.py"
      ]
    }
  }
}

  4. Salve o arquivo e reinicie o Claude for Desktop

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas:

Administração de Sandbox

  • create_sandbox: Crie um novo ambiente de sandbox
  • close_sandbox: Feche e limpe um sandbox
  • get_sandbox_status: Verifique o status dos sandboxes

Execução de Código

  • execute_code: Execute código Python em um sandbox
  • install_package: Instale um pacote Python
  • create_run_close: Ferramenta completa que cria um sandbox, executa código e limpa

Operações de Arquivos

  • list_files: Liste arquivos no sandbox
  • read_file: Leia o conteúdo de um arquivo
  • write_file: Escreva conteúdo em um arquivo
  • upload_file: Envie um arquivo para o sandbox

Estendendo com Novos Interpretadores

O sistema foi projetado para ser extensível. Para adicionar um novo interpretador de código:

  1. Crie um novo diretório em src/sandbox/ para a implementação do seu interpretador
  2. Implemente as interfaces definidas em src/sandbox/code_interpreter.py e src/sandbox/file_interface.py
  3. Adicione o novo tipo de interpretador ao src/sandbox/interpreter_factory.py
  4. Configure a variável de ambiente INTERPRETER_TYPE para o seu novo interpretador

Exemplo de implementação de um novo interpretador:

# src/sandbox/my_backend/my_interpreter.py
from src.sandbox.code_interpreter import CodeInterpreter, ExecutionResult
from src.sandbox.file_interface import FileInterface

class MyFileInterface(FileInterface):
    # Implement the required methods
    
class MyInterpreter(CodeInterpreter):
    # Implement the required methods

# Update src/sandbox/interpreter_factory.py to include your new interpreter

Descrições dos Módulos

Núcleo do Sandbox (src/sandbox/)

  • code_interpreter.py: Classe base abstrata para interpretadores de código
  • file_interface.py: Interface abstrata para operações de arquivos
  • interpreter_factory.py: Fábrica para criar instâncias de interpretadores de código

Implementação E2B (src/sandbox/e2b/)

  • e2b_interpreter.py: Implementação E2B do interpretador de código
  • e2b_file_interface.py: Implementação E2B das operações de arquivos

Ferramentas (tools/)

  • sandbox_tools.py: Ferramentas para administração de sandbox
  • code_execution_tools.py: Ferramentas para execução de código
  • file_tools.py: Ferramentas para operações de arquivos

Aplicação Principal

  • main.py: Ponto de entrada principal da aplicação

Solução de Problemas

Se você encontrar problemas:

  • Certifique-se de ter a chave de API correta para o interpretador escolhido
  • Verifique os logs para mensagens de erro detalhadas
  • Confirme que todos os pacotes necessários estão instalados
  • Garanta que o Claude for Desktop esteja configurado com o caminho correto para o seu script

Considerações de Segurança

  • A execução de código ocorre em ambientes de sandbox por segurança
  • Não use este servidor para executar código não confiável em ambientes de produção
  • O servidor atualmente não implementa autenticação - deve ser usado apenas em ambientes confiáveis

Licença

Licença MIT