docs(spec): MCP 2026-07-28 protocol upgrade (spec 058, blocked on mcp-go)#533
Conversation
Deploying mcpproxy-docs with
|
| Latest commit: |
4e57309
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://8f200589.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://057-mcp-2026-upgrade.mcpproxy-docs.pages.dev |
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 27528589065 --repo smart-mcp-proxy/mcpproxy-go
|
Dumbris
changed the title
|
Critic (Codex) review — Dumbris's PR #533
|
|
Critic (Codex) review — Dumbris's PR #533 Strengths: Spec-only scope is clear, the dependency gate is explicit, the spec calls out backward compatibility and proxy-specific header/stateless risks, and current mcp-go release data still supports the blocked-on-library premise ( Findings: none Provenance check: ok |
|
Triage (release-eng PR sweep, MCP-1760) — HOLD, not merged.
|
Dumbris
force-pushed
the
057-mcp-2026-upgrade
branch
from
88c86df to
2e07300
Compare
Related #532 Captures the full scope of upgrading mcpproxy to the MCP 2026-07-28 spec revision. Status is BLOCKED on mcp-go shipping 2026-07-28 support (currently v0.54.x targets 2025-11-25 only). ## Changes - specs/057-mcp-2026-upgrade/spec.md: 5 prioritized user stories, 27 FRs, 8 success criteria covering stateless sessions, server/discover + per-request _meta, required routing headers, MRTR, subscriptions/listen, error-code changes, and additive features (CacheableResult, deterministic ordering, JSON Schema 2020-12, trace context) - specs/057-mcp-2026-upgrade/checklists/requirements.md: spec quality checklist
Resolves spec-number collision with PR #531 (in-proxy profiles), which keeps 057.
Dumbris
force-pushed
the
057-mcp-2026-upgrade
branch
from
2e07300 to
4e57309
Compare
Dumbris
left a comment
Dumbris
left a comment
There was a problem hiding this comment.
CEO Code Review (standing in for CodexReviewer — MCP-3324, codex_local exhausted credits)
Verdict: ACCEPT
Spec-only PR (docs only, no code). Reviewed for completeness, internal consistency, and spec quality.
Positive:
- 27 FRs across 6 categories, all testable and unambiguous
- P1/P2 prioritisation correctly separates breaking changes from additive features
- Dependency Gate (FR-027) explicitly guards against premature mcp-go adoption
- Success criteria are measurable and technology-agnostic
- Edge cases cover proxy-specific scenarios: version bridging, double-handshake guard, Base64 header encoding, -32002→-32602 translation
Minor (non-blocking): Branch is 057-mcp-2026-upgrade but files land under specs/058-mcp-2026-upgrade/. Likely a numbering slip; no content impact.
Ready to merge. Plan/tasks should re-validate against finalized spec when mcp-go gate clears.
Dumbris
left a comment
Dumbris
left a comment
There was a problem hiding this comment.
Code Review: ACCEPT — MCP 2026-07-28 Protocol Upgrade Spec
Verdict: ACCEPT (cannot self-approve, posting review findings as comment)
This PR adds spec and requirements checklist only — no implementation code.
Strengths
- Properly dependency-gated: FR-027 + Dependency Gate section correctly block the default switch until
mcp-golibrary support exists. Right posture. - Comprehensive user stories: All 5 with Given/When/Then acceptance scenarios, covering the proxy-specific obligations (routing headers US-2, stateless architecture tension US-3).
- 27 numbered FRs: Proxy-specific concerns (header forwarding, version bridging, token-scoped views under stateless model) are distinct requirements.
- 8 measurable success criteria: SC-004 correctly captures the key invariant — concurrent differently-scoped tokens, canonical list facade byte-identical, no session ids.
- Edge cases: RC-may-shift risk, version-mismatch bridging, error-code translation (-32002→-32602), Base64 header encoding, deprecated transport co-existence.
- Assumptions recorded: Dual-version over hard-cutover, library-first adoption rationale.
Minor findings (plan-phase, non-blocking)
- FR-009
x-mcp-headerprovenance: Note whether this is from the 2026-07-28 RC spec or mcpproxy convention — clarify when writing the plan. - MRTR may also be library-gated: FR-015/016 (P2) may require
mcp-goMRTR type support independently of the version constant. Plan phase should assess explicitly. - SC-006 missing baseline: "measurable reduction in repeated fetches" — plan should include a baseline capture step before implementation.
- Checklist self-attested: Pre-checked at spec-write time; fine for a clean spec, just treat as self-attested.
Spec is comprehensive and production-quality for a blocked/draft feature. Ready to proceed to plan when the dependency gate clears.
Dumbris
left a comment
Dumbris
left a comment
There was a problem hiding this comment.
Code Review: ACCEPT — MCP 2026-07-28 Protocol Upgrade Spec
Verdict: ACCEPT (cannot self-approve — posting review as comment)
Spec-only PR, no implementation code. Review focused on spec quality and completeness.
Strengths
- Correctly dependency-gated on mcp-go library; FR-027 prevents premature default switch
- 5 user stories with clear Given/When/Then acceptance scenarios
- 27 numbered FRs covering proxy-specific obligations (header forwarding, version bridging, stateless token scoping)
- SC-004 correctly captures the key architectural invariant
- Edge cases: RC-may-shift, version-mismatch bridging, error-code translation (-32002→-32602), Base64 encoding, deprecated transport co-existence
- Assumptions documented with rationale
Minor findings (plan-phase, non-blocking)
- FR-009 x-mcp-header: note whether from 2026-07-28 RC spec or mcpproxy convention — clarify at plan time
- MRTR (FR-015/016) may independently require mcp-go type support beyond the version constant — assess separately in plan
- SC-006 lacks baseline measurement — plan should capture current baseline before implementation
- Requirements checklist is self-attested at spec-write time; acceptable for a draft/blocked spec
Spec is comprehensive and production-quality. Ready for plan phase when the dependency gate (mcp-go 2026-07-28 support) clears.
Review: ACCEPTCEO review (fallback — CodexReviewer exhausted usage limit). PR type: Spec/docs only — 2 files, no code changes. Quality assessment:
Verdict: ACCEPT — safe to merge. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Dumbris
left a comment
Dumbris
left a comment
There was a problem hiding this comment.
Code Review — CEO (spec 058 docs)
Verdict: ACCEPT
This is a documentation-only PR (spec.md + requirements checklist). The spec is thorough and well-structured.
Positives:
- 27 FRs with clear, testable acceptance criteria and success criteria (SC-001 through SC-008)
- Dependency gate prominently documented — correctly blocks implementation until mcp-go ships 2026-07-28 support
- Dual-version support over hard cutover is the right default for a proxy
- Edge cases are concrete and implementation-relevant (version mismatch bridging, error code translation, Base64 header encoding)
- Stateless operation tension (FR-011–FR-013) correctly identified as the highest-risk architectural point
- Checklist self-assessment is accurate; the note about protocol identifiers being user-facing contract (not implementation details) is correct
- MRTR and additive features (P2) correctly deprioritized relative to P1 handshake/header work
Minor observations (no blockers):
- Spec references 2026-07-28 revision as an RC; Assumptions already call this out with a re-validate note — plan/tasks authors should re-verify against the finalized spec when the gate clears
- FR-023 (serverName:toolName naming) is SHOULD rather than MUST — appropriate since it's an existing convention being blessed
No implementation details leak, no [NEEDS CLARIFICATION] markers, scope is clearly bounded. Ready to proceed to plan when the dependency gate clears.
2 participants
Summary
Adds spec 057 capturing the scope of upgrading mcpproxy to the MCP 2026-07-28 protocol revision. This is a spec-only PR — no code changes. Implementation is BLOCKED until
mcp-goships2026-07-28support (currently v0.54.x →2025-11-25).Tracking issue: #532
What's in the spec
server/discover+ per-request_meta, requiredMcp-Method/Mcp-Name/MCP-Protocol-Versionheaders, MRTR,subscriptions/listen,-32002→-32602CacheableResult, deterministic ordering, JSON Schema 2020-12, trace context in activity logWhy merge a blocked spec
Locks the analysis while it's fresh and gives a stable reference for the tracking issue and the scheduled mcp-go watcher. Plan/tasks come later, once unblocked and re-validated against the finalized (non-RC) spec.
Test plan
/speckit.plan