morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #7218] [MERGED] feat(mcp): support compact output schema advertisements #7724

New issue

Closed

opened 2026-11-03 13:39:55 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:39:55 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7218
Author: @gensokyo-dev
Created: 10/26/2026
Status: ✅ Merged
Merged: 10/26/2026
Merged by: @gensokyo-dev

Base: main ← Head: feat/2512-compact-output-schemas

📝 Commits (6)

d213f15 feat(mcp): advertise bounded output schemas in a compact profile
e934aa9 test(mcp): validate compact output advertisements as clients receive them
b8660b2 test(mcp): cover canonical rejection behind a reduced output advertisement
f735451 test(mcp): verify compact discovery on real ELF exports
ff0cad9 test(mcp): avoid unused AJV code optimization in schema checks
f3ad857 test(mcp): select advertised output schema by contract name

📊 Changes

22 files changed (+1831 additions, -771 deletions)

View changed files

📝 README.md (+6 -0)
📝 docs/client-configuration.md (+7 -4)
📝 docs/mcp-contracts.md (+29 -13)
➕ experiments/analysis-efficiency/mcp-output-profile.md (+123 -0)
➕ experiments/analysis-efficiency/mcp-output-profile.mjs (+229 -0)
📝 scripts/record-catalog-digests.mjs (+1 -1)
📝 src/catalogIdentity.ts (+37 -7)
📝 src/config/mcpOutputSchemaProfile.ts (+22 -2)
📝 src/contracts/compactInputSchema.ts (+21 -600)
➕ src/contracts/compactJsonSchema.ts (+597 -0)
➕ src/contracts/compactOutputSchema.test.ts (+171 -0)
➕ src/contracts/compactOutputSchema.ts (+95 -0)
📝 src/recordedCatalogDigests.ts (+1 -1)
📝 src/server/DeferredEvidenceMcpServer.ts (+2 -1)
📝 src/server/EvidenceMcpServer.ts (+5 -7)
📝 src/server/EvidenceMcpServerCore.ts (+52 -14)
📝 src/server/createServer.ts (+17 -15)
📝 tests/boundary/mcp/mcpDoctor.test.ts (+60 -50)
📝 tests/boundary/mcp/outputSchemaProfile.test.ts (+239 -9)
📝 tests/boundary/mcp/toolSchemaValidity.test.ts (+7 -47)

...and 2 more files

📄 Description

Summary

Frame-capped MCP clients cannot load the full REA catalog. Add opt-in REA_MCP_OUTPUT_SCHEMA_PROFILE=compact: each advertised output schema fits 4,096 bytes, while canonical server validation and complete structuredContent remain intact. Full remains the default; off is unchanged. Shared projection primitives own input/output schema traversal, and repeated listings reuse schema-object projections.

Fixes #2512. Integrates the three commits from #7054 by @akshad-exe, preserving Akshad Jogi's authorship, and adds a reproducible real-artifact investigation. No new provider, target execution or target mutation; a maintainer scope decision is not applicable.

Verification

Cached build, check:fast, docs:check (9 cases), repository formatting, 56 source cases, all 28 MCP doctor cases and all 27 schema-validity/identity cases passed. After rebasing onto main 7d36d172a, all 20 output-profile/schema-validity cases pass with default two workers, and check:fast/formatting plus both complete real workflows pass again.
Initial full-catalog compilation assertions exceeded their 30-second deadlines. A bounded probe isolated unnecessary AJV generated-code optimization in the new compile-only fixture (five largest schemas: 4.75 → 2.22 s). Disabled only that optimization; all dialect/reference compilation and negative cases remain, actual SDK validators and deadlines are unchanged. CI also caught formatting in the new measurement guide; corrected and the complete format check now passes.
Isolated public CLI setup with compact input/output settings passed, repeated setup is byte-idempotent, and an unrelated ambient setting is not persisted.
Review correction: the added SDK profile test selects its advertised schema by the named contract, rather than catalog position; the four profile cases and check:fast are rerun for this change.
Real public stdio SDK investigation: libcrypto.so.3, 5,367 exports, cold/warm summaries, selected source-index pages and complete bundle export. Full/compact profiles produce identical complete authenticated Evidence; every export name/address agrees with GNU nm. A small /usr/bin/ls pilot also completed.
At measured runtime 650d483b9: catalog 3,639,545 → 554,792 bytes, all 229 tools retained. The SDK rejects full discovery under a 1 MiB receive cap and completes the compact investigation under that same cap.
Complete one-discovery wire cl100k estimate: 939,165 → 123,501; actual model usage is unmeasured. Names/descriptions/input schemas remain identical at 56,909 estimated tokens, so clients forwarding only those fields gain no model-context reduction from this setting.
Whole harness full/compact: 9.86/6.18 s elapsed, 11.96/7.66 s CPU, 1.04/0.62 GiB sampled family RSS. Two CPU slots and an 8 GiB family guard; no OOM or cleanup failures. One pair does not establish a general speed/memory improvement, and initial compact discovery is slower.

