feat: add v2026-07-28 protocol adapter - #7265
Open
lloydrichards wants to merge 9 commits into
Open
Conversation
🦋 Changeset detectedLatest commit: ebcfcb4 The changes in this PR will be included in the next version bump. This PR includes changesets to release 30 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
Bundle Size AnalysisGenerated from PR build output; treat the content below as untrusted.
|
lloydrichards
force-pushed
the
feat/v2026-07-28
branch
from
August 15, 2026 18:56
70450e1 to
efcac61
Compare
lloydrichards
force-pushed
the
feat/v2026-07-28
branch
from
August 15, 2026 19:04
efcac61 to
dc63469
Compare
lloydrichards
force-pushed
the
feat/v2026-07-28
branch
from
August 15, 2026 19:10
dc63469 to
8066084
Compare
lloydrichards
force-pushed
the
feat/v2026-07-28
branch
from
August 15, 2026 19:14
8066084 to
360788f
Compare
lloydrichards
force-pushed
the
feat/v2026-07-28
branch
from
August 15, 2026 19:35
360788f to
96e534e
Compare
IMax153
reviewed
Aug 16, 2026
IMax153
left a comment
IMax153
left a comment
Member
There was a problem hiding this comment.
@lloydrichards - honestly this looks pretty good to me. The example you provided is quite nice for describing an MCP server.
What is our current test coverage with the 2026-07-28 features? Do we cover the entire spec? Or are we missing pieces currently.
| description: tool.description, | ||
| inputSchema: tool.inputSchema, | ||
| outputSchema: tool.outputSchema, | ||
| outputSchema: Schema.is(McpSchema.Tool.fields.outputSchema)(tool.outputSchema) |
Member
There was a problem hiding this comment.
These schema compilers should be extracted to layer / module scope where possible to avoid re-compiling every time.
Contributor
Author
There was a problem hiding this comment.
addressed with refactor: refinements from feedback
|
@lloydrichards you are a legend, thank you so much! |
Contributor
Author
Previously I was using the test+inspector to verify the v2026-07-28 conformance but I did another audit and added a few explicit spec tests that I was missing with some minor fixes: Test Results: pnpm run test packages/effect/test/unstable/ai/McpServer/v2026_07_28.test.ts
$ vitest packages/effect/test/unstable/ai/McpServer/v2026_07_28.test.ts
DEV v4.1.10 /Users/lloyd/Documents/GitHub/open_effect
✓ effect test/unstable/ai/McpServer/v2026_07_28.test.ts (117 tests) 242ms
✓ Mcp Conformance (2026-07-28) (1)
✓ Base Protocol > General fields (1)
✓ should preserve additional result metadata fields when decoding a result 1ms
✓ Mcp Conformance (2026-07-28) (11)
✓ Base Protocol > Stateless messages (11)
✓ should preserve string and numeric identifiers when requests succeed 10ms
✓ should reject a request when its JSON-RPC version is invalid 8ms
✓ should reject a request when its identifier is not a string or integer 2ms
✓ should return method not found when the requested method is unknown 2ms
✓ should return invalid params when request parameters do not match the method schema 1ms
✓ should send no response when an unknown notification is received 2ms
✓ should send no response when notification parameters are invalid 2ms
✓ should send exactly one result response when a request succeeds 2ms
✓ should send exactly one error response when a request fails 4ms
✓ should return a parse error when a JSON message is malformed 2ms
✓ should return invalid request when a JSON-RPC message omits its method 1ms
✓ Mcp Conformance (2026-07-28) (8)
✓ Transports > Stateless modern (8)
✓ should exchange one compact newline-delimited JSON-RPC message per stdio line 3ms
✓ should reconstruct a UTF-8 stdio message when its bytes arrive in separate chunks 2ms
✓ should process consecutive stateless stdio requests independently 3ms
✓ should shut down the stdio server when the client closes stdin 1ms
✓ should require application/json content and both supported response media types for HTTP POST 3ms
✓ should return application/json when an HTTP request has one JSON-RPC response 1ms
✓ should reject GET and unsupported HTTP methods when only POST is available 0ms
✓ should reject every MCP HTTP route when its Origin is not explicitly allowed 0ms
✓ Mcp Conformance (2026-07-28) (3)
✓ Utilities > Stateless modern (3)
✓ Cancellation (3)
✓ should send no response when a cancellation notification is received 2ms
✓ should interrupt work and suppress its response when an active request is cancelled 6ms
✓ should allow a later request to reuse an identifier cancelled before it was active 2ms
✓ Mcp Conformance (2026-07-28) (20)
✓ Tools (20)
✓ Capabilities (2)
✓ MUST advertise the tools capability when tools are registered 6ms
✓ MUST NOT advertise the tools capability when tools are not supported 2ms
✓ Listing Tools (3)
✓ SCHEMA preserves tool names and descriptions 2ms
✓ MUST return each tool input schema 2ms
✓ should list shared tools and gate modern-only tools by era 2ms
✓ Calling Tools (15)
✓ MUST call a registered tool with valid arguments 5ms
✓ MUST reject an unknown tool name with a protocol error 2ms
✓ MUST not invoke a tool handler when argument validation fails 2ms
✓ SCHEMA returns text content 7ms
✓ SCHEMA returns image content 1ms
✓ SCHEMA returns embedded resources 1ms
✓ MUST return multiple content items in order 1ms
✓ MUST return tool execution failures with isError 1ms
✓ MUST keep tool execution errors distinct from protocol errors 1ms
✓ SHOULD not expose defects or internal error details 1ms
✓ should return base64 audio content when an audio tool is called 1ms
✓ Structured content (3)
✓ should advertise an object output schema when a tool declares one 2ms
✓ should return a resource link when a resource-link tool is called 1ms
✓ should return structured content when a structured tool is called 1ms
✓ should report invalid tool arguments according to the selected revision 1ms
✓ Mcp Conformance (2026-07-28) (5)
✓ Tools > JSON Schema 2020-12 (3)
✓ should preserve 2020-12 keywords when listing an input schema 4ms
✓ should list a non-object output schema when the tool declares one 2ms
✓ should return primitive structured content when declared by the tool 2ms
✓ Tools > Modern request headers (1)
✓ should reject a tools/call request when its required routing name is missing 1ms
✓ Tools > Modern listing (1)
✓ should return tools in the same order when the registered inventory has not changed 2ms
✓ Mcp Conformance (2026-07-28) (12)
✓ Resources (12)
✓ Capabilities (2)
✓ MUST advertise resources when resources are registered 3ms
✓ MUST NOT advertise resources when resources are not supported 1ms
✓ Listing Resources (2)
✓ MUST list every resource visible to the initialized client 2ms
✓ SCHEMA preserves resource URI, name, description, and MIME type 1ms
✓ Reading Resources (5)
✓ MUST read text resource contents 1ms
✓ MUST read binary resource contents as base64 1ms
✓ SCHEMA preserves the resource URI and MIME type in returned contents 1ms
✓ MUST return multiple resource contents in order 1ms
✓ should return the revision-specific error when the resource URI is unknown 1ms
✓ Resource Templates (3)
✓ MUST list every registered resource template 2ms
✓ MUST match and decode a concrete resource-template URI 1ms
✓ MUST not invoke the handler when template parameter decoding fails 1ms
✓ Mcp Conformance (2026-07-28) (16)
✓ Prompts (16)
✓ Capabilities (2)
✓ MUST advertise prompts when prompts are registered 4ms
✓ MUST NOT advertise prompts when prompts are not supported 1ms
✓ Listing Prompts (3)
✓ MUST list every prompt visible to the initialized client 2ms
✓ SCHEMA preserves prompt names, descriptions, and arguments 1ms
✓ MUST mark required and optional prompt arguments correctly 1ms
✓ Getting Prompts (11)
✓ MUST get a registered prompt without arguments 2ms
✓ MUST get a registered prompt with valid arguments 1ms
✓ SHOULD reject an unknown prompt name with Invalid Params 1ms
✓ SHOULD reject missing required prompt arguments with Invalid Params 1ms
✓ SHOULD reject prompt arguments with invalid values 1ms
✓ MUST not invoke the prompt handler when argument validation fails 1ms
✓ SCHEMA preserves the prompt description and message order 1ms
✓ MUST return text message content 1ms
✓ MUST return image message content 1ms
✓ MUST return embedded resource message content 1ms
✓ should return base64 audio content when an audio prompt is requested 1ms
✓ Mcp Conformance (2026-07-28) (9)
✓ Completion (9)
✓ Capabilities (1)
✓ MUST advertise completions when argument completion is supported 3ms
✓ Requesting Completions (8)
✓ MUST complete a prompt argument 1ms
✓ MUST complete a resource template argument 1ms
✓ SHOULD reject an unknown prompt reference with Invalid Params 1ms
✓ MUST reject an unknown argument name 1ms
✓ MUST return completion values in order 1ms
✓ SCHEMA returns the total and additional-results indicator 1ms
✓ MUST return at most one hundred completion values 1ms
✓ should pass previously resolved arguments when completion context is supplied 1ms
✓ Mcp Conformance (2026-07-28) (4)
✓ Logging > Stateless modern (4)
✓ should advertise logging when request-scoped log filtering is supported 2ms
✓ should apply every specified log level to the request that declares it 10ms
✓ should reject a request when its request-scoped log level is unknown 1ms
✓ should preserve the level, logger, and JSON data when decoding a log notification 0ms
✓ Mcp Conformance (2026-07-28) (3)
✓ Multi round-trip requests (3)
✓ should return supported keyed input requests and resume when matching responses are supplied 5ms
✓ should remain input-required when continuation keys or request state do not match 2ms
✓ should reject a continuation when its input responses or request state are malformed 1ms
✓ Mcp Conformance (2026-07-28) (12)
✓ Subscriptions (12)
✓ should advertise supported subscription capabilities when features are registered 2ms
✓ should not advertise subscriptions and should reject listen when the transport cannot send notifications 2ms
✓ should acknowledge with the exact identifier when it is numeric or string-valued 4ms
✓ should deliver a change notification when its kind is requested 3ms
✓ should deliver a resource update when its URI is subscribed 3ms
✓ should acknowledge only the supported subset when requested filters exceed server capabilities 3ms
✓ should deliver a matching event to each subscription 3ms
✓ should keep another subscription active when its peer is cancelled 3ms
✓ should preserve notification metadata and own the subscription identifier 2ms
✓ should deliver modern changes only when an active subscription matches 4ms
✓ should preserve legacy notification delivery when modern and legacy adapters are configured 3ms
✓ should stream acknowledgment before matching events when using HTTP 3ms
✓ Mcp Conformance (2026-07-28) (13)
✓ Lifecycle (2)
✓ should discover the server when no initialization or session exists 2ms
✓ should serve independent requests when no discovery or session exists 1ms
✓ Transports (5)
✓ should exchange self-contained newline-delimited requests over stdio 1ms
✓ should accept every required routing name when the header matches the request 2ms
✓ should reject routing headers when they are missing, malformed, or mismatched 1ms
✓ should reject an unsupported request version with the supported versions 0ms
✓ should return method not found when a request uses an unknown or removed method 1ms
✓ Request metadata (3)
✓ should reject requests when required protocol metadata is missing 0ms
✓ should accept a request when optional client identity is omitted 0ms
✓ should preserve caller metadata alongside authoritative protocol facts 2ms
✓ Result envelopes (2)
✓ should attach modern result and cache metadata to every cacheable operation 5ms
✓ should attach a complete result type and server identity to every non-cacheable operation 2ms
✓ Multi round-trip request capabilities (1)
✓ should reject input requests when the client omits their required capabilities 1ms
Test Files 1 passed (1)
Tests 117 passed (117)
Start at 08:16:54
Duration 1.65s (transform 1.02s, setup 737ms, import 563ms, tests 242ms, environment 0ms)Its now a pretty solid 117 test coverage that I'm feeling confident is conformant with the new spec. I would probably do another pass on the Mcp Conformance suite afterwards though to clean up how the But with this, I'm gonna say the PR is ready for review 🤞 |
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
3 participants
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.
Type
Description
Add support the
McpProtocol.v2026_07_28which introduced the 'modern' stateless mcp architecture, while still supporting the previous session-based protocol versions. To support both lifecycles, we extract the protocol lifecycle handling into dedicated runtimes.McpServerselects the appropriate runtime for each adapter: older adapters keep their stateful initialization and session behavior, whilev2026_07_28selects and decodes the protocol from each request without creating session state.The main user-facing additions are:
server/discovernegotiation, with no initialization handshake or session state.McpRequestContextgives handlers access to request and client capabilities neutral to the runtime of the protocol.McpSchema.InputRequired, and clients can provide keyed elicitation, sampling, or roots responses on a later request.subscriptions/listen, delivering filtered server change notifications over stdio or Server-Sent Events.structuredContentfor every JSON value in the 2026-07-28 adapter. Earlier adapters continue to project only the shapes they support.A toy example of the stateless server and JSON tool output:
It wasn't possible to model a purely incremental session-era adapter due to the runtime changes, so this PR introduces a few structural changes to both Mcp and Rpc:
ProtocolAdaptersnow declare whether they use a stateful or stateless lifecycle policy.McpServerowns lifecycle runtime state, separating the existing sessionful path from the 2026-07-28 request-scoped path.McpRequestContext; legacy reverse operations continue to useMcpServerClient.Supporting
subscriptions/listenrequired a reusable RPC transport api for streaming responses and typed server-to-client notifications. The RPC change adds on top of the existing buffered HTTP behavior, while MCP can opt into streaming responses and notifications.How to Review
The files that deserve the most scrutiny should be:
mcpProtocol/v2026_07_28.ts+mcpSchema/v2026_07_28.ts-> dated wire behaviormcpRuntime.ts+mcpStatefulRuntime.ts-> stateless and preserved session lifecyclesRpcServer.ts-> streaming HTTP responses and notificationsBut its probably going to be easiest to just go through each commit ad there is a clear set of packages of work across each:
1. Runtime extraction
refactor: introduce MCP lifecycle runtimes and request contextExtracts the lifecycle ownership from the protocol adapters into
McpServerruntimes.This separates the existing sessionful protocol path from the new stateless path without retrofitting sessions onto 2026-07-28. It also introduces
McpRequestContext, allowing common handlers to read per-request protocol, capability, and client facts while legacy reverse operations keep usingMcpServerClient.2. Adding v2026-07-28
feat: add MCP 2026-07-28 protocol adapterAdds the dated wire schemas and adapter for MCP
2026-07-28.The adapter is selected from raw HTTP headers and request
_metabefore dated payload decoding. It servesserver/discover, requires self-contained routing metadata, and deliberately creates or consults noMcp-Session-Idstate.3. Adding MRTR
feat: support MCP multi-round-trip tool resultsAdds multi-round-trip tool results (MRTR).
Tool handlers can return
McpSchema.InputRequiredto ask for keyed elicitation, sampling, or roots input. A later self-contained request provides the corresponding responses throughMcpRequestContext, preserving the stateless model rather than holding a reverse-RPC session open.4. Adding subscriptions
feat: support RPC HTTP streaming and server notificationsfeat: add MCP 2026-07-28 subscriptionsFirst adds the transport primitive: request-selected streaming HTTP responses and typed server-to-client notifications for HTTP and stdio.
The protocol layer then uses that primitive for
subscriptions/listen, which delivers filtered MCP change notifications over SSE or stdio without changing legacy notification behavior.5. Clean up and compatibility hardening
feat: support JSON-valued MCP tool outputstest: organize MCP conformance suites by protocol behaviorfix: make MCP list-change scheduling deterministicFinishes the user-facing output model and makes version compatibility explicit:
structuredContentfor any JSON value; earlier adapters project only the shapes they support.Related