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 @@
@@ -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 shows the real default instead of an empty box. Applied
+ // to both copies β otherwise the untouched field would read as dirty.
+ const hydrated = hydrateConfigState(cfg)
+ state.working = hydrated.working
+ state.original = hydrated.original
+ formEpoch.value++
+ // hydrated.raw, not cfg: the Raw tab must show the untouched response,
+ // and this makes that dependency explicit rather than relying on the
+ // hydration helper's internal cloning.
+ configJson.value = JSON.stringify(hydrated.raw, null, 2)
configStatus.value = { valid: true }
loaded.value = true
maybePrefillInstructions()
diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index 60fd9deda..9e1dd7807 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -50,6 +50,10 @@ export interface SettingField {
valueKind?: ValueKind // extra format validation for text/secret fields
optional?: boolean // when true, an empty value is valid (skips kind validation)
resetDefault?: string // when set, render an inline "Reset to default" button that emits this value
+ // Value an absent/blank key actually resolves to on the Go side. Only needed
+ // for `omitempty` fields whose zero value is meaningful (the serialization
+ // modes: "" means "full"). See normalizeFieldDefaults below for why.
+ defaultValue?: string
}
export interface SettingsAccordion {
@@ -252,6 +256,36 @@ export const GENERAL_FIELDS: SettingField[] = [
// serving the old surface.
restart: true,
},
+ // Spec 085 / Spec 102 β the two SERIALIZATION axes. Neither is a routing
+ // mode: `routing_mode` picks the tool SURFACE, these two pick how each entry
+ // on that surface is rendered. Both hot-reload (the Go change detector sets
+ // requires_restart for neither), so no restart badge. Until this landed they
+ // were reachable only via the config file, an env var, a serve flag or the
+ // REST API β a tray-only user could not set them at all.
+ {
+ key: 'tool_response_mode',
+ docs: '/features/search-discovery#tool-response-mode',
+ label: 'Detail in tool-search results',
+ help: 'Applies to Retrieve mode. Full = every result carries its complete input schema. Compact = a one-line signature plus a first-sentence description, and the agent fetches a full schema on demand with describe_tool. Saves tokens; never changes which tools are found.',
+ control: 'select',
+ defaultValue: 'full',
+ options: [
+ { value: 'full', label: 'Full β complete schemas (default)' },
+ { value: 'compact', label: 'Compact β signatures, schema on demand' },
+ ],
+ },
+ {
+ key: 'direct_tool_response_mode',
+ docs: '/features/schema-deferred-direct-mode',
+ label: 'Detail in Direct-mode listings',
+ help: 'Applies to Direct mode, and to /mcp/all in any mode. Full = every tool is listed with its complete input schema. Deferred = name, description and a compact signature only, with schemas fetched on demand via describe_tool; a call whose arguments do not fit is rejected before it reaches the server, with the schema attached so the agent can correct itself.',
+ control: 'select',
+ defaultValue: 'full',
+ options: [
+ { value: 'full', label: 'Full β complete schemas (default)' },
+ { value: 'deferred', label: 'Deferred β signatures, schema on demand' },
+ ],
+ },
{ key: 'tools_limit', label: 'Search results limit', help: 'How many tools a single tool-search returns to the agent.', control: 'number', min: 1, max: 1000 },
{ key: 'tool_response_limit', label: 'Max tool response size (characters)', help: 'Responses larger than this are truncated and cached so the agent can page through them. 0 = never truncate.', control: 'number', min: 0 },
{ key: 'call_tool_timeout', label: 'Tool call timeout', help: 'How long to wait for a single tool call before giving up. e.g. 2m, 90s, 30s.', control: 'duration', placeholder: '2m' },
@@ -457,17 +491,74 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
* follows.
*/
export function restartRequiredLabels(): string[] {
- const fields = [
+ const labels: string[] = []
+ for (const f of allCatalogFields()) {
+ if (f.restart && !labels.includes(f.label)) labels.push(f.label)
+ }
+ return labels
+}
+
+/** Every field in the catalogue, across all sections and accordions. */
+export function allCatalogFields(): SettingField[] {
+ return [
...GENERAL_FIELDS,
...SECURITY_FIELDS,
...SERVER_EDITION_FIELDS,
...ADVANCED_ACCORDIONS.flatMap((a) => a.fields),
]
- const labels: string[] = []
- for (const f of fields) {
- if (f.restart && !labels.includes(f.label)) labels.push(f.label)
+}
+
+/**
+ * Fill in the resolved default for every catalogue field that declares a
+ * `defaultValue` and is currently blank in `cfg`. Mutates and returns cfg.
+ *
+ * The serialization-mode keys are `omitempty` on the Go side, where an absent
+ * value means "full" β so the config the API returns simply omits them until
+ * someone sets one. A native whose value matches no renders
+ * an empty box, which would make the default read as "unset" rather than as
+ * "full". Applied to BOTH the working copy and the last-saved snapshot so a
+ * field nobody touched never counts as an unsaved change.
+ */
+/**
+ * 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.
+ */
+export function aliasServerEdition(cfg: any): any {
+ if (cfg && cfg.server_edition == null && cfg.teams != null) {
+ cfg.server_edition = cfg.teams
}
- return labels
+ return cfg
+}
+
+/**
+ * Build the Settings form state from a raw `GET /api/v1/config` response.
+ *
+ * Extracted from Settings.vue so the hydration invariant is testable directly
+ * rather than by matching source text. That invariant:
+ *
+ * - `working` and `original` BOTH get the resolved defaults, so a field nobody
+ * touched never counts as an unsaved change.
+ * - `raw` is the untouched response. The Raw JSON tab must show server truth,
+ * and both helpers above MUTATE their argument, so the clones matter.
+ */
+export function hydrateConfigState(cfg: any): { working: any; original: any; raw: any } {
+ const clone = (v: any) => (v == null ? v : JSON.parse(JSON.stringify(v)))
+ return {
+ working: normalizeFieldDefaults(aliasServerEdition(clone(cfg))),
+ original: normalizeFieldDefaults(aliasServerEdition(clone(cfg))),
+ raw: clone(cfg),
+ }
+}
+
+export function normalizeFieldDefaults(cfg: any): any {
+ if (cfg == null || typeof cfg !== 'object') return cfg
+ for (const f of allCatalogFields()) {
+ if (f.defaultValue == null) continue
+ const cur = getPath(cfg, f.key)
+ if (cur == null || cur === '') setPath(cfg, f.key, f.defaultValue)
+ }
+ return cfg
}
export function getPath(obj: any, path: string): any {
diff --git a/frontend/tests/unit/settings-serialization-modes.spec.ts b/frontend/tests/unit/settings-serialization-modes.spec.ts
new file mode 100644
index 000000000..bfdd57f1c
--- /dev/null
+++ b/frontend/tests/unit/settings-serialization-modes.spec.ts
@@ -0,0 +1,178 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import {
+ GENERAL_FIELDS,
+ hydrateConfigState,
+ allCatalogFields,
+ normalizeFieldDefaults,
+ restartRequiredLabels,
+ getPath,
+ type SettingField,
+} from '@/views/settings/fields'
+
+function field(key: string): SettingField {
+ const f = allCatalogFields().find((x) => x.key === key)
+ if (!f) throw new Error(`no settings field for ${key}`)
+ return f
+}
+
+// Specs 085 + 102 β the two serialization knobs shipped with four ways to set them
+// (config file, env var, serve flag, REST API) and zero UI surfaces. A tray- or
+// Web-UI-only operator could not reach direct_tool_response_mode at all.
+describe('serialization-mode settings fields', () => {
+ it('exposes both serialization axes in the catalogue', () => {
+ expect(field('tool_response_mode').control).toBe('select')
+ expect(field('direct_tool_response_mode').control).toBe('select')
+ })
+
+ it('offers exactly the values the Go validator accepts', () => {
+ expect(field('tool_response_mode').options?.map((o) => o.value)).toEqual(['full', 'compact'])
+ expect(field('direct_tool_response_mode').options?.map((o) => o.value)).toEqual([
+ 'full',
+ 'deferred',
+ ])
+ })
+
+ // Both are hot-reloadable: internal/runtime/config_hotreload.go appends them
+ // to ChangedFields WITHOUT setting RequiresRestart. Badging them would tell
+ // the operator to restart for nothing β and routing_mode, right above them,
+ // genuinely does need one, so the distinction has to stay visible.
+ it('carries no restart badge, unlike routing_mode', () => {
+ expect(field('tool_response_mode').restart).toBeFalsy()
+ expect(field('direct_tool_response_mode').restart).toBeFalsy()
+ expect(field('routing_mode').restart).toBe(true)
+
+ const labels = restartRequiredLabels()
+ expect(labels).not.toContain(field('tool_response_mode').label)
+ expect(labels).not.toContain(field('direct_tool_response_mode').label)
+ expect(labels).toContain(field('routing_mode').label)
+ })
+
+ it('sits next to routing_mode, the knob it qualifies', () => {
+ const keys = GENERAL_FIELDS.map((f) => f.key)
+ expect(keys.slice(0, 3)).toEqual([
+ 'routing_mode',
+ 'tool_response_mode',
+ 'direct_tool_response_mode',
+ ])
+ })
+
+ it('links each field to a page that documents that axis', () => {
+ expect(field('tool_response_mode').docs).toBe('/features/search-discovery#tool-response-mode')
+ expect(field('direct_tool_response_mode').docs).toBe('/features/schema-deferred-direct-mode')
+ })
+
+ it('names the routing mode each axis applies to, since only one is live at a time', () => {
+ expect(field('tool_response_mode').help).toMatch(/Retrieve mode/)
+ expect(field('direct_tool_response_mode').help).toMatch(/Direct mode/)
+ })
+})
+
+describe('normalizeFieldDefaults', () => {
+ it('renders an omitted omitempty mode as its real default, not a blank select', () => {
+ const cfg = normalizeFieldDefaults({ listen: '127.0.0.1:8080' })
+ expect(cfg.tool_response_mode).toBe('full')
+ expect(cfg.direct_tool_response_mode).toBe('full')
+ })
+
+ it('treats an explicit empty string the same as absent (Go reads "" as full)', () => {
+ const cfg = normalizeFieldDefaults({ tool_response_mode: '', direct_tool_response_mode: '' })
+ expect(cfg.tool_response_mode).toBe('full')
+ expect(cfg.direct_tool_response_mode).toBe('full')
+ })
+
+ it('never overwrites a value the operator actually set', () => {
+ const cfg = normalizeFieldDefaults({
+ tool_response_mode: 'compact',
+ direct_tool_response_mode: 'deferred',
+ })
+ expect(cfg.tool_response_mode).toBe('compact')
+ expect(cfg.direct_tool_response_mode).toBe('deferred')
+ })
+
+ // The normalized copy genuinely diverges from the raw response β which is
+ // what makes the "normalize both snapshots" rule load-bearing. (Comparing two
+ // identically-normalized objects would pass unconditionally; that vacuous
+ // form is what cross-model review caught in the tray twin of this test.)
+ it('diverges from the raw response', () => {
+ const response = { listen: '127.0.0.1:8080' }
+ expect(getPath(response, 'tool_response_mode')).toBeUndefined()
+ expect(getPath(normalizeFieldDefaults({ ...response }), 'tool_response_mode')).toBe('full')
+ })
+
+ it('leaves fields that declare no default untouched', () => {
+ const cfg = normalizeFieldDefaults({})
+ for (const f of allCatalogFields()) {
+ if (f.defaultValue == null) expect(getPath(cfg, f.key)).toBeUndefined()
+ }
+ })
+
+ it('is a no-op on a null/non-object config instead of throwing', () => {
+ expect(normalizeFieldDefaults(null)).toBeNull()
+ expect(normalizeFieldDefaults(undefined)).toBeUndefined()
+ })
+})
+
+// hydrateConfigState is what Settings.vue's loadConfig() actually calls, so
+// these assert the invariant itself rather than matching source text β a
+// source-text match cannot tell whether `cfg` is still the untouched response
+// by the time the Raw tab serializes it.
+describe('hydrateConfigState', () => {
+ const response = () => ({ listen: '127.0.0.1:8080' })
+
+ it('normalizes both snapshots, so nothing reads as dirty on open', () => {
+ const { working, original } = hydrateConfigState(response())
+ expect(getPath(working, 'tool_response_mode')).toBe('full')
+ expect(getPath(original, 'tool_response_mode')).toBe('full')
+ for (const f of allCatalogFields()) {
+ expect(getPath(working, f.key)).toEqual(getPath(original, f.key))
+ }
+ })
+
+ it('keeps raw as the untouched server response for the Raw JSON tab', () => {
+ const { raw } = hydrateConfigState(response())
+ expect(JSON.stringify(raw)).not.toContain('tool_response_mode')
+ expect(JSON.stringify(raw)).not.toContain('direct_tool_response_mode')
+ expect(getPath(raw, 'listen')).toBe('127.0.0.1:8080')
+ })
+
+ it('does not mutate its argument', () => {
+ const cfg = response()
+ hydrateConfigState(cfg)
+ expect(getPath(cfg, 'tool_response_mode')).toBeUndefined()
+ })
+
+ it('still aliases a legacy teams-keyed config onto server_edition', () => {
+ const { working } = hydrateConfigState({ teams: { enabled: true } })
+ expect(getPath(working, 'server_edition.enabled')).toBe(true)
+ })
+
+ it('preserves an explicitly-set mode', () => {
+ const { working, raw } = hydrateConfigState({ direct_tool_response_mode: 'deferred' })
+ expect(getPath(working, 'direct_tool_response_mode')).toBe('deferred')
+ expect(getPath(raw, 'direct_tool_response_mode')).toBe('deferred')
+ })
+})
+
+// Regression: cross-model review found that a resolved default WAS writable.
+// SettingsSection keeps a component-local `dirty` ref and dirtyKeys is the
+// UNION of it and the working/original comparison. Reload replaces both
+// snapshots but used to leave that ref populated, so: pick Compact -> Reload ->
+// Save PATCHed `tool_response_mode: "full"` into a config that never had the
+// key. Settings.vue now keys every section on a form epoch bumped per
+// hydration, so the section remounts with an empty ref.
+describe('Settings.vue rehydration (stale-dirty regression)', () => {
+ const source = readFileSync(resolve(__dirname, '../../src/views/Settings.vue'), 'utf-8')
+
+ it('bumps a form epoch on every hydration', () => {
+ expect(source).toMatch(/formEpoch\.value\+\+/)
+ })
+
+ it('keys every SettingsSection on that epoch so the dirty ref cannot survive', () => {
+ const sections = source.match(/ %q is the same mode spelled two ways", tc.from, tc.to)
+ }
+
+ // Still detected when it really moves, in both directions.
+ assert.Contains(t,
+ DetectConfigChanges(mk(""), mk(config.ToolResponseModeCompact)).ChangedFields,
+ "tool_response_mode")
+ assert.Contains(t,
+ DetectConfigChanges(mk(config.ToolResponseModeCompact), mk(config.ToolResponseModeFull)).ChangedFields,
+ "tool_response_mode")
+
+ // Normalizing one axis must not leak into the other.
+ assert.NotContains(t,
+ DetectConfigChanges(mk(""), mk(config.ToolResponseModeCompact)).ChangedFields,
+ "direct_tool_response_mode")
+}
+
// TestDetectConfigChanges_RoutingModeRequiresRestart: /mcp is bound to ONE
// mcp-go server instance at startup and registered on an http.ServeMux, which
// cannot re-register a pattern β so a routing_mode change genuinely cannot take
diff --git a/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift b/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift
index 60185d790..d4e1a8aed 100644
--- a/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Settings/ConfigSettingsView.swift
@@ -28,6 +28,10 @@ final class ConfigStore: ObservableObject {
@Published var defaultInstructions: String?
private var original: [String: Any] = [:]
+ /// The API response exactly as the core sent it. `working`/`original` are
+ /// normalized (absent `omitempty` defaults filled in) so blank Pickers show
+ /// their real default, but the Raw tab must keep showing server truth.
+ private var raw: [String: Any] = [:]
private let appState: AppState
init(appState: AppState) { self.appState = appState }
@@ -40,11 +44,7 @@ final class ConfigStore: ObservableObject {
loading = true
loadError = nil
do {
- let cfg = try await api.getConfig()
- working = cfg
- original = cfg
- loaded = true
- revision += 1
+ hydrate(from: try await api.getConfig())
} catch {
loadError = (error as? APIClientError)?.errorDescription ?? error.localizedDescription
}
@@ -56,12 +56,30 @@ final class ConfigStore: ObservableObject {
loading = false
}
+ /// Populate the store from a raw `GET /api/v1/config` response.
+ ///
+ /// Split out of `load()` so the hydration invariant is testable without an
+ /// API client. That invariant: `working` and `original` BOTH get the
+ /// resolved defaults for `omitempty` keys the core omits (the serialization
+ /// modes β absent means "full") so their Picker shows the real default
+ /// instead of blank, while `raw` keeps the untouched response because the
+ /// Raw tab must show server truth. Normalizing only one of the two would
+ /// make an untouched field read as an unsaved change.
+ func hydrate(from cfg: [String: Any]) {
+ raw = cfg
+ let normalized = SettingsCatalog.normalizeDefaults(cfg)
+ working = normalized
+ original = normalized
+ loaded = true
+ revision += 1
+ }
+
/// The core's current (saved) configuration, pretty-printed for the
/// read-only Raw tab. Reflects server truth β not unsaved form edits.
var prettyJSON: String {
- guard JSONSerialization.isValidJSONObject(original),
+ guard JSONSerialization.isValidJSONObject(raw),
let data = try? JSONSerialization.data(
- withJSONObject: original, options: [.prettyPrinted, .sortedKeys]),
+ withJSONObject: raw, options: [.prettyPrinted, .sortedKeys]),
let str = String(data: data, encoding: .utf8)
else { return "{}" }
return str
@@ -105,8 +123,13 @@ final class ConfigStore: ObservableObject {
}.joined(separator: "; ")
throw APIClientError.httpError(statusCode: 422, message: msg.isEmpty ? "Validation failed" : msg)
}
- // Commit saved keys into the snapshot so they're no longer dirty.
- for k in keys { configSet(&original, k, configGet(working, k)) }
+ // Commit saved keys into the snapshot so they're no longer dirty. The
+ // Raw tab tracks the same commit, so it keeps reflecting what the core
+ // now holds rather than the config as it was at load time.
+ for k in keys {
+ configSet(&original, k, configGet(working, k))
+ configSet(&raw, k, configGet(working, k))
+ }
revision += 1
let requiresRestart = (result["requires_restart"] as? Bool) ?? false
return (requiresRestart, result["restart_reason"] as? String)
diff --git a/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift b/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift
index cd9d380f0..0446c885a 100644
--- a/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift
+++ b/native/macos/MCPProxy/MCPProxy/Settings/SettingsCatalog.swift
@@ -20,6 +20,10 @@ struct ConfigField: Identifiable {
var help: String? = nil
let control: ConfigControl
var options: [ConfigOption] = []
+ // Value an absent/blank key actually resolves to on the Go side. Only
+ // needed for `omitempty` fields whose zero value is meaningful (the
+ // serialization modes: "" means "full"). See normalizeDefaults below.
+ var defaultValue: String? = nil
var min: Double? = nil
var max: Double? = nil
// Increment for a `.number` stepper. Mirrors `step` in fields.ts β without
@@ -164,6 +168,37 @@ enum SettingsCatalog {
restart: true,
docs: "/features/routing-modes"
),
+ // Spec 085 / Spec 102 β the two SERIALIZATION axes. Neither is a
+ // routing mode: `routing_mode` picks the tool SURFACE, these two pick
+ // how each entry on that surface is rendered. Both hot-reload (the Go
+ // change detector sets requires_restart for neither), so no restart
+ // badge. Until this landed they were reachable only via the config
+ // file, an env var, a serve flag or the REST API β a tray-only user
+ // could not set them at all.
+ ConfigField(
+ key: "tool_response_mode",
+ label: "Detail in tool-search results",
+ help: "Applies to Retrieve mode. Full = every result carries its complete input schema. Compact = a one-line signature plus a first-sentence description, and the agent fetches a full schema on demand with describe_tool. Saves tokens; never changes which tools are found.",
+ control: .select,
+ options: [
+ ConfigOption(value: "full", label: "Full \u{2014} complete schemas (default)"),
+ ConfigOption(value: "compact", label: "Compact \u{2014} signatures, schema on demand"),
+ ],
+ defaultValue: "full",
+ docs: "/features/search-discovery#tool-response-mode"
+ ),
+ ConfigField(
+ key: "direct_tool_response_mode",
+ label: "Detail in Direct-mode listings",
+ help: "Applies to Direct mode, and to /mcp/all in any mode. Full = every tool is listed with its complete input schema. Deferred = name, description and a compact signature only, with schemas fetched on demand via describe_tool; a call whose arguments do not fit is rejected before it reaches the server, with the schema attached so the agent can correct itself.",
+ control: .select,
+ options: [
+ ConfigOption(value: "full", label: "Full \u{2014} complete schemas (default)"),
+ ConfigOption(value: "deferred", label: "Deferred \u{2014} signatures, schema on demand"),
+ ],
+ defaultValue: "full",
+ docs: "/features/schema-deferred-direct-mode"
+ ),
ConfigField(
key: "tools_limit",
label: "Search results limit",
@@ -350,6 +385,34 @@ enum SettingsCatalog {
]
),
]
+
+ /// Every field in the catalogue, across all sections.
+ static var allFields: [ConfigField] {
+ security + general + advanced.flatMap(\.fields)
+ }
+
+ /// Fill in the resolved default for every field that declares a
+ /// `defaultValue` and is currently blank in `cfg`.
+ ///
+ /// The serialization-mode keys are `omitempty` on the Go side, where an
+ /// absent value means "full" β so the config the API returns simply omits
+ /// them until someone sets one. A SwiftUI Picker whose selection matches
+ /// no tag renders blank, which would make the default read as "unset"
+ /// rather than as "full". Apply to BOTH the working copy and the
+ /// last-saved snapshot so an untouched field never counts as dirty; keep
+ /// the untouched response for the Raw tab, which must show server truth.
+ static func normalizeDefaults(_ cfg: [String: Any]) -> [String: Any] {
+ var out = cfg
+ for field in allFields {
+ guard let fallback = field.defaultValue else { continue }
+ let current = configGet(out, field.key)
+ let blank = current == nil
+ || current is NSNull
+ || (current as? String)?.isEmpty == true
+ if blank { configSet(&out, field.key, fallback) }
+ }
+ return out
+ }
}
// MARK: - Path helpers (operate on a JSON-decoded config dictionary)
diff --git a/native/macos/MCPProxy/MCPProxyTests/SettingsSerializationModeFieldsTests.swift b/native/macos/MCPProxy/MCPProxyTests/SettingsSerializationModeFieldsTests.swift
new file mode 100644
index 000000000..8d23698ff
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/SettingsSerializationModeFieldsTests.swift
@@ -0,0 +1,183 @@
+import XCTest
+@testable import MCPProxy
+
+/// The two serialization knobs (`tool_response_mode`, Spec 085, and
+/// `direct_tool_response_mode`, Spec 102) shipped with four ways to set them β
+/// the config file, an env var, a `serve` flag and the REST API β and zero UI
+/// surfaces. A tray-only operator could not reach `direct_tool_response_mode`
+/// at all, which is the whole point of the schema-deferred feature.
+///
+/// These pin the tray catalogue against the Web UI's fields.ts, which it must
+/// mirror 1:1 (SettingsCatalog.swift header contract).
+final class SettingsSerializationModeFieldsTests: XCTestCase {
+
+ private func field(_ key: String) throws -> ConfigField {
+ try XCTUnwrap(SettingsCatalog.allFields.first { $0.key == key },
+ "no settings field for \(key)")
+ }
+
+ // MARK: Catalogue
+
+ func testBothSerializationAxesAreReachable() throws {
+ XCTAssertEqual(try field("tool_response_mode").control, .select)
+ XCTAssertEqual(try field("direct_tool_response_mode").control, .select)
+ }
+
+ /// Only the values `cfg.Validate()` accepts β offering anything else would
+ /// hand the operator a 422 from PATCH /api/v1/config.
+ func testOptionsMatchTheGoValidator() throws {
+ XCTAssertEqual(try field("tool_response_mode").options.map(\.value), ["full", "compact"])
+ XCTAssertEqual(try field("direct_tool_response_mode").options.map(\.value), ["full", "deferred"])
+ }
+
+ /// internal/runtime/config_hotreload.go appends both keys to ChangedFields
+ /// WITHOUT setting RequiresRestart β badging them would demand a restart
+ /// for nothing. `routing_mode`, directly above them in the same section,
+ /// genuinely does need one, so the distinction has to stay visible.
+ func testNeitherClaimsARestartButRoutingModeStillDoes() throws {
+ XCTAssertFalse(try field("tool_response_mode").restart)
+ XCTAssertFalse(try field("direct_tool_response_mode").restart)
+ XCTAssertTrue(try field("routing_mode").restart)
+ }
+
+ func testPlacedNextToTheRoutingModeTheyQualify() {
+ XCTAssertEqual(Array(SettingsCatalog.general.prefix(3)).map(\.key),
+ ["routing_mode", "tool_response_mode", "direct_tool_response_mode"])
+ }
+
+ func testEachLinksToAPageDocumentingThatAxis() throws {
+ XCTAssertEqual(try field("tool_response_mode").docs, "/features/search-discovery#tool-response-mode")
+ XCTAssertEqual(try field("direct_tool_response_mode").docs,
+ "/features/schema-deferred-direct-mode")
+ }
+
+ /// Only one axis is live at a time (it depends on `routing_mode`), so each
+ /// help string has to say which mode it applies to.
+ func testHelpNamesTheApplicableRoutingMode() throws {
+ XCTAssertTrue(try XCTUnwrap(field("tool_response_mode").help).contains("Retrieve mode"))
+ XCTAssertTrue(try XCTUnwrap(field("direct_tool_response_mode").help).contains("Direct mode"))
+ }
+
+ // MARK: normalizeDefaults
+
+ /// Both keys are `omitempty` on the Go side, so a config that never set one
+ /// simply has no key. A SwiftUI Picker whose selection matches no tag
+ /// renders blank, which would show the default as "unset".
+ func testAbsentModeResolvesToItsRealDefault() {
+ let cfg = SettingsCatalog.normalizeDefaults(["listen": "127.0.0.1:8080"])
+ XCTAssertEqual(cfg["tool_response_mode"] as? String, "full")
+ XCTAssertEqual(cfg["direct_tool_response_mode"] as? String, "full")
+ }
+
+ func testEmptyStringIsTreatedAsAbsent() {
+ let cfg = SettingsCatalog.normalizeDefaults([
+ "tool_response_mode": "",
+ "direct_tool_response_mode": "",
+ ])
+ XCTAssertEqual(cfg["tool_response_mode"] as? String, "full")
+ XCTAssertEqual(cfg["direct_tool_response_mode"] as? String, "full")
+ }
+
+ func testExplicitNullIsTreatedAsAbsent() {
+ let cfg = SettingsCatalog.normalizeDefaults(["tool_response_mode": NSNull()])
+ XCTAssertEqual(cfg["tool_response_mode"] as? String, "full")
+ }
+
+ func testNeverOverwritesAnOperatorSetValue() {
+ let cfg = SettingsCatalog.normalizeDefaults([
+ "tool_response_mode": "compact",
+ "direct_tool_response_mode": "deferred",
+ ])
+ XCTAssertEqual(cfg["tool_response_mode"] as? String, "compact")
+ XCTAssertEqual(cfg["direct_tool_response_mode"] as? String, "deferred")
+ }
+
+ /// The normalized copy genuinely diverges from the raw response β which is
+ /// what makes the "normalize both snapshots" rule load-bearing rather than
+ /// decorative.
+ func testDivergesFromTheRawResponse() {
+ let raw: [String: Any] = ["listen": "127.0.0.1:8080"]
+ let normalized = SettingsCatalog.normalizeDefaults(raw)
+ XCTAssertNil(raw["tool_response_mode"], "the core omits the key entirely")
+ XCTAssertEqual(normalized["tool_response_mode"] as? String, "full")
+ }
+
+ func testLeavesFieldsWithoutADefaultUntouched() {
+ let cfg = SettingsCatalog.normalizeDefaults([:])
+ for field in SettingsCatalog.allFields where field.defaultValue == nil {
+ XCTAssertNil(configGet(cfg, field.key),
+ "\(field.key) declares no default but was populated")
+ }
+ }
+
+ /// Only the fields that opt in carry a default β a blanket fill would
+ /// invent values for every unset key in the config.
+ func testOnlyTheSerializationModesDeclareADefault() {
+ let withDefaults = SettingsCatalog.allFields
+ .filter { $0.defaultValue != nil }
+ .map(\.key)
+ .sorted()
+ XCTAssertEqual(withDefaults, ["direct_tool_response_mode", "tool_response_mode"])
+ }
+
+ // MARK: ConfigStore hydration
+ //
+ // Cross-model review caught that the assertion here used to compare two
+ // direct calls to normalizeDefaults β which passes even if ConfigStore
+ // normalizes only ONE snapshot, the exact bug it was meant to catch. These
+ // drive the real store instead, through the `hydrate(from:)` seam load()
+ // uses.
+
+ @MainActor
+ private func hydratedStore(_ cfg: [String: Any]) -> ConfigStore {
+ let store = ConfigStore(appState: AppState())
+ store.hydrate(from: cfg)
+ return store
+ }
+
+ /// The invariant that matters: after hydrating from a config that omits
+ /// both modes, neither field is dirty. Normalizing only `working` (and not
+ /// `original`) makes both read as unsaved changes the moment Settings opens.
+ @MainActor
+ func testHydrationLeavesTheOmittedModesUndirty() {
+ let store = hydratedStore(["listen": "127.0.0.1:8080"])
+ XCTAssertEqual(store.value("tool_response_mode") as? String, "full")
+ XCTAssertEqual(store.value("direct_tool_response_mode") as? String, "full")
+ XCTAssertFalse(store.isDirty("tool_response_mode"))
+ XCTAssertFalse(store.isDirty("direct_tool_response_mode"))
+ XCTAssertTrue(store.dirtyKeys(in: SettingsCatalog.allFields).isEmpty,
+ "a freshly hydrated form must have no unsaved changes")
+ }
+
+ /// The Raw tab reads `raw`, not the normalized snapshot, so it must not
+ /// show a key the config file does not contain.
+ @MainActor
+ func testRawTabShowsServerTruthNotTheInventedDefault() {
+ let store = hydratedStore(["listen": "127.0.0.1:8080"])
+ XCTAssertFalse(store.prettyJSON.contains("tool_response_mode"),
+ "Raw tab must not invent a key the core never sent")
+ XCTAssertTrue(store.prettyJSON.contains("listen"))
+ }
+
+ /// An explicitly-set mode survives hydration untouched and stays undirty.
+ @MainActor
+ func testHydrationPreservesAnExplicitMode() {
+ let store = hydratedStore([
+ "listen": "127.0.0.1:8080",
+ "direct_tool_response_mode": "deferred",
+ ])
+ XCTAssertEqual(store.value("direct_tool_response_mode") as? String, "deferred")
+ XCTAssertFalse(store.isDirty("direct_tool_response_mode"))
+ XCTAssertTrue(store.prettyJSON.contains("direct_tool_response_mode"))
+ }
+
+ /// A genuine edit is still detected β the guards above must not be passing
+ /// simply because dirty-tracking is broken.
+ @MainActor
+ func testAGenuineEditIsStillDirty() {
+ let store = hydratedStore(["listen": "127.0.0.1:8080"])
+ store.setValue("direct_tool_response_mode", "deferred")
+ XCTAssertTrue(store.isDirty("direct_tool_response_mode"))
+ XCTAssertFalse(store.isDirty("tool_response_mode"))
+ }
+}
diff --git a/roadmap.yaml b/roadmap.yaml
index b6a66fb1e..920d25e6a 100644
--- a/roadmap.yaml
+++ b/roadmap.yaml
@@ -343,11 +343,12 @@ epics:
- id: schema-deferred
title: "Deferred-schema serialization for the direct tools/list surface (spec 102)"
- status: in_progress
+ status: done
priority: P1
spec: specs/102-schema-deferred
+ pr: "#1063"
depends_on: []
- note: "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."
+ note: "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."
- id: token-bench
title: "Token-efficiency benchmark: measured savings, published results"
diff --git a/specs/102-schema-deferred/plan.md b/specs/102-schema-deferred/plan.md
index b4eb0220f..3cfe679c3 100644
--- a/specs/102-schema-deferred/plan.md
+++ b/specs/102-schema-deferred/plan.md
@@ -117,14 +117,14 @@ Technical approach, grounded in the code:
## Technical Context
-**Language/Version**: Go 1.24 module toolchain (repo builds with local Go 1.25). Backend-only; no frontend, tray, or Swift changes.
+**Language/Version**: Go 1.24 module toolchain (repo builds with local Go 1.25). Backend-only *as planned*; **superseded in delivery** β the follow-up settings work (#1082) added Vue (`frontend/src/views/settings/`) and Swift (`native/macos/.../Settings/`) changes to expose both serialization axes in the UI. The spec-102 implementation itself (#1063) was backend-only.
**Primary Dependencies**: existing only β `github.com/mark3labs/mcp-go` v0.57.0 (tool registration, `SetTools` listChanged notification, `WithInstructions`), `github.com/santhosh-tekuri/jsonschema/v6` (already used by the Spec-085 validator being reused), `go.uber.org/zap`, stdlib. **No new dependencies.**
**Storage**: none changed β BBolt and Bleve schemas untouched; the `directCatalog` is in-memory per-rebuild state; `ToolMetadata.OutputSchemaJSON` is already indexed (`internal/index/bleve.go:39`).
**Testing**: `go test -race ./internal/...` (locally: `internal/server` with the CI skip regex); frozen-golden gates in `internal/server` (see Test strategy); E2E in `internal/server/e2e_test.go`; token measurements against the frozen 45-tool corpus via the spec-083/085 profiler pipeline.
**Target Platform**: Linux/macOS/Windows core binary, personal + server editions β pure `internal/`, edition-agnostic (no `//go:build server` code touched; server-edition build verified).
**Project Type**: Single Go project (core server).
**Performance Goals**: Constitution I unaffected β serialization + registration-time work only; signatures come from the index-warmed cache via a pure read (`Peek`), no per-request compilation (FR-005); validation is memoized per tool hash and cheaper than the upstream round trip it prevents.
-**Constraints**: FR-015 byte-stability of full-mode direct listings; FR-010 existing goldens pass unregenerated except the two enumerated FR-009 regens; FR-008 identical tool-set membership across modes; FR-013b fail-open validation; SC-001 β₯70% token reduction on the 45-tool corpus.
+**Constraints**: FR-015 byte-stability of full-mode direct listings; FR-010 existing goldens pass unregenerated except the two enumerated FR-009 regens; FR-008 identical tool-set membership across modes; FR-013b fail-open validation; SC-001 β₯70% token reduction on the 45-tool corpus (**this constraint was NOT met β measured 29.7%, ceiling 38.9%; see spec.md SC-001**).
**Scale/Scope**: ~6 packages touched: `internal/server` (core of the change), `internal/config`, `internal/runtime` (one clause), `internal/toolsig` (one method), `cmd/mcpproxy` (one flag), `bench/arms` (one measurement arm for the SC-001/SC-002 gates); plus docs and generated OpenAPI artifacts.
## Constitution Check
@@ -135,7 +135,7 @@ Technical approach, grounded in the code:
|-----------|------------|
| **I. Performance at Scale** | PASS. BM25 search and indexing untouched. The direct rebuild already runs on upstream changes; deferred rendering *removes* per-entry schema unmarshal work and reads signatures via a pure cache lookup. Pre-dispatch validation is memoized per tool hash (existing validator). |
| **II. Actor-Based Concurrency** | PASS (with one justified primitive). The catalog is written only on the single routing-refresh listener goroutine and read on request paths β an immutable snapshot behind an `atomic.Pointer` swap, replacing the existing mutex-guarded `directToolPermissions` map with the same read-mostly pattern Spec 085 justified for the signature cache. The catalog swap and mcp-go's `SetTools` remain two publications and cannot be made one transaction (mcp-go owns its registry read), so the resulting skew window is closed by ordering + deny-on-miss + registry-membership rules rather than papered over β D13/R13, with an interleaving test. See Complexity Tracking. |
-| **III. Configuration-Driven Architecture** | PASS. One JSON config field with env override, serve flag, validation, and hot-reload (FR-001/FR-014); default preserves today's behavior; no tray state. |
+| **III. Configuration-Driven Architecture** | PASS. One JSON config field with env override, serve flag, validation, and hot-reload (FR-001/FR-014); default preserves today's behavior; no tray state *in this spec*. (The follow-up #1082 added a read/write settings control in both the Web UI and the tray β still no tray-held state: the tray remains a REST client that reads and PATCHes core config.) |
| **IV. Security by Default** | PASS. Serialization never changes membership (FR-008/FR-016): all discovery filters run before rendering. describe_tool on the direct surface applies listing-parity visibility *including the operation-permission tier the existing resolver lacks*, and never emits an existence-confirming reason code **or suggestion** for an id this session's listing omitted (FR-011). Parity is enforced on both sides (D10): the listing filters resolve through the catalog instead of re-parsing `__`, and both suggestion channels (`did_you_mean`, case-correction) are catalog-gated or suppressed β closing four concrete parity defects that exist in this tree today β three disclosure paths plus a wrong-safety-hint path (a listed destructive tool describing as `call_with: "read"`) β rather than opening any. Quarantine/approval gates on dispatch are untouched; validation is fail-open, never blocking a call a schemaless proxy would allow. The one place the design accepts staleness β an annotations-only change inside the two-publication window (Complexity Tracking, third row) β touches only listing/describe; call-time authorization is re-derived by the handler from its own captured annotations and is never one generation behind. |
| **V. Test-Driven Development** | PASS. Every behavior lands test-first; the golden gates make surface drift a failing test by construction (see Test strategy). |
| **VI. Documentation Hygiene** | PASS. `docs/configuration.md`, the feature doc under `docs/features/`, `CLAUDE.md` MCP-protocol line, and `make swagger` regen are in scope (see Documentation & wiring). |
diff --git a/specs/102-schema-deferred/spec.md b/specs/102-schema-deferred/spec.md
index 86b99a69b..1178263d7 100644
--- a/specs/102-schema-deferred/spec.md
+++ b/specs/102-schema-deferred/spec.md
@@ -2,7 +2,7 @@
**Feature Branch**: `102-schema-deferred`
**Created**: 2026-08-24
-**Status**: Draft
+**Status**: Draft β SHIPPED 2026-08-29 (all 89 tasks, PR #1063; settings UI in #1082). **SC-001 is measured and UNMET** (29.7% / 34.8% vs a >=70% target, 38.9% ceiling) and awaits a maintainer decision; see the SC-001 note under Measurable Outcomes.
**Input**: User description: "schema_deferred routing (issue #971): direct-mode tools/list keeps ALL tool names + descriptions but defers inputSchema; agents fetch full schemas on demand via describe_tool. Built as a thin composition over the Spec 085 compact-router machinery (compact signatures, describe_tool, pre-dispatch validation + self-healing errors) per the maintainer's accepted direction (issue #971 comment, 2026-08-13)."
**Related**: #971 (accepted-direction, 2026-08-13). Spec 085 (compact router β the reused machinery: signature cache, `describe_tool`, pre-dispatch validation, self-healing invalid-params errors). Specs 098/099 (preflight evaluator + `describe_tool` `check` mode β the full describe_tool contract travels wherever the tool is exposed). Industry precedent: Atlassian mcp-compressor "Low Compression" (94 tools: 17,600 β 3,900 tokens), Alibaba Qoder two-phase discovery, MCP client best-practices Catalog β Inspect β Execute.
@@ -19,11 +19,11 @@ Per the maintainer's accepted direction, this is **not a new routing mode**: `ro
### User Story 1 - Deferred enumeration: see everything, pay for schemas only when needed (Priority: P1)
-An agent connects to the direct surface of a proxy with deferred serialization enabled. `tools/list` returns every visible upstream tool β same `serverName__toolName` names, same annotations β but each entry carries the description plus its precompiled compact signature (`*` = required, `~` = lossy) instead of a full `inputSchema`; the declared input schema is a minimal permissive object. For a 100-tool fleet the listing drops from ~30K to roughly 3.5β5K tokens, and for flat (non-lossy) tools the agent can call directly from the signature with zero extra round trips.
+An agent connects to the direct surface of a proxy with deferred serialization enabled. `tools/list` returns every visible upstream tool β same `serverName__toolName` names, same annotations β but each entry carries the description plus its precompiled compact signature (`*` = required, `~` = lossy) instead of a full `inputSchema`; the declared input schema is a minimal permissive object. For a 100-tool fleet the listing was projected to drop from ~30K to roughly 3.5β5K tokens; **the shipped measurement contradicts that projection** β a 527-tool snapshot went 99,918 β 65,138 tokens (~34.8%), because names, descriptions and annotations, not schemas, carry most of the payload (see the SC-001 note). For flat (non-lossy) tools the agent can still call directly from the signature with zero extra round trips, which held.
**Why this priority**: This is the headline gap #971 names β full visibility at deferred-schema cost β and the entire token win of the feature.
-**Independent Test**: Enable deferral on a fixture proxy with multiple upstream servers; fetch `tools/list` on the direct surface and assert: every tool present, no entry carries upstream schema properties, every entry's description ends with its compact signature, and total payload tokens are reduced β₯70% versus full mode on the frozen 45-tool reference corpus.
+**Independent Test**: Enable deferral on a fixture proxy with multiple upstream servers; fetch `tools/list` on the direct surface and assert: every tool present, no entry carries upstream schema properties, every entry's description ends with its compact signature, and total payload tokens are reduced versus full mode on the frozen 45-tool reference corpus. (The β₯70% figure this test originally named was not met β measured 29.7%; the shipped gate in `bench/arms` asserts a 25% floor plus an upper guard, per T076.)
**Acceptance Scenarios**:
@@ -180,7 +180,22 @@ An operator flips deferred serialization on (or off) in config with the proxy ru
### Measurable Outcomes
-- **SC-001**: On the frozen 45-tool reference corpus, deferred direct-surface `tools/list` payload is β₯70% smaller in tokens than full mode, measured by the spec-083 profiler pipeline; on a ~100-tool fleet the projection matches the #971 estimate (~30K β ~3.5β5K tokens, β₯85% reduction).
+- **SC-001** (**NOT MET β measured, escalated, awaiting maintainer decision**): As written, this
+ required a β₯70% token reduction on the frozen 45-tool reference corpus and β₯85% on a ~100-tool
+ fleet.
+
+ > **Measured outcome (2026-08-29, T035a).** 29.7% on the reference corpus and 34.8% on a 527-tool
+ > snapshot (99,918 β 65,138 tokens). The **arithmetic ceiling is 38.9%** β that is what deleting
+ > *both* the schema and the signature would yield β so no implementation of this design can reach
+ > 70% on this corpus shape. The target rested on Spec 083 profiling attributing ~77% of the payload
+ > to schemas; at the corpus shapes actually measured, names, descriptions and annotations dominate.
+ >
+ > This is recorded rather than quietly restated: the feature works and delivers a real ~30% saving,
+ > but the criterion as written is unreachable. **Two options for the maintainer:** restate the
+ > threshold per corpus shape, or re-target SC-001 at a schema-heavy corpus where the original
+ > premise holds. Until then the shipped gate (`bench/arms`, T076) asserts a 25% floor plus an upper
+ > guard that fails loudly if anything ever does clear 70%. See tasks.md T035a and the Phase 3
+ > checkpoint for the full measurement table.
- **SC-002**: β₯80% of corpus tools (the non-lossy share; Spec 085 lossy-rate gate <20%) are callable one-shot from the deferred listing β zero `describe_tool` round trips β verified against the corpus signature set.
- **SC-003**: An agent whose guessed arguments fail validation completes the call in exactly one retry using only the error-embedded schema (no additional discovery calls), demonstrated in E2E.
- **SC-004**: With deferral off, automated comparison shows direct-surface responses byte-identical to pre-feature behavior modulo the single enumerated surface delta (FR-010); the existing tool-surface goldens pass **unregenerated** (the delta lands on a surface they do not cover), and the new direct-surface built-in gate pins that delta.
diff --git a/specs/102-schema-deferred/tasks.md b/specs/102-schema-deferred/tasks.md
index 4ca9cf0d3..f39638609 100644
--- a/specs/102-schema-deferred/tasks.md
+++ b/specs/102-schema-deferred/tasks.md
@@ -280,7 +280,7 @@ So T004 gates Phase 1; T001βT003 gate their own dependents and are otherwise c
## Phase 7: Polish & cross-cutting
-- [x] T073 Add the standalone direct built-in gate to `internal/server/toolslist_snapshot_test.go` with `testdata/toolslist_goldens/direct_mode_builtins.json`: zero upstream tools (listing = `describe_tool` only), **both** serialization modes, membership + byte-exact serialization, plus the direct server's instructions string captured with an empty `instructions` config so the bytes are deterministic. It MUST be standalone, not an entry in `toolsListGoldenSurfaces` β `_DeltaIsEnumerated` reads a frozen `pre099/.json` per listed surface, and direct mode has no pre-feature baseline.
+- [x] T073 Add the standalone direct built-in gate to `internal/server/toolslist_snapshot_test.go` (**landed in a new file, `internal/server/toolslist_direct_builtins_test.go`, because the task itself requires the gate to be standalone rather than an entry in `toolsListGoldenSurfaces` β a separate file expresses that better than an orphan test in the shared snapshot file**) with `testdata/toolslist_goldens/direct_mode_builtins.json`: zero upstream tools (listing = `describe_tool` only), **both** serialization modes, membership + byte-exact serialization, plus the direct server's instructions string captured with an empty `instructions` config so the bytes are deterministic. It MUST be standalone, not an entry in `toolsListGoldenSurfaces` β `_DeltaIsEnumerated` reads a frozen `pre099/.json` per listed surface, and direct mode has no pre-feature baseline.
- [x] T074 In the same gate, assert over `p.directServer.ListTools()` **and** a real `tools/list` driven through the direct server on a session with no agent token, treating any difference between the two sets as a failure. `ListTools()` is the registration map; `handleListTools` serves `filteredTools(ctx)`, and `directServer` is the one routing-mode server carrying `WithToolFilter`s β so registered and served can diverge on exactly this server. Sort by tool name before serializing: `ListTools()` returns a map and Go randomizes iteration order.
- [x] T075 [P] Add the deferred-direct arm to `bench/arms/` plus its `bench/arms/testdata/*_golden.txt` render golden, following the registry contract in `specs/083-discovery-profiler/contracts/arm-interface.md` and `bench/arms/arm.go`. The existing arms all encode `retrieve_tools` result sets; none renders a direct `tools/list`.
- [x] T076 Run the SC-001/SC-002 token gates over the frozen 45-tool corpus with the spec-083 profiler's pinned tokenizer: assert β₯70% payload reduction and β₯80% one-shot-callable (non-lossy) share, and record the measured numbers in the PR description.
@@ -321,9 +321,12 @@ So T004 gates Phase 1; T001βT003 gate their own dependents and are otherwise c
- [x] T083 Verify the five frozen gates land as predicted: gates 1 and 3 pass **unregenerated**; gate 2 shows exactly the two enumerated regens; gate 4 passes with the extended `describePlainDelta`; gate 5 is re-measured, not assumed. A diff anywhere else is a regression to fix, not a baseline to update.
**Verified, not assumed.** All five pass. Golden churn across the entire branch is exactly:
- the two enumerated regens (`default_server.json`, `retrieve_tools_mode.json`) plus four NEW
- files (`direct_full_prefeature.golden.json`, the two `direct_mode_builtins_*.json`, and the
- bench arm golden). `code_execution_mode.json` and both `pre099/` baselines are untouched β
+ the two enumerated regens (`default_server.json`, `retrieve_tools_mode.json`) plus three NEW
+ files (`direct_full_prefeature.golden.json`, `toolslist_goldens/direct_mode_builtins.json`, and
+ the bench arm golden `bench/arms/testdata/directdeferred_golden.txt`). *(Corrected 2026-08-29:
+ this note originally said "four NEW files β¦ the two `direct_mode_builtins_*.json`".
+ `git show 9aef8d6f1 --diff-filter=A` lists three; there is a single builtins golden, which
+ covers both serialization modes in one file rather than one file per mode.)* `code_execution_mode.json` and both `pre099/` baselines are untouched β
which is what confines the change to the two surfaces that register describe_tool.
`go test -race ./internal/...` is green except `TestResolveDockerStatusResolvableAndWorking`,