Reproduction, failed pilot receipts, cold/warm phase costs, the second-discovery accounting and limitations: experiments/analysis-efficiency/mcp-output-profile.md and .mjs. Raw measurements are pinned to their executed revision; the final-main repeat confirms identical complete Evidence and successful bounded-frame delivery.

Final CI scope

Final-head static checks, source tests, build/package and documentation passed; Greptile review passed and its actionable thread is fixed/resolved. Shard 5 had one unrelated failure in wakaruCommandConfiguration.test.ts: it expects the limiter as a string after main changed that owner to an invocationPath/resolvedPath object. The exact assertion fails on both this head and clean base 7d36d172a; the test and producing Wakaru/ArtifactCommandPath implementation are unchanged by this PR. The other seven shards were cancelled by fail-fast, so their final-head coverage is unavailable. No unrelated Wakaru change is included. The repository owner explicitly authorized bypass for proven main failures.

Author readiness

Human owner: @gensokyo-dev

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

The repository owner authorized proceeding with these declarations unchecked and bypassing the readiness gate; no human-review attestation is made.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/7218 **Author:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Created:** 10/26/2026 **Status:** ✅ Merged **Merged:** 10/26/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `feat/2512-compact-output-schemas` --- ### 📝 Commits (6) - [`d213f15`](https://github.com/morluto/rea/commit/d213f15b206494acaa6103f9f1ae8fcb492f90a6) feat(mcp): advertise bounded output schemas in a compact profile - [`e934aa9`](https://github.com/morluto/rea/commit/e934aa921c32728d4577f7a1d8ce7c0d8637750b) test(mcp): validate compact output advertisements as clients receive them - [`b8660b2`](https://github.com/morluto/rea/commit/b8660b202df649fb0ace2dadff54ea806e99f1ef) test(mcp): cover canonical rejection behind a reduced output advertisement - [`f735451`](https://github.com/morluto/rea/commit/f735451d99b41011b493af81c3425e1f0edcb9d9) test(mcp): verify compact discovery on real ELF exports - [`ff0cad9`](https://github.com/morluto/rea/commit/ff0cad960cfc2ee5c23c2360fc33fe6b407b6ecd) test(mcp): avoid unused AJV code optimization in schema checks - [`f3ad857`](https://github.com/morluto/rea/commit/f3ad857485112ef764a4633c7e174cee89e3b105) test(mcp): select advertised output schema by contract name ### 📊 Changes **22 files changed** (+1831 additions, -771 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+6 -0) 📝 `docs/client-configuration.md` (+7 -4) 📝 `docs/mcp-contracts.md` (+29 -13) ➕ `experiments/analysis-efficiency/mcp-output-profile.md` (+123 -0) ➕ `experiments/analysis-efficiency/mcp-output-profile.mjs` (+229 -0) 📝 `scripts/record-catalog-digests.mjs` (+1 -1) 📝 `src/catalogIdentity.ts` (+37 -7) 📝 `src/config/mcpOutputSchemaProfile.ts` (+22 -2) 📝 `src/contracts/compactInputSchema.ts` (+21 -600) ➕ `src/contracts/compactJsonSchema.ts` (+597 -0) ➕ `src/contracts/compactOutputSchema.test.ts` (+171 -0) ➕ `src/contracts/compactOutputSchema.ts` (+95 -0) 📝 `src/recordedCatalogDigests.ts` (+1 -1) 📝 `src/server/DeferredEvidenceMcpServer.ts` (+2 -1) 📝 `src/server/EvidenceMcpServer.ts` (+5 -7) 📝 `src/server/EvidenceMcpServerCore.ts` (+52 -14) 📝 `src/server/createServer.ts` (+17 -15) 📝 `tests/boundary/mcp/mcpDoctor.test.ts` (+60 -50) 📝 `tests/boundary/mcp/outputSchemaProfile.test.ts` (+239 -9) 📝 `tests/boundary/mcp/toolSchemaValidity.test.ts` (+7 -47) _...and 2 more files_ </details> ### 📄 Description ## Summary Frame-capped MCP clients cannot load the full REA catalog. Add opt-in `REA_MCP_OUTPUT_SCHEMA_PROFILE=compact`: each advertised output schema fits 4,096 bytes, while canonical server validation and complete structuredContent remain intact. Full remains the default; off is unchanged. Shared projection primitives own input/output schema traversal, and repeated listings reuse schema-object projections. Fixes #2512. Integrates the three commits from #7054 by @akshad-exe, preserving Akshad Jogi's authorship, and adds a reproducible real-artifact investigation. No new provider, target execution or target mutation; a maintainer scope decision is not applicable. ## Verification - Cached build, check:fast, docs:check (9 cases), repository formatting, 56 source cases, all 28 MCP doctor cases and all 27 schema-validity/identity cases passed. After rebasing onto main 7d36d172a, all 20 output-profile/schema-validity cases pass with default two workers, and check:fast/formatting plus both complete real workflows pass again. - Initial full-catalog compilation assertions exceeded their 30-second deadlines. A bounded probe isolated unnecessary AJV generated-code optimization in the new compile-only fixture (five largest schemas: 4.75 → 2.22 s). Disabled only that optimization; all dialect/reference compilation and negative cases remain, actual SDK validators and deadlines are unchanged. CI also caught formatting in the new measurement guide; corrected and the complete format check now passes. - Isolated public CLI setup with compact input/output settings passed, repeated setup is byte-idempotent, and an unrelated ambient setting is not persisted. - Review correction: the added SDK profile test selects its advertised schema by the named contract, rather than catalog position; the four profile cases and check:fast are rerun for this change. - Real public stdio SDK investigation: libcrypto.so.3, 5,367 exports, cold/warm summaries, selected source-index pages and complete bundle export. Full/compact profiles produce identical complete authenticated Evidence; every export name/address agrees with GNU nm. A small /usr/bin/ls pilot also completed. - At measured runtime 650d483b9: catalog 3,639,545 → 554,792 bytes, all 229 tools retained. The SDK rejects full discovery under a 1 MiB receive cap and completes the compact investigation under that same cap. - Complete one-discovery wire cl100k estimate: 939,165 → 123,501; actual model usage is unmeasured. Names/descriptions/input schemas remain identical at 56,909 estimated tokens, so clients forwarding only those fields gain no model-context reduction from this setting. - Whole harness full/compact: 9.86/6.18 s elapsed, 11.96/7.66 s CPU, 1.04/0.62 GiB sampled family RSS. Two CPU slots and an 8 GiB family guard; no OOM or cleanup failures. One pair does not establish a general speed/memory improvement, and initial compact discovery is slower. Reproduction, failed pilot receipts, cold/warm phase costs, the second-discovery accounting and limitations: `experiments/analysis-efficiency/mcp-output-profile.md` and `.mjs`. Raw measurements are pinned to their executed revision; the final-main repeat confirms identical complete Evidence and successful bounded-frame delivery. ## Final CI scope Final-head static checks, source tests, build/package and documentation passed; Greptile review passed and its actionable thread is fixed/resolved. Shard 5 had one unrelated failure in `wakaruCommandConfiguration.test.ts`: it expects the limiter as a string after main changed that owner to an invocationPath/resolvedPath object. The exact assertion fails on both this head and clean base 7d36d172a; the test and producing Wakaru/ArtifactCommandPath implementation are unchanged by this PR. The other seven shards were cancelled by fail-fast, so their final-head coverage is unavailable. No unrelated Wakaru change is included. The repository owner explicitly authorized bypass for proven main failures. ## Author readiness Human owner: @gensokyo-dev - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. The repository owner authorized proceeding with these declarations unchecked and bypassing the readiness gate; no human-review attestation is made. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-03 13:39:55 +00:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#7724

No description provided.

Rows
Columns