Repository navigation
feat(settings): expose both serialization modes in the Web UI and tray - #1082
Conversation
`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.
Deploying mcpproxy-docs with
|
| 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 |
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 33250033429 --repo smart-mcp-proxy/mcpproxy-go
|
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.
Cross-model review + 5-lens audit — 14 confirmed findingsReviewed 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 claimThe description above said a resolved default is "never written back". That was wrong.
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 failThe 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 Also in the earlier commit (
|
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.
…; 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.
The gap
tool_response_mode(Spec 085) anddirect_tool_response_mode(Spec 102) shipped with four ways to set them — the config file, an env var, aserveflag and the REST API — and zero UI surfaces. A tray-only operator could not reachdirect_tool_response_modeat 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.goappends both toChangedFieldswithout settingRequiresRestart, so they hot-apply — unlikerouting_moderight 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
omitemptyon the Go side, where an absent value means"full". Verified against a live instance — a fresh config returns neither key:A native
<select>(and a SwiftUIPicker) whose value matches no option renders an empty box — the default would have read as "unset". SoSettingField.defaultValuedeclares the resolved default, and a normalize pass fills it at hydration in both clients.Normalization is display-only and deliberately narrow:
originalfor it, so this adds a separaterawcopy rather than letting invented keys leak into that view.Docs defect found and fixed
tool_response_modehad no published documentation. The schema-deferred page sent readers to Search & Discovery for "its owntool_response_modeaxis" — 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):Settings saved · direct_tool_response_mode— not "restart required", matching the no-badge decision./mcp/allhot-switched with no restart:inputSchemabecame exactly{"type":"object"}, descriptions gained their compact signature (echo(message*:str)), tool count unchanged (14 → 14, serialization-only), payload 8630 → 6523 bytes.deferredshows as Deferred, absenttool_response_modeshows as Full, neither dirty.direct_tool_response_mode, does not contain the inventedtool_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
defaultValuefails 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.