morluto/rea

Fork 0

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

[PR #7228] [MERGED] feat(mcp): scope advertised tools by family #7729

New issue

Closed

opened 2026-11-03 13:39:57 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:39:57 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7228
Author: @gensokyo-dev
Created: 10/26/2026
Status: ✅ Merged
Merged: 10/26/2026
Merged by: @gensokyo-dev

Base: main ← Head: feat/3246-mcp-tool-families

📝 Commits (5)

490d925 feat(mcp): scope discovery by selected tool families
1cf1973 test(mcp): verify scoped registrations and real stdio workflows
dc71669 docs(mcp): record latest-main scoped workflow measurements
f5e05ed fix(mcp): share scoped catalog identity with CLI status
03cb8a1 fix(mcp): align recovery guidance with advertised families

📊 Changes

47 files changed (+1974 additions, -277 deletions)

View changed files

📝 docs/client-configuration.md (+8 -0)
📝 docs/installation.md (+2 -2)
📝 docs/mcp-contracts.md (+71 -0)
📝 docs/mcp-prompts.md (+7 -0)
📝 experiments/analysis-efficiency/mcp-output-profile.mjs (+7 -4)
📝 experiments/analysis-efficiency/mcp-profile-digest.mjs (+5 -4)
➕ experiments/analysis-efficiency/mcp-tool-families.md (+126 -0)
📝 scripts/lib/catalog-builders.mjs (+8 -140)
📝 scripts/lib/catalog-core.mjs (+1 -5)
📝 scripts/verify-claude-client.mjs (+7 -4)
📝 src/application/DirectAnalysisStatus.ts (+5 -2)
📝 src/application/Doctor.ts (+5 -1)
📝 src/application/Setup.configuration.test.ts (+57 -0)
📝 src/application/Setup.ts (+8 -0)
📝 src/application/SetupTypes.ts (+2 -0)
📝 src/application/binary/BinarySessionStatus.test.ts (+71 -1)
📝 src/application/binary/BinarySessionStatus.ts (+56 -1)
📝 src/catalogIdentity.ts (+59 -22)
📝 src/cli/setupCommands.ts (+20 -0)
📝 src/config/environment.ts (+2 -0)

...and 27 more files

📄 Description

Summary

Fixes #3246. Add opt-in REA_MCP_TOOL_FAMILIES=native,application,session and rea setup --tool-families so clients discover only relevant tools. Unset configuration retains the existing catalog. Builds on #3026 by @0xLLVEL; upstream authorship and assistance trailers are preserved.

Change and scope

The parsed family selection is retained in shared configuration; CLI capabilities/providers and MCP use one catalog-identity owner. One contract-owned family inventory drives registration, prompts, setup, doctor and catalog identity. Disabled tools reject direct calls; session status counts only advertised tools and skips unrelated optional-provider probes. Initialization/recovery guidance names only advertised tools; real stdio tests cover scopes that advertise no prompts (the SDK already normalizes absent prompt capability). All six input/output schema profiles and canonical response validation remain supported. Setup is additive, backed up and idempotent; invalid scope fails before writes.

Scope decision: not applicable; existing provider boundaries, no added target execution or mutation. CLI setup can write caller-selected configuration; analysis reads existing binaries. Evidence identity, coverage, limitations, retained paging and complete export remain intact. Include application for retained Evidence queries and analysis settings.

Evidence and validation

Source suites: 48 cases; targeted boundary suites: 74 cases across focused runs. Production doctor: 31 cases. Real setup CLI backup/idempotency/invalid-input acceptance passed.
Six CLI status boundary cases passed, including both scoped status commands. Eleven framing/guidance boundary cases passed. The CLI negative control reproduces both scoped-identity failures against the previous producer; the zero-prompts control passes on the previous SDK path, so no duplicate prompt-capability interpretation was added. Four scoped/invalid/empty-prompt production doctor cases passed, including both real CLI inventory commands.
Real stdio acceptance passed with full, compact and off output profiles, including scoped discovery/status and rejection of disabled tools.
npm run build:cached, npm run check:fast, npm run docs:check (9 checks), npm run format:check passed after rebasing onto e54bf1006.
Two existing live-identity tests initially exceeded their 30-second deadline; both passed in isolated reruns (21.4s/16.6s), and one clean-main control passed in 19.1s. Timing variability is unresolved; no timeout was relaxed. One combined verification run hit its outer 190-second guard after build/stdio/check passed; remaining docs/format passed separately.

Actual SDK workflow against system libcrypto.so.3: two discoveries, cold/warm export inspection, first/last retained pages, complete bundle export and offline verification. All four configurations returned the same 5,367 GNU-nm-verified names/addresses and identical full Evidence hash. Linux only; external deep providers were not required or verified by this feature.

Completed task	Main, compact	Selected families, compact	Selected families, full	Feature, scope unset
Tools	229	73	73	229
Catalog bytes	554,792	192,959	1,400,171	554,792
Input-schema tokens (estimate)	56,909	23,070	23,070	56,909
Two-discovery wire tokens (estimate)	240,494	88,881	716,419	240,494
Elapsed seconds	21.89	7.00	12.18	8.26
Process-family CPU seconds	12.16	6.56	12.23	7.59
Peak process-family GiB	0.596	0.560	1.037	0.594

Single sequential samples on a shared host; the unset control also varies substantially, so these do not establish a general speedup. Tokens use cl100k_base, not measured model usage. Each completed workflow includes cold/warm calls and cleanup; 2-CPU affinity, 8-GiB guard, no OOM. Reproduction, exact revisions, retained identities and measurement limitations: experiment.

CI attribution and authorized bypass

Final head 03cb8a110, CI run 40315595135: static checks, source tests, package build, docs, Windows capability/package checks, native package baselines and Greptile passed. Test shards 2 and 3 passed. Shard 8 failed one WorkBuddy path assertion; five other shards were cancelled, with four additional assertions found in their logs. Those cancelled shards do not establish complete coverage.

Exact clean-main e54bf1006 and feature controls reproduce all five built-suite assertions with identical failed-case names and diagnostics: WorkBuddy/Trae personal skill paths, redirected-AppData Claude Desktop uninstall, pwntools completed-read cleanup, and pcap ENOTDIR allocation. Related producers/tests are unchanged. Node 22.23.4 separately reproduces the same five SQLite descriptor-cleanup failures on both revisions (16 pass); Node 24 and 26 SQLite CI passes. Aggregate Portable tests/CI required failures derive from these results.

All reported assertion failures are attributed; no unclassified assertion failures remain in downloaded failed/cancelled logs. Unexecuted/cancelled coverage remains unverified. The user explicitly authorized bypass for demonstrated baseline failures and the unchecked human-readiness gate; no human review is attested.

Author readiness

Human owner: @gensokyo-dev

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.

These declarations remain unchecked; the user explicitly authorized opening ready for review and bypassing this gate without an AI attestation of human review.

_{🔄 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/7228 **Author:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Created:** 10/26/2026 **Status:** ✅ Merged **Merged:** 10/26/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `feat/3246-mcp-tool-families` --- ### 📝 Commits (5) - [`490d925`](https://github.com/morluto/rea/commit/490d92537e4627f63c86ee3356bf46cb1af3fdaf) feat(mcp): scope discovery by selected tool families - [`1cf1973`](https://github.com/morluto/rea/commit/1cf1973dd58a303dafcbb492b2e2d02775fb90e7) test(mcp): verify scoped registrations and real stdio workflows - [`dc71669`](https://github.com/morluto/rea/commit/dc71669d7f08251e1c24ddf5e70beddec4b6f370) docs(mcp): record latest-main scoped workflow measurements - [`f5e05ed`](https://github.com/morluto/rea/commit/f5e05edf45be86e405cbe2ed3ff3a8ffa9777175) fix(mcp): share scoped catalog identity with CLI status - [`03cb8a1`](https://github.com/morluto/rea/commit/03cb8a110eb278f617fe58f51f4c55b0ee1ba1f0) fix(mcp): align recovery guidance with advertised families ### 📊 Changes **47 files changed** (+1974 additions, -277 deletions) <details> <summary>View changed files</summary> 📝 `docs/client-configuration.md` (+8 -0) 📝 `docs/installation.md` (+2 -2) 📝 `docs/mcp-contracts.md` (+71 -0) 📝 `docs/mcp-prompts.md` (+7 -0) 📝 `experiments/analysis-efficiency/mcp-output-profile.mjs` (+7 -4) 📝 `experiments/analysis-efficiency/mcp-profile-digest.mjs` (+5 -4) ➕ `experiments/analysis-efficiency/mcp-tool-families.md` (+126 -0) 📝 `scripts/lib/catalog-builders.mjs` (+8 -140) 📝 `scripts/lib/catalog-core.mjs` (+1 -5) 📝 `scripts/verify-claude-client.mjs` (+7 -4) 📝 `src/application/DirectAnalysisStatus.ts` (+5 -2) 📝 `src/application/Doctor.ts` (+5 -1) 📝 `src/application/Setup.configuration.test.ts` (+57 -0) 📝 `src/application/Setup.ts` (+8 -0) 📝 `src/application/SetupTypes.ts` (+2 -0) 📝 `src/application/binary/BinarySessionStatus.test.ts` (+71 -1) 📝 `src/application/binary/BinarySessionStatus.ts` (+56 -1) 📝 `src/catalogIdentity.ts` (+59 -22) 📝 `src/cli/setupCommands.ts` (+20 -0) 📝 `src/config/environment.ts` (+2 -0) _...and 27 more files_ </details> ### 📄 Description ## Summary Fixes #3246. Add opt-in `REA_MCP_TOOL_FAMILIES=native,application,session` and `rea setup --tool-families` so clients discover only relevant tools. Unset configuration retains the existing catalog. Builds on #3026 by @0xLLVEL; upstream authorship and assistance trailers are preserved. ## Change and scope The parsed family selection is retained in shared configuration; CLI `capabilities`/`providers` and MCP use one catalog-identity owner. One contract-owned family inventory drives registration, prompts, setup, doctor and catalog identity. Disabled tools reject direct calls; session status counts only advertised tools and skips unrelated optional-provider probes. Initialization/recovery guidance names only advertised tools; real stdio tests cover scopes that advertise no prompts (the SDK already normalizes absent prompt capability). All six input/output schema profiles and canonical response validation remain supported. Setup is additive, backed up and idempotent; invalid scope fails before writes. Scope decision: not applicable; existing provider boundaries, no added target execution or mutation. CLI setup can write caller-selected configuration; analysis reads existing binaries. Evidence identity, coverage, limitations, retained paging and complete export remain intact. Include `application` for retained Evidence queries and analysis settings. ## Evidence and validation - Source suites: 48 cases; targeted boundary suites: 74 cases across focused runs. Production doctor: 31 cases. Real setup CLI backup/idempotency/invalid-input acceptance passed. - Six CLI status boundary cases passed, including both scoped status commands. Eleven framing/guidance boundary cases passed. The CLI negative control reproduces both scoped-identity failures against the previous producer; the zero-prompts control passes on the previous SDK path, so no duplicate prompt-capability interpretation was added. Four scoped/invalid/empty-prompt production doctor cases passed, including both real CLI inventory commands. - Real stdio acceptance passed with `full`, `compact` and `off` output profiles, including scoped discovery/status and rejection of disabled tools. - `npm run build:cached`, `npm run check:fast`, `npm run docs:check` (9 checks), `npm run format:check` passed after rebasing onto `e54bf1006`. - Two existing live-identity tests initially exceeded their 30-second deadline; both passed in isolated reruns (21.4s/16.6s), and one clean-main control passed in 19.1s. Timing variability is unresolved; no timeout was relaxed. One combined verification run hit its outer 190-second guard after build/stdio/check passed; remaining docs/format passed separately. Actual SDK workflow against system `libcrypto.so.3`: two discoveries, cold/warm export inspection, first/last retained pages, complete bundle export and offline verification. All four configurations returned the same 5,367 GNU-nm-verified names/addresses and identical full Evidence hash. Linux only; external deep providers were not required or verified by this feature. | Completed task | Main, compact | Selected families, compact | Selected families, full | Feature, scope unset | | --- | ---: | ---: | ---: | ---: | | Tools | 229 | 73 | 73 | 229 | | Catalog bytes | 554,792 | 192,959 | 1,400,171 | 554,792 | | Input-schema tokens (estimate) | 56,909 | 23,070 | 23,070 | 56,909 | | Two-discovery wire tokens (estimate) | 240,494 | 88,881 | 716,419 | 240,494 | | Elapsed seconds | 21.89 | 7.00 | 12.18 | 8.26 | | Process-family CPU seconds | 12.16 | 6.56 | 12.23 | 7.59 | | Peak process-family GiB | 0.596 | 0.560 | 1.037 | 0.594 | Single sequential samples on a shared host; the unset control also varies substantially, so these do not establish a general speedup. Tokens use `cl100k_base`, not measured model usage. Each completed workflow includes cold/warm calls and cleanup; 2-CPU affinity, 8-GiB guard, no OOM. Reproduction, exact revisions, retained identities and measurement limitations: [experiment](experiments/analysis-efficiency/mcp-tool-families.md). ## CI attribution and authorized bypass Final head `03cb8a110`, CI run [40315595135](https://github.com/morluto/rea/actions/runs/40315595135): static checks, source tests, package build, docs, Windows capability/package checks, native package baselines and Greptile passed. Test shards 2 and 3 passed. Shard 8 failed one WorkBuddy path assertion; five other shards were cancelled, with four additional assertions found in their logs. Those cancelled shards do not establish complete coverage. Exact clean-main `e54bf1006` and feature controls reproduce all five built-suite assertions with identical failed-case names and diagnostics: WorkBuddy/Trae personal skill paths, redirected-AppData Claude Desktop uninstall, pwntools completed-read cleanup, and pcap ENOTDIR allocation. Related producers/tests are unchanged. Node 22.23.4 separately reproduces the same five SQLite descriptor-cleanup failures on both revisions (16 pass); Node 24 and 26 SQLite CI passes. Aggregate Portable tests/CI required failures derive from these results. All reported assertion failures are attributed; no unclassified assertion failures remain in downloaded failed/cancelled logs. Unexecuted/cancelled coverage remains unverified. The user explicitly authorized bypass for demonstrated baseline failures and the unchecked human-readiness gate; no human review is attested. ## Author readiness Human owner: @gensokyo-dev - [ ] 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. These declarations remain unchecked; the user explicitly authorized opening ready for review and bypassing this gate without an AI attestation of human review. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-03 13:39:57 +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#7729

No description provided.

Rows
Columns