morluto/rea

Fork 0

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

[PR #3905] feat(cli): report MCP catalog size in doctor #5961

New issue

Open

opened 2026-10-31 01:10:46 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:10:46 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3905
Author: @rancy777
Created: 10/15/2026
Status: 🔄 Open

Base: main ← Head: codex/mcp-catalog-diagnostics

📝 Commits (1)

d392eb0 feat(cli): report MCP catalog size in doctor

📊 Changes

5 files changed (+280 additions, -12 deletions)

View changed files

📝 docs/cli.md (+24 -0)
📝 src/mcpDoctor.ts (+25 -11)
➕ src/mcpDoctorCatalog.ts (+72 -0)
📝 tests/boundary/cli/mcpDoctorHelpCli.test.ts (+47 -0)
📝 tests/boundary/mcp/mcpDoctor.test.ts (+112 -1)

📄 Description

Summary

MCP startup can be healthy while its tool catalog is too large for a caller's workflow. rea mcp doctor previously reported counts and identity, but did not show where the catalog bytes were spent.

The report now includes catalog: requested input/output schema profiles, the received tools/list result's UTF-8 JSON size, input/output schema value totals, remaining metadata bytes, and the largest tool/input schema/output schema. It reports the observed SDK result, rather than reconstructing the catalog from source contracts.

Scope and boundaries

Reuses the existing bounded JSON serializer, profile parsers, catalog identity and production stdio doctor. No dependency, configuration change, new MCP tool or new target/provider authority.
Discovery failure returns catalog: null; an observed empty catalog has zero schema bytes and null largest entries. A continuation cursor marks the measurement as one incomplete page.
Schema omission contributes zero bytes. Invalid probe replies retain discovered byte facts while the existing health check fails.
Sizes exclude the JSON-RPC envelope and transport framing. They are not model tokens, client-rendered request sizes, or proof of provider acceptance. Profiles describe requested child configuration; server identity is checked separately.
Size alone does not change health or exit status. This diagnoses existing profile choices; it does not automatically shrink a catalog or change the caller's configuration.
Maintainer scope decision: not applicable to this extension of the existing target-free diagnostic. No target code is loaded or executed.

Validation

npm run compile — passes on the final rebased tree.
npm run check:fast — typecheck and lint pass.
npx --no-install vitest run tests/boundary/mcp/mcpDoctor.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts — 24/24 tests pass. Coverage includes the production schema profiles, public CLI/full-output delivery, invalid probes, startup failure/timeout and cleanup, UTF-8/JSON escaping, empty catalogs and continuation cursors.
Final public CLI/stdio MCP verification reports healthy: true in all four explicit profile combinations. All 216 tools are advertised, expected and observed catalog digests match, and the target-free binary_session request flow passes.

Input profile	Output profile	Measured tools/list JSON bytes
full	full	3,705,454
compact	full	3,043,135
full	off	929,484
compact	off	267,165

The profile behavior already existed; these measurements demonstrate the diagnostic, not a payload reduction introduced by this PR.

Validated on Windows x64 with Node 24.18.0/npm 11.16.0. Final commit: d392eb00c5d9b14a9f72d7970832301c62166393; fetched upstream baseline: 66aacc6fba7fb498302ca58894f179d77a847444. The branch is exactly one commit above that baseline and the worktree is clean. Full hosted CI, Linux/macOS, hosted client/model acceptance, model tokens, CPU time and peak process-family memory remain unverified. No binaries or generated build artifacts are included.

Author readiness

Human owner: @rancy777

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.

Keep this PR in draft until the human owner completes these declarations.

_{🔄 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/3905 **Author:** [@rancy777](https://github.com/rancy777) **Created:** 10/15/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/mcp-catalog-diagnostics` --- ### 📝 Commits (1) - [`d392eb0`](https://github.com/morluto/rea/commit/d392eb00c5d9b14a9f72d7970832301c62166393) feat(cli): report MCP catalog size in doctor ### 📊 Changes **5 files changed** (+280 additions, -12 deletions) <details> <summary>View changed files</summary> 📝 `docs/cli.md` (+24 -0) 📝 `src/mcpDoctor.ts` (+25 -11) ➕ `src/mcpDoctorCatalog.ts` (+72 -0) 📝 `tests/boundary/cli/mcpDoctorHelpCli.test.ts` (+47 -0) 📝 `tests/boundary/mcp/mcpDoctor.test.ts` (+112 -1) </details> ### 📄 Description ## Summary MCP startup can be healthy while its tool catalog is too large for a caller's workflow. `rea mcp doctor` previously reported counts and identity, but did not show where the catalog bytes were spent. The report now includes `catalog`: requested input/output schema profiles, the received `tools/list` result's UTF-8 JSON size, input/output schema value totals, remaining metadata bytes, and the largest tool/input schema/output schema. It reports the observed SDK result, rather than reconstructing the catalog from source contracts. ## Scope and boundaries - Reuses the existing bounded JSON serializer, profile parsers, catalog identity and production stdio doctor. No dependency, configuration change, new MCP tool or new target/provider authority. - Discovery failure returns `catalog: null`; an observed empty catalog has zero schema bytes and null largest entries. A continuation cursor marks the measurement as one incomplete page. - Schema omission contributes zero bytes. Invalid probe replies retain discovered byte facts while the existing health check fails. - Sizes exclude the JSON-RPC envelope and transport framing. They are not model tokens, client-rendered request sizes, or proof of provider acceptance. Profiles describe requested child configuration; server identity is checked separately. - Size alone does not change health or exit status. This diagnoses existing profile choices; it does not automatically shrink a catalog or change the caller's configuration. - Maintainer scope decision: not applicable to this extension of the existing target-free diagnostic. No target code is loaded or executed. ## Validation - `npm run compile` — passes on the final rebased tree. - `npm run check:fast` — typecheck and lint pass. - `npx --no-install vitest run tests/boundary/mcp/mcpDoctor.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts` — 24/24 tests pass. Coverage includes the production schema profiles, public CLI/full-output delivery, invalid probes, startup failure/timeout and cleanup, UTF-8/JSON escaping, empty catalogs and continuation cursors. - Final public CLI/stdio MCP verification reports `healthy: true` in all four explicit profile combinations. All 216 tools are advertised, expected and observed catalog digests match, and the target-free `binary_session` request flow passes. | Input profile | Output profile | Measured tools/list JSON bytes | | --- | --- | ---: | | full | full | 3,705,454 | | compact | full | 3,043,135 | | full | off | 929,484 | | compact | off | 267,165 | The profile behavior already existed; these measurements demonstrate the diagnostic, not a payload reduction introduced by this PR. Validated on Windows x64 with Node 24.18.0/npm 11.16.0. Final commit: `d392eb00c5d9b14a9f72d7970832301c62166393`; fetched upstream baseline: `66aacc6fba7fb498302ca58894f179d77a847444`. The branch is exactly one commit above that baseline and the worktree is clean. Full hosted CI, Linux/macOS, hosted client/model acceptance, model tokens, CPU time and peak process-family memory remain unverified. No binaries or generated build artifacts are included. ## Author readiness Human owner: @rancy777 - [x] 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. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. Keep this PR in draft until the human owner completes these declarations. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-31 01:10:46 +00:00

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

No description provided.

Rows
Columns