perf(mcp): add opt-in hot/cold tool discovery (#9046)

Add per-connection discovery that loads canonical named tools on demand while preserving the default full catalog. Bound discovery replies before changing visibility, preserve family exclusions and Evidence workflows, and reset visibility on HTTP reconnect.

Verified with focused protocol tests and real Codex CLI artifact investigations; token costs remain task-dependent, so the profile is opt-in.
This commit is contained in:
gensokyo-dev authored and GitHub committed 2026-11-05 20:27:31 +00:00
1 parent ad518cff65
commit 0beedcd712
22 files changed
+956 -42

No files matched your search

+27
View File
@@ -102,6 +102,33 @@ does not repair a client's naming behavior or infer permission drift from an
unfamiliar prefix. The unavailable fork reported in
[#5512](https://github.com/morluto/rea/issues/5512) has not been reverified.
## Hot/cold catalogs
For a client that supports MCP catalog refresh, set
`REA_MCP_TOOL_CATALOG_PROFILE=hot-cold` in REA's server environment and restart
the connection. REA then advertises a small initial catalog and loads other
named tools through `discover_tools`. Setup preserves this explicit setting.
See the [discovery contract](mcp-contracts.md#hotcold-catalog-discovery) for
pagination, identity and family-scope semantics.
Codex CLI 0.165.0 requires its experimental `mcp_tool_list_changed` feature for
this workflow. Merge these entries into the existing `~/.codex/config.toml`
without replacing other feature or REA settings:
```toml
[features]
mcp_tool_list_changed = true
[mcp_servers.rea.env]
REA_MCP_TOOL_CATALOG_PROFILE = "hot-cold"
```
The server setting alone does not enable client refresh. If a successful
discovery call is followed by a missing tool, check the client's refresh feature
and tool allow/deny lists. Clients without refresh should use the default
`REA_MCP_TOOL_CATALOG_PROFILE=full`; reconnect after changing it. Other clients'
hot/cold behavior has not been verified.
## Fiddler Everywhere alongside REA
Connect Fiddler Everywhere's MCP server separately for HTTP traffic debugging,
+43 -2
View File
@@ -899,7 +899,7 @@ registrations, reports their command vectors as aligned, stale, missing, or
invalid, and keeps live-server state `unknown` unless the active connection
supplies identity.
`tools/list` returns the complete canonical tool inventory, including tools that
By default, `tools/list` returns the complete canonical tool inventory, including tools that
are currently unavailable. Opening or closing a target or observing a provider
health transition leaves that catalog unchanged and does not emit
`notifications/tools/list_changed`.
@@ -911,7 +911,7 @@ share status facts. `tool_availability.client_requirements` is the baseline for
each group; a group's optional `client_requirements` replaces that baseline for
the group's tools. Expand each group's `names` into one tool entry, carrying its
availability, reason, remediation, default-mode status, modes, and client
requirements. Compare the union of group names with `tools/list` when checking
requirements. With the default full catalog, compare the union of group names with `tools/list` when checking
that a client received the full catalog. An operation absent from all groups is
missing from the complete inventory; it is not an implicit unavailable entry.
@@ -1873,6 +1873,47 @@ check full-profile local-path rules. Compact MCP workflow tests verify canonical
rejection of invalid inputs before provider work, independent of how much detail
the selected advertisement retains.
### Hot/cold catalog discovery
`REA_MCP_TOOL_CATALOG_PROFILE=hot-cold` opts into per-connection loading for
clients that refresh `tools/list` after `notifications/tools/list_changed`.
The default, `full`, retains the complete upfront advertisement. Restart the
server to change profiles. See [client configuration](client-configuration.md#hotcold-catalogs).
Hot/cold initially advertises `binary_session`, `open_binary`, `close_binary`,
`get_evidence_bundle`, `inspect_analysis_view`, and the adapter's `discover_tools`.
An explicit tool-family scope can remove any of those domain tools.
`discover_tools` searches canonical names and descriptions using case-insensitive
words, or accepts exact `names`. It loads the matching page and returns names
and abbreviated descriptions with their configured input schemas, so the next
call can use the returned arguments contract. Output schemas remain in
`tools/list`. Search defaults to three results, allows up to
20 per page, and returns `total_matches` and `next_offset`. Exact names preserve
request order and reject unknown or excluded names before loading anything.
Use fewer keywords when no result matches; search requires every word to match.
Both reply representations must fit the configured response budget before any
tools load. An oversized page returns a resource constraint; reduce `limit` or
request fewer exact names and retry. Input schemas are retained in full within
the selected input profile.
Loaded definitions retain their original names, complete configured schemas,
annotations, handlers and client approval rules. Loading does not execute an
analysis, open a target, or initialize the deferred analysis runtime. A batch
emits one list-change notification; repeating it emits none. Loaded tools remain
available until the connection ends. There is no generic execution gateway.
If a loaded tool does not appear in the client, enable client catalog refresh
or reconnect using `REA_MCP_TOOL_CATALOG_PROFILE=full`.
The catalog identity covers the complete in-scope inventory, the discovery
contract and the hot/cold policy; its count includes `discover_tools`. It differs
from full advertisement and remains stable as tools load. `rea mcp doctor`
checks the profile's initial advertisement and identity. The domain inventory in
`binary_session.tool_availability` continues to describe provider and target
availability, independently of whether a definition is loaded. Load a listed
cold tool before calling it. Provider health and target changes do not load,
unload or remove definitions. The input/output schema profiles and explicit
family exclusions continue to apply.
### Tool family advertising scope
Agents pay context for every advertised tool schema, and clients that send
+5 -2
View File
@@ -8,8 +8,11 @@ Extend a tool when intent and result contract match; add one for a distinct
outcome or materially different authority. Public names and semantics remain
provider-neutral, with exact coverage reported per provider.
Keep the catalog complete; report capability/session availability instead of
truncating schemas. Serialized bytes alone do not establish agent usability.
Keep the discoverable inventory complete within the caller's selected scope;
report capability/session availability independently of catalog visibility.
An opt-in dynamic catalog must retain canonical named contracts and provide
discovery and recovery for clients without refresh. Serialized bytes alone do
not establish agent usability.
## Choose the tool shape