todo-full · 串起手册要点的完整示例

一个 todo list，两条路对比实现，接真 DeepSeek。用一份可运行代码把 MCP 全套手册的要点串起来。

覆盖的要点

• 三原语：MCP server 里 Tools + Resources + Prompts 都有
• function calling：MCP client 把工具翻译成 DeepSeek 的 tools，跑工具循环
• JSON-RPC 原始消息：VERBOSE=1 打印底层 tools/call 请求与响应
• 手搓 vs MCP：manual_way.py 是不用 MCP 的对照组
• 换个 Host 也能跑：同一个 server 经 .mcp.json 接进 Claude Code，代码一行不改

文件

文件	是什么
db.py	共用的 SQLite 数据库层（两条路都调它）
mcp_server.py	路 A：MCP server，三原语齐全
mcp_client.py	路 A：MCP client + DeepSeek 工具循环（主程序）
manual_way.py	路 B：手搓 prompt + 解析 + 分发（对照组）
对照说明.md	代码 ↔ 手册要点的逐条对照
pyproject.toml / uv.lock	uv 项目清单与锁文件，统一管理依赖

跑起来

需要 uv 和一个 DeepSeek API key。

# 首次运行前安装依赖（uv run 也会自动同步，这一步可省略）
uv sync

# 路 A：MCP（主示例）
DEEPSEEK_API_KEY=sk-xxx uv run mcp_client.py

# 路 A + 看底层 JSON-RPC 消息
DEEPSEEK_API_KEY=sk-xxx VERBOSE=1 uv run mcp_client.py

# 路 B：手搓对照
DEEPSEEK_API_KEY=sk-xxx uv run manual_way.py

mcp_client.py 会自动把 mcp_server.py 当子进程拉起（stdio），你不用单独启动它。 依赖统一声明在 pyproject.toml 里，uv run 会按 uv.lock 自动建虚拟环境并安装，无需手动管理。

配合 Claude Code 使用

除了跑 mcp_client.py（自己当 Host+Client），也可以让 Claude Code 直接当 Host 连这个 server —— 同一个 mcp_server.py 一行不用改，这正是「server 不关心对面是谁」的体现。

.mcp.json 已经把它注册好了：

{
  "mcpServers": {
    "todo": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-primer", "mcp_server.py"]
    }
  }
}

在项目目录里启动 claude 即可自动加载，/mcp 面板能看到连接状态和三原语。用法：

• Tools：直接说「加一个任务：写周报」，模型会调 mcp__todo__add_task
• Resources：@todo:todos://all 引用全部任务；todos://{status} 是模板资源， @todo:todos://done / @todo:todos://pending 同样可读（模板资源不会出现在资源列表里，但能直接取）
• Prompts：daily_review 也会一并暴露，具体入口见 /mcp 面板

这条路看不到 JSON-RPC 原始消息

VERBOSE=1 是 mcp_client.py 自己在应用层打印的，走 Claude Code 这条路不生效。Claude Code 的 claude --debug mcp --debug-file <path> 只给连接生命周期的摘要，不含协议报文：

[DEBUG] MCP server "todo": Successfully connected (transport: stdio) in 313ms
[DEBUG] MCP server "todo": Connection established with capabilities: {"hasTools":true,...}
[DEBUG] ToolSearchTool: selected mcp__todo__add_task

实测这份日志里 grep jsonrpc / tools/call / tools/list 命中数为 0。/mcp 面板同理，是状态面板不是协议探针。

想看原始报文，就在 Host 和 server 之间插一层 tee —— stdio 传输本质就是两条管道，原样转发不影响功能：

#!/bin/bash
# mcp_server_debug.sh，记得 chmod +x
DIR="$(cd "$(dirname "$0")" && pwd)"
mkdir -p "$DIR/mcp_logs"
tee -a "$DIR/mcp_logs/in.jsonl" \
  | uv run --directory "$DIR" mcp_server.py \
  | tee -a "$DIR/mcp_logs/out.jsonl"

把 .mcp.json 的 command 指向这个脚本（"command": "/path/to/mcp_server_debug.sh", "args": []），重连后 in.jsonl（Host→server）和 out.jsonl（server→Host）会记下全部方法的报文 —— 不只是 tools/call， initialize、tools/list、resources/read 都在里面，比 VERBOSE=1 只覆盖 tools/call 更全。 日志是追加写且含任务内容，记得加进 .gitignore。

说明

• 数据库文件 todos.db 首次运行自动创建在项目目录，重启后任务不丢。
• 若访问 DeepSeek 需要代理，脚本已带 httpx[socks]，设置 ALL_PROXY 即可。
• mcp 锁在 1.x（mcp>=1.28,<2）：2.0 是大改版、API 不同，示例按 1.x 写。