MCP代码执行服务器

Name: MCP代码执行服务器
Author: ipdelete

作者：ipdelete8 星标更新：2025-11-09

安装使用来源：spider==github.com

项目介绍

MCP代码执行 - Python运行时

通过逐步发现工具来减少模型上下文协议（MCP）服务器中的令牌数量，实现98.7%的令牌减少。

概述

此运行时允许AI代理通过逐步披露模式与MCP工具进行交互：

代理探索./servers/以发现可用工具
代理仅读取所需的工具定义
代理编写Python脚本，通过MCP工具获取数据
脚本返回结果（原始或处理过的）-代理可以在后续轮次中处理/总结

结果：发送给代理的令牌减少了约98.7%。

特性

🦥 懒加载：只有在调用工具时服务器才连接
🔒 类型安全：所有工具输入/输出都使用Pydantic模型
🔄 防御性编程：处理可变的MCP响应结构
📦 自动生成包装器：从MCP模式生成类型的Python函数
🛠️ 字段规范化：处理不一致的API大小写（例如，ADO）

安装

先决条件

Python 3.11+
uv 包管理器
Node.js（用于MCP服务器）

设置

# 安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库
git clone https://github.com/ipdelete/mcp-code-execution.git
cd mcp-code-execution

# 安装依赖
uv sync --all-extras

# 在可编辑模式下安装
uv pip install -e ".[dev]"

快速开始

1. 配置MCP服务器

创建mcp_config.json：

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "."]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

2. 生成工具包装器并发现模式（可选）

# 从inputSchema生成包装器
uv run mcp-generate

如果您的MCP服务器缺少outputSchema定义，可以自动生成它们：

# 步骤1：使用LLM驱动的测试参数生成发现配置
uv run mcp-generate-discovery

# 步骤2：查看discovery_config.json并根据需要删除/修改

# 步骤3：执行安全工具并推断模式
uv run mcp-discover

这将在servers/中创建类型化的包装器：

servers/
  git/
    __init__.py
    git_status.py
    git_log.py
    git_diff.py
    discovered_types.py       # 生成的输出模式
  fetch/
    __init__.py
    fetch.py
    discovered_types.py

3. 工作原理

当您请求AI代理处理您的数据时：

代理探索可用的MCP工具通过./servers/
代理编写一个脚本，使用call_mcp_tool()从MCP服务器获取数据
脚本返回数据 - 根据用例，可能是原始数据或预处理过的数据
代理处理结果 - 可以总结、重塑或将其作为后续工具调用的输入

关键见解：并非所有处理都需要在脚本中完成。LLM可以在后续交互中处理总结和数据转换。脚本专注于高效的数据检索。

代理可能编写的示例脚本：

"""分析git仓库提交记录。"""

import asyncio
from runtime.mcp_client import call_mcp_tool

async def main():
    # 获取最近的提交记录
    result = await call_mcp_tool(
        "git__git_log",
        {"repo_path": ".", "max_count": 10}
    )

    # 返回数据供代理处理
    # 代理可以总结、分析或将其作为其他工具输入
    print(f"获取到提交日志")
    return result

if __name__ == "__main__":
    asyncio.run(main())

4. 代理执行

当代理需要运行脚本时，它会使用以下命令：

# 代理自动运行此命令
uv run python -m runtime.harness workspace/my_script.py

# 或通过方便的别名
uv run mcp-exec workspace/my_script.py

该环境管理MCP客户端生命周期，连接到服务器，并捕获脚本的输出以发送回代理。

架构

逐步披露模式

传统方法（高令牌使用量）：

代理 → MCP服务器 → [全数据50KB] → 代理处理全部

逐步披露（98.7%减少）：

代理 → 发现工具 → 编写脚本
脚本 → MCP服务器 → [全数据50KB] → 返回给代理
代理 → 处理/总结 → 在后续调用中使用

关键组件

runtime/mcp_client.py：懒加载的MCP客户端管理器
runtime/harness.py：脚本执行环境
runtime/generate_wrappers.py：自动生成类型化的包装器
runtime/normalize_fields.py：处理API字段大小写
runtime/schema_utils.py：JSON模式 → Pydantic转换

开发

运行测试

# 所有测试
uv run pytest

# 单元测试
uv run pytest tests/unit/

# 集成测试
uv run pytest tests/integration/

# 带覆盖率
uv run pytest --cov=src/runtime

代码质量

# 类型检查
uv run mypy src/

# 格式化
uv run black src/ tests/

# 代码检查
uv run ruff check src/ tests/

# 格式检查
uv run black --check src/ tests/

项目脚本

# 从工具定义生成包装器
uv run mcp-generate

# （可选）使用LLM参数生成生成发现配置
uv run mcp-generate-discovery

# （可选）执行安全工具并推断模式
uv run mcp-discover

# 使用可用的MCP工具执行Python脚本
uv run mcp-exec workspace/script.py

Python特定功能

使用Pydantic确保类型安全

所有工具参数和结果都使用Pydantic进行验证：

from runtime.servers.git import git_status, GitStatusParams

# 类型安全参数
params = GitStatusParams(repo_path=".")

# 类型安全结果
result = await git_status(params)

异步支持

基于asyncio实现高效的I/O：

import asyncio
from runtime.mcp_client import call_mcp_tool

async def main():
    # 并发工具调用
    results = await asyncio.gather(
        call_mcp_tool("git__git_status", {"repo_path": "."}),
        call_mcp_tool("git__git_log", {"repo_path": ".", "max_count": 5}),
    )

asyncio.run(main())

字段规范化

自动处理不一致的API大小写：

from runtime.normalize_fields import normalize_field_names

# ADO返回小写，期望PascalCase
ado_response = {"system.title": "Task", "custom.priority": "High"}
normalized = normalize_field_names(ado_response, "ado")
# 结果：{"System.title": "Task", "Custom.priority": "High"}

处理缺失的输出模式

许多MCP服务器在其工具定义中没有提供outputSchema，这是MCP规范中的可选项。该项目提供了使用LLM驱动的参数生成的自动模式发现：

工作原理

生成发现配置（mcp-generate-discovery）
- 连接到所有配置的MCP服务器
- 使用Claude从inputSchema生成合理的测试参数
- 根据模式将工具分类为安全/危险/未知
- 写入discovery_config.json供审查
审查和编辑（手动步骤）
- 审查生成的配置
- 根据需要添加/移除工具
- 如有必要，修改测试参数
发现模式（mcp-discover）
- 使用测试参数执行安全工具
- 从实际响应推断Pydantic模型
- 写入servers/{server}/discovered_types.py

工具分类

工具自动按安全性分类：

安全：匹配模式如get_*，list_*，read_*，fetch，search_*等
危险：匹配模式如delete_*，remove_*，update_*，write_*等
未知：不匹配任何模式的工具（需要手动审查）

危险工具默认被排除在自动发现之外。

示例

{
  "servers": {
    "github": {
      "safeTools": {
        "search_code": {"q": "language:python", "per_page": 1},
        "list_repositories": {"sort": "stars", "per_page": 1}
      }
    }
  },
  "metadata": {
    "generated": true,
    "generated_count": 2,
    "skipped_count": 3,
    "tools_skipped": {
      "dangerous": ["delete_repository"],
      "unknown": ["analyze_code", "deploy_release", "configure_webhook"]
    }
  }
}

示例

参见workspace/example_progressive_disclosure.py以了解完整的示例，展示令牌减少模式。

贡献

# 安装开发依赖
uv sync --all-extras

# 提交前运行质量检查
uv run black src/ tests/
uv run mypy src/
uv run ruff check src/ tests/
uv run pytest

许可证

MIT