MCP Code Executor

MCP Code Executor

O MCP Code Executor é um servidor MCP que permite que LLMs executem código Python em um ambiente Python especificado. Isso permite que LLMs executem código com acesso a bibliotecas e dependências definidas no ambiente. Ele também suporta geração incremental de código para lidar com blocos de código grandes que podem exceder os limites de tokens.

Recursos

• Executar código Python a partir de prompts de LLM
• Suporte para geração incremental de código para superar limitações de tokens
• Executar código em um ambiente especificado (Conda, virtualenv ou UV virtualenv)
• Instalar dependências quando necessário
• Verificar se os pacotes já estão instalados
• Configurar dinamicamente o ambiente em tempo de execução
• Diretório de armazenamento de código configurável

Pré-requisitos

• Node.js instalado
• Um dos seguintes:
  • Conda instalado com o ambiente Conda desejado criado
  • Python virtualenv
  • UV virtualenv

Configuração

1. Clone este repositório:

git clone https://github.com/bazinga012/mcp_code_executor.git

2. Navegue até o diretório do projeto:

cd mcp_code_executor

3. Instale as dependências do Node.js:

npm install

4. Compile o projeto:

npm run build

Configuração

Para configurar o servidor MCP Code Executor, adicione o seguinte ao seu arquivo de configuração de servidores MCP:

Usando Node.js

{
  "mcpServers": {
    "mcp-code-executor": {
      "command": "node",
      "args": [
        "/path/to/mcp_code_executor/build/index.js" 
      ],
      "env": {
        "CODE_STORAGE_DIR": "/path/to/code/storage",
        "ENV_TYPE": "conda",
        "CONDA_ENV_NAME": "your-conda-env"
      }
    }
  }
}

Usando Docker

{
  "mcpServers": {
    "mcp-code-executor": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp-code-executor"
      ]
    }
  }
}

Nota: O Dockerfile foi testado apenas com o tipo de ambiente venv-uv. Outros tipos de ambiente podem exigir configuração adicional.

Variáveis de Ambiente

Variáveis Obrigatórias

• CODE_STORAGE_DIR: Diretório onde o código gerado será armazenado

Tipo de Ambiente (escolha uma configuração)

• Para Conda:

  • ENV_TYPE: Defina como conda
  • CONDA_ENV_NAME: Nome do ambiente Conda a ser usado

• Para Virtualenv Padrão:

  • ENV_TYPE: Defina como venv
  • VENV_PATH: Caminho para o diretório do virtualenv

• Para UV Virtualenv:

  • ENV_TYPE: Defina como venv-uv
  • UV_VENV_PATH: Caminho para o diretório do UV virtualenv

Ferramentas Disponíveis

O MCP Code Executor fornece as seguintes ferramentas para LLMs:

1. execute_code

Executa código Python no ambiente configurado. Melhor para trechos de código curtos.

{
  "name": "execute_code",
  "arguments": {
    "code": "import numpy as np\nprint(np.random.rand(3,3))",
    "filename": "matrix_gen"
  }
}

2. install_dependencies

Instala pacotes Python no ambiente.

{
  "name": "install_dependencies",
  "arguments": {
    "packages": ["numpy", "pandas", "matplotlib"]
  }
}

3. check_installed_packages

Verifica se os pacotes já estão instalados no ambiente.

{
  "name": "check_installed_packages",
  "arguments": {
    "packages": ["numpy", "pandas", "non_existent_package"]
  }
}

4. configure_environment

Altera dinamicamente a configuração do ambiente.

{
  "name": "configure_environment",
  "arguments": {
    "type": "conda",
    "conda_name": "new_env_name"
  }
}

5. get_environment_config

Obtém a configuração atual do ambiente.

{
  "name": "get_environment_config",
  "arguments": {}
}

6. initialize_code_file

Cria um novo arquivo Python com conteúdo inicial. Use este como o primeiro passo para código mais longo que pode exceder os limites de tokens.

{
  "name": "initialize_code_file",
  "arguments": {
    "content": "def main():\n    print('Hello, world!')\n\nif __name__ == '__main__':\n    main()",
    "filename": "my_script"
  }
}

7. append_to_code_file

Adiciona conteúdo a um arquivo de código Python existente. Use este para adicionar mais código a um arquivo criado com initialize_code_file.

{
  "name": "append_to_code_file",
  "arguments": {
    "file_path": "/path/to/code/storage/my_script_abc123.py",
    "content": "\ndef another_function():\n    print('This was appended to the file')\n"
  }
}

8. execute_code_file

Executa um arquivo Python existente. Use este como o passo final após construir o código com initialize_code_file e append_to_code_file.

{
  "name": "execute_code_file",
  "arguments": {
    "file_path": "/path/to/code/storage/my_script_abc123.py"
  }
}

9. read_code_file

Lê o conteúdo de um arquivo de código Python existente. Use este para verificar o estado atual de um arquivo antes de adicionar mais conteúdo ou executá-lo.

{
  "name": "read_code_file",
  "arguments": {
    "file_path": "/path/to/code/storage/my_script_abc123.py"
  }
}

Uso

Uma vez configurado, o MCP Code Executor permitirá que LLMs executem código Python gerando um arquivo no CODE_STORAGE_DIR especificado e executando-o no ambiente configurado.

LLMs podem gerar e executar código referenciando este servidor MCP em seus prompts.

Lidando com Blocos de Código Grandes

Para blocos de código maiores que podem exceder os limites de tokens do LLM, use a abordagem de geração incremental de código:

1. Inicialize um arquivo com a estrutura básica usando initialize_code_file
2. Adicione mais código em chamadas subsequentes usando append_to_code_file
3. Verifique o conteúdo do arquivo se necessário usando read_code_file
4. Execute o código completo usando execute_code_file

Esta abordagem permite que LLMs escrevam código complexo e de múltiplas partes sem encontrar limitações de tokens.

Compatibilidade Retroativa

Este pacote mantém compatibilidade retroativa com versões anteriores. Usuários de versões anteriores que especificaram apenas um ambiente Conda continuarão funcionando sem nenhuma alteração em sua configuração.

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou envie um pull request.

Licença

Este projeto é licenciado sob a Licença MIT.