星战科技xingzhan.cloud
返回市场
MCP服务器代码执行模式

MCP服务器代码执行模式

作者：elusznik217 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

MCP代码执行服务器：零上下文发现100+ MCP工具

MseeP.ai安全评估徽章

**停止每次查询支付30,000个令牌。**此桥接实现了Anthropic的无上下文发现模式，将MCP上下文从30K减少到200个令牌，同时代理任何标准I/O服务器。

Anthropic工程 Cloudflare博客 Docker MCP网关 Apple机器学习 MCP协议 在MseeP上验证

概述

此桥接实现了“使用MCP进行代码执行”的模式，这是一个来自行业领导者的理念融合：

  • Apple的CodeAct：“当生成代码时，您的LLM代理表现更好。”
  • Anthropic的使用MCP进行代码执行：“构建更高效的代理。”
  • Cloudflare的代码模式：“LLM更适合编写调用MCP的代码，而不是直接调用MCP。”
  • Docker的动态MCP：“停止硬编码您的代理的世界。”
  • 终端基准's Terminus：“用于评估LLM代理的真实终端环境。”

与其将数百个单独的工具暴露给LLM（这会消耗大量上下文并混淆模型），此桥接仅暴露一个工具：run_python。LLM编写Python代码来发现、调用和组合其他工具。

为什么选择这个而不是JS“代码模式”？

虽然有基于JavaScript的替代方案（如universal-tool-calling-protocol/code-mode），但该项目是为数据科学和安全性设计的：

特性本项目（Python）JS代码模式（Node.js）
原生语言Python（AI/ML的语言）TypeScript/JavaScript
数据科学原生（pandas，numpy，scikit-learn）不可能 / 非法
隔离严格（Podman/Docker容器）软（Node.js虚拟机）
安全性企业级（无特权，无网络，只读）进程级
哲学基础设施（独立桥接）库（可嵌入）

如果需要： 您希望代理分析数据、生成图表、使用科学库，或需要严格的容器化隔离来运行不受信任的代码。

解决的问题（其他人无法解决的）

痛点：MCP令牌破产

连接Claude到11个MCP服务器，大约100个工具 = 30,000个令牌的工具模式加载到每个提示中。这意味着在您提出第一个问题之前，每次查询成本为0.09美元。扩展到50个服务器，您的上下文窗口就会崩溃。

为什么现有“解决方案”失败

  • Docker MCP网关：漂亮地管理容器，但仍将所有工具模式流式传输到Claude的上下文中。没有令牌优化。
  • Cloudflare代码模式：V8隔离速度快，但您不能代理现有的MCP服务器（Serena，Wolfram，自定义工具）。平台锁定。
  • 学术论文：描述了Anthropic的发现模式，但没有提供加固的实现。
  • 概念证明：跳过安全性（无特权），跳过持久性（冷启动），跳过代理边缘情况。

解决方案：先发现架构

  • 固定200个令牌开销，无论服务器数量多少
  • 代理任何标准I/O MCP服务器到无特权容器
  • 跨服务器模糊搜索，无需预加载模式
  • 生产加固，具有能力降级和安全隔离

架构：如何不同

传统MCP（上下文绑定）
┌─────────────────────────────┐
│   LLM上下文（30K令牌）      │
│  - serverA.tool1: {...}     │
│  - serverA.tool2: {...}     │
│  - serverB.tool1: {...}     │
│  - … （数十个更多）         │
└─────────────────────────────┘
        ↓
  LLM选择工具
        ↓
   工具执行

此桥接（先发现）
┌─────────────────────────────┐
│  LLM上下文（≈200令牌）      │
│  “使用discovered_servers()，│
│   query_tool_docs()，        │
│   search_tool_docs()”       │
└─────────────────────────────┘
        ↓
      LLM发现服务器
        ↓
      LLM填充模式
        ↓
      LLM编写Python
        ↓
   桥接代理执行

结果：固定开销。无论您管理10个还是1000个工具，系统提示都保持合适大小，模式仅在请求时流动。

对比一览

