# Tool Calling 与 MCP 配套指南

2026-09-11，原九篇重组为十一篇，先解释 Function Calling、Tool Calling 与 MCP，再展开契约、执行循环、失败恢复、审批、协议、传输、安全、生产模块和贯穿实战。所有订单、政策和退款回执为教学数据。

本轮没有运行示例、安装依赖、调用模型、启动 Server、执行测试、Astro 检查、构建或预览。以下命令供读者运行，输出描述是源码预期，不是已验证结果。

## 正文目录

1. [Function Calling、Tool Calling 与 MCP：模型怎样使用外部能力](/posts/agent_runtime/5.tool/01-function-tool-and-mcp/)
2. [怎样设计一个好用的工具：名称、参数、结果与业务契约](/posts/agent_runtime/5.tool/02-tool-contracts/)
3. [一次工具调用怎样完成：执行循环、结果回填与多工具协作](/posts/agent_runtime/5.tool/03-execution-loop/)
4. [工具调用失败以后：超时、重试、幂等与取消](/posts/agent_runtime/5.tool/04-failures-and-idempotency/)
5. [工具什么时候可以执行：授权、审批与可恢复工作流](/posts/agent_runtime/5.tool/05-authorization-and-approval/)
6. [为什么需要 MCP：从本地工具到跨应用能力连接](/posts/agent_runtime/5.tool/06-mcp-architecture/)
7. [MCP 不只有工具：Resources、Prompts 与多轮请求](/posts/agent_runtime/5.tool/07-mcp-primitives/)
8. [MCP 怎样连接与授权：stdio、HTTP 和凭据的完整路径](/posts/agent_runtime/5.tool/08-transports-and-authorization/)
9. [接入工具以后，系统多了哪些风险：MCP 与工具安全边界](/posts/agent_runtime/5.tool/09-tool-security/)
10. [生产中怎样设计工具平台：注册、策略、执行与连接管理](/posts/agent_runtime/5.tool/10-production-tool-runtime/)
11. [从头接通一个工具系统：Python 实战与 MCP 源码导读](/posts/agent_runtime/5.tool/11-tools-in-practice/)

## 标准库主线

Python 3.10+。下载入口时同时下载它引用的同目录文件；单独下载一个脚本不会自动获取依赖。

| 文件 | 内容 | 同目录依赖 |
| --- | --- | --- |
| [tool_contracts.py](python/tool_contracts.py) | 参数、归属校验与固定订单 | 无 |
| [tool_loop.py](python/tool_loop.py) | 预置调用、分发、结果回填 | tool_contracts.py |
| [streamed_arguments.py](python/streamed_arguments.py) | 人工流片段缓冲与完成 | 无 |
| [approval_runtime.py](python/approval_runtime.py) | 批准绑定、到期、幂等冲突与模拟账本 | 无 |
| [failure_scenarios.py](python/failure_scenarios.py) | 模拟响应丢失并查询回执 | approval_runtime.py |
| [runtime_registry.py](python/runtime_registry.py) | 只读注册、次数与并发限制 | tool_contracts.py |

```bash
# 无需模型凭据；数据与调用轨迹由作者手工构造。
python tool_loop.py
python approval_runtime.py
python failure_scenarios.py
```

`simulated_submitted` 不是实际退款成功。账本在内存中，不能跨重启保存，不具备跨进程事务与下游幂等保证。布尔类型检查不替代审批身份验证；示例的 authorized/eligible 为明确占位，正式服务必须查询真实权限和业务状态。

## MCP SDK 与进程通信

下载 [mcp-requirements.txt](python/mcp-requirements.txt)、[mcp_server.py](python/mcp_server.py)、[mcp_client_demo.py](python/mcp_client_demo.py) 与 [tool_contracts.py](python/tool_contracts.py)。直接依赖固定 MCP Python SDK 2.1.1，不是完整传递依赖锁文件。

```bash
# 单独建立虚拟环境，避免与其他系列的 SDK 版本混装。
python3 -m venv .venv-tool-mcp
source .venv-tool-mcp/bin/activate
python -m pip install -r mcp-requirements.txt
python mcp_client_demo.py --mode memory
python mcp_client_demo.py --mode stdio
```

内存模式走 SDK 直接分发，没有真实 JSON-RPC 帧传输；stdio 模式会启动子进程并传递协议消息。二者都没有调用语言模型。Server 绑定固定教学主体，只适用于本地单用户数据演示，没有实现远程认证或多用户授权中间件。

工具返回预期包含 A1042、签收十天与质量尚未核实；Resource 返回 P7-v2 教学条款，Prompt 返回建议消息。原 [test_mcp_server.py](python/test_mcp_server.py) 保留为内存演示兼容入口，不称为完整测试套件。

## 可选真实模型接入

