MCP代码执行服务器

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

停止为每次查询支付30000个令牌。 此桥实现了Anthropic的无根安全发现模式，将MCP上下文从30K减少到200个令牌，同时代理任何stdio服务器。

概述

这座桥实现了 “使用MCP执行代码” 模式，来自行业领导者的想法的融合：

• 苹果的 代码行为：“您的LLM代理在生成代码时表现更好。”
• 人类学 使用MCP执行代码：“建立更高效的代理人。”
• Cloudflare的 代码模式：“LLM更擅长编写代码来调用MCP，而不是直接调用MCP。”
• Docker的 动态MCP：“停止硬编码你的特工世界。”
• 终端工作台s 终点：“评估法学硕士代理人的现实终端环境。”

这个桥没有向LLM暴露数百个单独的工具（这会消耗大量的上下文并混淆模型），而是暴露了 一 工具： run_pythonLLM编写Python代码来发现、调用和组合其他工具。

为什么是This vs.JS“代码模式”？

虽然有基于JavaScript的替代方案（如 universal-tool-calling-protocol/code-mode)，这个项目是为 数据科学 和 安全:

在以下情况下选择此选项： 您希望您的代理分析数据、生成图表、使用科学库，或者如果您需要严格的基于容器的隔离来运行不受信任的代码。

这解决了什么（其他人没有）

痛苦：MCP代币破产

使用约100个工具将Claude连接到11个MCP服务器= 30000个代币 每个提示符中加载的工具模式。那是 每次查询0.09美元 在你问一个问题之前。扩展到50台服务器和您的上下文窗口 休息.

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

• Docker MCP网关：很好地管理容器，但仍然可以流式传输 所有工具模式 克劳德的背景。没有令牌优化。
• Cloudflare代码模式：V8隔离速度很快，但你 无法代理现有的MCP服务器 （Serena、Wolfram、定制工具）。平台锁定。
• 学术论文：描述Anthropic的发现模式，但提供 没有强化实施.
• 概念证明：跳过安全性（没有无根），跳过持久性（冷启动），跳过代理边缘情况。

解决方案：发现优先架构

• 固定200代币开销 无论服务器数量多少
• 代理任何stdio MCP服务器 放入无根容器
• 跨服务器的模糊搜索 无需预加载模式
• 生产硬化 具有能力下降和安全隔离功能

建筑：它有什么不同

Traditional MCP (Context-Bound)
┌─────────────────────────────┐
│   LLM Context (30K tokens)  │
│  - serverA.tool1: {...}     │
│  - serverA.tool2: {...}     │
│  - serverB.tool1: {...}     │
│  - … (dozens more)          │
└─────────────────────────────┘
        ↓
  LLM picks tool
        ↓
   Tool executes

This Bridge (Discovery-First)
┌─────────────────────────────┐
│  LLM Context (≈200 tokens)  │
│  “Use discovered_servers(), │
│   query_tool_docs(),        │
│   search_tool_docs()”       │
└─────────────────────────────┘
        ↓
      LLM discovers servers
        ↓
      LLM hydrates schemas
        ↓
      LLM writes Python
        ↓
   Bridge proxies execution

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

比较一览

与动态工具集（Speakeasy）相比

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

1. 搜索：“查找GitHub问题的工具”
2. 描述：“获取的架构 create_issue"
3. 执行：“呼叫 create_issue"

此桥（代码优先）折叠了该循环：

1. 代码：“进口 mcp_github，搜索“问题”，如果缺少，则创建一个。"

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

与OneMCP（根特罗）相比

OneMCP 提供了一个“手册”聊天界面，您可以在其中提问并计划执行。这对于简单的查询很好，但会将执行变成 黑匣子.

这座桥 给代理人 原始沙盒控制。代理人并没有要求黑匣子“做这件事”；代理人 是 程序员，编写与API交互的精确代码。这允许进行精确的边缘案例处理和复杂的数据处理，而自然语言规划者可能会错过这些处理。

独特功能

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

