📚 首页 / 06-mcp/labs / lab.md

Lab 06 — MCP 动手实验

环境：uv（推荐，免预装依赖）或 pip install mcp（Python 3.10+）。本模块示例实测环境：mcp SDK 2.1.1。 来源: https://github.com/modelcontextprotocol/python-sdk、https://py.sdk.modelcontextprotocol.io/client/（访问于 2026-08-30）

Lab A：跑通三方架构与三大原语 ✅（无需 key）

cd 06-mcp/examples
uv run --with mcp python 01_server_primitives_demo.py

对照输出完成：

  1. 找到 protocol_version 输出（应为 2026-07-28）——这是 SDK 自动协商的结果（Modern 规范：无 initialize 握手）
  2. tools/list 返回了什么？host 为什么需要这一步才能组装 Claude API 的 tools 参数？
  3. resources/templates/list 里 catalog://{section} 是 Resource Template（RFC 6570 URI 模板）；把 resources/read 的调用换成一个不存在的 section，观察行为
  4. prompts/get 渲染出的消息是给谁的？（提示：prompts 是 user-controlled，由用户触发）

验收：能口头回答——tools / resources / prompts 各自由谁控制？

Lab B：工具错误是「对话的一部分」 ✅（无需 key）

uv run --with mcp python 02_tool_error_handling.py

观察四段输出（成功 / ToolError / 未知工具 / 修复后重试），回答：

  1. 业务错误与协议错误的区别体现在哪？（is_error=True + content 里的错误文本 vs 抛异常）
  2. server 端抛 ToolError 时为什么要把「已知 SKU 列表」写进错误消息？（修复式重试的线索）
  3. host 侧消费结果的正确顺序是什么？（先查 is_error，再信任结构化数据）

对照规范：tools/call 结果携带 isError 标志。 来源: https://modelcontextprotocol.io/specification/2026-07-28/server/tools（访问于 2026-08-30）

Lab C：量化「工具定义吃上下文」 ✅（无需 key）

uv run --with mcp python 03_context_cost_simulator.py

两个场景（12 工具 vs 210 工具）输出后：

  1. 210 工具场景全量注入占了窗口的多少？超过官方建议的切换阈值（窗口的 1%–5%）了吗？
  2. 打开脚本，把 task_needs 改成 1 或 10 再跑——progressive discovery 的成本对任务用到的工具数敏感吗？
  3. 把 servers 字典改成你想象的真实公司栈（如 crm 20 + wiki 50 + helpdesk 80），估算你们要治理到什么程度

对照官方数据点：上百工具全量定义 ~150,000 tokens vs 渐进式 ~2,000 tokens。 来源: https://modelcontextprotocol.io/docs/2026-07-28/develop/clients/client-best-practices（访问于 2026-08-30）

Lab D：扩展你自己的 server ✅（无需 key，动手编码）

把 01_server_primitives_demo.py 复制到 /tmp/my_server.py（不要改 examples 原文件），然后：

  1. 加一个带枚举语义参数的 tool（如 check_order_status(order_id: str, verbose: bool = False)），未知 order_id 时抛带修复线索的 ToolError
  2. 加一个 Resource Template（如 orders://{customer_id}）
  3. 加一个 Prompt 模板（如 summarize_orders(period: str)）
  4. 跑通后在 main 里对每个新原语做一次 list + 调用

参考 API：@mcp.tool()、@mcp.resource("scheme://{param}")、@mcp.prompt()、from mcp.server.mcpserver.exceptions import ToolError。 来源: https://github.com/modelcontextprotocol/python-sdk（访问于 2026-08-30）

验收：故意调用未知 order_id，确认输出是 is_error=True 而不是崩溃。

Lab E：MCP connector（静态阅读 / 可选实跑 🔑）

  1. 静态阅读 04_mcp_connector_api.py，找出三个组件：mcp_servers 定义、mcp_toolset 工具配置、beta header mcp-client-2025-11-20
  2. 对照官方文档列出它的限制：只支持 tool 调用（无 resources/prompts）、server 必须公网 HTTP（Streamable HTTP 与 SSE）、stdio 不可直连

    3. 来源: https://platform.claude.com/docs/en/agents-and-tools/mcp-connector（访问于 2026-08-30）

  3. （可选，需 ANTHROPIC_API_KEY + 一个公网 MCP server）按文件头注释的 env vars 实跑；没有 server 可用时可参考官方文档中的 https://example-server.modelcontextprotocol.io/sse 示例形态

完成标准

📚 目录