功能Docker MCP网关Cloudflare代码模式研究模式此桥接
解决令牌膨胀❌ 手动预加载❌ 固定目录❌ 理论✅ 发现运行时
普通MCP代理✅ 容器⚠️ 平台特定❌ 未提供✅ 任何标准I/O服务器
无特权安全⚠️ 可选✅ V8隔离❌ 未处理✅ 能力降级沙箱
自动发现⚠️ 目录绑定❌ 不适用❌ 未实现✅ 9个配置路径
工具文档搜索❌❌⚠️ 概念✅ search_tool_docs()
生产加固⚠️ 取决于您✅ 管理服务❌ 原型✅ 测试桥接

与动态工具集（Speakeasy）对比

Speakeasy的动态工具集使用三步流程：search_tools → describe_tools → execute_tool。虽然这节省了令牌，但它迫使代理进入“聊天循环”：

  1. 搜索：“查找GitHub问题工具”
  2. 描述：“获取create_issue模式”
  3. 执行：“调用create_issue”

此桥接（代码优先）合并了该循环：

  1. 代码：“导入mcp_github，搜索‘问题’，并在缺失时创建一个。”

代理编写一个单个Python脚本，在一个往返中执行发现、逻辑和执行。它更快、更便宜（较少的中间LLM调用），并且处理复杂的逻辑（循环、重试）——简单的“执行”工具无法做到这一点。

与OneMCP（Gentoro）对比

OneMCP提供了一个“手册”聊天界面，您可以提问，它计划执行。这对于简单查询很好，但将执行变成一个黑盒。

此桥接给予代理原始、沙箱控制。代理不是让黑盒“做”，而是自己编写精确的代码来与API交互。这允许对边缘情况的精确处理和复杂的数据处理，而自然语言规划者可能会忽略这些。

独特功能

  1. 两阶段发现 – discovered_servers()揭示存在的内容；query_tool_docs(name)仅加载您需要的模式。

  2. 跨服务器模糊搜索 – 让模型找到工具，无需记住目录名称：

    from mcp import runtime

匹配项 = await runtime.search_tool_docs("日历事件", limit=5)
for 命中 in 匹配项:
    print(命中["server"], 命中["tool"], 命中.get("description", ""))

  3. 零拷贝代理 – 每次工具调用都保持在沙箱内，通过标准I/O镜像，并带有严格的超时。

  4. 默认无特权 – Podman/Docker容器以--cap-drop=ALL，只读根，不允许新权限，并明确设置内存/PID限制。

  5. 紧凑+TOON输出 – 大多数运行的最小纯文本响应，通过MCP_BRIDGE_OUTPUT_MODE=toon可用确定性TOON块。

谁受益

  • 管理双位数MCP服务器的团队，无法承受上下文膨胀。
  • 编排循环、重试和条件的代理，而不仅仅是单一工具调用。
  • 需要无特权隔离以运行LLM生成代码的安全意识操作员。
  • 希望重复使用现有MCP目录而不手动整理清单的从业者。

哲学：无MCP方法

此服务器符合您可能根本不需要MCP的理念。与其为简单任务构建刚性的MCP服务器，您可以使用此服务器给予代理原始、沙箱访问Bash和Python的能力。

  • 临时工具：需要脚本来抓取网站或解析文件？只需编写并运行它。无需部署新的MCP服务器。
  • 可组合性：在命令之间传递输出，保存中间结果到文件，并使用标准Unix工具。
  • 安全性：不像给予代理对您机器的原始shell访问，此服务器在安全的无特权容器中运行一切。您获得了“Bash/代码”的力量，而没有风险。

关键特性

🛡️ 坚固性和可靠性

  • 懒惰运行时检测：即使Podman/Docker尚未准备好也能立即启动。仅在请求代码执行时检查运行时。
  • 自我引用预防：自动检测并跳过可能导致桥接递归启动的配置。
  • 噪声过滤：忽略来自嘈杂MCP客户端的良性JSON解析错误（如空白行）。
  • 智能卷共享：探测Podman VM以确保卷共享工作，即使在旧版本上也是如此。

🔒 安全第一

  • 无特权容器 - 不需要特权助手
  • 网络隔离 - 无网络访问
  • 只读文件系统 - 不变的根
  • 降级能力 - 无系统访问
  • 非特权用户 - 作为UID 65534运行
  • 资源限制 - 内存、PID、CPU、时间
  • 自动清理 - 临时IPC目录

⚡ 性能

  • 持久会话 - 变量和状态在调用间保留
  • 持久客户端 - MCP服务器保持温暖
  • 上下文效率 - 相比传统MCP减少95%以上
  • 异步执行 - 合理的资源管理
  • 单个工具 - 只有run_python在Claude的上下文中