2. 跨服务器的模糊搜索 –让模型在不记忆目录名称的情况下查找工具：

   复制

   from mcp import runtime
   
   matches = await runtime.search_tool_docs("calendar events", limit=5)
   for hit in matches:
       print(hit["server"], hit["tool"], hit.get("description", ""))
   

3. 零拷贝代理 –每个工具调用都留在沙箱中，在stdio上镜像，并严格超时。

4. 默认情况下无根 –Podman/Docker容器使用 --cap-drop=ALL，只读根目录，无新权限，显式内存/PID上限。

5. 紧凑型+TOON输出 –大多数运行的纯文本响应最少，可通过以下方式获得确定性TOON块 MCP_BRIDGE_OUTPUT_MODE=toon.

这对谁有帮助

• 团队需要处理两位数的MCP服务器，这些服务器负担不起上下文膨胀。
• 协调循环、重试和条件语句而不是单个工具调用的代理。
• 具有安全意识的操作员需要对LLM生成的代码进行无根隔离。
• 希望重复使用现有MCP目录而无需手动整理清单的从业者。

哲学：“无MCP”方法

此服务器符合以下理念 您可能根本不需要MCP 对于每一个小工具。您可以使用此服务器为您的代理提供服务，而不是为简单的任务构建僵化的MCP服务器 对Bash和Python的原始沙盒访问.

• 特殊工具：需要一个脚本来抓取网站或解析文件吗？只需编写并运行它。无需部署新的MCP服务器。
• 可组合性：在命令之间进行管道输出，将中间结果保存到文件中，并使用标准的Unix工具。
• 安全：与让代理对您的计算机进行原始shell访问不同，此服务器在安全、无根的容器中运行所有内容。您可以毫无风险地获得“Bash/Code”的强大功能。

主要特点

🛡️ 稳健性和可靠性

• 延迟运行时检测：即使Podman/Docker尚未就绪，也会立即启动。仅在请求执行代码时检查运行时。
• 自我参照预防：自动检测并跳过将递归启动网桥的配置。
• 噪声滤波：忽略来自健谈的MCP客户端的良性JSON解析错误（如空行）。
• 智能卷共享：探测Podman VM以确保卷共享工作，即使在旧版本上也是如此。

🔒 安全第一

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

⚡ 演出

• 持续会话 -跨调用保留的变量和状态
• 持久客户端 -MCP服务器保持温暖
• 上下文效率 -与传统MCP相比减少95%以上
• 异步执行 -适当的资源管理
• 单一工具 -只有 run_python 在克劳德的语境中

🔧 开发者体验

• 多种访问模式:

  复制

  mcp_servers["server"]           # Dynamic lookup
  mcp_server_name                 # Attribute access
  from mcp.servers.server import * # Module import
  

• 顶层等待 -现代Python模式

• 类型安全 -适当的签名和文件

• 紧凑的响应 -默认情况下为纯文本输出，请求时可选择TOON块

响应格式

• 默认值（紧凑型） –响应呈现为纯文本加最小值 structuredContent 仅包含非空字段的有效载荷。 stdout/stderr 行保持不变，因此提示在不牺牲内容的情况下保持简洁。
• 可选TOON –设置 MCP_BRIDGE_OUTPUT_MODE=toon 发出 面向令牌的对象表示法 阻碍。我们仍然会丢弃空白字段，并在中镜像相同的结构 structuredContent；当您希望对下游提示进行确定性标记时，TOON非常方便。
• 回退JSON –如果TOON编码器不可用，我们会自动回退到漂亮的JSON块，同时保留修剪后的有效载荷。

🧠 持久存储系统

• 跨会话持久性 -内存数据在容器重启和会话中幸存下来
• 基于JSON的存储 -灵活的值类型（字符串、字典、列表等）
• 元数据支持 -向内存条目添加标签和自定义元数据
• 原子更新 -使用自定义函数更新内存值
• 发现友好 -列出所有记忆并检查是否存在

# Save context for future sessions
save_memory("project_context", {
    "goal": "Build REST API",
    "current_task": "Implement auth",
    "decisions": ["Use JWT tokens", "PostgreSQL backend"]
})