[claude_tool_loop.py](python/claude_tool_loop.py) 使用标准库请求 Claude Messages API，需要 ANTHROPIC_API_KEY 与 TOOL_MODEL。型号由读者选择其有权限且支持工具的模型，本文不硬编码最新型号。不要将凭据写入正文、日志或提交到仓库。

```bash
# 先在本地安全设置 ANTHROPIC_API_KEY 与 TOOL_MODEL，再运行。
# 此入口会发送真实模型请求，可能产生费用；工具数据仍然是教学数据。
python claude_tool_loop.py
```

此入口还需要 tool_contracts.py。它使用非流式 Messages API，处理普通客户端 tool_use/tool_result，限制轮数与调用次数；不是全功能生产模型适配器。超时停止等待不保证远端任务已经取消。

[mcp_model_bridge.py](python/mcp_model_bridge.py) 将相同模型循环的执行器替换为 stdio MCP。需同时下载 claude_tool_loop.py、mcp_client_demo.py、mcp_server.py、tool_contracts.py，并安装 MCP 依赖。

```bash
# 真实模型 + 真实 stdio 通信；只允许两个只读教学工具。
python mcp_model_bridge.py
```

桥接会发现并筛选工具，映射 Schema、参数与结构化结果。没有暴露退款执行工具。MCP 返回错误会保留错误语义；第三方复杂 Schema、多模态结果及完整 OAuth 需要另外适配。

## LangGraph 审批入口

[safe_tool_graph.py](python/safe_tool_graph.py) 保留 interrupt/Command 演示，需同目录 approval_runtime.py，以及原 [requirements.txt](python/requirements.txt) 中框架依赖。原文件声明 LangChain 1.3.17、LangGraph 1.2.11、MCP 2.1.1，本轮未安装或验证它们的完整组合。

本次修正了字符串布尔转换、订单号作为唯一幂等键和 exactly-once 表述。示例通过固定 True 模拟人类批准；并未实现真实审批 UI、身份认证、数据库持久化或支付网关。

## 固定版本源码阅读

[sdk_inspect.py](python/sdk_inspect.py) 需要 MCP 依赖、mcp_server.py 和 tool_contracts.py。它打印安装包来源位置与工具 Schema，再直接调用 Server；不验证传输或授权。

阅读路径：

1. [MCPServer 注册与协议转换](https://github.com/modelcontextprotocol/python-sdk/blob/v2.1.1/src/mcp/server/mcpserver/server.py)。
2. [Tool.from_function 与执行](https://github.com/modelcontextprotocol/python-sdk/blob/v2.1.1/src/mcp/server/mcpserver/tools/base.py)。
3. [ToolManager 名称查找与分发](https://github.com/modelcontextprotocol/python-sdk/blob/v2.1.1/src/mcp/server/mcpserver/tools/tool_manager.py)。
4. [Client 连接与请求](https://github.com/modelcontextprotocol/python-sdk/blob/v2.1.1/src/mcp/client/client.py)。

源码阅读聚焦这一条路径，没有宣称已审计 SDK 全部实现或运行兼容测试。

## Java 示例

保留 [Java README](java/README.md)、[pom.xml](java/pom.xml)、[SafeToolAgentDemo.java](java/src/main/java/dev/elaine/examples/SafeToolAgentDemo.java) 与 [McpClientRegistrationDemo.java](java/src/main/java/dev/elaine/examples/McpClientRegistrationDemo.java)。固定 AgentScope Java 2.0.0 的既有接入方式，本轮未编译或连接验证。

Java 只读示例限定固定教学订单，避免让格式正确的任意编号都返回虚构记录。它没有真实认证；MCP 入口需要 Python 解释器安装对应依赖。工具注册不等于已经运行模型 Agent 循环。

## 协议来源与迁移

- [MCP 版本](https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning)：正文以 2026-07-28 为基线，旧握手另作兼容说明。
- [传输](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports)、[授权](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)：区分 stdio、HTTP 和凭据边界。
- [Python SDK](https://py.sdk.modelcontextprotocol.io/)、[错误处理](https://py.sdk.modelcontextprotocol.io/servers/handling-errors/)、[多轮请求](https://py.sdk.modelcontextprotocol.io/handlers/multi-round-trip/)：对应实现机制。
- [Claude 工具使用](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)、[LangGraph 中断](https://docs.langchain.com/oss/python/langgraph/interrupts)：模型与审批接口。

旧路线转到第一篇，Schema 转第二篇，执行循环转第三篇，审批转第五篇；架构与协议边界转第六篇，原语、传输、安全分别转第七至九篇。重试幂等新增第四篇，生产与实战新增第十、十一篇。配置详见[迁移表](/examples/series-migration.json)。

旧链接跳转与导航为源码变更，未经本轮构建或发布，不能描述为已上线。已有其他系列修改保留，未提交 Git。