Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
```
Expand Down Expand Up @@ -154,15 +154,6 @@ graph LR

</details>

<details>
<summary>🔵 Deferred-schema serialization for the direct tools/list surface (spec 102) — In progress · P1</summary>

> 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/)

</details>

<details>
<summary>🔵 Telemetry identity &amp; data quality (machine_id + CI-filter hardening) — In progress · P1</summary>

Expand Down Expand Up @@ -711,6 +702,15 @@ graph LR

</details>

<details>
<summary>🟢 Deferred-schema serialization for the direct tools/list surface (spec 102) — Done · P1</summary>

> 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

</details>

<details>
<summary>🟢 Tray↔core decoupling: socket/REST API only, no config-file reads — Done · P2</summary>

Expand Down Expand Up @@ -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 |
Expand All @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

---

Expand All @@ -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

Expand Down
9 changes: 8 additions & 1 deletion docs/features/schema-deferred-direct-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
32 changes: 32 additions & 0 deletions docs/features/search-discovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
11 changes: 7 additions & 4 deletions docs/features/settings-page.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, …).
Expand All @@ -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.

Expand Down
47 changes: 25 additions & 22 deletions frontend/src/views/Settings.vue
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
<div v-if="loaded && search.trim()" class="card bg-base-100 shadow-md" data-test="settings-search-results">
<div class="card-body">
<h2 class="card-title text-lg">🔍 Search results <span class="text-sm font-normal text-base-content/60">({{ filteredFields.length }})</span></h2>
<SettingsSection section-id="search" :fields="filteredFields" :working="state.working" :original="state.original" />
<SettingsSection :key="`sec-${formEpoch}`" section-id="search" :fields="filteredFields" :working="state.working" :original="state.original" />
</div>
</div>

Expand Down Expand Up @@ -82,15 +82,15 @@
{{ p.label }}: {{ p.on ? 'on' : 'off' }}
</span>
</div>
<SettingsSection section-id="security" :fields="securityFields" :working="state.working" :original="state.original" />
<SettingsSection :key="`sec-${formEpoch}`" section-id="security" :fields="securityFields" :working="state.working" :original="state.original" />
</div>
</div>

<!-- General -->
<div v-show="activeTab === 'general'" class="card bg-base-100 shadow-md">
<div class="card-body">
<h2 class="card-title text-lg">⚙️ General</h2>
<SettingsSection section-id="general" :fields="generalFields" :working="state.working" :original="state.original" />
<SettingsSection :key="`sec-${formEpoch}`" section-id="general" :fields="generalFields" :working="state.working" :original="state.original" />
</div>
</div>

Expand All @@ -110,7 +110,7 @@
:data-test="`settings-accordion-docs-${acc.id}`"
>Learn more ↗</a>
</p>
<SettingsSection :section-id="acc.id" :fields="acc.fields" :working="state.working" :original="state.original" />
<SettingsSection :key="`acc-${acc.id}-${formEpoch}`" :section-id="acc.id" :fields="acc.fields" :working="state.working" :original="state.original" />
</div>
</details>
<div class="text-xs text-base-content/50 px-1">
Expand All @@ -123,7 +123,7 @@
<div v-if="hasServerEdition" v-show="activeTab === 'teams'" class="card bg-base-100 shadow-md">
<div class="card-body">
<h2 class="card-title text-lg" data-test="settings-server-edition-title">{{ serverEditionTitle }}</h2>
<SettingsSection section-id="teams" :fields="serverEditionFields" :working="state.working" :original="state.original" />
<SettingsSection :key="`sec-${formEpoch}`" section-id="teams" :fields="serverEditionFields" :working="state.working" :original="state.original" />
</div>
</div>

Expand Down Expand Up @@ -194,6 +194,7 @@ import {
docsUrl,
isBlankInstructions,
restartRequiredLabels,
hydrateConfigState,
type SettingField,
type SettingsAccordion,
} from '@/views/settings/fields'
Expand Down Expand Up @@ -248,6 +249,13 @@ const loadError = ref('')
const activeTab = ref<string>('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.
Expand Down Expand Up @@ -319,20 +327,6 @@ const editorOptions = {
lineNumbers: 'on' as const,
}

function clone<T>(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 = ''
Expand All @@ -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 <select> 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()
Expand Down
Loading
Loading