🔧 开发者体验

  • 多种访问模式：

    mcp_servers["server"]           # 动态查找
mcp_server_name                 # 属性访问
from mcp.servers.server import * # 模块导入

  • 顶级等待 - 现代Python模式

  • 类型安全 - 正确的签名和文档

  • 紧凑响应 - 默认纯文本输出，请求时可选TOON块

响应格式

  • 默认（紧凑） – 响应呈现为纯文本加上仅包含非空字段的最小structuredContent负载。stdout/stderr行保持完整，因此提示保持精简而不牺牲内容。
  • 可选TOON – 设置MCP_BRIDGE_OUTPUT_MODE=toon以发出面向令牌的对象表示法块。我们仍然删除空字段并在structuredContent中镜像相同的结构；当您需要下游提示的确定性标记化时，TO_ _N很有用。
  • 回退JSON – 如果TOON编码器不可用，我们将自动回退到漂亮的JSON块，同时保留修剪的负载。

发现工作流程

  • SANDBOX_HELPERS_SUMMARY在工具模式中仅宣传发现助手（discovered_servers()，list_servers()，query_tool_docs()，search_tool_docs()等）。它永远不会包括个别服务器或工具文档。
  • 在首次使用时，LLM通常调用discovered_servers()（或list_servers_sync()以获取缓存列表）来枚举MCP服务器，然后调用query_tool_docs(server) / query_tool_docs_sync(server)或search_tool_docs("关键词") / search_tool_docs_sync("关键词")来获取相关子集的文档。
  • 工具元数据按需流式传输，保持系统提示大约200个令牌，无论安装了多少服务器或工具。
  • 一旦LLM有了所需的文档，它就编写Python代码，使用生成的mcp_<别名>代理或mcp.runtime助手来调用工具。

需要简短描述而不探测助手吗？ 调用runtime.capability_summary()以打印一段概述，适合回答诸如“代码执行MCP可以做什么？”等问题。

快速开始

1. 先决条件（macOS或Linux）

  • 检查版本：python3 --version
  • 如需安装，请通过包管理器或python.org安装Python 3.14
  • macOS：brew install podman 或 brew install --cask docker
  • Ubuntu/Debian：sudo apt-get install -y podman 或 curl -fsSL https://get.docker.com | sh
curl -LsSf https://astral.sh/uv/install.sh | sh

podman pull python:3.14-slim
# 或
docker pull python:3.14-slim

关于Pydantic兼容性（Python 3.14）：

  • 如果您使用Python 3.14，请确保安装了现代版本的Pydantic（例如，pydantic >= 2.12.0）。某些较旧的Pydantic版本或从PyPI安装单独typing包的环境可能会引发错误，例如：
TypeError: _eval_type() got an unexpected keyword argument 'prefer_fwd_module'

如果您看到此错误，请运行：

pip install -U pydantic
pip uninstall typing  # 如果存在；应使用stdlib的typing

并重新运行项目设置（例如，删除.venv/并uv sync）。

2. 安装依赖

使用uv同步项目环境：

uv sync

3. 启动桥接

uvx --from git+https://github.com/elusznik/mcp-server-code-execution-mode mcp-server-code-execution-mode run

如果您偏好从本地检出运行，等效命令如下：

uv run python mcp_server_code_execution_mode.py

4. 注册到您的代理

将以下服务器配置添加到您的代理MCP设置文件中（例如，mcp_config.json，claude_desktop_config.json等）：

{
  "mcpServers": {
    "mcp-server-code-execution-mode": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/elusznik/mcp-server-code-execution-mode",
        "mcp-server-code-execution-mode",
        "run"
      ],
      "env": {
        "MCP_BRIDGE_RUNTIME": "podman"
      }
    }
  }
}

5. 执行代码

# 在沙箱代码中使用MCP工具
结果 = await mcp_filesystem.read_file(path='/tmp/test.txt')

# 复杂的工作流
数据 = await mcp_search.search(query="TODO")
await mcp_github.create_issue(repo='owner/repo', title=数据.title)

显式加载服务器

run_python仅加载您请求的MCP服务器。通过servers数组传递它们，以便在沙箱调用中可用的代理如mcp_serena或mcp_filesystem：

{
  "code": "print(await mcp_serena.search(query='最新的人工智能