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:
1 parent
ad518cff65
commit
0beedcd712
22 files changed
+956
-42
No files matched your search
@@ -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
@@ -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
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user