[PR #1059] [MERGED] perf(mcp): advertise each tool JSON Schema once per target #2613

New issue

Closed

opened 2026-10-17 21:08:13 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:08:13 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1059
Author: @kaoru0822-kitauji
Created: 10/8/2026
Status: ✅ Merged
Merged: 10/8/2026
Merged by: @morluto

Base: main ← Head: perf/memoize-tool-json-schemas

📝 Commits (1)

bbdded1 perf(mcp): advertise each tool JSON Schema once per target

📊 Changes

3 files changed (+108 additions, -15 deletions)

View changed files

➕ src/contracts/toolSchemaMetadata.test.ts (+55 -0)
📝 src/contracts/toolSchemaMetadata.ts (+48 -13)
📝 src/server/toolRegistrationOptions.ts (+5 -2)

📄 Description

Summary

The MCP SDK (2.3.1) rebuilds the whole tool catalog on every tools/list: for each of the 139 registered tools it calls standardSchemaToJsonSchema on both the input and output schema. That reruns Zod's JSON Schema conversion (plus REA's describeProperties pass) every time. A CPU profile of 20 listings showed ~710 ms of 1.1 s in standardSchemaToJsonSchema. REA's earlier schema cache (67436444) was dropped when #555 moved conversion back to the SDK.

A registered contract cannot change, so this PR memoizes the advertised projection on the registration clones:

toolInputSchemaWithMetadata and a new toolOutputSchemaWithMetadata share one withAdvertisedJsonSchema helper. It clones the canonical schema with .meta() as before, then wraps ~standard.jsonSchema[io] so the projection is computed once per target.
Calls that pass libraryOptions are not cached.
The parser (~standard.validate) and the canonical contracts are unchanged.
The cached value is shared, like the SDK's own memoized outputSchemaJson. Both SDKs only read and spread these objects, and the client re-parses listings through Zod.

Measurements (stdio server, macOS arm64, Node 26)

	`main`	this PR
first `tools/list`	~70 ms	~71 ms
repeated `tools/list`	~62 ms	~18 ms
`tools/list` payload SHA-256	`da2f0a07…d7d5`	`da2f0a07…d7d5` (byte-identical)

The payload was compared for both the 2025-06-18 and 2025-11-25 protocol versions.

I first tried returning a structuredCloned, deep-frozen projection. It added ~15 ms to the first listing, so I took it out.

Verification

npm run test:focused -- src/contracts/toolSchemaMetadata.test.ts (new: one projection per target, other targets and libraryOptions kept separate, examples preserved, output projection equal to the uncached Zod one, parser still validates)
npx vitest run --project mcp-boundary: 62 files passed, 2 skipped
npm run check:fast, npm run docs:check (generated catalog unchanged)

No real Hopper or Ghidra verification needed; this touches only the MCP schema advertisement.

🤖 Generated with Claude Code

_{🔄 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/1059 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/8/2026 **Status:** ✅ Merged **Merged:** 10/8/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `perf/memoize-tool-json-schemas` --- ### 📝 Commits (1) - [`bbdded1`](https://github.com/morluto/rea/commit/bbdded13d5546f515729864c9387b34cb37aa6b9) perf(mcp): advertise each tool JSON Schema once per target ### 📊 Changes **3 files changed** (+108 additions, -15 deletions) <details> <summary>View changed files</summary> ➕ `src/contracts/toolSchemaMetadata.test.ts` (+55 -0) 📝 `src/contracts/toolSchemaMetadata.ts` (+48 -13) 📝 `src/server/toolRegistrationOptions.ts` (+5 -2) </details> ### 📄 Description ## Summary The MCP SDK (2.3.1) rebuilds the whole tool catalog on every `tools/list`: for each of the 139 registered tools it calls `standardSchemaToJsonSchema` on both the input and output schema. That reruns Zod's JSON Schema conversion (plus REA's `describeProperties` pass) every time. A CPU profile of 20 listings showed ~710 ms of 1.1 s in `standardSchemaToJsonSchema`. REA's earlier schema cache (67436444) was dropped when #555 moved conversion back to the SDK. A registered contract cannot change, so this PR memoizes the advertised projection on the registration clones: - `toolInputSchemaWithMetadata` and a new `toolOutputSchemaWithMetadata` share one `withAdvertisedJsonSchema` helper. It clones the canonical schema with `.meta()` as before, then wraps `~standard.jsonSchema[io]` so the projection is computed once per `target`. - Calls that pass `libraryOptions` are not cached. - The parser (`~standard.validate`) and the canonical contracts are unchanged. - The cached value is shared, like the SDK's own memoized `outputSchemaJson`. Both SDKs only read and spread these objects, and the client re-parses listings through Zod. ## Measurements (stdio server, macOS arm64, Node 26) | | `main` | this PR | |---|---|---| | first `tools/list` | ~70 ms | ~71 ms | | repeated `tools/list` | ~62 ms | ~18 ms | | `tools/list` payload SHA-256 | `da2f0a07…d7d5` | `da2f0a07…d7d5` (byte-identical) | The payload was compared for both the `2025-06-18` and `2025-11-25` protocol versions. I first tried returning a `structuredClone`d, deep-frozen projection. It added ~15 ms to the first listing, so I took it out. ## Verification - `npm run test:focused -- src/contracts/toolSchemaMetadata.test.ts` (new: one projection per target, other targets and `libraryOptions` kept separate, examples preserved, output projection equal to the uncached Zod one, parser still validates) - `npx vitest run --project mcp-boundary`: 62 files passed, 2 skipped - `npm run check:fast`, `npm run docs:check` (generated catalog unchanged) No real Hopper or Ghidra verification needed; this touches only the MCP schema advertisement. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:08:13 +00:00