# Retrieve in a later session
context = load_memory("project_context")
print(f"Working on: {context['current_task']}")

# Update incrementally
update_memory("project_context", lambda ctx: {
    **ctx,
    "decisions": ctx["decisions"] + ["Add rate limiting"]
})

# List all saved memories
for mem in list_memories():
    print(f"{mem['key']}: created {mem['created_at']}")

# Check existence before loading
if memory_exists("user_preferences"):
    prefs = load_memory("user_preferences")

内存文件存储在 /projects/memory/ 容器内部，映射到 ~/MCPs/user_tools/memory/ 在主机上。这在会话和容器重新启动时持续存在。

发现工作流程

• 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("keyword") / search_tool_docs_sync("keyword") 获取相关文档子集。
• 工具元数据按需流式传输，无论安装了多少服务器或工具，系统提示都保持在大约200个令牌。
• 一旦LLM有了它需要的文档，它就会编写Python，使用生成的 mcp_<alias> 代理或 mcp.runtime 调用工具的助手。

需要一个简短的描述而不询问助手吗？ 呼叫 runtime.capability_summary() 打印一段概述，适合回答“代码执行MCP能做什么？”等问题

快速开始

1.先决条件（macOS或Linux）

• 检查版本： python3 --version （需要Python 3.11+）
• 如果需要，通过包管理器安装Python或 python.org
• 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.13-slim
# or
docker pull python:3.13-slim

关于Pydantic兼容性的说明：

• 如果你使用Python 3.14+，请确保你安装了现代Pydantic版本（例如， pydantic >= 2.12.0).一些较旧的Pydantic版本或环境安装了单独的 typing PyPI中的包可能会引发以下错误：

TypeError: _eval_type() got an unexpected keyword argument 'prefer_fwd_module'

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

pip install -U pydantic
pip uninstall typing  # if present; the stdlib's typing should be used

并重新运行项目设置（例如删除 .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.执行代码

# Use MCP tools in sandboxed code
result = await mcp_filesystem.read_file(path='/tmp/test.txt')

# Complex workflows
data = await mcp_search.search(query="TODO")
await mcp_github.create_issue(repo='owner/repo', title=data.title)

显式加载服务器

run_python 仅加载您请求的MCP服务器。通过 servers 当您调用该工具时，使用数组进行代理，例如 mcp_serena 或 mcp_filesystem 在沙盒中可用：

{
  "code": "print(await mcp_serena.search(query='latest AI papers'))",
  "servers": ["serena", "filesystem"]
}

如果省略该列表，发现帮助程序仍将枚举所有内容，但任何针对卸载服务器的RPC调用都会返回 Server '<name>' is not available.

注： servers 数组只控制为沙箱调用生成哪些代理。它不设置服务器配置字段，例如 cwdThe cwd 属性是主机/服务器配置的一部分，LLM应调用 runtime.describe_server(name) 或检查 runtime.list_loaded_server_metadata() 发现已配置的 cwd 在假定服务器的工作目录之前。

注意：服务器配置可以包括可选 cwd 财产。如果存在，网桥将启动该工作目录中的主机MCP服务器进程；代理商应检查 runtime.describe_server(name) 发现服务器的配置 cwd 在做出假设之前。

测试

项目环境支持CPython 3.11+。确保您的本地环境使用兼容的Python版本：

uv python pin 3.13
uv sync

运行时依赖关系保持精简；开发依赖项（pytest等）可通过 dev 额外：

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Or run without installing dev dependencies permanently
uv run --with pytest pytest

建筑

┌─────────────┐
│ MCP Client  │ (Your Agent)
└──────┬──────┘
       │ stdio
       ▼
┌──────────────┐
│ MCP Code Exec │ ← Discovers, proxies, manages
│ Bridge        │
└──────┬──────┘
       │ container
       ▼
┌─────────────┐
│ Container   │ ← Executes with strict isolation
│ Sandbox     │
└─────────────┘

零上下文发现

