Sandbox MCP Server

Sandbox MCP Server

Um servidor MCP que fornece ambientes Docker isolados para execução de código. Este servidor permite que você:

• Crie contêineres com qualquer imagem Docker
• Escreva e execute código em várias linguagens de programação
• Instale pacotes e configure ambientes de desenvolvimento
• Execute comandos em contêineres isolados

Pré-requisitos

• Python 3.9 ou superior
• Docker instalado e em execução
• Gerenciador de pacotes uv (recomendado)
• Servidor MCP Docker (recomendado)

Instalação

1. Clone este repositório:

git clone <your-repo-url>
cd sandbox_server

2. Crie e ative um ambiente virtual com uv:

uv venv
source .venv/bin/activate  # On Unix/MacOS
# Or on Windows:
# .venv\Scripts\activate

3. Instale as dependências:

uv pip install .

Integração com Claude Desktop

1. 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

2. Adicione a configuração do servidor sandbox:

{
    "mcpServers": {
        "sandbox": {
            "command": "uv",
            "args": [
                "--directory",
                "/absolute/path/to/sandbox_server",
                "run",
                "sandbox_server.py"
            ],
            "env": {
                "PYTHONPATH": "/absolute/path/to/sandbox_server"
            }
        }
    }
}

Substitua /absolute/path/to/sandbox_server pelo caminho real do diretório do seu projeto.

3. Reinicie o Claude Desktop

Exemplos de Uso

Uso Básico

Uma vez conectado ao Claude Desktop, você pode:

1. Criar um contêiner Python:

Could you create a Python container and write a simple hello world program?

2. Executar código em diferentes linguagens:

Could you create a C program that calculates the fibonacci sequence and run it?

3. Instalar pacotes e usá-los:

Could you create a Python script that uses numpy to generate and plot some random data?

Salvando e Reproduzindo Ambientes

O servidor fornece várias maneiras de salvar e reproduzir seus ambientes de desenvolvimento:

Criando Contêineres Persistentes

Ao criar um contêiner, você pode torná-lo persistente:

Could you create a persistent Python container with numpy and pandas installed?

Isso criará um contêiner que:

• Permanece em execução após o Claude Desktop ser fechado
• Pode ser acessado diretamente através do Docker
• Preserva todos os pacotes e arquivos instalados

O servidor fornecerá instruções para:

• Acessar o contêiner diretamente (docker exec)
• Parar e iniciar o contêiner
• Removê-lo quando não for mais necessário

Salvando o Estado do Contêiner

Após configurar seu ambiente, você pode salvá-lo como uma imagem Docker:

Could you save the current container state as an image named 'my-ds-env:v1'?

Isso irá:

1. Criar uma nova imagem Docker com todos os seus:
   • Pacotes instalados
   • Arquivos criados
   • Alterações de configuração
2. Fornecer instruções para reutilizar o ambiente

Você pode então compartilhar esta imagem ou usá-la como ponto de partida para novos contêineres:

Could you create a new container using the my-ds-env:v1 image?

Gerando Dockerfiles

Para tornar seu ambiente totalmente reproduzível, você pode gerar um Dockerfile:

Could you export a Dockerfile that recreates this environment?

O Dockerfile gerado incluirá:

• Especificação da imagem base
• Arquivos criados
• Modelo para etapas adicionais de configuração

Você pode usar este Dockerfile para:

1. Compartilhar a configuração do seu ambiente com outras pessoas
2. Controlar versões do seu ambiente de desenvolvimento
3. Modificar e personalizar o processo de build
4. Implantar em diferentes sistemas

Fluxo de Trabalho Recomendado

Para ambientes de desenvolvimento reproduzíveis:

1. Crie um contêiner persistente:

Create a persistent Python container for data science work

2. Instale os pacotes necessários e configure o ambiente:

Install numpy, pandas, and scikit-learn in the container

3. Teste sua configuração:

Create and run a test script to verify the environment

4. Salve o estado:

Save this container as 'ds-workspace:v1'

5. Exporte um Dockerfile:

Generate a Dockerfile for this environment

Isso oferece várias opções para recriar seu ambiente:

• Use a imagem Docker salva diretamente
• Construa a partir do Dockerfile com modificações
• Acesse o contêiner original, se necessário

Notas de Segurança

• Todo o código é executado em contêineres Docker isolados
• Os contêineres são removidos automaticamente após o uso
• Os sistemas de arquivos são isolados entre contêineres
• O acesso ao sistema host é restrito

Estrutura do Projeto

sandbox_server/
├── sandbox_server.py     # Main server implementation
├── pyproject.toml        # Project configuration
└── README.md            # This file

Ferramentas Disponíveis

O servidor fornece três ferramentas principais:

1. create_container_environment: Cria um novo contêiner Docker com a imagem especificada
2. create_file_in_container: Cria um arquivo em um contêiner
3. execute_command_in_container: Executa comandos em um contêiner
4. save_container_state: Salva o estado do contêiner em um contêiner persistente
5. export_dockerfile: Exporta um arquivo Docker para criar um ambiente persistente
6. exit_container: Fecha um contêiner para limpar o ambiente quando terminar