Skip to content

feat: notification publisher and subscriptions/listen (T16) - #312

Draft
sideeffffect wants to merge 14 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t16-subscriptions-listen
Draft

sideeffffect wants to merge 14 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t16-subscriptions-listen

Conversation

@sideeffffect

@sideeffffect sideeffffect commented Nov 19, 2026 •

Copy link
Copy Markdown

T16 — closes #254: notification publisher and subscriptions/listen

Layer 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

final class NotificationPublisher: // chimp.server
  def toolsListChanged(): Unit
  def promptsListChanged(): Unit
  def resourcesListChanged(): Unit
  def resourceUpdated(uri: String): Unit
  def close(): Unit // ends every open subscription gracefully

// on McpServer, StreamingMcpServer, SecuredMcpServer, SecuredStreamingMcpServer
def withPublisher(publisher: NotificationPublisher)
  • The publisher is thread-safe and works from anywhere in the application, not only inside a tool call.
  • withSubscriptions is already the legacy resources/subscribe handler, so the new builder is withPublisher.
  • Open for review: the publish methods return Unit, not F[Unit]. A publisher must work before any transport supplies a MonadError, 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/discover advertises listChanged and resources.subscribe only when the server has a publisher, a streaming transport and that feature.
  • The legacy initialize result still says listChanged: false (legacy clients have no stream for it); legacy subscribe still follows .withSubscriptions.

subscriptions/listen

  • The acknowledgement is the first message; its filter keeps only the requested types the server can send.
  • Every message carries _meta["io.modelcontextprotocol/subscriptionId"].
  • Resource updates go only to the URIs in resourceSubscriptions.
  • Progress and log messages never go on a listen stream.
  • Several subscriptions can be open at once. A subscription is registered before it is acknowledged, so no event is lost right after the acknowledgement.

Ending a subscription

  • HTTP: closing the response stream cancels it (ZIO, Ox, Pekko). Pekko notices the close only on its next write to that stream.
  • stdio: notifications/cancelled for the listen request ends it; at end of stdin each subscription gets a listen result, then notifications/cancelled (sync, Ox, ZIO, Pekko).
  • publisher.close() ends each subscription with a successful listen result carrying the subscription id (plus notifications/cancelled on stdio).
  • Sync HTTP cannot hold a stream: subscriptions/listen → -32601 / HTTP 404, and no list changes are advertised.
  • Legacy resources/subscribe / resources/unsubscribe are unchanged.

Race fix (0654f6b)

  • An event published while the acknowledgement was being sent could be dropped: acknowledge() set its flag only after sending, and deliver dropped events until then. deliver now takes the same lock as acknowledge and end, so such an event waits for the acknowledgement. A NotificationPublisherSpec test reproduces the race deterministically (failed every time before, 30/30 after).
  • ServerStdioTransportTests reads server output on a separate thread and fails after 10 s instead of blocking forever in readLine.

Tests, conformance, docs

  • New: NotificationPublisherSpec (11), McpServerSubscriptionHttpTests (3, on ZIO, Ox, Pekko), 2 new ServerStdioTransportTests (sync, Ox, ZIO, Pekko). testFull 318 passed, Integration passed.
  • Conformance server: fixtures test_trigger_tool_change, test_trigger_prompt_change; calls publisher.close() on shutdown.
  • Server conformance 2026-07-28: 128 → 133 checks pass, no regressions. server-stateless passes 29/30; the last check needs test_streaming_elicitation (T14, #252), so it stays in the baseline.
  • Docs: docs/server/capabilities.md (publishing and subscriptions), docs/server/resources.md.
  • ServerStreamingHttpTransport gets a new private[server] abstract method subscriptionStream, so an HTTP backend outside chimp.server can no longer implement it.

Stack

  1. #311 — T8 follow-ups
  2. this PR — T16 subscriptions/listen
  3. #313 — T14 part 1: input-required outcomes
  4. #314 — T14 part 2: request-state signer
  5. #315 — T13 x-mcp-header
  6. #316 — T10 client stateless lifecycle
  7. #317 — T12 client HTTP request headers
  8. #318 — T11 client automatic era detection

…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.
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant