Skip to content

feat(settings): expose both serialization modes in the Web UI and tray - #1082

Merged
Dumbris merged 3 commits into
mainfrom
feat/serialization-mode-settings-ui
Aug 29, 2026
Merged

Dumbris merged 3 commits into
mainfrom
feat/serialization-mode-settings-ui

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 29, 2026

Copy link
Copy Markdown
Member

The gap

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 entire point of the schema-deferred feature.

What changed

Both fields now sit in Settings → General, directly under routing_mode, the knob they qualify — in the Web UI and the macOS tray.

Neither carries a restart badge. internal/runtime/config_hotreload.go appends both to ChangedFields without setting RequiresRestart, so they hot-apply — unlike routing_mode right above them, which genuinely needs one. Tests pin that asymmetry in both catalogues.

The one new mechanism, and why it was needed

Both keys are omitempty on the Go side, where an absent value means "full". Verified against a live instance — a fresh config returns neither key:

'routing_mode'              -> 'direct'
'tool_response_mode'        -> <ABSENT>
'direct_tool_response_mode' -> <ABSENT>

A native <select> (and a SwiftUI Picker) whose value matches no option renders an empty box — the default would have read as "unset". So SettingField.defaultValue declares the resolved default, and a normalize pass fills it at hydration in both clients.

Normalization is display-only and deliberately narrow:

  • Applied to both the working copy and the last-saved snapshot, so an untouched field never counts as an unsaved change.
  • Never written back. Saving one mode PATCHes only that key; the other stays absent from the config file.
  • The Raw JSON tab keeps showing server truth. The Web UI already serialized the untouched response; the tray reused original for it, so this adds a separate raw copy rather than letting invented keys leak into that view.
  • Only the two opted-in fields declare a default, and a test pins that exact list so the pass cannot quietly start inventing values for other unset keys.

Docs defect found and fixed

tool_response_mode had no published documentation. The schema-deferred page sent readers to Search & Discovery for "its own tool_response_mode axis" — and that page never mentioned it. Now documented there, with the cross-reference repaired to a pinned anchor ({#tool-response-mode}, verified present in the built site), which also gives the new field a docs link that resolves.

Verification

Against a real instance on an isolated port with a scratch data-dir and config (the user's own ~/.mcpproxy/ untouched; core torn down after):

  • Both selects render "Full — complete schemas (default)" on a config containing neither key; no phantom dirty state, no unsaved-changes banner.
  • Flipping the mode through the Settings UI saved as Settings saved · direct_tool_response_mode — not "restart required", matching the no-badge decision.
  • /mcp/all hot-switched with no restart: inputSchema became exactly {"type":"object"}, descriptions gained their compact signature (echo(message*:str)), tool count unchanged (14 → 14, serialization-only), payload 8630 → 6523 bytes.
  • After reload: explicit deferred shows as Deferred, absent tool_response_mode shows as Full, neither dirty.
  • Raw JSON tab read from the Monaco model: contains the real direct_tool_response_mode, does not contain the invented tool_response_mode.

Suites: frontend 973/973; Swift 1149 tests, 1 failure — AppLifecycleTests.testTheSharedJournalNeverWritesToTheRealInstanceRootUnderTests, which I confirmed fails identically on a clean tree with these changes stashed. go build ./... clean; docs site builds clean.

The frontend catalogue test was mutation-checked (dropping defaultValue fails it). One assertion I wrote was vacuous — comparing two identically-normalized objects passes unconditionally — and is rewritten to assert the divergence from the raw response, which is what gives the "normalize both copies" rule teeth.

Not covered

The tray is verified at unit and compile level only, not visually — a live tray check needs the prod-bundle swap, which would disrupt the running tray and its managed core.

`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 entire point of the
schema-deferred feature.

Both now sit in Settings → General, directly under `routing_mode`, the knob
they qualify. Neither carries a restart badge: the Go change detector appends
them to ChangedFields without setting RequiresRestart, so they hot-apply —
unlike `routing_mode` right above them, which genuinely needs a restart.

Rendering the default honestly needed one new mechanism. Both 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 — verified live: a
fresh instance returns neither key. A native <select> (and a SwiftUI Picker)
whose value matches no option renders an empty box, which would have shown the
default as "unset". `SettingField.defaultValue` declares the resolved default
and a normalize pass fills it at hydration, in both clients.

Normalization is display-only, and deliberately narrow:

- Applied to BOTH the working copy and the last-saved snapshot, so an untouched
  field never counts as an unsaved change.
- Never written back. Saving one mode PATCHes only that key; the other stays
  absent from the config file. Verified end to end.
- The Raw JSON tab keeps showing server truth. The Web UI already serialized
  the untouched response; the tray reused `original` for it, so this adds a
  separate `raw` copy rather than letting invented keys leak into that view.
- Only the two fields that opt in declare a default; a test pins that list so
  the pass cannot quietly start inventing values for other unset keys.

`tool_response_mode` had no published documentation — the schema-deferred page
pointed at Search & Discovery for "its own tool_response_mode axis" and that
page never mentioned it. Documents it there and repairs the cross-reference to
a pinned anchor, which also gives the new field a docs link that resolves.

Verified against a real instance on an isolated port and scratch data-dir:
flipping the mode through the Settings UI hot-switched /mcp/all with no restart
— inputSchema became exactly {"type":"object"}, descriptions gained their
compact signature, tool count unchanged, payload 8630 → 6523 bytes.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 29, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 6154686
Status: ✅  Deploy successful!
Preview URL: https://90e8cb46.mcpproxy-docs.pages.dev
Branch Preview URL: https://feat-serialization-mode-sett.mcpproxy-docs.pages.dev

View logs

@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: feat/serialization-mode-settings-ui

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (26 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (21 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 33250033429 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

Two findings from a gpt-5.6-sol review, both verified against the code before
fixing.

1. `tool_response_mode` was compared raw in DetectConfigChanges, so "" -> "full"
   reported a change when nothing moved. The direct axis three lines below
   normalizes and documents exactly why ("the apply RESULT would still misreport
   to the caller") — that normalization landed in Spec 102 review and was never
   mirrored to the retrieve axis. Exposing "full" as an explicit choice in the
   Settings form is what makes the explicit-vs-absent round trip reachable from
   the UI, so it matters now. Regression test mirrors the direct-axis one and
   fails against the raw comparison.

2. The Swift "both copies normalized" assertion was vacuous: it compared two
   direct calls to normalizeDefaults, which passes even when ConfigStore
   normalizes only one snapshot — precisely the bug it was written to catch.
   (The Web UI side had a source-level wiring assertion; the tray had nothing.)

   Fixed by extracting ConfigStore.hydrate(from:) from load() and testing the
   real store through it: after hydrating a config that omits both modes, the
   fields resolve to "full", neither is dirty, the form reports zero unsaved
   changes, and the Raw tab does not contain the invented key. A genuine edit
   is still dirty, so the guards cannot pass by dirty-tracking being broken.

   Mutation-checked: normalizing only `working` fails 4 of the new tests and
   none of the old one.
…pec/docs

A 5-lens audit of the branch produced 14 confirmed findings (9 more were
refuted and dropped). This lands the ones that belong in this PR; the four
live-verification findings that are pre-existing and unrelated are filed as
issues #1083 and #1084 rather than widened into this change.

THE REAL BUG — a resolved default WAS writable, which falsifies the claim
this PR made:

  SettingsSection keeps a component-local `dirty` ref, and dirtyKeys is the
  UNION of that ref and the working/original comparison. Nothing keyed the
  section, so Reload replaced both snapshots while leaving the ref populated:
  pick Compact -> Reload -> Save PATCHed `tool_response_mode: "full"` into a
  config that never had the key. Every section is now keyed on a form epoch
  bumped per hydration, so it remounts with an empty ref. Verified live: after
  Reload the abandoned edit is gone, Save is disabled, and the key is still
  absent from the config file on disk.

  This also fixes the general case — the stale ref could strand ANY field.

TESTS THAT COULD NOT FAIL. Cross-model review caught the vacuous
"both copies normalized" assertion in the tray test; the same audit found I
had left the identical tautology in the Web UI twin, plus a Raw-tab test that
matched source text and so could not see whether `cfg` was still the untouched
response by the time it was serialized. Both are now real assertions against
an extracted `hydrateConfigState` helper (the Vue counterpart of the Swift
`hydrate(from:)` seam). Mutation-checked in both directions: normalizing one
snapshot fails them, and stripping the section keys fails the regression test.

SYNC:
- roadmap.yaml: the schema-deferred epic still said `in_progress` with a note
  ending "plan in progress" — spec 102 shipped in #1063. Now `done` with a
  `pr:` ref, and the note's "~88% smaller listing" projection is corrected with
  the measured 29.7%/34.8% and the 38.9% ceiling. ROADMAP.md is GENERATED, so
  the edit is in the YAML and the file regenerated via scripts/gen-roadmap.py.
- spec.md/plan.md asserted SC-001's >=70% as fact in four more places, and
  plan.md claimed "Backend-only; no frontend, tray, or Swift changes" plus
  "no tray state" — both contradicted by the UI work. SC-001 is now marked
  NOT MET with the measurement, the ceiling, and the two options open to the
  maintainer. tasks.md was already honest; only two drift notes corrected
  (T083 said four new goldens, git shows three; T073 named the wrong file).
- docs: "routing_mode sits directly above it" was wrong — tool_response_mode
  is between them. The settings-page restart list named `data_dir`, which is
  not a field at all, and omitted routing_mode.
@Dumbris

Dumbris commented Aug 29, 2026

Copy link
Copy Markdown
Member Author

Cross-model review + 5-lens audit — 14 confirmed findings

Reviewed with opencode / gpt-5.6-sol, then a 5-lens audit fan-out (roadmap sync, spec sync, docs sync, adversarial code review, live end-to-end verification), each finding adversarially verified before action. 9 further findings were refuted and dropped.

The one that falsified this PR's own claim

The description above said a resolved default is "never written back". That was wrong. SettingsSection keeps a component-local dirty ref, and dirtyKeys is the UNION of that ref and the working/original comparison. Nothing keyed the section, so Reload replaced both snapshots while leaving the ref populated:

pick Compact → click Reload → Save → PATCHes tool_response_mode: "full" into a config that never had the key.

Fixed by keying every section on a form epoch bumped per hydration. This also fixes the general case — the stale ref could strand any field, not just the new ones.

Verified live on a rebuilt binary: after Reload the abandoned edit is gone, Save is disabled, and the key is still absent from the config file on disk.

Tests that could not fail

The earlier commit fixed a vacuous "both copies normalized" assertion in the tray test. The audit found I had left the identical tautology in the Web UI twin, plus a Raw-tab test that matched source text and so could not tell whether cfg was still the untouched response by the time it was serialized. Both now assert against an extracted hydrateConfigState helper — the Vue counterpart of the Swift hydrate(from:) seam. Mutation-checked both ways: normalizing one snapshot fails them; stripping the section keys fails the regression test.

Also in the earlier commit (cd0aee326)

DetectConfigChanges compared tool_response_mode raw, so "" → "full" reported a change that never happened. The direct axis three lines below normalizes and documents exactly why — that landed in spec 102's own review and was never mirrored across. Exposing "full" as an explicit UI choice is what makes the round trip reachable.

Roadmap / spec / docs sync

  • roadmap.yaml — the schema-deferred epic still read in_progress with a note ending "plan in progress"; spec 102 shipped in feat(102): schema-deferred direct mode — complete (89/89 tasks) #1063. Now done with a pr: ref, and the note's "~88% smaller listing" projection replaced with the measured 29.7% / 34.8% and the 38.9% ceiling. ROADMAP.md is generated — the edit is in the YAML, file regenerated via scripts/gen-roadmap.py.
  • spec.md / plan.md — asserted SC-001's ≥70% as fact in four more places, and plan.md claimed "Backend-only; no frontend, tray, or Swift changes" and "no tray state", both contradicted by this work. SC-001 is now marked NOT MET with the measurement, the ceiling, and the two options open to you. tasks.md was already honest — only two drift notes corrected (T083 claimed four new goldens, git show lists three; T073 named the wrong file).
  • docs — "routing_mode sits directly above it" was wrong (tool_response_mode is between them). The settings-page restart list named data_dir, which is not a field at all, and omitted routing_mode.

Filed separately rather than widened into this PR

Verification

Full frontend suite 978/978. internal/runtime green under -race (154s). Swift 1153 tests, 1 failure — the environmental AppLifecycleTests one, confirmed identical on a clean tree with changes stashed, and green in CI.

Live, on an isolated port with a scratch data-dir (user's ~/.mcpproxy/ untouched, core torn down): saving through the UI hot-switched /mcp/all with no restart — inputSchema → {"type":"object"}, signature appended, 14 tools unchanged, payload 8630 → 6523 bytes.

@Dumbris
Dumbris merged commit bb38943 into main Aug 29, 2026
39 checks passed
@Dumbris
Dumbris deleted the feat/serialization-mode-settings-ui branch August 29, 2026 11:44
Dumbris added a commit that referenced this pull request Aug 29, 2026
The Unreleased section is hand-written, and the flagship feature of the next
release was missing from it entirely: schema-deferred direct mode shipped in
#1063 with no changelog entry, and the settings UI in #1082 likewise.

The feature entry states the two things a reader most needs and would otherwise
get wrong: that it is OPT-IN (default `full`, unchanged behaviour), and that the
measured saving is ~30% — not the ~88% the roadmap projected until today. Any
launch copy drafted from the old number would be wrong.

Also records #1083 and #1084 under Bug Fixes.
Dumbris added a commit that referenced this pull request Aug 29, 2026
…; restate SC-001 (#1086)

* fix: direct-surface describe ids (#1083), config-apply errors (#1084); restate SC-001

Closes #1083. Closes #1084.

#1083 — describe_tool on the DIRECT surface returned identifiers that surface
cannot be asked for: the canonical "<server>:<tool>" (it registers
"<server>__<tool>") and a `call_with` naming call_tool_read/write/destructive
(intent variants the direct surface does not expose). Following either verbatim
gave "tool not found". Deferred mode makes this the live discovery path, since
it tells agents to recover schemas through describe_tool.

  applyDirectSurfaceIdentity sits at the same assembly seam as output_schema —
  putting it in the shared builder would change indexed-surface bytes. It swaps
  the registered display name in and drops `call_with`. Dropped rather than
  retargeted: it answers "which variant do I dispatch through", a question this
  surface does not have. No signal is lost — DeriveCallWith is a pure function
  of `annotations`, which travels on the same definition, so a consumer can
  recompute the tier. The D10 safety test is re-pointed at that source rather
  than deleted. Both id spellings still WORK as input; only the echo changes.
  Verified live: the identifier describe_tool returns now executes.

#1084 — three defects:
  1. A value the validator rejects returned 500. ApplyConfig discarded its
     structured errors, so handlers could not tell "you sent a bad value" from
     "we failed to persist a good one" without string-matching. The errors now
     ride on the result and writeApplyConfigError classifies: 400 with the
     offending field in a structured payload, 500 reserved for real faults.
  2. internal/httpapi/server.go called SugaredLogger.Error(msg, "key", val),
     which CONCATENATES — hence "patcherrorconfiguration...". 97 call sites
     converted to the *w variants, including ones passing zap.Field values to
     the sugared API (broken a second way). Argument-parity checked per call.
  3. /api/v1/status embedded a status snapshot whose upstream_stats and
     tools_indexed nothing refreshed — stuck at "Connecting"/0 for the life of
     a process whose servers were long Ready, disagreeing with the correct
     top-level field.

     Cross-model review caught two defects in my first attempt: refreshing
     inside Server.GetStatus() made every poll walk all servers TWICE, and the
     SSE stream forwards a snapshot that never passes through GetStatus() at
     all, so it stayed stale. Now a withLiveUpstreamStats helper at the API
     layer, applied at all three emission sites, each reusing the traversal it
     already does for its top-level field. It copies rather than mutates — the
     SSE map is owned by the publisher.

SC-001 restated per corpus shape (maintainer decision). The original ≥70%/≥85%
was unreachable: measured 29.7% (45-tool corpus) and 34.8% (527-tool snapshot)
against an arithmetic ceiling of 38.9%, because the target assumed schemas
dominate the payload and names/descriptions/annotations actually do. Now ≥25%
and ≥30% — roughly 15% relative headroom below each measured value, as a
regression floor rather than a second projection. Both bounds are asserted, so
that test file IS the SC-001 gate; a new fleet-scale case independently
reproduces T035a's numbers from its own loader. The original 70% is retained as
an upper tripwire: clearing it means the corpus premise changed.

* docs(changelog): record spec 102, the settings UI, and these fixes

The Unreleased section is hand-written, and the flagship feature of the next
release was missing from it entirely: schema-deferred direct mode shipped in
#1063 with no changelog entry, and the settings UI in #1082 likewise.

The feature entry states the two things a reader most needs and would otherwise
get wrong: that it is OPT-IN (default `full`, unchanged behaviour), and that the
measured saving is ~30% — not the ~88% the roadmap projected until today. Any
launch copy drafted from the old number would be wrong.

Also records #1083 and #1084 under Bug Fixes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants