Skip to content

docs(specs): 102-schema-deferred — deferred-schema serialization for the direct tools/list surface - #1035

Merged
github-actions[bot] merged 4 commits into
mainfrom
102-schema-deferred
Aug 25, 2026
Merged

github-actions[bot] merged 4 commits into
mainfrom
102-schema-deferred

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 24, 2026 •

Copy link
Copy Markdown
Member

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

…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.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 24, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

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

View logs

@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Aug 24, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: 102-schema-deferred

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (25 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (20 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 32765635371 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

…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
@Dumbris Dumbris changed the title docs(specs): 102-schema-deferred — deferred-schema routing mode for direct tools/list docs(specs): 102-schema-deferred — deferred-schema serialization for the direct tools/list surface Aug 24, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved (Model B): Paperclip review verdicts = ACCEPT and qa-gate green at this head SHA. Arming auto-merge; GitHub merges when all required checks pass.

@github-actions
github-actions Bot merged commit 4ccb8a0 into main Aug 25, 2026
56 of 59 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants