关键词

Python执行代码沙箱MCP工具LLM集成函数调用

项目简介

本项目是一个基于Model Context Protocol (MCP) 标准实现的Python后端服务。它提供了一个核心工具，允许外部客户端（如大型语言模型LLM）以标准化的方式请求执行Python代码。服务支持STDIO和SSE两种数据传输协议，旨在方便地将Python的计算能力集成到LLM应用的工作流程中。本项目特别针对云平台部署进行了优化。

主要功能点

  • 提供一个名为 'code_exec_python' 的MCP工具，用于执行任意Python代码片段。
  • 支持在执行Python代码前，根据请求自动安装指定的Python包（通过pip）。
  • 提供在临时的、隔离的虚拟环境中执行代码的选项，增强包管理的隔离性（注意：这非完全安全的沙箱环境，代码仍可能访问文件系统、网络等）。
  • 实现了基于标准输入/输出（STDIO）的MCP服务器，适合作为一次性进程或在容器/Job环境中使用。
  • 实现了基于Server-Sent Events（SSE）的HTTP MCP服务器，适合作为长时间运行的Web服务。
  • 包含用于本地开发、测试和远程部署的详细指南及客户端示例。

安装步骤

  1. 环境准备: 确保你的系统安装了Python 3.7+ 版本，并且Python环境中包含 'venv' 模块（Python 3.3+ 通常默认包含）。
  2. 克隆仓库: 从GitHub克隆本项目的源代码到你的本地机器： 
    git clone https://github.com/heroku/mcp-code-exec-python.git
cd mcp-code-exec-python
  3. 创建并激活虚拟环境: 推荐使用虚拟环境来隔离项目依赖： 
    python -m venv venv
source venv/bin/activate  # 在Windows上使用 'venv\Scripts\activate'
  4. 安装依赖: 安装项目运行所需的所有Python包： 
    pip install -r requirements.txt
  5. 配置环境变量: 根据你的使用场景（本地测试、部署），需要设置一些必要的环境变量。最重要的包括：
    • 'API_KEY': 用于SSE模式的认证密钥，你需要生成一个安全的随机字符串作为密钥。
    • 'STDIO_MODE_ONLY': 设置为 'true' 或 'false'，决定是否仅启用STDIO模式。
    • 其他如 'PORT', 'WEB_CONCURRENCY' 等，可根据需要配置。 可以在项目根目录创建 '.env' 文件来管理本地开发时的环境变量。

服务器配置 (供MCP客户端参考)

要使兼容MCP的客户端（如LLM应用或MCP客户端库）能够连接并使用此服务器，客户端需要知道如何与服务器建立通信。以下是MCP客户端通常需要配置的信息：

  • 服务器名称 (Server Name): 客户端会用一个标识符来区分不同的MCP服务器。你可以为此服务指定一个描述性的名称，例如在客户端配置中将其命名为 '"python_code_executor"'。
  • 传输协议 (Transport Protocol): 指明客户端将使用哪种协议与服务器通信。本项目支持 'stdio' 和 'sse'。客户端配置中需要明确指定使用其中一种。
  • 连接参数:
    • 若使用 STDIO 协议，客户端需要配置启动服务器进程的命令。对于本项目，这个命令通常是 'python -m src.stdio_server'。客户端库或运行时环境会负责在需要时启动这个命令，并通过其标准输入和输出与服务器交换JSON-RPC消息。客户端配置可能需要指定这个命令及其所需的任何命令行参数或环境变量。
    • 若使用 SSE 协议，客户端需要配置HTTP服务器的URL地址。在部署后，这通常是部署服务的 '/sse' 端点URL（例如 'https://your-deployed-app-name.com/sse'）。在本地运行时，默认URL通常是 'http://localhost:8000/sse'。
  • 认证信息 (仅SSE模式): 如果服务器启用了认证（本项目SSE模式强制要求API Key），客户端需要在HTTP请求中提供相应的认证信息。本项目要求在 'Authorization: Bearer YOUR_API_KEY' 或 'X-API-Key: YOUR_API_KEY' HTTP头中提供配置的API Key。客户端配置可能需要包含这个密钥。
  • 服务器能力 (Capabilities): 虽然MCP协议允许客户端发现服务器提供的能力（如工具列表），但客户端配置有时也可以包含对服务器提供的工具的初步描述，例如本项目主要提供一个名为 'code_exec_python' 的工具。

基本使用方法

  1. 启动服务器:
    • STDIO模式: 通常不作为长期运行的服务单独启动。客户端（或其运行时环境）在需要时通过执行上面提到的命令来启动 'src.stdio_server' 脚本，并在会话结束后进程退出。
    • SSE模式: 需要作为Web服务启动。在本地，激活虚拟环境并配置API Key后，可以运行 'uvicorn src.sse_server:app --reload' 启动。部署到云平台（如Heroku）时，通过配置Procfile和dyno来运行。
  2. 连接服务器: 使用支持MCP协议的客户端库或应用，根据上述配置信息连接到正在运行的服务器实例。
  3. 初始化会话: 客户端通常会发送一个 'initialize' JSON-RPC请求来建立会话并声明客户端能力。
  4. 发现工具: 客户端可以发送 'list_tools' 请求来获取服务器提供的所有工具的详细列表。你将看到关于 'code_exec_python' 工具的描述，包括其名称、功能说明以及所需的输入参数（'code', 'packages', 'use_temp_dir'）。
  5. 调用工具: 客户端通过发送 'tools/call' JSON-RPC请求来调用 'code_exec_python' 工具。请求的 'params' 字段需要包含 'name: "code_exec_python"' 和 'arguments' 对象，其中 'arguments' 包含要执行的 'code' 字符串、可选的 'packages' 列表，以及可选的 'use_temp_dir' 布尔值。
  6. 处理结果: 服务器将返回一个JSON-RPC响应，其中包含工具执行的结果。对于 'code_exec_python' 工具，结果将是一个JSON对象，包含 'returncode'（执行退出码）、'stdout'（标准输出内容）和 'stderr'（标准错误内容或安装失败信息）。

信息

分类

AI与计算

访问项目