Repository navigation
feat: notification publisher and subscriptions/listen (T16) - #312
Draft
sideeffffect wants to merge 14 commits into
Draft
sideeffffect wants to merge 14 commits into
sideeffffect wants to merge 14 commits into
Conversation
…Level Add RequestInfo (protocol version, client capabilities, client info, log level, progress token) and expose it as ServerContext.request. The handler builds it once per request and passes it to the transport's context factory, which replaces the bare progress-token argument. A modern (2026-07-28) request takes all facts from _meta. A legacy request gives only the protocol version (header or _meta) and the progress token, because the server keeps no state from initialize. StreamingServerContext.log now follows the per-request log level of a modern request: it sends notifications/message only at or above _meta logLevel, and none when the request sets no level, as the 2026-07-28 spec requires. Legacy requests keep receiving all messages.
…ontext Add serverLogicWithContext to tools, prompts, resources and resource templates. The logic receives the ServerContext, so it can read the request facts (protocol version, client capabilities, client info, log level) without a streaming server. Until now only streaming tools got a context.
A tool can now declare the client capabilities it needs with withRequiredClientCapabilities. When a modern (2026-07-28) tools/call targets such a tool and _meta clientCapabilities does not declare them, the request fails before any logic runs with -32021 MissingRequiredClientCapability, HTTP 400, and data.requiredCapabilities set to the tool's requirement, as the schema requires. The check runs in requestRejection, so a streaming transport answers with plain JSON and not an SSE stream. Capabilities are compared key by key, recursively for nested objects. Legacy requests carry no capabilities, so they are not checked.
RequestId decoded numeric ids only as Int. A request with a larger id (for example a millisecond timestamp, which the conformance harness sends) failed to decode as a request and was taken for a notification, so the server answered with an empty response. RequestId now also holds a Long; small numbers still decode as Int, so existing ids compare equal.
…ce fixtures The server-stateless scenario (2026-07-28) calls test_missing_capability without declaring sampling and expects -32021 with HTTP 400, and calls test_logging_tool without a logLevel and expects no notifications/message. test_missing_capability declares sampling as a required client capability; test_logging_tool logs once at every level and relies on the per-request log gate. Both checks now pass. The scenario stays in the baseline, because it also covers subscriptions/listen and other later work.
Describe ctx.request (RequestInfo) and which facts a modern and a legacy request give, serverLogicWithContext, the logLevel gate on ctx.log for modern requests, and withRequiredClientCapabilities with its -32021 rejection. Add -32021 to the table of modern request errors.
…og level The shared streaming tests run with a legacy client (Pekko) and with a modern 2026-07-28 client (ZIO, Ox). The modern client sends no _meta logLevel yet, so under the per-request log level rule it must receive no notifications/message. Each spec now states its client protocol version, and the log tests expect the messages for a legacy client and none for a modern one. This covers the log gate end to end over HTTP on all three backends.
server/discover was the era-agnostic bootstrap and skipped all checks. A discover that declares a version (in _meta or in the MCP-Protocol-Version header) is now a modern request and gets the same checks: -32602 for missing _meta keys, -32022 with the supported and requested versions for an unsupported version, -32020 for a header that differs from _meta, and the SEP-2243 Mcp-Method check, all with HTTP 400. A discover with no version, or a legacy one, is still answered, so a probing client can discover the server. Two ordering fixes follow the conformance harness: a header/_meta version mismatch is now reported (-32020) before an unsupported _meta version (-32022), and a modern HTTP request without the MCP-Protocol-Version header fails with -32020.
…ling NotificationPublisher lets application code publish tools, prompts and resources list changes and resource updates from any thread. Servers take it with withPublisher. A handler for a transport that can hold a stream open accepts a modern subscriptions/listen request, acknowledges the subset of the filter it honours, tags every message with the subscription id, and ends it with a successful listen result when the publisher closes. Modern discover advertises listChanged and resources.subscribe only when the server can publish them; legacy initialize is unchanged. Without a streaming transport, subscriptions/listen stays -32601.
The streaming HTTP transports answer an accepted subscriptions/listen request with an SSE stream that stays open: the acknowledgement first, then the publisher's notifications that the filter asks for. ZIO, Ox and Pekko each deliver into their own stream and cancel the subscription when the client closes the stream. A subscription is registered before it is acknowledged, and gets no notification before the acknowledgement, so an event published right after the client sees the acknowledgement is not lost. Shared HTTP tests run on all three backends.
All subscriptions of a stdio connection share its output and are told apart by the subscription id. The client ends one with notifications/cancelled naming the listen request. When the input ends, the server ends each open subscription with a successful listen result followed by notifications/cancelled. The sync, Ox, ZIO and Pekko stdio transports share this logic; the ZIO transport now serialises its writes, because notifications can arrive from other threads.
…e conformance fixtures The conformance server publishes tools and prompts list changes from the two fixture tools and closes its subscriptions on shutdown. The five subscriptions/listen checks of server-stateless now pass. The scenario stays in the baseline: only http-server-no-independent-requests-on-stream still fails, because it needs the test_streaming_elicitation tool (T14).
capabilities.md explains how to publish list changes and resource updates, which capabilities follow from a publisher, the listen stream rules over HTTP and stdio, and that a streaming transport is needed. resources.md points modern clients to the resourceSubscriptions filter.
This was referenced Nov 19, 2026
…owledged A subscription sent its acknowledgement first and set its acknowledged flag after. Over stdio the acknowledgement is written and flushed at once, so a client could read it and publish before the flag was set; the event was then dropped. This made the stdio subscription test wait forever for a tools/list_changed notification. Delivery now takes the same lock as the acknowledgement and the final result: an event published while the acknowledgement is on its way waits for it, and no notification follows the final result. A unit test publishes from another thread while the acknowledgement is being sent, which fails without the fix. The stdio tests now read the server output on their own thread and fail after 10 seconds instead of blocking in readLine.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
T16 — closes #254: notification publisher and
subscriptions/listenLayer 2 of a stack. Depends on #311 (T8 follow-ups). Until #311 merges, this diff also shows its commits; the T16 delta alone: sideeffffect/chimp@feat/t8-request-facts...feat/t16-subscriptions-listen
Publishing
withSubscriptionsis already the legacyresources/subscribehandler, so the new builder iswithPublisher.Unit, notF[Unit]. A publisher must work before any transport supplies aMonadError, so a plain thread-safe call was the simplest fit (ZIO:ZIO.succeed(publisher.toolsListChanged())). Happy to change it to an effect-typed API.Capabilities
server/discoveradvertiseslistChangedandresources.subscribeonly when the server has a publisher, a streaming transport and that feature.initializeresult still sayslistChanged: false(legacy clients have no stream for it); legacysubscribestill follows.withSubscriptions.subscriptions/listen_meta["io.modelcontextprotocol/subscriptionId"].resourceSubscriptions.Ending a subscription
notifications/cancelledfor the listen request ends it; at end of stdin each subscription gets a listen result, thennotifications/cancelled(sync, Ox, ZIO, Pekko).publisher.close()ends each subscription with a successful listen result carrying the subscription id (plusnotifications/cancelledon stdio).subscriptions/listen→-32601/ HTTP 404, and no list changes are advertised.resources/subscribe/resources/unsubscribeare unchanged.Race fix (
0654f6b)acknowledge()set its flag only after sending, anddeliverdropped events until then.delivernow takes the same lock asacknowledgeandend, so such an event waits for the acknowledgement. ANotificationPublisherSpectest reproduces the race deterministically (failed every time before, 30/30 after).ServerStdioTransportTestsreads server output on a separate thread and fails after 10 s instead of blocking forever inreadLine.Tests, conformance, docs
NotificationPublisherSpec(11),McpServerSubscriptionHttpTests(3, on ZIO, Ox, Pekko), 2 newServerStdioTransportTests(sync, Ox, ZIO, Pekko).testFull318 passed, Integration passed.test_trigger_tool_change,test_trigger_prompt_change; callspublisher.close()on shutdown.server-statelesspasses 29/30; the last check needstest_streaming_elicitation(T14, #252), so it stays in the baseline.docs/server/capabilities.md(publishing and subscriptions),docs/server/resources.md.ServerStreamingHttpTransportgets a newprivate[server]abstract methodsubscriptionStream, so an HTTP backend outsidechimp.servercan no longer implement it.Stack
subscriptions/listenx-mcp-header