mcp-multi-poc-alpha

mcp-multi-poc

用于验证如何通过单个 PyPI 包提供多个 MCP 服务的概念验证项目（PoC），通过子命令选择服务，并使用可选 extras 按需安装依赖。 该项目旨在回答 Couchbase MCP 单体仓库相关问题（alpha = operational，beta = analytics，tabulate = analytics SDK — 之所以选择它，是因为它不在 fastmcp 的传递依赖树中；httpx 和 pyyaml 则在其中，会悄然绕过 extras 防护）。

此 PoC 必须回答的问题

#	问题	测试位置
1	两个 MCP 注册表条目能否指向同一个 PyPI 包？	发布 server.alpha.json 和 server.beta.json
2	注册表所有权验证是否接受同一个包 README 中的多个 mcp-name 注释？	上方的两个 HTML 注释
3	注册表架构／验证器是否接受 identifier 中的 extras 语法（mcp-multi-poc[beta]）？	server.beta.json — 如果被拒绝，则改用纯 identifier，并记录无法表达 extras
4	客户端能否根据注册表元数据正确运行子命令形式（uvx mcp-multi-poc alpha）？	从客户端安装两个服务（Claude Desktop / MCP Inspector）
5	是否存在符合架构的方式，运行名称不同于包名的控制台脚本（mcp-multi-poc-beta）？	server.beta-script.json。5a（失败）：identifier = 脚本名 → 404，identifier 必须是实际的 PyPI 包。5b（当前文件）：identifier = 实际包名，将脚本名作为位置参数 runtimeArgument 混入 → uvx --from 'mcp-multi-poc[beta]' mcp-multi-poc-beta mcp-multi-poc；追加的 identifier 会变成多余参数，服务必须忽略它。如果 5b 也失败，备用方案是为每个脚本使用一个垫片包

目前的发现（2026-07-31）

• Q1 — 每个 PyPI 包对应多个条目：是。 mcp-multi-poc-alpha 已针对共享包发布。
• Q2 — 一个 README 中有多个 mcp-name 注释：是（存在三个注释时，alpha 验证通过）。
• Q3 — identifier 中使用 extras：不行，但可以通过 runtimeArguments 表达。 identifier 中的 extras 会导致字面 PyPI 查询失败 — PyPI package 'mcp-multi-poc[beta]' not found (status: 404)。备用方案可行：mcp-multi-poc-beta 已成功发布，使用纯 identifier: mcp-multi-poc + runtimeArguments: --from "mcp-multi-poc[beta]" （已在注册表上线，并通过 /v0/servers API 验证）。
• Q5a — 将名称不同的控制台脚本用作 identifier：不行（发布时已确认）。 同样会触发 404（'mcp-multi-poc-beta' not found）——注册表会先验证 identifier 是否为实际的 PyPI 包。
• Q5b — 将脚本名作为位置参数 runtimeArgument：可以，已发布。 io.github.nithishr/mcp-multi-poc-beta-script 已上线（发布于 2026-07-31；将 description 缩短至 100 字符上限后发布成功，这是唯一的验证问题）。在本地，uvx --from 'mcp-multi-poc[beta]' mcp-multi-poc-beta mcp-multi-poc 能完成 MCP 初始化握手——末尾的 identifier 会被静默忽略，因为 main() 从不解析 argv。注意事项：仅当入口点能够容忍多余 argv 时才安全（click 需要 ignore_unknown_options + allow_extra_args，或一个虚设的可选参数）；依赖客户端保留 runtimeArguments 的顺序——这是使用最少的元数据路径；注册表 UI 会将 identifier 显示为可运行项。生产环境中，若每个服务使用独立脚本，优先为每个脚本使用一个垫片包（identifier == 脚本名，完全不使用 runtimeArguments）。
• 发现的注册表验证限制： description ≤ 100 字符；identifier 必须是一个字面存在的 PyPI 包（不接受 extras）；不验证 runtimeArguments/packageArguments 的内容。

