MCP 服务器 + 客户端

PersonalKB：一个真正的模型上下文协议（MCP）服务器，提供笔记搜索和实时天气查询，以及一个与之通信的客户端/代理。MCP 协议层从未被模拟：每个测试都会启动一个真实的服务器子进程，并通过它进行真实的 JSON-RPC 通信，要么通过 stdio，要么通过真实 HTTP。唯一在离线状态下被伪造的是 LLM 自身的工具选择决策；除最后的 --real 标志外，运行这里的任何内容都不需要 API 密钥。

问题： 用手工编写的 JSON 数据块把模型接到工具上，这种方法在需要第二个客户端、远程服务器或别人的工具之前是可行的。MCP 是 Anthropic 的开放标准，规定了模型如何通过真实的线上协议发现和调用工具、读取资源以及使用提示词模板。本项目基于该协议构建了一个真实服务器，从装饰器一直到可工作的客户端桥接和代理循环。

展示的技能： 使用 FastMCP 构建 MCP 服务器（工具、资源、提示词），stdio 和 streamable-HTTP 两种传输，一个通过协议实时发现工具的客户端桥接，一个离线确定性工具路由器，以及一个针对 Claude API 的真实代理循环，SQLite 全文搜索（FTS5），以及针对真实协议流量的 pytest（无模拟）。

技术栈： Python 3.10+、mcp SDK（FastMCP）、SQLite（标准库）、用于真实代理路径的 Anthropic SDK、用于实时天气（Open-Meteo）的 requests、pytest。

它暴露了什么

运行 mcp_kb.server 会启动一个 MCP 服务器 PersonalKB，它基于存储在 SQLite 中并带有全文搜索的笔记运行：

• 工具：search_notes(query, limit)、add_note(title, body, tags)、 list_tags()、get_weather(city)。

• 资源：note://{note_id}（获取一条笔记），notebook://summary（整个 笔记本的摘要）。

• 提示词：research_prompt(topic)，一个可复用的提示词模板。

Related MCP server: MCP Apple Notes

运行它

python -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python generate_data.py           # seeds data/notes.db with 15 hand-written notes

python -m mcp_kb tools                                  # list tools/resources/prompts
python -m mcp_kb ask "find notes about python"
python -m mcp_kb ask "what's the weather in Paris"
python -m mcp_kb serve                                  # run the server directly (stdio)
python -m mcp_kb serve --http                            # or over streamable-HTTP

pytest -q                          # the full suite, all real protocol traffic, no key needed

ask 会启动真实服务器，通过 MCP 实时发现其工具，并默认使用离线确定性路由器回答你的问题，或者通过 --real 使用真实的 Claude API（需要在 .env 中提供 ANTHROPIC_API_KEY）。

它是如何组合在一起的

mcp_kb/
├── db.py         SQLite + FTS5 notes store: search, add, tags
├── weather.py     an offline table, or real keyless Open-Meteo data with --live-weather
├── server.py      the actual MCP server (FastMCP-based): tools, resources, a prompt
├── bridge.py       the MCP client wrapper: discovers tools/resources/prompts live
├── llm.py         the offline deterministic tool-choice router
├── agent.py        the agentic loop: offline router, or a real Claude tool-use loop
└── cli.py           python -m mcp_kb tools|ask|serve
tests/                41 tests, all real protocol traffic (stdio and HTTP), no mocking

关键的设计选择是：server.py 是对 db.py 和 weather.py 的薄封装；MCP 层的唯一职责是在协议与普通 Python 函数之间进行转换。正是这种拆分，使得底层逻辑可以在零协议开销的情况下进行测试，而协议层本身也在每个测试中得到了真实的验证。

连接真实的 MCP 客户端

同一个服务器也可以原样运行在真正的 Claude Desktop 应用内：将其 MCP 配置指向 python -m mcp_kb serve，它就能在普通聊天中搜索你的笔记或查看天气，调用 server.py 中定义的完全相同的工具。连接步骤以及将 HTTP 传输部署到远程客户端可访问位置的方法，请参阅 hosting/HOSTING_GUIDE.md。

我学到了什么

• MCP 将 工具做什么 与 客户端如何发现并调用它 分开：服务器只需 声明一次工具、资源和提示词，任何符合规范的客户端（手工编写的桥接，或 Claude Desktop）都可以发现并使用它们，而无需定制胶水代码。

• 保持协议层精简，并将逻辑推入普通、可测试的 Python 函数中，这使得测试套件能够运行真实的客户端/服务器流量， 而不会变得缓慢或脆弱。

• stdio 和 streamable-HTTP 只是同一协议下的两种传输方式；服务器暴露的工具、资源和提示词 不会因客户端如何访问它而改变。