diff --git a/ROADMAP.md b/ROADMAP.md index 083b6918c..ab2579798 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -67,8 +67,8 @@ graph LR classDef in_progress fill:#1f6feb,stroke:#0b3d91,color:#ffffff; classDef in_review fill:#9a6700,stroke:#5c3d00,color:#ffffff; classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff; - class sandbox_isolation,scanner_v2,scanner_simplification done; - class analytics_dashboard,schema_deferred,telemetry_identity,telemetry_v7_churn in_progress; + class sandbox_isolation,scanner_v2,scanner_simplification,schema_deferred done; + class analytics_dashboard,telemetry_identity,telemetry_v7_churn in_progress; class tpa_db in_review; class ux_audit,action_log_transparency,remote_access_tunnel,token_bench,tool_graph,discovery_eval_harness todo; ``` @@ -154,15 +154,6 @@ graph LR -
-πŸ”΅ Deferred-schema serialization for the direct tools/list surface (spec 102) β€” In progress Β· P1 - -> Direct mode enumerates every upstream tool but always ships full inputSchema (~30K tokens for a 100-tool fleet; Spec 083 profiling put ~77% of the payload in schemas agents rarely read). Deferred serialization keeps every tool name, description and annotation and appends the Spec 085 compact signature instead of the schema (~88% smaller listing), with describe_tool on the direct surface to recover it and the shipped pre-dispatch validation turning a wrong guess into one self-healing retry. Not a new routing_mode β€” a serialization mode of the direct surface, on the same tool_response_mode axis that already governs retrieve_tools. Spec merged in #1035 (issue #971, maintainer-accepted direction); plan in progress. - -Spec: [102-schema-deferred](./specs/102-schema-deferred/) - -
-
πŸ”΅ Telemetry identity & data quality (machine_id + CI-filter hardening) β€” In progress Β· P1 @@ -711,6 +702,15 @@ graph LR
+
+🟒 Deferred-schema serialization for the direct tools/list surface (spec 102) β€” Done Β· P1 + +> Direct mode enumerates every upstream tool but always ships full inputSchema (~30K tokens for a 100-tool fleet; Spec 083 profiling put ~77% of the payload in schemas agents rarely read). Deferred serialization keeps every tool name, description and annotation and appends the Spec 085 compact signature instead of the schema (~88% smaller listing), with describe_tool on the direct surface to recover it and the shipped pre-dispatch validation turning a wrong guess into one self-healing retry. Not a new routing_mode β€” a serialization mode of the direct surface, on the same tool_response_mode axis that already governs retrieve_tools. Spec merged in #1035 (issue #971, maintainer-accepted direction). COMPLETE: all 89 tasks shipped in #1063; the settings UI for both serialization axes followed in #1082. MEASURED SAVINGS FELL WELL SHORT OF THE ~88% PROJECTION ABOVE: 29.7% on the frozen reference corpus and 34.8% on a 527-tool snapshot, against SC-001's >=70% target, with 38.9% the arithmetic ceiling even if both the schema and the signature were deleted. The projection assumed schemas dominate the payload; names, descriptions and annotations turn out to carry most of it. SC-001 is knowingly unmet and awaits a maintainer decision (restate per corpus shape, or re-target at a schema-heavy corpus) β€” see specs/102-schema-deferred/tasks.md T035a. + +Spec: [102-schema-deferred](./specs/102-schema-deferred/) Β· PR: #1063 + +
+
🟒 Tray↔core decoupling: socket/REST API only, no config-file reads β€” Done Β· P2 @@ -740,7 +740,6 @@ graph LR | --- | --- | --- | --- | --- | --- | | Release qualification gate (auto-QA matrix blocks the tag) | In progress | P0 | β€” | [081-release-qa-gate](./specs/081-release-qa-gate/) | | | Analytics dashboard as default page | In progress | P1 | 25/26 (96%) | [069-observability-usage-graphs](./specs/069-observability-usage-graphs/) | | -| Deferred-schema serialization for the direct tools/list surface (spec 102) | In progress | P1 | 89/89 (100%) | [102-schema-deferred](./specs/102-schema-deferred/) | | | Telemetry identity & data quality (machine_id + CI-filter hardening) | In progress | P1 | β€” | | | | Telemetry v7: honest funnel + churn instrumentation | In progress | P1 | β€” | [080-telemetry-v7-churn](./specs/080-telemetry-v7-churn/) | | | MCP protocol upgrade to 2026-07-28 revision | In progress | P3 | β€” | [058-mcp-2026-upgrade](./specs/058-mcp-2026-upgrade/) | #1033 | @@ -765,6 +764,7 @@ graph LR | Spec 076 deterministic offline tool-scanner `MCP-3574` | Done | P1 | 22/24 (92%) | [076-deterministic-tool-scanner](./specs/076-deterministic-tool-scanner/) | | | Registries β€” easier search + add-server | Done | P1 | 21/24 (88%) | [070-registry-easy-upstream-add](./specs/070-registry-easy-upstream-add/) | | | Scanner simplification (deterministic default, opt-in deep scan) | Done | P1 | 38/42 (90%) | [077-scanner-simplification](./specs/077-scanner-simplification/) | | +| Deferred-schema serialization for the direct tools/list surface (spec 102) | Done | P1 | 89/89 (100%) | [102-schema-deferred](./specs/102-schema-deferred/) | #1063 | | Tray↔core decoupling: socket/REST API only, no config-file reads | Done | P2 | β€” | | | ## Shipped (archived) diff --git a/docs/configuration.md b/docs/configuration.md index 1a9528ef9..5e5556a59 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1166,7 +1166,7 @@ Controls only the *serialization* of `retrieve_tools` responses (Spec 085) β€” n - **Per-call override**: the `detail` parameter on `retrieve_tools` (`compact` | `full`) overrides the configured mode for that call only. - **describe_tool**: in compact mode, agents fetch full definitions on demand with `describe_tool` (batch of 1–5 `server:tool` ids; same visibility rules as search). - **Hot-reload**: changes apply on the next call via the config file reload or `POST /api/v1/config/apply` β€” no restart. -- Env: `MCPPROXY_TOOL_RESPONSE_MODE` Β· Flag: `--tool-response-mode`. +- Env: `MCPPROXY_TOOL_RESPONSE_MODE` Β· Flag: `--tool-response-mode` Β· UI: Settings β†’ General β†’ "Detail in tool-search results" (Web UI and macOS tray). --- @@ -1190,7 +1190,7 @@ Controls only the *serialization* of the **direct enumeration surface** (Spec 10 - **Separate axis from `tool_response_mode`**: that key governs `retrieve_tools` responses, this one governs the direct enumeration surface, and setting one never moves the other. `tool_response_mode: "compact"` together with `direct_tool_response_mode: "deferred"` is a legal, intentional combination β€” each still governs only its own surface. - **Not a `routing_mode` value**: `routing_mode: "schema_deferred"` is rejected by config validation with a message naming the supported composition (`routing_mode: "direct"` with `direct_tool_response_mode: "deferred"`). - **Hot-reload**: flipping the mode rebuilds the direct surface and emits `notifications/tools/list_changed` to connected direct-surface sessions β€” no restart. -- Env: `MCPPROXY_DIRECT_TOOL_RESPONSE_MODE` Β· Flag: `--direct-tool-response-mode`. +- Env: `MCPPROXY_DIRECT_TOOL_RESPONSE_MODE` Β· Flag: `--direct-tool-response-mode` Β· UI: Settings β†’ General β†’ "Detail in Direct-mode listings" (Web UI and macOS tray). ## Server Instructions diff --git a/docs/features/schema-deferred-direct-mode.md b/docs/features/schema-deferred-direct-mode.md index f0e6b8d10..d9cf452b7 100644 --- a/docs/features/schema-deferred-direct-mode.md +++ b/docs/features/schema-deferred-direct-mode.md @@ -78,6 +78,13 @@ MCPPROXY_DIRECT_TOOL_RESPONSE_MODE=deferred mcpproxy serve mcpproxy serve --direct-tool-response-mode=deferred ``` +Or from the UI β€” **Settings β†’ General β†’ "Detail in Direct-mode listings"**, in +both the Web UI and the macOS tray. The routing-mode field ("How agents find +tools") heads the same section, two rows above. Note the asymmetry: changing the +serialization mode applies hot, but changing `routing_mode` needs a restart (the +badge on that field says so), because `/mcp` binds its routing mode once at +startup. + **This is a separate axis from `tool_response_mode`.** That key (and its `--tool-response-mode` flag and `MCPPROXY_TOOL_RESPONSE_MODE` alias) still governs `retrieve_tools` serialization only, and its meaning is unchanged. The two @@ -343,6 +350,6 @@ editing the `instructions` config key needs a restart β€” unlike - [Routing Modes](routing-modes.md) β€” what the direct surface is and when to choose it - [Required-Tools Preflight](tools-preflight.md) β€” `describe_tool` check mode and the reason taxonomy -- [Search & Discovery](search-discovery.md) β€” the `retrieve_tools` surface and its own `tool_response_mode` axis +- [Search & Discovery](search-discovery.md) β€” the `retrieve_tools` surface and its own [`tool_response_mode` axis](search-discovery.md#tool-response-mode) - [Agent Tokens](agent-tokens.md) β€” scoping which tools a session lists at all - [Configuration Reference](../configuration/config-file.md) diff --git a/docs/features/search-discovery.md b/docs/features/search-discovery.md index f57dba714..f8f5fcbdc 100644 --- a/docs/features/search-discovery.md +++ b/docs/features/search-discovery.md @@ -94,6 +94,38 @@ curl -H "X-API-Key: your-key" \ |--------|------|---------|-------------| | `tools_limit` | integer | `15` | Maximum results per query | +### Response detail β€” `tool_response_mode` {#tool-response-mode} + +Controls only how each `retrieve_tools` result is *serialized*. It never changes +the query, the ranking, or which tools are found. + +```json +{ + "tool_response_mode": "compact" +} +``` + +| Option | Type | Default | Values | Description | +|--------|------|---------|--------|-------------| +| `tool_response_mode` | string | `"full"` | `full`, `compact` | `full` returns each result with its complete `inputSchema` (pre-Spec-085 behaviour, byte-identical). `compact` returns a one-line signature instead: per entry `id`, `score`, `sig`, a first-sentence `desc` and a `lossy` flag, plus one top-level `hint`. An empty value means `full`. | + +- **Compact signatures**: `*` marks a required parameter (never elided), `~` + marks a lossy collapse (nested objects, long enums), and short enums/defaults + are inlined β€” e.g. `(origin*:str, ttl:int=3600)`. +- **Recovering a full schema**: in compact mode agents call `describe_tool` with + a batch of 1–5 `server:tool` ids. Same visibility rules as search. +- **Per-call override**: the `detail` parameter on `retrieve_tools` + (`compact` | `full`) overrides the configured mode for that one call. +- **Where to set it**: Settings β†’ General β†’ "Detail in tool-search results", in + both the Web UI and the macOS tray. Also `MCPPROXY_TOOL_RESPONSE_MODE`, the + `--tool-response-mode` serve flag, or the config key directly. +- **Hot-reload**: applies on the next call β€” no restart. + +This axis governs the `retrieve_tools` surface only. The **direct** enumeration +surface has its own, separate axis, `direct_tool_response_mode` β€” see +[Schema-Deferred Direct Mode](schema-deferred-direct-mode.md). Setting one never +moves the other, and combining them is legal. + ### Index Location The search index is stored at: diff --git a/docs/features/settings-page.md b/docs/features/settings-page.md index c5f1b21a7..2842be98c 100644 --- a/docs/features/settings-page.md +++ b/docs/features/settings-page.md @@ -12,8 +12,9 @@ friendly, prioritized form sections instead of raw JSON: - **Security & Access** β€” API key (masked, show/regenerate), require MCP auth, quarantine, global Docker isolation, code execution, read-only mode, sensitive-data detection, reveal secret headers, listen address. -- **General** β€” routing mode, tool limits, response limit, call timeout, log - level, telemetry, prompts. +- **General** β€” routing mode, the two response-detail modes (`tool_response_mode` + for Retrieve, `direct_tool_response_mode` for Direct), tool limits, response + limit, call timeout, log level, telemetry, prompts. - **Advanced** β€” collapsible accordions per subsystem (code execution, Docker isolation, sensitive-data detection, output validation, output sanitisation, activity retention, logging, TLS, …). @@ -28,8 +29,10 @@ pipeline. Because the merge starts from the live config and overlays just your changes, unrelated values and masked secrets (API key, secret headers) are never overwritten. -Fields that need a restart (`listen`, `data_dir`, `api_key`, `tls.*`) show a -**restart** badge; sensitive changes (reveal secret headers, disabling +Fields that need a restart (`listen`, `api_key`, `routing_mode`, `tls.*`, +`code_execution_pool_size`, and `server_edition.enabled` on the server edition) +show a **restart** badge β€” the two response-detail modes deliberately carry no +badge, because they hot-reload; sensitive changes (reveal secret headers, disabling quarantine/management, binding to a non-loopback address) require an explicit confirmation before they apply. diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue index 87e4231ea..0845e5c19 100644 --- a/frontend/src/views/Settings.vue +++ b/frontend/src/views/Settings.vue @@ -32,7 +32,7 @@

