Skip to content

feat: request facts, per-request log level and -32021 (T8 follow-ups) - #311

Open
sideeffffect wants to merge 8 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t8-request-facts
Open

sideeffffect wants to merge 8 commits into
softwaremill:2026-07-28-protocol-supportfrom
sideeffffect:feat/t8-request-facts

Conversation

@sideeffffect

@sideeffffect sideeffffect commented Nov 19, 2026 •

Copy link
Copy Markdown

T8 follow-ups — part of #246

Layer 1 of a stack (base 2026-07-28-protocol-support). It adds the request-level rules of 2026-07-28 that #274 left open.

Request facts in the server context

  • New RequestInfo on ServerContext.request: protocol version, client capabilities, client info, log level, progress token.
  • Modern requests take every fact from _meta. New key ProtocolMeta.LogLevel (io.modelcontextprotocol/logLevel, from the schema).
  • Legacy requests: only the version and the progress token. The rest is None, because the server keeps no state from initialize.
  • Plain tools, prompts, resources and resource templates get serverLogicWithContext, so they can read the facts.

Per-request log level

  • For a modern request, ctx.log sends notifications/message only at or above _meta logLevel.
  • With no logLevel it sends nothing: the schema says the server "MUST NOT send any".
  • Legacy requests still get every message.

-32021 MissingRequiredClientCapability

  • A tool declares its needs with tool(...).withRequiredClientCapabilities(ClientCapabilities(...)).
  • A modern tools/call whose _meta.clientCapabilities lacks them is rejected before any logic runs: HTTP 400, plain JSON, data.requiredCapabilities set.
  • Legacy calls are not checked.

server/discover validation

  • A server/discover that declares a version (header or _meta) gets the same checks as other modern requests: -32602 for missing _meta keys, -32022 for an unsupported version, -32020 for a header/_meta mismatch or a wrong Mcp-Method. All HTTP 400.
  • A discover with no version, or a legacy one, is still answered with 200, so a probing client can still discover the server.
  • A header/_meta mismatch is checked before an unsupported version, and a modern HTTP request without MCP-Protocol-Version gets -32020 (both match the harness's own mock server). Stdio is not affected.

Other

  • RequestId accepts ids beyond the Int range. The harness sends id: Date.now(), which the server took for a notification.
  • Conformance server fixtures: test_missing_capability (needs sampling) and test_logging_tool (logs once at every level).
  • The Ox and ZIO HTTP specs (modern client, no logLevel yet) expect no log messages; Pekko (legacy client) still expects them.
  • Docs: docs/server/capabilities.md.

Tests and conformance

  • McpHandlerSpec 43 → 62 tests; red→green shown for the log gate, -32021, the Long id and discover validation. testFull 289 passed, Integration 117 passed.
  • Server conformance 2026-07-28: 117 → 128 checks pass, no regressions. 2025-11-25 unchanged (63 passed). Client conformance unchanged.
  • server-stateless: 24 of 28 checks pass. It stays in the baseline: 3 checks need subscriptions/listen (T16, next layer), 1 needs test_streaming_elicitation (T14).

Not in this PR

  • Rejecting a present-but-malformed logLevel / clientCapabilities with -32602 (today it becomes None).
  • A DSL method that gives secured, non-streaming logic both the principal and the context.
  • The client sending _meta.logLevel (T10–T12).

Stack

  1. this PR — T8 follow-ups
  2. #312 — 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.
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