[GH-ISSUE #8388] [Design] Make scoped MCP native workflows discoverable without the full catalog #6579

New issue

Open

opened 2026-11-01 21:12:23 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:12:23 +00:00

Owner

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

Before submitting

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

Decision needed

How should a family-scoped MCP connection communicate that its catalog is intentionally narrowed and help a caller discover how to enable a needed native-analysis workflow, without loading the full catalog or changing the caller's registration automatically?

Context and evidence

I captured real stdio initialize, tools/list, prompts, and calls on REA main 6e9ee97a, Node 24.22.1, SDK 2.3.1, and protocol 2025-11-25, with REA_MCP_OUTPUT_SCHEMA_PROFILE=compact:

The documented native,artifact,session example is explicitly described as covering Mach-O, signatures, property lists and extraction. It advertises 79 tools, including session and artifact workflows, but not analyze_function, trace_native_values, procedure_pseudo_code, search_procedures, inspect_analysis_view, search_guidance or read_guidance_section. The three advertised prompts concern reconstruction, unknowns and process capture.
If the caller already knows a hidden name and calls it, the SDK returns ProtocolError: Tool trace_native_values disabled (likewise for the others tested); the error does not identify its family. The startup instructions mention adding application for runtime settings in a specific recovery case, but do not identify the selected families or explain where to find an omitted native-analysis capability. binary_session intentionally reports the scoped inventory, not disabled operations.
Control: with session,enhanced,application, 60 tools were advertised. On the same source-owned unexecuted Mach-O, real Ghidra 12.1.4 and Kuna 1.986 both completed open_binary → analyze_function summary for a known function → inspect_analysis_view pseudocode → Evidence export → close. The retrieved page matched the respective complete dossier. Focused direct search/assembly/pseudocode tools were not advertised in that scope; add direct when those capabilities are needed. This is one known-function task, not proof of full native workflow coverage.

A caller starting solely with the narrowed catalog has no names for omitted tools to try; that is an inference from the advertised surface, not an observed model-selection or abandonment rate. The documentation's metadata-only scope is not itself incorrect. Existing family filtering and canonical validation behaved as documented.

A separate direct-only stdio MCP control reproduced a narrower broken recovery: read_bytes with no target instructed the caller to invoke open_binary, but that tool is disabled in the scoped connection. See #8657 for the real control and session,direct working comparison.

Expected interaction with targets

No target interaction for the proposed discovery/guidance change. The verification above read a local fixture and launched the existing providers.

Boundary details

Preserve the caller-selected scope: do not automatically enable tools, change registration files, infer provider absence from a scoped catalog, or expose an unbounded second copy of the catalog. Family configuration is read at startup; changing it requires the existing restart/setup workflow.

Options and tradeoffs

Add a short conditional initialization instruction naming the active family scope and explaining that omitted tools may be enabled by updating REA_MCP_TOOL_FAMILIES and restarting; point to the family mapping. This costs some context and must not prescribe hidden tools as callable.
Add a task-oriented native-decompilation example to the scope-selection documentation, explaining the enhanced/application path and when direct is useful.
Keep the present behavior if scope is expected to be an explicit host/user decision and out-of-band documentation is sufficient. A solution should avoid confusing provider availability with registration scope.

Verification available so far

I have a prototype or observed results.

Success criteria and open questions

Check unscoped and several scoped initialize/tools/list payloads, selection of the suggested families, actual SDK calls and canonical schema validation, and expected behavior when settings tools are excluded. Measure payload/context impact and run controlled host/model trials before making a selection-effect claim. How can a scoped caller find an appropriate family mapping without requiring an unavailable guidance tool?

References

Related catalog economics: #723 and #7155; #7154 proposes family metadata on advertised tools, which does not expose omitted tools on a scoped connection. Source guidance: docs/mcp-contracts.md#tool-family-advertising-scope. MCP supports optional output schemas and does not prescribe host presentation: https://modelcontextprotocol.io/specification/2025-11-25/server/tools . Maintainers: @gensokyo-dev @kaoru0822-kitauji @N0zoM1z0

Originally created by @morluto on GitHub (Oct 31, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/8388 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related discussion. - [x] I understand the contribution scope must be reviewed before integration; open questions are welcome here. - [x] This discussion does not include credentials, private samples, or sensitive target data. ### Decision needed How should a family-scoped MCP connection communicate that its catalog is intentionally narrowed and help a caller discover how to enable a needed native-analysis workflow, without loading the full catalog or changing the caller's registration automatically? ### Context and evidence I captured real stdio `initialize`, `tools/list`, prompts, and calls on REA main `6e9ee97a`, Node 24.22.1, SDK 2.3.1, and protocol `2025-11-25`, with `REA_MCP_OUTPUT_SCHEMA_PROFILE=compact`: - The documented `native,artifact,session` example is explicitly described as covering Mach-O, signatures, property lists and extraction. It advertises 79 tools, including session and artifact workflows, but not `analyze_function`, `trace_native_values`, `procedure_pseudo_code`, `search_procedures`, `inspect_analysis_view`, `search_guidance` or `read_guidance_section`. The three advertised prompts concern reconstruction, unknowns and process capture. - If the caller already knows a hidden name and calls it, the SDK returns `ProtocolError: Tool trace_native_values disabled` (likewise for the others tested); the error does not identify its family. The startup instructions mention adding `application` for runtime settings in a specific recovery case, but do not identify the selected families or explain where to find an omitted native-analysis capability. `binary_session` intentionally reports the scoped inventory, not disabled operations. - Control: with `session,enhanced,application`, 60 tools were advertised. On the same source-owned unexecuted Mach-O, real Ghidra 12.1.4 and Kuna 1.986 both completed `open_binary` → `analyze_function` summary for a known function → `inspect_analysis_view` pseudocode → Evidence export → close. The retrieved page matched the respective complete dossier. Focused direct search/assembly/pseudocode tools were not advertised in that scope; add `direct` when those capabilities are needed. This is one known-function task, not proof of full native workflow coverage. A caller starting solely with the narrowed catalog has no names for omitted tools to try; that is an inference from the advertised surface, not an observed model-selection or abandonment rate. The documentation's metadata-only scope is not itself incorrect. Existing family filtering and canonical validation behaved as documented. A separate direct-only stdio MCP control reproduced a narrower broken recovery: `read_bytes` with no target instructed the caller to invoke `open_binary`, but that tool is disabled in the scoped connection. See #8657 for the real control and `session,direct` working comparison. ### Expected interaction with targets No target interaction for the proposed discovery/guidance change. The verification above read a local fixture and launched the existing providers. ### Boundary details Preserve the caller-selected scope: do not automatically enable tools, change registration files, infer provider absence from a scoped catalog, or expose an unbounded second copy of the catalog. Family configuration is read at startup; changing it requires the existing restart/setup workflow. ### Options and tradeoffs - Add a short conditional initialization instruction naming the active family scope and explaining that omitted tools may be enabled by updating `REA_MCP_TOOL_FAMILIES` and restarting; point to the family mapping. This costs some context and must not prescribe hidden tools as callable. - Add a task-oriented native-decompilation example to the scope-selection documentation, explaining the `enhanced`/`application` path and when `direct` is useful. - Keep the present behavior if scope is expected to be an explicit host/user decision and out-of-band documentation is sufficient. A solution should avoid confusing provider availability with registration scope. ### Verification available so far I have a prototype or observed results. ### Success criteria and open questions Check unscoped and several scoped `initialize`/`tools/list` payloads, selection of the suggested families, actual SDK calls and canonical schema validation, and expected behavior when settings tools are excluded. Measure payload/context impact and run controlled host/model trials before making a selection-effect claim. How can a scoped caller find an appropriate family mapping without requiring an unavailable guidance tool? ### References Related catalog economics: #723 and #7155; #7154 proposes family metadata on advertised tools, which does not expose omitted tools on a scoped connection. Source guidance: `docs/mcp-contracts.md#tool-family-advertising-scope`. MCP supports optional output schemas and does not prescribe host presentation: https://modelcontextprotocol.io/specification/2025-11-25/server/tools . Maintainers: @gensokyo-dev @kaoru0822-kitauji @N0zoM1z0

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

No description provided.

Rows
Columns