[PR #1433] [MERGED] perf(mcp): reuse output validators across catalog refreshes #2883

New issue

Closed

opened 2026-10-17 21:11:23 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:11:23 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1433
Author: @N0zoM1z0
Created: 10/10/2026
Status: ✅ Merged
Merged: 10/10/2026
Merged by: @N0zoM1z0

Base: main ← Head: perf/mcp-output-schema-cache-1065

📝 Commits (1)

6c1c13f perf(mcp): reuse output validators across catalog refreshes

📊 Changes

4 files changed (+213 additions, -4 deletions)

View changed files

📝 docs/mcp-contracts.md (+7 -0)
📝 src/contracts/toolOutputReferences.test.ts (+58 -0)
📝 src/contracts/toolSchemaMetadata.ts (+40 -4)
➕ tests/boundary/mcp/outputValidatorReuse.test.ts (+108 -0)

📄 Description

A complete tools/list refresh makes the pinned SDK prepare all output validators again. Schemas without an identity get recompiled even when their content is unchanged. Advertise a schema-local, content- and dialect-bound $id so clients reuse the existing Ajv compilation; changed schemas receive a new identity.

Refs #1065 and #723. The full tool inventory, input guidance, output schemas and validation rules remain available. Equivalent outputs can share a validator across tool names. Explicit IDs and relative external reference bases are preserved, and projections remain cached by their conversion target. SDK freshness, availability and reconnect handling remain responsible for choosing the current tool definition.

Validation on source 6c1c13f7, based on main 28595276, Node 24.18.0/npm 11.16.0, Linux x64 under the existing two-CPU resource guard:

26 tests across seven files passed: SDK-converted schema validity/catalog parity, reordered registration, numeric/string constraints, dialects, explicit IDs, relative references, schema changes, availability transitions, reconnects, server identity and MCP doctor.
npm run check:fast, changed-file formatting, Git whitespace checks and npm run docs:check passed. Static checking uses the documented single-threaded compiler with its full scope preserved.
Actual compiled stdio REA workflows with SDK 2.3.1's default Ajv implementation: complete 139-tool discovery, directory analysis, retained-Evidence summary/module page, ping, close and reconnect passed. Only compiler/cache-hit counts were instrumented; no named toolDefinition shortcut was used.
Cold validator preparation compiles 118 distinct output schemas and reuses 21 equivalents. The next two catalog refreshes compile none; reconnecting the same client to a new REA process also compiles none for unchanged schemas. In the measured run, first binary_session took 2.74 seconds including 2.43 seconds of compilation, refresh calls took 114.6/29.6 ms, and the whole two-connection workflow took 9.60 seconds with 916 MiB peak process-family RSS.
Complete compact discovery grows from 1,870,570 to 1,884,470 bytes because of the identities. This is a validator CPU/recompilation improvement, not a reduction of model context or the complete catalog. Cold eager compilation of unrequested schemas remains an SDK follow-up.

Generated catalog/document outputs are ignored build artifacts and are not committed. No providers, executable bytes, Evidence/result representation or runtime authority change. Real Hopper/Ghidra runs are not applicable to this metadata change.

_{🔄 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/1433 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/10/2026 **Status:** ✅ Merged **Merged:** 10/10/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `perf/mcp-output-schema-cache-1065` --- ### 📝 Commits (1) - [`6c1c13f`](https://github.com/morluto/rea/commit/6c1c13f75eb6621423a576e86c9291193f4af7f7) perf(mcp): reuse output validators across catalog refreshes ### 📊 Changes **4 files changed** (+213 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-contracts.md` (+7 -0) 📝 `src/contracts/toolOutputReferences.test.ts` (+58 -0) 📝 `src/contracts/toolSchemaMetadata.ts` (+40 -4) ➕ `tests/boundary/mcp/outputValidatorReuse.test.ts` (+108 -0) </details> ### 📄 Description A complete `tools/list` refresh makes the pinned SDK prepare all output validators again. Schemas without an identity get recompiled even when their content is unchanged. Advertise a schema-local, content- and dialect-bound `$id` so clients reuse the existing Ajv compilation; changed schemas receive a new identity. Refs #1065 and #723. The full tool inventory, input guidance, output schemas and validation rules remain available. Equivalent outputs can share a validator across tool names. Explicit IDs and relative external reference bases are preserved, and projections remain cached by their conversion target. SDK freshness, availability and reconnect handling remain responsible for choosing the current tool definition. Validation on source `6c1c13f7`, based on main `28595276`, Node 24.18.0/npm 11.16.0, Linux x64 under the existing two-CPU resource guard: - 26 tests across seven files passed: SDK-converted schema validity/catalog parity, reordered registration, numeric/string constraints, dialects, explicit IDs, relative references, schema changes, availability transitions, reconnects, server identity and MCP doctor. - `npm run check:fast`, changed-file formatting, Git whitespace checks and `npm run docs:check` passed. Static checking uses the documented single-threaded compiler with its full scope preserved. - Actual compiled stdio REA workflows with SDK 2.3.1's default Ajv implementation: complete 139-tool discovery, directory analysis, retained-Evidence summary/module page, ping, close and reconnect passed. Only compiler/cache-hit counts were instrumented; no named `toolDefinition` shortcut was used. - Cold validator preparation compiles 118 distinct output schemas and reuses 21 equivalents. The next two catalog refreshes compile none; reconnecting the same client to a new REA process also compiles none for unchanged schemas. In the measured run, first `binary_session` took 2.74 seconds including 2.43 seconds of compilation, refresh calls took 114.6/29.6 ms, and the whole two-connection workflow took 9.60 seconds with 916 MiB peak process-family RSS. - Complete compact discovery grows from 1,870,570 to 1,884,470 bytes because of the identities. This is a validator CPU/recompilation improvement, not a reduction of model context or the complete catalog. Cold eager compilation of unrequested schemas remains an SDK follow-up. Generated catalog/document outputs are ignored build artifacts and are not committed. No providers, executable bytes, Evidence/result representation or runtime authority change. Real Hopper/Ghidra runs are not applicable to this metadata change. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:11:23 +00:00