本地冒烟测试（发布任何内容之前）

cd mcp-registry-poc
uv venv && uv pip install -e .
mcp-multi-poc alpha          # starts alpha on stdio (Ctrl+C to exit)
mcp-multi-poc beta           # must FAIL with the friendly extras message
uv pip install -e ".[beta]"
mcp-multi-poc beta           # now starts
mcp-multi-poc                # bare command runs alpha (backward-compat check)
mcp-multi-poc-beta           # Option 1 script works locally once extra installed

发布到 PyPI 后的 uvx 行为：

uvx mcp-multi-poc alpha                  # base only
uvx "mcp-multi-poc[beta]" beta           # extras via uvx — key UX under test
uvx --from "mcp-multi-poc[beta]" mcp-multi-poc-beta   # Option 1 fallback form

发布步骤（手动，按顺序）

1. 如果 PyPI 上已有人使用 mcp-multi-poc，请选择其他名称并统一重命名 （pyproject 中的 name、[project.scripts]，以及两个 server.json 标识符）。
2. 构建并发布到正式 PyPI（注册表验证会从 pypi.org 获取；TestPyPI 不可用）：uv build && uv publish。
3. 安装 mcp-publisher 并登录： mcp-publisher login github（交互式）——必须与 io.github.<username> 命名空间匹配。
4. 发布条目： mcp-publisher publish server.alpha.json、... server.beta.json 和 ... server.beta-script.json——最后一个预期会验证失败； 记录准确的错误信息（如果 CLI 要求文件位于 ./server.json，请先依次将每个文件复制到该位置）。
5. 通过注册表 API 验证： curl "https://registry.modelcontextprotocol.io/v0/servers?search=mcp-multi-poc"
6. 根据注册表元数据在客户端中配置这两个服务，并调用 echo（alpha）和 make_table（beta）。
7. 记录上方各问题的结果，然后弃用或删除 PoC 条目。

Q4 — 从客户端测试已发布的条目

大多数客户端尚不能直接从官方注册表安装，因此 Q4 分为两部分：（a）规范要求的命令构造方式 （uvx <runtimeArguments> <identifier> <packageArguments>）能否生成可正常运行的 服务；（b）使用注册表的客户端是否会以相同方式构造命令。

1. 获取实际发布的内容并检查 packages 区块： curl "https://registry.modelcontextprotocol.io/v0/servers?search=mcp-multi-poc"
2. MCP Inspector——针对手动组装的命令进行交互式工具调用：

   npx @modelcontextprotocol/inspector uvx mcp-multi-poc alpha
   npx @modelcontextprotocol/inspector uvx --from "mcp-multi-poc[beta]" mcp-multi-poc beta
   

3. Claude Code——使用与 stdio 服务相同的命令，然后调用 echo / make_table：

   claude mcp add poc-alpha -- uvx mcp-multi-poc alpha
   claude mcp add poc-beta -- uvx --from "mcp-multi-poc[beta]" mcp-multi-poc beta
   

   （对于 Claude Desktop，对应的 claude_desktop_config.json 条目如下：）

   {
     "mcpServers": {
       "poc-alpha": { "command": "uvx", "args": ["mcp-multi-poc", "alpha"] },
       "poc-beta":  { "command": "uvx", "args": ["--from", "mcp-multi-poc[beta]", "mcp-multi-poc", "beta"] }
     }
   }
   

4. 通过注册表原生安装（真正的（b）测试）：VS Code 的 MCP 服务 库由官方注册表提供支持——在那里搜索 mcp-multi-poc 并安装；这将测试客户端是否会自行组装 runtimeArguments + identifier + packageArguments。条目可能会延迟显示，或在显示前经过筛选。

步骤 2–3 只能证明（a）；只有步骤 4（或其他使用注册表的客户端） 才能证明（b），而 beta/beta-script 条目实际上依赖的正是这一点。