Repository navigation
Commit 5a8d9d9
authored
feat(mcp): Spec 058 US3 stateless list surfaces (#1691)
## Summary
Spec 058 (MCP 2026-07-28 upgrade), user story US3 — stateless readiness,
landed under the FR-028 legacy pin. Tracking issue #532. Tasks
T020–T036b in `specs/058-mcp-2026-upgrade/tasks.md`; decisions recorded
in research.md D11.
Under the 2026-07-28 revision there are no sessions, so `*/list` results
must not vary per connection (FR-012) and nothing a request does may
persist per-connection state (FR-011). The one piece of connection state
mcpproxy holds is the legacy `set_profile` selection. This PR makes the
modern era clean, fixes the pre-existing FR-012 violation on legacy, and
closes two defects the era exposes.
### Behaviour
- **Era-gated session tier.** `profileSessionIDFromContext` returns `""`
for a 2026-07-28 request whatever the transport reports — stdio reports
the constant `"stdio"` in both eras, and before this a modern stdio
`set_profile` persisted a selection (proven by
`TestProfileEra_ModernStdioRequestCannotPersistSelection`). Both
resolvers (v2 precedence and Spec 108 v3) read the one gate.
- **List-only resolution.** `resolveActiveProfileForList` /
`listOnlyProfileResolution` skip the session tier and record nothing on
the session; the direct-tools filter uses it at list time only
(call-time re-evaluation keeps the full precedence) and the
aggregated-prompts filter uses it for `prompts/list` (`prompts/get`
keeps its handler gate). Fixes the pre-existing `prompts/list` FR-012
violation research D1 named.
- **`set_profile`** validates the slug before the session guard (an
unknown slug is answered `unknown profile '<slug>'` in both eras) and
refuses a modern request with guidance naming `/mcp/p/<slug>`.
- **Cross-client cancellation guard (R1, security).** mcp-go keys
in-flight cancels as `"<sessionID>:<id>"`; every modern request has
session id `""`, so two clients using JSON-RPC id 1 collide and one can
cancel the other's call — reproduced in
`TestCancelIsolation_LibraryCollisionStillPresent`. The notification is
handled before any hook, so the guard is HTTP middleware
(`modernCancellationGuard`): a cancellation notification on a modern
POST is acknowledged (202) and dropped. Legacy flows are untouched
(`TestCancelIsolation_LegacySelfCancelStillWorks`).
- **Stdio era pin (T036a).** mcp-go has no stdio equivalent of the
Streamable HTTP version pin; `rejectUnservedProtocolOnStdio` refuses a
declared version outside `clientFacingProtocolVersions()`, the constant
set the HTTP option now reads too, so T041 lifts both in one place.
- **Attribution without `initialize` (T032/T033).**
`activityAttribution` falls back to
`RequestProtocolInfoFromContext(ctx).ClientInfo` (name + new
`ClientVersion` → `metadata.client_version`), and the `BeforeAny` hook
feeds the Spec 044 activation funnel and client-seen presence from the
same data, debounced per client identity per minute.
- **FR-016b on `/mcp/all` is now asserted** over the live direct routing
fixture (T036b).
- Server edition:
`TestEntitlementStateless_TwoUsersIsolatedWithoutSession` (`-tags
server`) proves two OAuth users with differing entitlements are isolated
over modern requests with no session (FR-013, research D4's untested
half).
### Era harness
Modern-era tests reach the proxy through `unpinnedProxyEndpoint`: the
proxy's own MCP server over an unpinned Streamable HTTP transport behind
the production auth middleware. `rawEraClient` speaks JSON-RPC by hand
so byte-identity can be asserted on the wire. Every modern-era test
proves it took the modern path (`requireEra`).
### Deliberate residual (documented)
`filterProfileV3Tools` (Spec 108 FR-017 / Spec 115 FR-011) still hides
the built-in administration tools according to a legacy session's
selection at list time — a Spec 108 contract pinned by its visibility
matrix tests, out of US3's scope. It cannot happen in the modern era and
disappears at T077 (deprecation-window closeout). research.md D11 and
the profiles docs name it.
### Upstream issue
The mcp-go report for the inflight-key collision could not be filed:
`mark3labs/mcp-go` restricts interactions to collaborators (2026-10-20).
The draft is in
`specs/058-mcp-2026-upgrade/upstream-issues/mcp-go-inflight-cancel-collision.md`;
`inflightKey` is unchanged on mcp-go `main` (v1.3.0).
**No new dependencies.**
## Verification
- `./scripts/test-api-e2e.sh`
- `go test -race` for `./internal/server/... ./internal/runtime/...`
(bare) and `./internal/serveredition/... ./internal/server/...` (`-tags
server`) with the unit-tests.yml `-skip` regex
- golangci-lint v2 with `.github/.golangci.yml`, bare and `--build-tags
server`: no findings in touched files (remaining findings are
pre-existing in untouched files)
- Cross-model review, one round: **zcode (GLM) could not run** (expired
project-token login; needs a human `zcode login`), so the round ran on
opencode `github-copilot/gpt-6.1-sol` in three chunks. 7 findings, 6
fixed (bounded client recorder; era gate on the session write paths;
`metadata.client_name` on modern records so per-client usage counts
them; two test-vacuity fixes; an accurately scoped server-edition test
plus a production-chain agent-token test), 1 declined with rationale
(body buffering: mcp-go already buffers the whole POST before era
detection). Round 2 (incremental, on the fixes): 1 finding (a vacuous
work-session assertion), fixed with a storage-backed test proven to
bite. Table in research.md D11.
Closes nothing on its own; part of #532.
## Verified on a live instance
Scratch core from this branch (`./mcpproxy serve --config
<scratch>/mcp_config.json --data-dir <scratch>/data --listen
127.0.0.1:18731`, two disabled upstreams, profiles `research`/`deploy`,
API key auth), driven with raw JSON-RPC over curl; stdio via `./mcpproxy
serve --listen ":0"` on a second scratch data dir.
| Check | Result |
|---|---|
| Two fresh legacy connections, `tools/list` | both 200, 14 tools,
result bytes identical (sha256 `8c0242b4cb8e74e8…` on both) |
| Legacy `set_profile("research")` on A, then `tools/list` A vs B |
set_profile OK (`profile_source: session`); lists differ by
`credentials`/`profiles` only — the documented built-in-visibility
residual (Spec 108, legacy era only) |
| Modern (`2026-07-28`) `tools/list` and `set_profile` on the pinned
endpoint | 400, `-32022 unsupported protocol version` — never
dispatched, nothing persisted |
| Modern `notifications/cancelled` POST | 202 from
`modernCancellationGuard` (the same endpoint answers a modern request
with 400), A unaffected and still serving |
| Legacy `notifications/cancelled` with A's session id | 202, passes
through to mcp-go unchanged |
| stdio: modern `tools/list` with `_meta` | `-32600 protocol version
2026-07-28 is not served on the stdio surface: the client-facing era is
pinned to 2025-11-25, …` |
| stdio: legacy `initialize` + `tools/list` | initialize result
`protocolVersion: 2025-11-25`, tools listed |
The modern-era handler behaviour itself (refusal naming `/mcp/p/<slug>`,
identity-scoped lists, attribution) is reachable only through the
in-process era harness while FR-028 pins the listening endpoint; those
are the `forEachEra`/`unpinnedProxyEndpoint` tests in this PR.
🤖 Generated with [Claude Code](https://claude.com/claude-code)1 parent 1c639c0 commit 5a8d9d9
23 files changed
Lines changed: 2053 additions & 73 deletions
File tree
- docs/features
- internal
- runtime
- serveredition/api
- server
- specs/058-mcp-2026-upgrade
- upstream-issues
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1012 | 1012 | | |
1013 | 1013 | | |
1014 | 1014 | | |
1015 | | - | |
| 1015 | + | |
1016 | 1016 | | |
1017 | 1017 | | |
1018 | 1018 | | |
| |||
1122 | 1122 | | |
1123 | 1123 | | |
1124 | 1124 | | |
1125 | | - | |
| 1125 | + | |
1126 | 1126 | | |
1127 | 1127 | | |
1128 | 1128 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
110 | 110 | | |
111 | 111 | | |
112 | 112 | | |
113 | | - | |
| 113 | + | |
114 | 114 | | |
115 | 115 | | |
116 | 116 | | |
| |||
189 | 189 | | |
190 | 190 | | |
191 | 191 | | |
192 | | - | |
193 | | - | |
| 192 | + | |
| 193 | + | |
194 | 194 | | |
195 | 195 | | |
196 | 196 | | |
| |||
199 | 199 | | |
200 | 200 | | |
201 | 201 | | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
202 | 218 | | |
203 | 219 | | |
204 | 220 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
23 | 23 | | |
24 | 24 | | |
25 | 25 | | |
26 | | - | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
27 | 33 | | |
28 | 34 | | |
29 | 35 | | |
| |||
51 | 57 | | |
52 | 58 | | |
53 | 59 | | |
| 60 | + | |
54 | 61 | | |
55 | 62 | | |
56 | 63 | | |
| |||
68 | 75 | | |
69 | 76 | | |
70 | 77 | | |
| 78 | + | |
71 | 79 | | |
72 | 80 | | |
73 | 81 | | |
74 | 82 | | |
75 | 83 | | |
76 | 84 | | |
77 | 85 | | |
78 | | - | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
79 | 90 | | |
80 | 91 | | |
81 | 92 | | |
| |||
88 | 99 | | |
89 | 100 | | |
90 | 101 | | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
91 | 120 | | |
92 | 121 | | |
93 | 122 | | |
| |||
0 commit comments