Skip to content

feat(ui): routing + schema-detail switcher in the header, and a config pipeline that can tell running from desired - #1133

Merged
Dumbris merged 2 commits into
mainfrom
claude/mode-switcher-deferred-schemas-3c477b
Aug 30, 2026
Merged

Dumbris merged 2 commits into
mainfrom
claude/mode-switcher-deferred-schemas-3c477b

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 30, 2026

Copy link
Copy Markdown
Member

Pull Request

Description

The header's Mode: Retrieve was read-only — a cursor-help pointer, a native title tooltip most people never wait out, and no way to act on what it said. It is now a dropdown switcher, mirroring the profile switcher beside it, with two tabs each labelled by its current value so neither setting hides below the fold:

  • Surface — the three routing modes, each with what it costs an agent, the dedicated endpoint that always serves it (/mcp/call, /mcp/all, /mcp/code), and a serving now / after restart / needs restart badge.
  • Schema detail — both serialization axes (tool_response_mode, Spec 085; direct_tool_response_mode, Spec 102), with the measured deferred-mode savings (29.7% on the 45-tool corpus, 34.8% on 527 tools) and the describe_tool round trip they cost on ~-marked tools. Under code-execution mode it says the retrieve axis cannot reach /mcp there, because that surface pins itself to full schemas (Spec 085 FR-011).

Does it need a restart? Routing mode yes, deferred schemas no — and the UI now says so per option instead of leaving the operator to find out. /mcp binds its mode to an http.ServeMux pattern at startup, so a routing switch is saved and marked pending: the badge keeps naming what /mcp is really serving, the panel says which mode the next start will adopt, points out that the dedicated endpoint already serves it if you would rather repoint the client than restart, and offers Cancel — keep <mode>. Both serialization axes hot-reload with a tools/list_changed to connected clients.

GET /api/v1/routing gains tool_response_mode, direct_tool_response_mode (both resolved), pending_routing_mode and restart_required.

Defects this surfaced, all fixed here

Making the header honest meant the backend had to be. Five real defects, each reproduced before fixing:

  1. A restart-pending change was silently destroyed by the next save. PATCH /api/v1/config merged onto the live config, which by design does not carry a restart-gated field. Switch to Direct, toggle deferred schemas, and the routing switch was gone from disk behind a success toast. The runtime now tracks the desired (on-disk) config separately, and PATCH, GET /config and the docker-isolation patch all merge onto it.
  2. A restart-gated apply discarded the hot half of the same write — exactly the headline "Direct + deferred" flow. ApplyConfig now pins restart-gated fields to the running values and hot-applies the rest; reverting a field to what is already running no longer claims a restart.
  3. Every surface reported the configured mode as the served one. A hand-edited config file is hot-reloaded into memory while /mcp stays bound, so /api/v1/routing, /api/v1/status and mcpproxy status all named a surface nobody was being served. The mode is now recorded where /mcp binds it, and the reload path pins restart-gated fields instead of adopting them.
  4. The desired config went stale on four other commit paths (UpdateConfig, SaveConfiguration, the admission gate), so the next PATCH re-persisted a document that had lost whatever they added. Reproduced: add a custom registry, change any setting from the switcher, and the registry was erased from mcp_config.json — registries live only in the config file, so nothing splices them back from config.db. SaveConfiguration also rewrote the whole file from the running config, reverting a pending switch on every server enable/disable.
  5. routing_mode was compared raw, so an apply body that merely omits the key reported a restart-required change to the mode already in force, then persisted "".

Testing

  • I have tested these changes locally
  • I have added/updated tests that prove my fix is effective or my feature works
  • All existing tests pass

Automated. 995 frontend unit tests (14 new in frontend/tests/unit/mode-switcher.spec.ts); internal/runtime including -race (new apply_config_pending_restart_test.go and restart_gated_test.go, the latter pinning pinRestartGated to DetectConfigChanges so the two lists cannot drift); internal/httpapi, internal/config, internal/server, cmd/mcpproxy; golangci-lint v2 with .github/.golangci.yml clean.

Manual, against an isolated instance (high port, scratch --config and --data-dir): staged Direct → deferred applied instantly while Direct stayed staged → added a registry and a server → PATCHed another setting; registry, server and the pending switch all survived → cancel cleared the pending state without a restart prompt → restart adopted Direct with schema_deferred: true → hand-editing the file reported the edit as pending rather than active. Browser-verified in Retrieve, Direct and Code-Exec.

Notes for the reviewer

  • The desired / running config split touches the config pipeline, not just the UI. That is the part worth your eyes. r.cfg now means "what is running", desiredCfg means "what the file holds / the next start will use", and pinRestartGated is the one place that separates them.
  • One deliberate behaviour change: pinning restart-gated fields on the file-reload path means a hand-edited api_key now takes effect on restart rather than on the next request. That matches what DetectConfigChanges has always claimed for that field and what the API path already did, but it is a change. Easy to back out by dropping api_key from the pinned set — though it would then also have to leave the detector's restart-gated list, or the two disagree again.
  • Three watcher tests were amended, not weakened: their subject (the watcher must not echo our own save back as a disk reload) is untouched; their final assertions moved from a hot field to listen, because the hot half of a restart-required apply now applies immediately by design.
  • Reviewed by two adversarial multi-agent passes; the second caught defect 4, which the first pass had introduced. opencode (gpt-5.6-sol) produced no output across four attempts in this environment, so it did not contribute a review.

