delivery-mcp-server

AI-Forward Delivery Leader Build Program 的 PH.02。 一个 MCP（Model Context Protocol）服务器，将 delivery-copilot 的索引项目文档——SOW、状态报告、QBR 笔记、风险登记册——作为工具、一个资源和一条提示暴露出来，任何 MCP 主机（Claude Desktop、Claude Code）都可以直接使用，并且从 PH.01 直接沿用了按账户隔离。

状态

已构建并验证：3 个工具、1 个资源、1 条提示，全部通过真实的 MCP Client 以及 Claude Code 中的 claude mcp add 进行了端到端测试。

MCP 是什么，以及为什么这样构建

MCP 标准化了 主机 应用程序（Claude Desktop、Claude Code）与暴露数据和功能的 服务器 之间的通信方式——一种集成，而不是每个应用一种定制集成。服务器暴露三种不同的原语类型，本构建刻意全部使用这三种类型，以实际动手的方式展示其区别，而不仅仅是描述它：

• 工具 — 模型 在对话过程中决定调用的一种操作，自行选择参数。search_delivery_docs 是本服务器的主要工具。

• 资源 — 应用程序 按 URI 选择加载的只读数据，就像浏览器获取网页一样——而不是模型自行调用的东西。delivery://{account}/{filename} 是本服务器的资源：当您已经知道想要哪个文档时，就获取整个文档。

• 提示 — 人 按名称调用的一条消息模板，类似斜杠命令。draft_status_update 是本服务器的提示：选择一个账户，就会将一条预先写好的指令插入到对话中。

检索/生成分离才是这里真正的架构决策。 delivery-copilot/ask.py 在一个脚本中检索分块 并 调用 Claude 来生成带引用的答案，因为该流水线中没有其他东西是模型。而在 MCP 服务器内部，循环中已经有一个模型——即任何驱动主机对话的模型。因此 search_delivery_docs 只做检索，并将匹配的分块作为数据返回；主机自己的模型读取这些分块，并在工具的 docstring 中内置的引用/拒绝指令的指导下自行起草有依据的答案（这是服务器唯一能留下关于依据来源的指令的地方，因为它不拥有系统提示词）。有一个值得指出的后果：该服务器调用 Claude 的次数为零。 没有 ANTHROPIC_API_KEY，没有计费请求——它只是本地嵌入和向量搜索，正是 ingest.py 已经在做的事情。生成成本完全由主机承担。

隔离从 PH.01 起保持不变。 每个工具都接受一个 account 参数，并且只读取该账户的 Chroma 集合（delivery_docs__<account>）——在此层再次用一个临时第二账户验证：向它提出一个无关的问题（只有 meridian-health 才能回答的问题），返回的只有自己的单条笔记，绝无 Meridian 内容。

仓库布局——为什么这不是离 delivery-copilot 一步之遥的 Python 导入

本仓库对 delivery-copilot 的依赖恰好只有一项：位于 chroma_db/ 的 数据产物，而不是它的代码。没有跨仓库的 pip install -e，也没有共享模块：

• list_accounts() 读取 client.list_collections() 并去除 delivery_docs__ 前缀——完全不需要 data/raw/。

• list_documents(account) 读取该集合的块元数据中已存储的不同 source 值。

• delivery:// 资源通过按原始顺序拼接其分块来重建文档（分块是从 ingest.py 已分配的 source::N 分块 ID 中解析出来的）。

将 DELIVERY_DB_PATH 指向任何已构建的 Chroma 存储（默认：../delivery-copilot/chroma_db，假设两个仓库作为兄弟目录克隆），这个服务器就能工作——在代码上真正自包含、可独立克隆，这与 ai-fundamentals-rig 和 delivery-copilot 彼此独立的方式一致。

一个值得留意的发现（环境）

mcp[cli] 引入了 pyjwt[crypto] → cryptography。cryptography 从 v46.0.4 开始放弃预构建的 x86_64 macOS wheels（此后仅提供 arm64 版本）——在这台（确实是 Intel）机器上安装时，尝试从源代码编译，并在缺少 Rust/OpenSSL 头文件的情况下失败。在 requirements.txt 中将 cryptography==46.0.3 固定为最后一个包含 x86_64 wheel 的版本，完全满足 pyjwt 的 cryptography>=3.4.0 要求。这提醒我们：“pip install” 会默默假设你的 CPU 架构有对应的 wheel——但并非总是如此。

另外：MCP Python SDK 的当前主版本（v2）要求 Python 3.10+；这台机器的系统 Python 是 3.9.6。通过官方 python.org 安装程序安装了 3.13，与系统解释器并存，专门用于本仓库的 .venv。

设置

# needs delivery-copilot's index already built: `python ingest.py` in that repo first
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

运行

手动测试，无需主机——通过一个真实的内存 Client 调用每个工具/资源/提示：

python test_server.py

MCP Inspector（交互式，打开本地 Web UI）：

uv run mcp dev server.py     # or: pip install uv, then the same command

注册到 Claude Code：

claude mcp add delivery-copilot \
  -e DELIVERY_DB_PATH=/absolute/path/to/delivery-copilot/chroma_db \
  -- /absolute/path/to/delivery-mcp-server/.venv/bin/python /absolute/path/to/delivery-mcp-server/server.py

claude mcp list   # confirm it connects

然后，在 Claude Code 对话中：“使用 delivery-copilot MCP 服务器，根据文档，meridian-health 的 Okta 风险由谁负责？” — Claude 会自行调用 search_delivery_docs 并引用返回的内容。

下一步

PH.02 已功能完备：3 个工具、1 个资源、1 条提示，已在本地并通过 Claude Code 进行实测。自然的扩展（非阻塞）：一旦出现第二个真实账户就加入（这里没有任何 meridian-health 特有的东西），并且 PH.03 的智能体式状态/风险代理可以合理地基于 draft_status_update 构建，而不是从头开始。

属于 AI-Forward Delivery Leader Build Program 的一部分。