Repository navigation
docs(specs): 102-schema-deferred — deferred-schema serialization for the direct tools/list surface - #1035
Merged
Conversation
…spec Related #971 Speckit stage-1 spec for schema-deferred serialization of the direct enumeration surface: tools/list keeps all names + descriptions (with Spec 085 compact signatures appended), strips inputSchema, exposes describe_tool on the direct surface, and extends pre-dispatch validation + self-healing errors to direct dispatch. Opt-in, no new routing_mode. 3 NEEDS CLARIFICATION markers: config axis (one-axis vs dedicated key), outputSchema stripping, describe_tool batch cap.
Deploying mcpproxy-docs with
|
| Latest commit: |
34049e5
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://9999ea4f.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://102-schema-deferred.mcpproxy-docs.pages.dev |
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 32765635371 --repo smart-mcp-proxy/mcpproxy-go
|
…rom cross-model review Cross-model review (opencode gpt-5.6-sol) plus code verification found the stage-1 spec asserted several things about existing behavior that are not true, and left three implementable gaps. Spec-only; no code changes. Factual corrections: - FR-003: /mcp/p/<slug> serves retrieve_tools mode, not direct — there is no profile-scoped direct surface. Enumerate the real direct-serving routes (/mcp/all, /mcp under routing_mode:direct, and the legacy /v1/tool_code and /v1/tool-code aliases wired to the same handler). - FR-010/SC-004: the frozen tool-surface goldens do NOT cover direct mode (it is deliberately excluded — its listing is a live upstream projection). The delta therefore regenerates nothing; the goldens must stay byte-identical and a NEW gate must pin the direct surface's built-in set. - FR-011/Edge Cases: direct dispatch never parses the display name — each handler closes over its original (server, tool) pair. "Same first-__ parse as dispatch" is unachievable; resolution must go through the registration mapping. Added the display-name collision case. - FR-014: the config-reloaded branch does not rebuild the direct surface today; that wiring is new work, plus a no-op-when-unchanged requirement. - FR-005: the signature cache's only accessor compiles on miss, so "no per-request compilation" needs a new non-compiling lookup. - FR-007: no routing-mode server carries MCP instructions today; the channel must be chosen, not left as "and/or". - FR-001: the axis also has a --tool-response-mode flag and a MCPPROXY_TOOL_RESPONSE_MODE env alias; both move under either resolution. Gaps closed: - FR-011: direct-surface resolution must also gate on the operation-permission tier (the existing resolver does not), or a read-scoped token could describe a destructive tool hidden from its own tools/list; and must collapse existence-confirming reason codes to not_found per this session's listing. - FR-017 (new): one authoritative direct-surface catalog snapshot shared by listing, signature, describe_tool and validation. Today the listing is live-discovery while describe/signature are index-backed, so a tool pending tool-level approval is listed but has no schema, no signature and no way to recover either — strictly worse than full mode. - FR-018 (new): the direct tool set is replaced wholesale on every upstream refresh, so describe_tool must be composed into construction or it is silently dropped. - FR-009: describe_tool's prose says "found via retrieve_tools" and is byte-pinned by the goldens; resolve rather than inherit. - SC-007 added; SC-005 given explicit no-widening assertions. The three deliberate [NEEDS CLARIFICATION] markers are unchanged. Related #971
…mode Round-2 cross-model review caught a contradiction introduced by round 1: FR-011 told describe_tool to answer a listed pending-approval tool with its reason code, while US2 scenario 5, FR-017 and SC-007 all required every listed tool to be describable. Both cannot hold — a non-agent session's direct listing deliberately retains pending/changed/quarantined/disabled tools, since the callability filter narrows only agent-token sessions. Resolved by splitting the rule along the axis describe_tool already has: - invisible to this session → plain not_found in BOTH definition and check mode; - visible to this session → definition mode returns the snapshot-backed definition (withholding it buys no confidentiality once the tool is listed, and under deferral the listing no longer carries the schema itself), while check:true returns the informative availability verdict, which is exactly what check mode exists for. US2 scenario 5, SC-007 and the FR-017 membership bullet now say "definition mode" explicitly so the two modes cannot be conflated again. Related #971
… with the mode split
Round-3 cross-model review found the edge case still described the pre-fix
outcome ("no way to recover either — describe_tool not_found") in a way that
read as specified behavior, contradicting US2 scenario 5, FR-011, FR-017 and
SC-007. Reworded to mark it explicitly as the naive outcome FR-017 and FR-011
prevent, and to state what the spec actually requires: a listed pending or
changed tool resolves to its snapshot-backed definition in definition mode and
to a pending_approval/changed verdict under check:true, with only the signature
(not the schema) degraded until the tool is approved and indexed.
Related #971
github-actions Bot
pushed a commit
that referenced
this pull request
Aug 25, 2026
…specs 101/102 tracked (#1041) - release-qa-gate-playwright (T2): in_review -> done, pr #1030 (advisory Playwright web-UI sweep merged into the release gate). - mcp-2026-upgrade: blocked -> in_progress. The mcp-go gate cleared with v1.0.0-beta.1 (2026-08-12); spec 058 revision in review as #1033. Note rewritten: the remaining blocker is the Spec 057 cross-spec conflict, not the dependency. - tpa-db: todo -> in_review with spec: specs/101-tpa-db and pr #1028 (spec stage only; all three child tasks stay todo). - New epic schema-deferred (P1, spec 102, in_progress): deferred-schema serialization for the direct tools/list surface, spec merged in #1035 (issue #971), plan in progress. Reconnect-backoff work (#1014/#1039/#1040) is deliberately not added — the roadmap never tracked it; git history does. ROADMAP.md regenerated; gen-roadmap.py --check passes.
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
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.
Spec-only (speckit stage 1) for #971's accepted direction: direct-mode tools/list keeps all tool names + descriptions (compact signatures appended) but defers inputSchema; describe_tool joins the direct surface; pre-dispatch validation + self-healing errors extend to direct dispatch.
Built as a thin composition over Spec 085 machinery — opt-in, no new routing_mode value; 3 NEEDS CLARIFICATION markers (config axis, outputSchema stripping, describe_tool batch cap).
Cross-model review: opencode (gpt-5.6-sol), 4 rounds, CLEAN — codex is quota-locked, so gpt Sol was reached via opencode per standing directive. Review corrected several claims the draft made about existing behavior (no profile-scoped direct endpoint; the frozen tool-surface goldens don't cover direct mode; direct dispatch never parses the display name; the config-reload path doesn't rebuild the direct surface) and added FR-017/FR-018 plus a permission-tier and disclosure gate on describe_tool.
Related #971