You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 667854f
Browse filesBrowse the repository at this point in the historyBrowse files
* 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.
**Input**: User description: "MCP protocol upgrade to the 2026-07-28 spec revision"
7
7
8
-
## Dependency Gate *(read first)*
8
+
## Dependency Gate *(CLEARED 2026-08-12)*
9
9
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.)
11
15
12
16
## Cross-Spec Reconciliation *(read at plan time)*
13
17
@@ -17,7 +21,11 @@ This feature **cannot begin implementation** until the upstream MCP client/serve
17
21
> -**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.
18
22
> -**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.
19
23
>
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.)
21
29
22
30
## User Scenarios & Testing *(mandatory)*
23
31
@@ -116,19 +124,21 @@ mcpproxy emits the new caching and ordering hints and modern schema defaults so
116
124
117
125
### Functional Requirements
118
126
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
+
119
129
**Protocol negotiation & handshake**
120
130
121
131
-**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.
122
132
-**FR-002**: mcpproxy MUST implement the `server/discover` RPC, returning supported versions, server capabilities, and server identity.
123
133
-**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.
124
134
-**FR-004**: mcpproxy MUST retain backward-compatible handling of the legacy `initialize`/`initialized` handshake for clients that still use it.
125
135
-**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.)*
127
137
128
138
**Routing headers & metadata**
129
139
130
140
-**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.
132
142
-**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.
133
143
-**FR-010**: mcpproxy MUST reject or flag tools that declare an invalid `x-mcp-header` mapping rather than forwarding them.
134
144
@@ -147,11 +157,11 @@ mcpproxy emits the new caching and ordering hints and modern schema defaults so
147
157
**Subscriptions & error codes**
148
158
149
159
-**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.)*
151
161
152
162
**Additive feature adoption**
153
163
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).
155
165
-**FR-020**: mcpproxy MUST produce deterministic ordering for `tools/list` results given unchanged state.
156
166
-**FR-021**: mcpproxy MUST treat tool input/output schemas as JSON Schema 2020-12 by default and MUST NOT auto-dereference external `$ref`s.
157
167
-**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
165
175
**Compatibility & rollout**
166
176
167
177
-**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.
169
180
170
181
### Key Entities
171
182
@@ -195,7 +206,14 @@ mcpproxy emits the new caching and ordering hints and modern schema defaults so
195
206
-**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.
196
207
-**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.
197
208
-**`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.
0 commit comments