Skip to content

Commit 667854f

Browse files
authored
docs(specs): 058 revision — mcp-go v1.0.0-beta.1 clears the 2026-07-28 gate (#1033)
* docs(specs): revise spec 058 — mcp-go v1.0.0-beta.1 clears the 2026-07-28 gate Related #532 Dependency gate cleared 2026-08-12: mcp-go v1.0.0-beta.1 (mark3labs/mcp-go#951) ships full 2026-07-28 support with per-request era detection. ## Changes - Dependency Gate section rewritten as CLEARED (pin corrected v0.54.0 -> v0.57.0); merge constraint: no beta pin on main without v1.0.0 stable or the FR-028 legacy pin - Error codes updated to the final renumbering: FR-008 -32001 -> -32020 (HEADER_MISMATCH), FR-006 cites -32022 (UNSUPPORTED_PROTOCOL_VERSION); FR-018 -32602 mapping verified against beta.1 (-32002 legacy-era only) - Scope note: FR-001..006 / FR-014..016 recast as adopt-and-verify (library provides era detection, server/discover, GET/DELETE handling, MRTR, legacy conformance) - Cross-Spec Reconciliation: Spec-057 Option A/B decision is now the mandatory first task; acceptance = the 2 tests failing under beta.1; ~21-call-site ClientSessionFromContext audit flagged - New FR-028: pin client-facing transport legacy-only via WithStreamableHTTPProtocolVersions(LegacyProtocolVersions()...) as the safe merge state - 'RC may shift' assumption resolved (spec FINAL 2026-07-28); new Risks & Watch Items section (OAuth authorization-hardening churn, frozen goldens, JSON Schema 2020-12) * docs(specs): 058 — qualify synthesized-session claim in Dependency Gate Related #532 Review round 1 (P2): the gate paragraph said synthesized legacy session state keeps ClientSessionFromContext handlers working, contradicting the Reconciliation section where session-id-dependent set_profile fails. Qualified: handlers receive a session object, but no persistent session id is bound. * docs(specs): correct two mcp-go claims in the 058 gate revision Both found by cross-model review and verified against the beta.1 module cache. - The scope note listed FR-015/FR-016 as "adopt-and-verify" on the strength of "MRTR bridging" in mcp-go v1.0.0-beta.1. The library ships MRTR *participation*, not *bridging*: a server can raise an input_required result (mcp.NewInputRequiredResult, MultiRoundTripResult embedded in CallToolResult / GetPromptResult / ReadResourceResult) and a client can answer one locally (client/mrtr.go gathers responses from handlers and re-sends with the echoed requestState). A proxy must do neither - relay outward without answering, then carry inputResponses back upstream under a new request id. Nothing in beta.1 does that, and requestState is opaque and upstream-scoped, so whether it can be forwarded verbatim is an open plan-time question. FR-015/FR-016 moved to the mcpproxy-specific list. - Risks & Watch Items said CallToolResult gains resultType / ttlMs / cacheScope. It gains resultType (embedded mcp.Result) and the MRTR fields, but ttlMs and cacheScope live on mcp.CacheableResult, which is embedded only by PaginatedResult, ReadResourceResult and DiscoverResult - which is exactly FR-019's "list/read responses" scope, so FR-019 itself was right. Everything else in the revision checked out against the module and the repo: v1.0.0-beta.1 exists and v0.58.0 is the latest v0.x; the pin really is v0.57.0; server/streamable_http_modern.go carries the 2026-07-28 era detection; WithCacheHints/WithMethodCacheHints exist at server/server.go:254,267; the error renumbering is real (HEADER_MISMATCH -32020, MISSING_REQUIRED_CLIENT_CAPABILITY -32021, UNSUPPORTED_PROTOCOL_VERSION -32022, with -32020..-32099 reserved); and server/resource_errors.go returns INVALID_PARAMS on the modern era and RESOURCE_NOT_FOUND on the legacy one, as FR-018 describes. The compile probe was re-run rather than trusted: on main @ 4d30624 with the beta.1 pin, both editions build, go vet is clean, and TestProfile_ produces exactly the two named failures. That result is now recorded inline.
1 parent 74de58a commit 667854f

1 file changed

Lines changed: 28 additions & 10 deletions

File tree

‎specs/058-mcp-2026-upgrade/spec.md‎

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,16 @@
22

33
**Feature Branch**: `058-mcp-2026-upgrade`
44
**Created**: 2026-05-28
5-
**Status**: Draft (BLOCKED — see Dependency Gate)
5+
**Status**: Draft — READY FOR PLANNING (dependency gate CLEARED 2026-08-12; spec revised 2026-08-24)
66
**Input**: User description: "MCP protocol upgrade to the 2026-07-28 spec revision"
77

8-
## Dependency Gate *(read first)*
8+
## Dependency Gate *(CLEARED 2026-08-12)*
99

10-
This feature **cannot begin implementation** until the upstream MCP client/server library (`github.com/mark3labs/mcp-go`) ships support for protocol revision `2026-07-28`. As of 2026-05-28 the pinned library (v0.54.0) and the latest published release (v0.54.1) both target only `2025-11-25`; no `2026-07-28` constant exists in the library. This spec captures the full upgrade scope now so execution can start immediately once the gate clears. A scheduled tracking agent watches the library and the spec's RC→final status and notifies the maintainer when the gate opens.
10+
**The gate has cleared.** `github.com/mark3labs/mcp-go` **v1.0.0-beta.1** (released 2026-08-12, mark3labs/mcp-go#951) ships full `2026-07-28` support with per-request protocol-era detection: both protocol eras are served concurrently on one endpoint, modern (stateless) requests synthesize legacy session state so existing `ClientSessionFromContext`-based handlers still receive a session object — though no persistent session id is bound, so session-id-dependent behavior (e.g. Spec-057's session-scoped `set_profile`) still fails; see Cross-Spec Reconciliation — and client-side `initialize` is capped at `2025-11-25`, and a conformance suite pins legacy byte-compatibility. The stable v0.x line (latest v0.58.0, 2026-08-11) does **not** include this support. mcpproxy currently pins **v0.57.0** (an earlier revision of this paragraph said v0.54.0; the pin has moved since).
11+
12+
A compile probe against v1.0.0-beta.1 produced **zero compile errors** on both editions, a clean `go vet`, and exactly **2 unit-test failures** — `TestProfile_SetProfileSessionScoped` and `TestProfile_SetProfileUnknown` (`internal/server/profile_integration_test.go`) — which is precisely the Spec-057 tension flagged in the Cross-Spec Reconciliation section below. *(Independently reproduced 2026-08-26 on `main` @ `4d30624`: `go get github.com/mark3labs/mcp-go@v1.0.0-beta.1` → `go build ./...` exit 0, `go build -tags server ./cmd/mcpproxy` exit 0, `go vet ./internal/...` exit 0, `go test ./internal/server -run TestProfile_` → exactly those two failures and no others.)*
13+
14+
**Merge constraint:** a v1.0.0-beta.x library pin MUST NOT merge to main unless either (a) mcp-go v1.0.0 stable has shipped, or (b) the client-facing Streamable HTTP transport is pinned legacy-only per FR-028. (Gate history: opened 2026-05-28 against v0.54.x; tracked weekly on issue #532 until cleared.)
1115

1216
## Cross-Spec Reconciliation *(read at plan time)*
1317

@@ -17,7 +21,11 @@ This feature **cannot begin implementation** until the upstream MCP client/serve
1721
> - **Option A — treat the profile URL path as request-carried identity.** Each request line carries the slug, so arguably it is *not* connection state. But a client that opens a stream to `/mcp/p/<slug>` binds the profile to that endpoint, which is closer to connection state than to `_meta` identity, and FR-014 forbids relying on a long-lived GET stream — so profile routing must remain correct in a purely stateless, request-scoped model.
1822
> - **Option B — move profile selection into `_meta`/a header** (e.g. a `profile` field in per-request `_meta`), demoting or deprecating the `/mcp/p/<slug>` path form for `2026-07-28` clients while keeping it for `2025-11-25` clients during the deprecation window.
1923
>
20-
> **Action for plan.md:** pick A or B explicitly, add an acceptance scenario proving per-profile filtering (Spec 057) works under the stateless model without per-connection list variation, and confirm `GET`/`DELETE` on `/mcp/p/<slug>` follow FR-014. Do not implement 058 without resolving this — building FR-012 naively would break shipped per-profile routing. (028 needs no change; 057 does.)
24+
> **Update 2026-08-24 — this decision is now the MANDATORY FIRST TASK.** Under mcp-go v1.0.0-beta.1 the upgraded client library defaults to the stateless `2026-07-28` era, so no `Mcp-Session-Id` is bound and session-scoped `set_profile` fails with "set_profile requires an active MCP session; no session id is bound to this request" (`internal/server/profile_tool.go`, session resolved via `ClientSessionFromContext` in `profile_resolver.go`). The A/B choice can no longer be deferred as a plan-time detail: it is the first implementation task, and its acceptance criteria are the two tests that currently fail under beta.1 — `TestProfile_SetProfileSessionScoped` and `TestProfile_SetProfileUnknown` in `internal/server/profile_integration_test.go`.
25+
>
26+
> The audit is broader than `set_profile`: every `ClientSessionFromContext` call site (~21 across `internal/server` — the `describe_tool` session cache, the `code_execution` session, output sanitisation, request routing, and profile resolution) must be reviewed for correctness under the stateless era, not just the profile path.
27+
>
28+
> **Action for plan.md:** pick A or B explicitly (A: treat the `/mcp/p/<slug>` URL path as request-carried identity; B: profile in `_meta`/header), add an acceptance scenario proving per-profile filtering (Spec 057) works under the stateless model without per-connection list variation, and confirm `GET`/`DELETE` on `/mcp/p/<slug>` follow FR-014. Do not implement 058 without resolving this — building FR-012 naively would break shipped per-profile routing. (028 needs no change; 057 does.)
2129
2230
## User Scenarios & Testing *(mandatory)*
2331

@@ -116,19 +124,21 @@ mcpproxy emits the new caching and ordering hints and modern schema defaults so
116124

117125
### Functional Requirements
118126

127+
> **Scope note (2026-08-24, post-gate):** mcp-go v1.0.0-beta.1 itself implements protocol-era detection, `server/discover`, `GET`/`DELETE` endpoint handling, MRTR **endpoints on both sides**, and legacy byte-compatibility (conformance-tested upstream). FR-001–FR-006 and FR-014 are therefore **adopt-and-verify** requirements — configure the library correctly and prove the behavior with mcpproxy-level tests — rather than build-from-scratch work. **FR-015/FR-016 are NOT adopt-and-verify.** What the library ships is MRTR *participation*, not MRTR *bridging*: the server side can RAISE an `input_required` result (`mcp.NewInputRequiredResult`, `InputRequiredResult`, `MultiRoundTripResult` embedded in `CallToolResult`/`GetPromptResult`/`ReadResourceResult`), and the client side can ANSWER one locally (`client/mrtr.go` gathers responses from handlers and re-sends them with the echoed `requestState`). A proxy must do neither: it has to RELAY an upstream's `input_required` outward without answering it, and carry the client's `inputResponses` back to the upstream under a new request id. No primitive in beta.1 does that, and `requestState` is opaque and upstream-scoped, so whether it can be handed to the client verbatim or must be wrapped in a proxy-side token is an open design question for plan.md. mcpproxy-specific engineering therefore concentrates on FR-007–FR-010 (proxy header forwarding on both hops), FR-012/FR-013 plus the Spec-057 Option A/B decision (see Cross-Spec Reconciliation), FR-015/FR-016 (MRTR relay + continuation), FR-019 (`WithCacheHints`/`WithMethodCacheHints` configuration), FR-022 (trace context → activity log), FR-025, and FR-028.
128+
119129
**Protocol negotiation & handshake**
120130

121131
- **FR-001**: mcpproxy MUST advertise `2026-07-28` as a supported protocol version to connecting clients and MUST continue to support `2025-11-25` during the deprecation window.
122132
- **FR-002**: mcpproxy MUST implement the `server/discover` RPC, returning supported versions, server capabilities, and server identity.
123133
- **FR-003**: mcpproxy MUST accept per-request identity/version metadata (`_meta`: protocolVersion, clientInfo, clientCapabilities) in lieu of an `initialize`/`initialized` handshake for `2026-07-28` clients.
124134
- **FR-004**: mcpproxy MUST retain backward-compatible handling of the legacy `initialize`/`initialized` handshake for clients that still use it.
125135
- **FR-005**: mcpproxy MUST negotiate protocol versions independently on its client-facing side and its upstream-facing side, translating between versions when they differ.
126-
- **FR-006**: mcpproxy MUST return the spec-defined unsupported-protocol error when a client requests a version it cannot serve.
136+
- **FR-006**: mcpproxy MUST return the spec-defined unsupported-protocol error (`-32022`, `UNSUPPORTED_PROTOCOL_VERSION`) when a client requests a version it cannot serve. *(Final spec renumbering: `2026-07-28` reserves `-32020`…`-32099` for MCP-defined errors — `-32020` header mismatch, `-32021` missing required client capability, `-32022` unsupported protocol version.)*
127137

128138
**Routing headers & metadata**
129139

130140
- **FR-007**: mcpproxy MUST set `Mcp-Method` and `MCP-Protocol-Version` on every request/notification it forwards upstream, and `Mcp-Name` on `tools/call`, `resources/read`, and `prompts/get`.
131-
- **FR-008**: mcpproxy MUST validate that incoming `MCP-Protocol-Version` (and related required headers) match the request body `_meta`, returning the header-mismatch error (`-32001`) on disagreement and not forwarding the request.
141+
- **FR-008**: mcpproxy MUST validate that incoming `MCP-Protocol-Version` (and related required headers) match the request body `_meta`, returning the header-mismatch error (`-32020`, `HEADER_MISMATCH` per SEP-2243 — the RC-era `-32001` was renumbered in the final spec) on disagreement and not forwarding the request.
132142
- **FR-009**: mcpproxy MUST support `x-mcp-header` param-to-header mirroring, copying designated tool params into `Mcp-Param-*` headers and Base64-encoding non-ASCII values.
133143
- **FR-010**: mcpproxy MUST reject or flag tools that declare an invalid `x-mcp-header` mapping rather than forwarding them.
134144

@@ -147,11 +157,11 @@ mcpproxy emits the new caching and ordering hints and modern schema defaults so
147157
**Subscriptions & error codes**
148158

149159
- **FR-017**: mcpproxy MUST route resource update subscriptions via `subscriptions/listen` instead of `resources/subscribe`/`unsubscribe`.
150-
- **FR-018**: mcpproxy MUST emit `-32602` for resource-not-found conditions and MUST translate an upstream's legacy `-32002` to `-32602` when bridging.
160+
- **FR-018**: mcpproxy MUST emit `-32602` (Invalid Params) for resource-not-found conditions on the `2026-07-28` era and MUST translate an upstream's legacy `-32002` to `-32602` when bridging across eras. *(Verified against mcp-go v1.0.0-beta.1: the final spec aligns resource-not-found with JSON-RPC `INVALID_PARAMS`; `-32002` remains emitted to, and accepted from, legacy-era peers only, so translation applies at era boundaries.)*
151161

152162
**Additive feature adoption**
153163

154-
- **FR-019**: mcpproxy MUST include `ttlMs` and a `cacheScope` (`public`/`private`) on list/read responses, choosing `private` for identity-scoped content and `public` for shared content.
164+
- **FR-019**: mcpproxy MUST include `ttlMs` and a `cacheScope` (`public`/`private`) on list/read responses, choosing `private` for identity-scoped content and `public` for shared content (configured via mcp-go's `WithCacheHints`/`WithMethodCacheHints` server options).
155165
- **FR-020**: mcpproxy MUST produce deterministic ordering for `tools/list` results given unchanged state.
156166
- **FR-021**: mcpproxy MUST treat tool input/output schemas as JSON Schema 2020-12 by default and MUST NOT auto-dereference external `$ref`s.
157167
- **FR-022**: mcpproxy MUST capture W3C/OTel trace context (`traceparent`/`tracestate`/`baggage`) from request `_meta` into activity-log records for cross-hop correlation.
@@ -165,7 +175,8 @@ mcpproxy emits the new caching and ordering hints and modern schema defaults so
165175
**Compatibility & rollout**
166176

167177
- **FR-026**: The personal edition's existing tool-discovery/curation behavior MUST remain functionally unchanged from the connecting agent's perspective after the upgrade.
168-
- **FR-027**: The upgrade MUST be gated behind the availability of `2026-07-28` support in the underlying MCP library; the codebase MUST NOT switch its negotiated default to `2026-07-28` until that support exists and is verified.
178+
- **FR-027**: The upgrade MUST be gated behind the availability of `2026-07-28` support in the underlying MCP library; the codebase MUST NOT switch its negotiated default to `2026-07-28` until that support exists and is verified. *(Availability satisfied by mcp-go v1.0.0-beta.1 as of 2026-08-12; "verified" additionally requires the FR-028 intermediate state or v1.0.0 stable before the client-facing default changes.)*
179+
- **FR-028** *(added 2026-08-24 — safe intermediate state)*: Until the Spec-057 Option A/B reconciliation is implemented and its acceptance tests pass, the client-facing Streamable HTTP transport MUST be pinned to legacy protocol versions only via `server.WithStreamableHTTPProtocolVersions(mcp.LegacyProtocolVersions()...)`. A v1.0.0-beta.x pin of `mcp-go` MUST NOT merge to main without either mcp-go v1.0.0 stable or this pin in place.
169180

170181
### Key Entities
171182

@@ -195,7 +206,14 @@ mcpproxy emits the new caching and ordering hints and modern schema defaults so
195206
- **Library-first adoption**: The upgrade rides on `mcp-go` adding `2026-07-28`; mcpproxy will not hand-roll the protocol primitives unless the library stalls indefinitely. Hand-rolling is explicitly out of scope for this spec.
196207
- **mcpproxy remains tool-centric**: Resources/prompts/sampling proxying stays as-is (largely unimplemented); MRTR and subscription work is scoped to correct framing, not to newly proxying capabilities mcpproxy doesn't proxy today.
197208
- **`cacheScope` selection**: identity-scoped content defaults to `private`; globally shared content defaults to `public`.
198-
- **RC may shift before final**: The `2026-07-28` revision is a release candidate; details (field names, codes) may change before final. Plan/tasks should re-validate against the finalized spec when the gate clears.
209+
- **RC may shift before final — RESOLVED (2026-08-24)**: The `2026-07-28` revision went FINAL on 2026-07-28. This spec's FRs have been re-validated against the final spec as implemented by mcp-go v1.0.0-beta.1; the RC→final deltas affecting this document were the error-code renumbering now encoded in FR-006/FR-008/FR-018.
210+
211+
## Risks & Watch Items *(added 2026-08-24)*
212+
213+
- **OAuth "authorization hardening" churn between beta.1 and v1.0.0**: mcp-go v1.0.0-beta.1 explicitly left the OAuth surface untouched, but names authorization hardening (issuer-keyed credentials, CIMD) as the next v1.x workstream. mcpproxy's OAuth integration is load-bearing there — `internal/oauth/persistent_token_store.go` (implements `client.TokenStore`), `internal/oauth/config.go` (`client.OAuthConfig`), and the three near-duplicate authorize-URL emission paths in `internal/upstream/core/connection_oauth.go`. Mitigation: keep the feature branch rebased onto each beta and re-run the `internal/oauth` test suite on every library bump.
214+
- **Frozen tool-surface goldens**: in beta.1 `CallToolResult` gains `resultType` (via the embedded `mcp.Result`) and the MRTR fields (via the embedded `MultiRoundTripResult`) — but **not** `ttlMs`/`cacheScope`. Those two live on `mcp.CacheableResult`, which is embedded only by `PaginatedResult` (hence every `*/list`), `ReadResourceResult` and `DiscoverResult` — matching FR-019's "list/read responses" scope exactly. Legacy-era responses omit `resultType`. The three frozen tool-surface golden tests must be re-verified as part of the dependency bump.
215+
- **Schema dialect shift**: Spec 056's output-schema validation must be re-verified under JSON Schema 2020-12 as the default dialect (FR-021).
216+
- **Beta churn**: watch for v1.0.0-beta.2+ and v1.0.0 stable; re-run the compile/test probe on each bump before rebasing the branch.
199217

200218
## Out of Scope
201219

0 commit comments

Comments
 (0)