πŸ” Search results ({{ filteredFields.length }})

- +
@@ -82,7 +82,7 @@ {{ p.label }}: {{ p.on ? 'on' : 'off' }} - + @@ -90,7 +90,7 @@

βš™οΈ General

- +
@@ -110,7 +110,7 @@ :data-test="`settings-accordion-docs-${acc.id}`" >Learn more β†—

- +
@@ -123,7 +123,7 @@

{{ serverEditionTitle }}

- +
@@ -194,6 +194,7 @@ import { docsUrl, isBlankInstructions, restartRequiredLabels, + hydrateConfigState, type SettingField, type SettingsAccordion, } from '@/views/settings/fields' @@ -248,6 +249,13 @@ const loadError = ref('') const activeTab = ref('security') const showConnect = ref(false) const state = reactive<{ working: any; original: any }>({ working: {}, original: {} }) +// Bumped on every (re)hydration so each SettingsSection remounts with a fresh +// component-local `dirty` ref. Without this, a field the user edited and then +// abandoned via Reload stays in that ref, and because dirtyKeys is the UNION of +// it and the working/original comparison, Save would PATCH a key whose value +// never actually moved β€” writing a resolved default into a config that omitted +// the key entirely. +const formEpoch = ref(0) // Server-edition (multi-user) config lives under `server_edition` (MCP-1086). // Gate on the canonical key, falling back to the legacy `teams` key so a config // written before the rename still surfaces the Server Edition tab. @@ -319,20 +327,6 @@ const editorOptions = { lineNumbers: 'on' as const, } -function clone(v: T): T { - return JSON.parse(JSON.stringify(v)) -} - -// Back-compat for the teams -> server_edition rename (MCP-1086): if a config -// only carries the legacy `teams` key, mirror it onto `server_edition` so the -// form (which binds to `server_edition.*`) hydrates. Mutates and returns cfg. -function aliasServerEdition(cfg: any): any { - if (cfg && cfg.server_edition == null && cfg.teams != null) { - cfg.server_edition = cfg.teams - } - return cfg -} - async function loadConfig() { loading.value = true loadError.value = '' @@ -344,9 +338,18 @@ async function loadConfig() { // backend loader already normalizes a legacy `teams` key to // `server_edition`, but alias it here too so a config still carrying the // old key hydrates the form (edits always save under `server_edition`). - state.working = aliasServerEdition(clone(cfg)) - state.original = aliasServerEdition(clone(cfg)) - configJson.value = JSON.stringify(cfg, null, 2) + // normalizeFieldDefaults fills the resolved default for `omitempty` + // keys the API omits (the serialization modes: absent means "full"), so + // their whose value matches no