morluto/rea

Fork 0

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

[GH-ISSUE #2512] [Feature] Opt-in output-schema-light tools/list advertisement for frame-capped MCP clients #831

New issue

Closed

opened 2026-10-15 18:28:49 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:28:49 +00:00

Owner

Originally created by @wu546526 on GitHub (Oct 13, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2512

Before submitting

I searched the open and closed issues and pull requests for a related proposal (#723, #1143, #1484 reviewed).
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This request does not include credentials, private samples, or sensitive target data.

Area

MCP or agent integration

Current limitation

REA 6.4.0's tools/list response arrives as a single JSON-RPC line of 1,954,727 bytes (170 tools). Measured field shares:

field	bytes	share
`outputSchema`	1,493,900	76%
`inputSchema`	365,646	19%
`description`	58,941	3%
`annotations`	15,243	<1%
`name` + `title`	7,352	<1%

Clients that cap a single stdio frame below ~2 MB cannot finish the handshake and load 0 tools. Concrete case: pi-web-ui 0.104.4's built-in MCP bridge caps one JSON-RPC line at 1,048,576 chars and treats the oversized tools/list line as a protocol error, killing the server on every start — REA never loads in that host (0 tools), while the pi CLI on the same machine (SDK STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 MB) loads all 170 tools.

Mitigations already measured:

REA_MCP_INPUT_SCHEMA_PROFILE=compact: 1,954,727 → 1,772,799 bytes. It only trims inputSchema; outputSchema (76%) is untouched, and no switch affects it today.
#1143 (shipped $ref sharing for repeated output definitions): helped, but the frame is still ~1.9 MB because the per-tool output contracts are largely distinct.

Use cases

Embedded/panel hosts with hand-rolled stdio readers and 1 MB-class line guards (pi-web-ui and clients following the same pattern).
Faster first tools/list for constrained transports and token-budgeted agent harnesses.

Desired outcome and success criteria

An opt-in switch in the spirit of #1484 — e.g. REA_MCP_OUTPUT_SCHEMA_PROFILE=compact|off (naming at your discretion) — that trims or omits the advertised outputSchema while keeping canonical server-side validation and complete results unchanged, mirroring how compact preserves canonical input validation. Success criterion: with the switch set, the full 170-tool tools/list frame fits under 1 MB. (Cursor pagination for tools/list would equally solve it if you prefer that route.)

Expected interaction with targets

No target interaction (documentation or usability only)

Verification available so far

I have a prototype or observed results.

Verification details

Probe: spawn npx rea-agents@6.4.0 mcp, initialize → tools/list over stdio; the single response line measured 1,954,727 bytes with the per-field shares above (170 tools).
With REA_MCP_INPUT_SCHEMA_PROFILE=compact: single line = 1,772,799 bytes (still > 1 MB).
Client reproduction: the 1 MB-capped host logs 单行超过 1MB 上限，按协议错误关闭 ("single line exceeds the 1 MB cap; closed as protocol error") and kills the server at every handshake; the same server reports ready, 170 tools in 2.96 s through a client with a 10 MB receive budget.

Related: #723 (umbrella design for discovery size), #1143 (shipped $ref sharing), #1484 (compact input-schema profile precedent).

Originally created by @wu546526 on GitHub (Oct 13, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2512 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal (#723, #1143, #1484 reviewed). - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This request does not include credentials, private samples, or sensitive target data. ### Area MCP or agent integration ### Current limitation REA 6.4.0's `tools/list` response arrives as a single JSON-RPC line of **1,954,727 bytes** (170 tools). Measured field shares: | field | bytes | share | | --- | ---: | ---: | | `outputSchema` | 1,493,900 | 76% | | `inputSchema` | 365,646 | 19% | | `description` | 58,941 | 3% | | `annotations` | 15,243 | <1% | | `name` + `title` | 7,352 | <1% | Clients that cap a single stdio frame below ~2 MB cannot finish the handshake and load 0 tools. Concrete case: [pi-web-ui](https://github.com/xing-shuyin/pi-web-ui) 0.104.4's built-in MCP bridge caps one JSON-RPC line at 1,048,576 chars and treats the oversized `tools/list` line as a protocol error, killing the server on every start — REA never loads in that host (0 tools), while the pi CLI on the same machine (SDK `STDIO_DEFAULT_MAX_BUFFER_SIZE` = 10 MB) loads all 170 tools. Mitigations already measured: - `REA_MCP_INPUT_SCHEMA_PROFILE=compact`: 1,954,727 → 1,772,799 bytes. It only trims `inputSchema`; `outputSchema` (76%) is untouched, and no switch affects it today. - #1143 (shipped `$ref` sharing for repeated output definitions): helped, but the frame is still ~1.9 MB because the per-tool output contracts are largely distinct. ### Use cases - Embedded/panel hosts with hand-rolled stdio readers and 1 MB-class line guards (pi-web-ui and clients following the same pattern). - Faster first `tools/list` for constrained transports and token-budgeted agent harnesses. ### Desired outcome and success criteria An opt-in switch in the spirit of #1484 — e.g. `REA_MCP_OUTPUT_SCHEMA_PROFILE=compact|off` (naming at your discretion) — that trims or omits the advertised `outputSchema` while keeping canonical server-side validation and complete results unchanged, mirroring how `compact` preserves canonical input validation. Success criterion: with the switch set, the full 170-tool `tools/list` frame fits under 1 MB. (Cursor pagination for `tools/list` would equally solve it if you prefer that route.) ### Expected interaction with targets - No target interaction (documentation or usability only) ### Verification available so far I have a prototype or observed results. ### Verification details - Probe: spawn `npx rea-agents@6.4.0 mcp`, `initialize` → `tools/list` over stdio; the single response line measured 1,954,727 bytes with the per-field shares above (170 tools). - With `REA_MCP_INPUT_SCHEMA_PROFILE=compact`: single line = 1,772,799 bytes (still > 1 MB). - Client reproduction: the 1 MB-capped host logs `单行超过 1MB 上限，按协议错误关闭` ("single line exceeds the 1 MB cap; closed as protocol error") and kills the server at every handshake; the same server reports `ready, 170 tools` in 2.96 s through a client with a 10 MB receive budget. Related: #723 (umbrella design for discovery size), #1143 (shipped `$ref` sharing), #1484 (compact input-schema profile precedent).

bsakaguchi added the

area: mcp

enhancement

labels

2026-10-15 18:28:49 +00:00

bsakaguchi

2026-10-31 00:29:45 +00:00

closed this issue
added
enhancement
and removed
enhancement
labels

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#831

No description provided.

Rows
Columns