morluto/rea

Fork 0

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

[PR #4828] [CLOSED] fix(claude): prefer compact profiles for oversized tool schemas #6430

New issue

Closed

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

bsakaguchi commented

2026-10-31 01:14:23 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4828
Author: @XiaoBinGan
Created: 10/17/2026
Status: ❌ Closed

Base: main ← Head: fix/claude-desktop-compact-profile

📝 Commits (3)

70d1fab fix(setup): select the compact input-schema profile for Claude Desktop
3fb269b Merge remote-tracking branch 'upstream/main' into fix/claude-desktop-compact-profile
29086b0 Merge remote-tracking branch 'upstream/main' into fix/claude-desktop-compact-profile

📊 Changes

7 files changed (+197 additions, -9 deletions)

View changed files

📝 docs/client-configuration.md (+9 -0)
📝 docs/mcp-contracts.md (+7 -0)
📝 src/application/ClientRegistrationStatus.ts (+11 -5)
📝 src/application/SetupClientConfiguration.ts (+2 -1)
📝 src/config/mcpInputSchemaProfile.ts (+11 -0)
📝 tests/boundary/filesystem/claudeDesktopClientConfiguration.test.ts (+13 -3)
➕ tests/boundary/filesystem/claudeDesktopSchemaProfile.test.ts (+144 -0)

📄 Description

Summary

Claude Desktop's connector refused to register compare_web_captures ("a problem with that connector") while every other REA tool registered. The advertised input schema for that tool was 179,878 bytes — more than five times the next largest tool (32,947 bytes) — the only tool in the catalog that large. REA already has the documented remedy for this class of failure: the compact input-schema profile bounds every advertised schema to 13,312 bytes, which setup selects by default for Kimi after Moonshot's measured single-tool size cap (issue #1484). This change selects the same bounded advertisement by default when setup writes or refreshes a Claude Desktop registration, and reports an older registration without an explicit profile as stale so doctor and setup converge on the fix.

Problem and expected behavior

Claude Desktop registration	Before	After
New or refreshed, no explicit profile	advertised full catalog; `compare_web_captures` at 179,878 bytes → connector refused	`env.REA_MCP_INPUT_SCHEMA_PROFILE = "compact"`; the same tool advertises at 224 bytes
Explicit `full` or `compact` profile stored or passed to setup	respected	still respected (unchanged)
Older registration without an explicit profile	—	reported `stale` until setup adds the compact profile

Measured on the advertised schema (SDK tools/list projection): compare_web_captures is 179,878 bytes under the full profile; compactAdvertisedInputSchema bounds the same schema to 224 bytes within the documented 13,312-byte budget. No other REA tool approaches the size outlier (next largest: 32,947 bytes).

Change and scope

src/config/mcpInputSchemaProfile.ts: new shared policy compactInputSchemaProfileByDefault(clientName) — kimi and claude_desktop — replacing the inline client.name === "kimi" checks so the write and status paths cannot drift.
src/application/SetupClientConfiguration.ts: the registration environment for those clients gains REA_MCP_INPUT_SCHEMA_PROFILE: "compact" when none is set (behavior unchanged for Kimi; newly applies to Claude Desktop).
src/application/ClientRegistrationStatus.ts: the effective-environment read and the stale rule use the same helper, so a Claude Desktop registration without an explicit profile is stale and doctor/setup add the profile.
Tests: new tests/boundary/filesystem/claudeDesktopSchemaProfile.test.ts (compact default, explicit-profile preservation, caller overrides, stale-until-setup, and a control showing Cursor stays unbounded); the existing claudeDesktopClientConfiguration.test.ts expectations updated (+13/−3) for the new env key.
Docs: docs/client-configuration.md and docs/mcp-contracts.md describe the Claude Desktop selection with the measured schema sizes.

Contract and boundary impact

Semantic owner and earliest changed stage: setup registration writing and registration-status alignment, before the MCP server starts.
Contribution scope fit and linked maintainer decision: the issue is a direct report; the fix follows the documented, measured pattern REA already applies to Kimi/Moonshot for the same class of connector rejection. No new scope decision required.
CLI and MCP/tool-catalog contract: the canonical tool contracts are unchanged (the compact profile only changes the advertised schema presentation for the two constrained clients; "Canonical server-side validation remains unchanged" per compactInputSchema.ts). Other clients keep the full catalog.
Provider, bridge, target-format, or platform compatibility: Windows/MSIX Claude Desktop is covered by the same registration path; the resolver already writes the registration through the package-aware configuration location.
Evidence, artifact, provenance, or reconstruction contract: none.
Target selection, authority, upstream behavior, and cleanup details: not applicable.
Generated metadata / package / installation impact: none.

Expected effects:

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Measured advertised schemas (default full profile): compare_web_captures 179,878 bytes; next largest 32,947 bytes; not keyword appears only in this tool.
compactAdvertisedInputSchema(compare_web_captures_schema, 13_312) → 224 bytes, presentation reduced (the documented budget-bounded fallback).
New profile tests: 6 passed; original Claude Desktop lifecycle tests with updated expectations: 13 passed; Kimi profile tests unchanged: 31 passed.
npx vitest run tests/boundary/filesystem/ src/application/ src/setupEnvironment.test.ts src/config/ → 3806 passed, 13 skipped (280 files).
npm run check:fast, npm run format:check, npm run docs:check, npm run verify:test-discovery → all pass (1418 test files discovered exactly once).

Unverified gaps: no real Claude Desktop (MSIX, Windows) session was available locally, so the connector acceptance was not observed live; the schema-size outlier and the same-class Kimi remediation are the supporting evidence. The issue's own reproduction remains reproducible on 6.5.0 until a user re-runs setup after updating.

Compatibility, safety, and release

Breaking changes or migration steps: existing Claude Desktop registrations without an explicit profile become stale and are rewritten to include the compact profile on the next setup; explicitly selected profiles are preserved.
Real Hopper/Ghidra, browser, or OS coverage: none required.
Package or release metadata impact: none.
Security, privacy, process, or containment review: none applicable; the change only adds an environment entry to an existing MCP registration.

Author readiness

Human owner: @XiaoBinGan

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.

Before-merge:

I will respond to review feedback and keep the PR current with main until it merges.
This PR addresses a concrete problem or an agreed enhancement.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 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/4828 **Author:** [@XiaoBinGan](https://github.com/XiaoBinGan) **Created:** 10/17/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/claude-desktop-compact-profile` --- ### 📝 Commits (3) - [`70d1fab`](https://github.com/morluto/rea/commit/70d1fabaf8a0581b17d47de9b6f5b5849eb425f1) fix(setup): select the compact input-schema profile for Claude Desktop - [`3fb269b`](https://github.com/morluto/rea/commit/3fb269b081cfbf8d1f5004bbb1285b635a8cb576) Merge remote-tracking branch 'upstream/main' into fix/claude-desktop-compact-profile - [`29086b0`](https://github.com/morluto/rea/commit/29086b062e10ad335c4369534b3a363d32aa9bb0) Merge remote-tracking branch 'upstream/main' into fix/claude-desktop-compact-profile ### 📊 Changes **7 files changed** (+197 additions, -9 deletions) <details> <summary>View changed files</summary> 📝 `docs/client-configuration.md` (+9 -0) 📝 `docs/mcp-contracts.md` (+7 -0) 📝 `src/application/ClientRegistrationStatus.ts` (+11 -5) 📝 `src/application/SetupClientConfiguration.ts` (+2 -1) 📝 `src/config/mcpInputSchemaProfile.ts` (+11 -0) 📝 `tests/boundary/filesystem/claudeDesktopClientConfiguration.test.ts` (+13 -3) ➕ `tests/boundary/filesystem/claudeDesktopSchemaProfile.test.ts` (+144 -0) </details> ### 📄 Description ## Summary Claude Desktop's connector refused to register `compare_web_captures` ("a problem with that connector") while every other REA tool registered. The advertised input schema for that tool was 179,878 bytes — more than five times the next largest tool (32,947 bytes) — the only tool in the catalog that large. REA already has the documented remedy for this class of failure: the compact input-schema profile bounds every advertised schema to 13,312 bytes, which setup selects by default for Kimi after Moonshot's measured single-tool size cap (issue #1484). This change selects the same bounded advertisement by default when setup writes or refreshes a Claude Desktop registration, and reports an older registration without an explicit profile as stale so doctor and setup converge on the fix. ## Problem and expected behavior | Claude Desktop registration | Before | After | | --- | --- | --- | | New or refreshed, no explicit profile | advertised full catalog; `compare_web_captures` at 179,878 bytes → connector refused | `env.REA_MCP_INPUT_SCHEMA_PROFILE = "compact"`; the same tool advertises at 224 bytes | | Explicit `full` or `compact` profile stored or passed to setup | respected | still respected (unchanged) | | Older registration without an explicit profile | — | reported `stale` until setup adds the compact profile | Measured on the advertised schema (SDK `tools/list` projection): `compare_web_captures` is 179,878 bytes under the full profile; `compactAdvertisedInputSchema` bounds the same schema to 224 bytes within the documented 13,312-byte budget. No other REA tool approaches the size outlier (next largest: 32,947 bytes). ## Change and scope - `src/config/mcpInputSchemaProfile.ts`: new shared policy `compactInputSchemaProfileByDefault(clientName)` — `kimi` and `claude_desktop` — replacing the inline `client.name === "kimi"` checks so the write and status paths cannot drift. - `src/application/SetupClientConfiguration.ts`: the registration environment for those clients gains `REA_MCP_INPUT_SCHEMA_PROFILE: "compact"` when none is set (behavior unchanged for Kimi; newly applies to Claude Desktop). - `src/application/ClientRegistrationStatus.ts`: the effective-environment read and the stale rule use the same helper, so a Claude Desktop registration without an explicit profile is `stale` and doctor/setup add the profile. - Tests: new `tests/boundary/filesystem/claudeDesktopSchemaProfile.test.ts` (compact default, explicit-profile preservation, caller overrides, stale-until-setup, and a control showing Cursor stays unbounded); the existing `claudeDesktopClientConfiguration.test.ts` expectations updated (+13/−3) for the new `env` key. - Docs: `docs/client-configuration.md` and `docs/mcp-contracts.md` describe the Claude Desktop selection with the measured schema sizes. ## Contract and boundary impact - Semantic owner and earliest changed stage: setup registration writing and registration-status alignment, before the MCP server starts. - Contribution scope fit and linked maintainer decision: the issue is a direct report; the fix follows the documented, measured pattern REA already applies to Kimi/Moonshot for the same class of connector rejection. No new scope decision required. - CLI and MCP/tool-catalog contract: the canonical tool contracts are unchanged (the compact profile only changes the advertised schema presentation for the two constrained clients; "Canonical server-side validation remains unchanged" per `compactInputSchema.ts`). Other clients keep the full catalog. - Provider, bridge, target-format, or platform compatibility: Windows/MSIX Claude Desktop is covered by the same registration path; the resolver already writes the registration through the package-aware configuration location. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details: not applicable. - Generated metadata / package / installation impact: none. Expected effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Measured advertised schemas (default full profile): `compare_web_captures` 179,878 bytes; next largest 32,947 bytes; `not` keyword appears only in this tool. - `compactAdvertisedInputSchema(compare_web_captures_schema, 13_312)` → 224 bytes, presentation `reduced` (the documented budget-bounded fallback). - New profile tests: **6 passed**; original Claude Desktop lifecycle tests with updated expectations: **13 passed**; Kimi profile tests unchanged: **31 passed**. - `npx vitest run tests/boundary/filesystem/ src/application/ src/setupEnvironment.test.ts src/config/` → **3806 passed**, 13 skipped (280 files). - `npm run check:fast`, `npm run format:check`, `npm run docs:check`, `npm run verify:test-discovery` → all pass (1418 test files discovered exactly once). Unverified gaps: no real Claude Desktop (MSIX, Windows) session was available locally, so the connector acceptance was not observed live; the schema-size outlier and the same-class Kimi remediation are the supporting evidence. The issue's own reproduction remains reproducible on 6.5.0 until a user re-runs setup after updating. ## Compatibility, safety, and release - Breaking changes or migration steps: existing Claude Desktop registrations without an explicit profile become `stale` and are rewritten to include the compact profile on the next setup; explicitly selected profiles are preserved. - Real Hopper/Ghidra, browser, or OS coverage: none required. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none applicable; the change only adds an environment entry to an existing MCP registration. ## Author readiness  Human owner: @XiaoBinGan - [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. Before-merge: - [x] I will respond to review feedback and keep the PR current with `main` until it merges. - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:14:23 +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#6430

No description provided.

Rows
Columns