…witcher

The header's `Mode: Retrieve` was read-only: a `cursor-help` pointer, a native
title tooltip most people never wait out, and no way to act on what it said.
It now opens a two-tab panel, mirroring the profile switcher beside it:

- **Surface** — the three routing modes, each with what it costs an agent, the
  dedicated endpoint that always serves it, and whether picking it needs a
  restart.
- **Schema detail** — both serialization axes (`tool_response_mode`,
  `direct_tool_response_mode`), with the measured deferred-mode savings (29.7% /
  34.8%) and the describe_tool round trip they cost. These apply instantly.

A routing-mode switch is restart-gated (/mcp binds its mode to a ServeMux
pattern at startup), so the panel keeps naming the mode /mcp is really serving,
says which mode the next start will adopt, points at the dedicated endpoint that
already serves it, and offers to cancel.

Making that honest exposed three defects underneath, all fixed here:

1. **A restart-pending change was silently destroyed by the next save.** PATCH
   /api/v1/config merged onto the LIVE config, which by design does not carry a
   restart-gated field. Switch to Direct, then change anything else, and the
   routing switch vanished from disk behind a success toast. The runtime now
   tracks the desired (on-disk) config separately; PATCH, GET /config and the
   docker-isolation patch all merge onto it.
2. **A restart-gated apply discarded the hot half of the same write.** Turning
   on deferred schemas while switching to Direct left deferred schemas off.
   ApplyConfig now pins the restart-gated fields to the running values and
   hot-applies the rest; reverting a field to what is already running no longer
   claims a restart.
3. **Every surface reported the configured mode as the served one.** A
   hand-edited config file is hot-reloaded into memory while /mcp stays bound,
   so /api/v1/routing, /api/v1/status and `mcpproxy status` all named a surface
   nobody was being served. The mode is now recorded where /mcp binds it.

Also: `routing_mode` is normalized before comparison, so an apply body that
merely omits the key no longer reports a restart-required change to the mode
already in force.

GET /api/v1/routing gains `tool_response_mode`, `direct_tool_response_mode`
(resolved), `pending_routing_mode` and `restart_required`.
Review of the desired/served split found the split itself was half-applied.
`desiredCfg` was written in three places, but four other paths commit config —
`UpdateConfig` (registry-source CRUD, server add/remove), `SaveConfiguration`
(every enable/disable/quarantine toggle) and the admission gate — and they
replace or mutate the live config without it. Since PATCH and GET
/api/v1/config now merge onto the desired config, a stale copy meant the next
save re-persisted a document that had lost whatever those paths added.
Reproduced: add a custom registry, then change any setting from the header
switcher, and the registry was erased from mcp_config.json behind a success
toast — registries live only in the config file, so nothing splices them back
from config.db.

- `setDesiredLocked` folds each commit into the desired config while keeping
  whatever is still waiting for a restart, and every commit path calls it.
- `SaveConfiguration` rewrote the whole file from the RUNNING config, so a
  server toggle silently reverted a routing-mode switch the API was still
  reporting as pending. It now overlays the pending restart-gated values onto
  what it writes (marked as a self-write, so the watcher does not read them
  back as an external edit), leaving the in-memory stores on the running values.
- `ReloadConfiguration` adopted a hand-edited restart-gated field into memory
  while /mcp stayed bound, so the running config named a surface nobody was
  served. It now pins those fields and republishes the pinned config to
  configsvc, so the snapshot and r.cfg cannot disagree.
- The hot-field merge into ChangedFields runs on every path, not only the
  restart branch — cancelling a pending switch was skipping the server reload
  and update-check re-gate its own hot half had earned.
- `mcpproxy doctor` labels its routing mode "configured" and points at
  `mcpproxy status` for the served one; it reads the config file, not the daemon.
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 7a7b5be
Status: ✅  Deploy successful!
Preview URL: https://187e1532.mcpproxy-docs.pages.dev
Branch Preview URL: https://claude-mode-switcher-deferre.mcpproxy-docs.pages.dev

View logs

@codecov-commenter

codecov-commenter commented Aug 30, 2026 •

Copy link
Copy Markdown

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

Codecov Report

❌ Patch coverage is 75.55556% with 44 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/runtime/runtime.go 72.46% 10 Missing and 9 partials ⚠️
internal/runtime/lifecycle.go 54.54% 7 Missing and 3 partials ⚠️
internal/config/config.go 0.00% 6 Missing ⚠️
internal/httpapi/server.go 90.69% 3 Missing and 1 partial ⚠️
cmd/mcpproxy/status_cmd.go 0.00% 2 Missing ⚠️
internal/runtime/restart_gated.go 91.66% 1 Missing and 1 partial ⚠️
internal/runtime/config_load_admission_gate.go 50.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@github-actions

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: claude/mode-switcher-deferred-schemas-3c477b

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 33297266979 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

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