[debugmcpdev]

Summary

PR 1 of 5 for #1025 step 2 (protocol 2026-07-28 beside 2025-11-25; plan and decisions on the issue). A pure refactor: the wire is unchanged, both transports still speak the 2025-11-25 era, and http still builds one core per MCP session.

The v2 SDK's 2026-07-28 serving entries build a Server per HTTP request (createMcpHandler) or per stdio connection plus a discarded probe instance (serveStdio), so nothing that outlives a request can hang off the SDK Server. Today DebugMcpServer is one object: SDK Server + dependency container + SessionManager + logger. This PR splits it.

• DebugMcpServer is the core. The dependency container, the SessionManager, the per-process services, the mode-gated instructions and the new NotificationHub. It constructs no SDK Server any more.
• createProtocolServer(core, { era, deliver }) (src/server/protocol-facade.ts) builds the SDK Server: the eight MCP handlers closing over the core, the onerror/oninitialized hooks (the [MCP Server] Client initialized line is unchanged), and one notification sink that is attached at construction and removed on server.onclose. deliver: 'external' (the future per-request HTTP instance) attaches none. The SDK's createMcpHandler chains onclose rather than replacing it, so the hook survives the serving entries.
• NotificationHub (src/server/notification-hub.ts) replaces the per-server OutputResourceNotifier: one process-wide 150 ms coalescer per output URI, fanned out to every attached sink. A legacy facade filters pings by its own resources/subscribe set (FacadeSubscriptions); a modern pin will send every URI and let the SDK's listen router filter. create_debug_session, child adoption and session removal all notify through the hub.
• The tools/call dispatch index is built once per core (a WeakMap keyed on the ToolContext), not per facade, so a facade costs a few closures. Measured in the facade suite: a second facade over a built core stays well under the 20 ms bound.
• stdio-command / http-command take an injected protocolServerFactory (default createProtocolServer) and connect the facade to the transport where they connected debugMcpServer.server before.

Tests

• New: tests/core/unit/server/notification-hub.test.ts (11) and protocol-facade.test.ts (10): coalescing per URI, fan-out, sink removal on close, filtered vs unfiltered sinks, no sink for external delivery, the eight handlers, the hooks, the cost bound.
• The server unit suites build the core with one facade through the helper createDebugServerWithFacade; server-initialization now pins that the core builds no Server; the stdio/http unit suites pin the facade wiring.
• Gates run locally: typecheck:all 0 errors (ratchet 0/0), lint, unit 411 files / 8222 passed, integration tests/integration/cli/ + mcp-server-self-debug 40/40, conformance 7/7 (0.1.16, unchanged), Python stdio smoke (real resources/subscribe + notifications/resources/updated) and HTTP smoke 7/7.

One stated deviation. The hub arms the 150 ms coalescer on every output event and the facade filters when it fires; the old notifier filtered when arming. A client that subscribes inside a 150 ms window after output arrived therefore receives one ping for that output, where before it received none until the next output. The resource did change, so the ping is true; strict equivalence would have coupled the hub to the facades' subscription sets.

Review follow-ups (second commit). A suite drives a real SDK Server/Client pair over the in-memory transport and pins that the facade's sink is detached when either side closes (the chain PR 2's per-process core relies on); the http onclose-before-connect ordering that chain depends on is commented; the release version is read once per core, not per facade; forgetUri guards each sink like the sends; a composed two-facade subscription test; CLAUDE.md and the system overview name the two new modules.

No user-visible change; labelled no-changelog. Next: PR 2 (one shared core per http process, ownership and lifetime).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[debugmcpdev]

Reviewed the core/facade separation, notification fan-out, connection lifecycle and SDK close-chain tests at 91745a9. No blocking code findings. The original head passed all applicable CI checks; current-main validation is required again before merge. This is the first PR in the #1114 → #1115 → #1116 → #1117 → #1118 stack.