与预加载每个工具定义（有时超过30000个令牌）的传统MCP服务器不同，此网桥将其系统提示固定到大约200个令牌，并训练LLM按需发现所需内容：

1. LLM电话 discovered_servers() → 学习哪些桥在不加载模式的情况下可用。
2. LLM电话 query_tool_docs("serena") → 仅对该服务器的工具文档进行水合处理，并可选择按工具进行筛选。
3. LLM编写编排代码→ 调用助手，如 mcp_serena.search() 或 mcp.runtime.call_tool().

结果： 无论您配置了多少MCP服务器，上下文使用率都保持不变。

流程：

1. 客户电话 run_python(code, servers, timeout)
2. 桥接加载请求的MCP服务器
3. 准备沙箱调用：收集MCP工具元数据，将入口点写入共享 /ipc 数量和出口 MCP_AVAILABLE_SERVERS
4. 生成的入口点将stdio重新连接到JSON框架的消息中，并通过容器的stdin/stdout管道代理MCP调用
5. 持续执行：容器启动一次（如果未运行）并保持活动状态。
6. 状态保留：在一个调用中定义的变量、导入和函数在后续调用中可用。
7. 主机流处理程序处理JSON帧，转发MCP流量，强制超时，并为下一个请求保持容器活动。

配置

环境变量

服务器发现

网桥会自动从多个配置源发现MCP服务器：

支持的地点：

注： 较早的来源优先。如果在多个位置定义了同一台服务器，则第一台获胜。

示例服务器 (~/MCPs/filesystem.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

注： 为了防止递归启动，网桥会自动跳过任何出现的配置条目 mcp-server-code-execution-mode 再次（包括 uvx … mcp-server-code-execution-mode run).集 MCP_BRIDGE_ALLOW_SELF_SERVER=1 如果您有意将网桥作为嵌套的MCP服务器公开。

Docker MCP网关集成

当你依赖 docker mcp gateway run 为了公开第三方MCP服务器，网桥只需执行网关二进制文件。网关负责拉取工具映像和连接stdio传输，因此请确保主机环境已准备就绪：

