mcp-resource-subscribe-test

最小化的 MCP Streamable HTTP 服务器，用于测试 MCP 客户端是否正确处理 resources/subscribe 和 notifications/resources/updated。

此存储库旨在作为 CLI AI 代理（如 Codex CLI、Gemini CLI、OpenCode、GitHub Copilot CLI、Claude Code、Goose 和 Crush）的可复现问题/兼容性实验室。

目的

服务器公开了一个固定的 MCP 资源：

test://review/status

初始内容：

status: pending
version: 1
message: Waiting for simulated review result.

在客户端订阅该资源后，服务器会等待 MCP_TEST_UPDATE_DELAY_SECONDS，更改资源，并发送：

{
  "method": "notifications/resources/updated",
  "params": {
    "uri": "test://review/status"
  }
}

更新后的内容：

status: reviewed
version: 2
message: Simulated review result is now available.

Related MCP server: mcp-hello-world

为什么使用 Resources/Subscribe 而不是 Tools/Call

tools/call 对于显式操作很有用，但许多代理工作流依赖于在原始请求之后发生变化的上下文。轮询每个源既嘈杂又依赖于特定客户端。MCP 资源订阅为客户端提供了一种协议级的方法，以了解已知的上下文对象已更改并应重新读取。

订阅行为至关重要的示例：

• Copilot 审查结果

• PR 审查线程

• CI 状态

• Codecov 评论

• GitHub 问题讨论

• 本地构建/测试结果

此测试服务器专注于客户端是否注意到资源更新、重新运行 resources/read，并在代理循环/模型上下文中反映新内容。

启动

docker compose up --build

MCP URL：

http://127.0.0.1:8089/mcp

用于本地开发：

npm install
npm run dev

配置

如果 MCP_TEST_SEND_LIST_CHANGED=true，服务器也会在模拟更新后发送 notifications/resources/list_changed。

预期的客户端行为

理想的 MCP 客户端应遵循此流程：

initialize
  ↓
resources/list
  ↓
resources/read test://review/status
  ↓
resources/subscribe test://review/status
  ↓
receive notifications/resources/updated
  ↓
resources/read test://review/status again
  ↓
reflect updated status: reviewed in agent context

服务器功能

初始化响应声明了：

{
  "resources": {
    "subscribe": true,
    "listChanged": true
  }
}

已实现的 MCP 消息

• initialize

• resources/list

• resources/read

• resources/subscribe

• resources/unsubscribe

• notifications/resources/updated

• 当 MCP_TEST_SEND_LIST_CHANGED=true 时发送 notifications/resources/list_changed

未实现任何工具。

日志

服务器记录每条重要消息，以便客观地检查客户端行为：

[initialize] client connected
[resources/list] requested
[resources/read] uri=test://review/status version=1
[resources/subscribe] uri=test://review/status
[resource/update] uri=test://review/status version=2
[notification/send] notifications/resources/updated uri=test://review/status
[resources/read] uri=test://review/status version=2
[resources/unsubscribe] uri=test://review/status

资源订阅支持的关键证据是：

resources/subscribe was received
notification was sent
resources/read was received again after the notification

测试

npm test

测试套件验证：

• resources/list 返回 test://review/status

• 初始 resources/read 返回版本 1

• resources/subscribe 触发内部更新至版本 2

• 接收到 notifications/resources/updated

• 更新后的 resources/read 返回版本 2

客户端兼容性说明

Codex CLI

• MCP 连接：

• 是否调用 resources/list？

• 是否调用 resources/read？

• 是否调用 resources/subscribe？

• 是否接收到 notifications/resources/updated？

• 更新后是否重新读取资源？

• 说明：

Gemini CLI

• MCP 连接：

• 是否调用 resources/list？

• 是否调用 resources/read？

• 是否调用 resources/subscribe？

• 是否接收到 notifications/resources/updated？

• 更新后是否重新读取资源？

• 说明：

OpenCode

• MCP 连接：

• 是否调用 resources/list？

• 是否调用 resources/read？

• 是否调用 resources/subscribe？

• 是否接收到 notifications/resources/updated？

• 更新后是否重新读取资源？

• 说明：

GitHub Copilot CLI

• MCP 连接：

• 是否调用 resources/list？

• 是否调用 resources/read？

• 是否调用 resources/subscribe？

• 是否接收到 notifications/resources/updated？

• 更新后是否重新读取资源？

• 说明：

Claude Code

• MCP 连接：

• 是否调用 resources/list？

• 是否调用 resources/read？

• 是否调用 resources/subscribe？

• 是否接收到 notifications/resources/updated？

• 更新后是否重新读取资源？

• 说明：

Goose

• MCP 连接：

• 是否调用 resources/list？

• 是否调用 resources/read？

• 是否调用 resources/subscribe？

• 是否接收到 notifications/resources/updated？

• 更新后是否重新读取资源？

• 说明：

Crush

• MCP 连接：

• 是否调用 resources/list？

• 是否调用 resources/read？

• 是否调用 resources/subscribe？

• 是否接收到 notifications/resources/updated？

• 更新后是否重新读取资源？

• 说明：