执行工具 MCP 服务器

源文件：chapter4/execution-tools/README.md

执行工具 MCP 服务器

一个 MCP（Model Context Protocol）服务器，为 AI Agent 提供内置安全机制的、功能完整的执行工具。

功能特性

安全机制

1. 基于 LLM 的审批：不可逆操作在执行前必须先获得第二个 LLM 的批准
2. 结果摘要：执行工具的输出超过 10000 字符时，会自动由 LLM 生成摘要，便于后续处理
3. 自动校验：可校验的操作（例如语法检查）会自动进行验证

工具分类

文件系统工具

• file_write：写入文件内容，并自动进行语法校验
• file_edit：编辑已有文件，支持 diff 预览与校验

通用执行工具

• code_interpreter：在沙箱中执行 Python 代码，并提供结果分析
• virtual_terminal：执行 shell 命令，并对错误进行摘要

外部系统集成工具

• google_calendar_add：向 Google 日历添加事件
• github_create_pr：创建 GitHub Pull Request，并做校验

安装

pip install -r requirements.txt
​

配置

1. 把 env.example 复制为 .env：

cp env.example .env
​

2. 配置你的环境变量：

# LLM Configuration (for safety checks and summarization)
PROVIDER=kimi

# API Keys (set the one for your provider)
KIMI_API_KEY=your_kimi_key
# SILICONFLOW_API_KEY=your_siliconflow_key
# DOUBAO_API_KEY=your_doubao_key
# OPENROUTER_API_KEY=your_openrouter_key

# Model (optional, defaults to provider's default)
# MODEL=kimi-k3

# Model parameters
TEMPERATURE=0.7
MAX_TOKENS=4096

# External Services (optional)
GOOGLE_CALENDAR_CREDENTIALS_FILE=credentials.json
GITHUB_TOKEN=your_github_token

# Safety Settings
REQUIRE_APPROVAL_FOR_DANGEROUS_OPS=true
AUTO_SUMMARIZE_COMPLEX_OUTPUT=true
AUTO_VERIFY_CODE=true
​

支持的提供商：

• siliconflow：Qwen/Qwen3-235B-A22B-Thinking-2507
• doubao：doubao-seed-1-6-thinking-250715
• kimi/moonshot：kimi-k3
• openrouter：google/gemini-3.5-flash（或 openai/gpt-5.6-luna、anthropic/claude-sonnet-4.6）

通用 OpenRouter 回退：当所配置 PROVIDER 的 key 缺失、但设置了
OPENROUTER_API_KEY 时，LLM 步骤（审批、摘要、错误/语法分析）会通过
Config.effective_provider() 透明地切到 openrouter。为 OpenRouter
设置 MODEL 时请使用 provider/model 形式的 id，例如
MODEL=openai/gpt-5.6-luna。

用法

命令行入口 (CLI)

cli.py 是统一的命令行入口，用于列出、单独调用每个执行工具，并运行端到端演示。
它复用与 MCP 服务器相同的工具实现，因此行为完全一致。

# 查看总帮助与所有子命令
python cli.py --help

# 列出所有执行工具
python cli.py list

# 端到端离线演示（推荐先看这个；无需 API key 即可运行）
python cli.py demo

# 单独调用某个工具
python cli.py code --language python --code "print(2 ** 10)"
python cli.py shell "python3 --version"
python cli.py write --path notes.txt --content "hello" --overwrite
python cli.py edit --path notes.txt --search hello --replace world
​

全局开关（放在子命令之前）：

离线运行：list、demo 以及关闭了审批/总结/非 Python 校验的
code/shell/write/edit 均无需 API key。需要 API key 的场景为：LLM 事前审批、
长输出的 LLM 总结、非 Python 语法校验。calendar 与 pr 还额外需要相应外部凭据。

长输出的截断与持久化：当 code_interpreter / virtual_terminal 的输出
超过阈值（默认 200 行或 10000 字符）时，工具只在上下文中保留头尾各 50 行，
完整输出落盘到临时文件，并在返回值的 stdout_file / stderr_file 字段给出路径。
该机制不依赖 LLM，可离线工作。

运行 MCP 服务器

python server.py
​

配合 MCP 客户端使用

from mcp import Client

# Connect to the MCP server
client = Client("stdio://python server.py")

# Use file write tool
result = await client.call_tool("file_write", {
    "path": "test.py",
    "content": "print('Hello, World!')"
})

# Use code interpreter
result = await client.call_tool("code_interpreter", {
    "code": "import math\nprint(math.sqrt(16))"
})

# Use virtual terminal
result = await client.call_tool("virtual_terminal", {
    "command": "ls -la"
})
​

单独测试某个工具

# Test file operations
python test_file_tools.py

# Test execution tools
python test_execution_tools.py

# Test external integrations
python test_external_tools.py
​

架构

服务器采用分层架构：

1. 安全层：拦截并校验危险操作
2. 工具层：实现各个工具的具体逻辑
3. 校验层：校验输出并给出反馈
4. 集成层：对接外部服务

示例

完整用法示例见 examples.py。

实验 4-2：执行工具 MCP 服务器

本项目对应书中第 4 章「执行工具」一节的实验 4-2，聚焦执行工具的安全机制：
分层安全防护（输入验证、权限控制、LLM 事前审批）、自动语法验证与反馈闭环、
以及长输出的截断与持久化。推荐从 python cli.py demo 开始。