• 跑 docker login 对于网关目录中引用的每个注册表（例如Docker Hub mcp/* 图像， ghcr.io/github/github-mcp-server).如果没有缓存的凭据，在任何工具上线之前，拉取步骤都会失败。
• 为这些服务器提供所需的机密--github-official 需求 github.personal_access_token，其他人可能期望API密钥或身份验证令牌。使用 docker mcp secret set <name> （或网关配置的任何机制），以便容器在启动时看到这些值。
• 镜像目录所需的任何卷装载或环境变量（文件系统路径、存储卷等）。缺少挂载或凭据通常表现为 failed to connect: calling "initialize": EOF 在stdio握手期间。
• 如果 list_tools 仅返回内部管理助手(mcp-add, code-mode，…），网关从未完成初始化外部服务器——请检查网关日志中是否存在丢失的机密或注册表访问错误。

状态目录和卷共享

• 运行时工件（包括生成的 /ipc/entrypoint.py 以及相关的握手元数据） ~/MCPs/ 默认情况下。集 MCP_BRIDGE_STATE_DIR 重新安置他们。
• 当所选运行时为Podman时，网桥会自动发出 podman machine set --rootful --now --volume <state_dir>:<state_dir> 因此VM可以挂载该目录。关于老年人 podman machine 不支持的构建 --volume，网桥现在使用以下命令探测VM podman machine ssh test -d <state_dir> 如果该份额已经可用，则继续进行。
• Docker Desktop不公开用于文件共享的CLI；确保所选状态目录在Docker Desktop中标记为共享→ 设置→ 资源→ 运行网桥之前共享文件。
• 要手动验证共享，请运行 docker run --rm -v ~/MCPs:/ipc alpine ls /ipc （或Podman等效工具）并确认文件可见。

使用示例

文件处理

# List and filter files
files = await mcp_filesystem.list_directory(path='/tmp')

for file in files:
    content = await mcp_filesystem.read_file(path=file)
    if 'TODO' in content:
        print(f"TODO in {file}")

数据管道

# Extract data
transcript = await mcp_google_drive.get_document(documentId='abc123')

# Process
summary = transcript[:500] + "..."

# Store
await mcp_salesforce.update_record(
    objectType='SalesMeeting',
    recordId='00Q5f000001abcXYZ',
    data={'Notes': summary}
)

多系统工作流

# Jira → GitHub migration
issues = await mcp_jira.search_issues(project='API', status='Open')

for issue in issues:
    details = await mcp_jira.get_issue(id=issue.id)

    if 'bug' in details.description.lower():
        await mcp_github.create_issue(
            repo='owner/repo',
            title=f"Bug: {issue.title}",
            body=details.description
        )

检查可用服务器

from mcp import runtime

print("Discovered:", runtime.discovered_servers())
print("Cached servers:", runtime.list_servers_sync())
print("Loaded metadata:", runtime.list_loaded_server_metadata())
print("Selectable via RPC:", await runtime.list_servers())

# Peek at tool docs for a server that's already loaded in this run
loaded = runtime.list_loaded_server_metadata()
if loaded:
  first = runtime.describe_server(loaded[0]["name"])
  for tool in first["tools"]:
    print(tool["alias"], "→", tool.get("description", ""))

# Ask for summaries or full schemas only when needed
if loaded:
  summaries = await runtime.query_tool_docs(loaded[0]["name"])
  detailed = await runtime.query_tool_docs(
    loaded[0]["name"],
    tool=summaries[0]["toolAlias"],
    detail="full",
  )
  print("Summaries:", summaries)
  print("Cached tools:", runtime.list_tools_sync(loaded[0]["name"]))
  print("Detailed doc:", detailed)

# Fuzzy search across loaded servers without rehydrating every schema
results = await runtime.search_tool_docs("calendar events", limit=3)
for result in results:
  print(result["server"], result["tool"], result.get("description", ""))

# Synchronous helpers for quick answers without extra awaits
print("Capability summary:", runtime.capability_summary())
print("Docs from cache:", runtime.query_tool_docs_sync(loaded[0]["name"]) if loaded else [])
print("Search from cache:", runtime.search_tool_docs_sync("calendar"))

LLM在使用存根服务器运行上述代码段时看到的示例输出：

Discovered: ('stub',)
Loaded metadata: ({'name': 'stub', 'alias': 'stub', 'tools': [{'name': 'echo', 'alias': 'echo', 'description': 'Echo the provided message', 'input_schema': {...}}]},)
Selectable via RPC: ('stub',)

喜欢的客户 listMcpResources 可以跳过执行助手代码段，而是请求 resource://mcp-server-code-execution-mode/capabilities 资源。服务器通过以下方式进行公告 resources/list，阅读它会返回相同的助手摘要和一个简短的加载清单 服务器明确。

安全

容器约束

能力矩阵

文档

• README.md -这个文件，快速开始
• GUIDE.md -全面的用户指南
• 建筑.md -技术深潜
• 历史.md -演变和教训
• 状态.md -现状和路线图

资源

外部

• 使用MCP执行代码（Anthropic）
• 代码模式（Cloudflare）
• 模型上下文协议
• 使用Docker的动态MCP
• CodeAct：你的LLM代理在生成代码时表现更好（苹果）
• 终端工作台

状态

✅ 实现

• 无根容器沙箱
• 单 run_python 工具
• MCP服务器代理
• 持久会话（状态保留）
• 持久客户端（热MCP服务器）
• 综合文档

🔄 进行中

• 自动化测试
• 可观察性（日志记录、指标）
• 策略控制
• 运行时诊断

📋 路线图

• 连接池
• Web用户界面
• 多语言支持
• 工作流编排
• 代理可见发现通道（已代理主机 mcp-find/mcp-add)
• 执行遥测（结构化日志、指标、跟踪）
• 持久和可共享的代码模式工件

许可证

GPLv3许可证

支持

有关问题或疑问，请参阅文档或提交问题。