Skip to content

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

Merged
Dumbris merged 3 commits into
mainfrom
fix/direct-surface-describe-ids-and-config-errors
Aug 29, 2026
Merged

Dumbris merged 3 commits into
mainfrom
fix/direct-surface-describe-ids-and-config-errors

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 29, 2026

Copy link
Copy Markdown
Member

Closes #1083. Closes #1084. Resolves the SC-001 threshold decision left open after spec 102.

Reviewed with opencode / gpt-5.6-sol, which found two defects in my first attempt at the third fix — both corrected here (details below).

#1083 — describe_tool returned uncallable identifiers

On the direct surface the response named the tool <server>:<tool> (it registers <server>__<tool>) and recommended call_with: "call_tool_read" (intent variants this surface does not expose). Following either verbatim gave "tool not found." Deferred mode makes this the live discovery path — 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 in the registered display name and drops call_with.

Dropped rather than retargeted: call_with 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 the tier is recomputable. The D10 safety test that guarded against downgrading a pending destructive tool is re-pointed at that source, not deleted. Both id spellings still work as input; only the echoed identifier changes.

Verified live: the identifier describe_tool returns now actually executes.

#1084 — three defects

  1. 500 → 400. ApplyConfig discarded its structured errors, so handlers could not distinguish bad input from a persist failure without string-matching. They now ride on the result; writeApplyConfigError answers 400 with the offending field in a structured payload, reserving 500 for real faults.
  2. Malformed log lines. SugaredLogger.Error(msg, "key", val) 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; 2 non-kv calls deliberately left alone.
  3. Stale nested stats. /api/v1/status embedded a snapshot whose upstream_stats/tools_indexed nothing refreshed — stuck at "Connecting"/0 for the life of a process whose servers were long Ready.

What the review caught in my first attempt at (3)

  • Refreshing inside Server.GetStatus() made every status poll walk all servers twice (O(N) duplicated).
  • The SSE stream forwards a snapshot that never passes through GetStatus(), so it stayed stale regardless.

Now a withLiveUpstreamStats helper at the API layer, applied at all three emission sites, each reusing the traversal it already performs for its top-level field — one walk per response instead of two. It copies rather than mutates, because the SSE map is owned by the publisher.

SC-001 restated per corpus shape

The original ≥70% / ≥85% was unreachable. Measured:

corpus tools full deferred reduction originally asked
corpus_v2 (frozen reference) 45 6116 4301 29.7% ≥70%
livemcptool_snapshot 527 99918 65138 34.8% ≥85%

Arithmetic ceiling is 38.9% — what deleting both schema and signature would yield. The target assumed schemas dominate the payload (~77% per spec-083); at these shapes names, descriptions and annotations do, and FR-004 forbids touching those.

Now ≥25% and ≥30% — roughly 15% relative below each measured value, as a regression floor, not a second projection. Both bounds are asserted, so that file is the SC-001 gate rather than a stand-in. 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 and the criterion must be re-derived.

Verification

Live, on an isolated port with scratch data-dir and config (~/.mcpproxy/ untouched, core torn down):

  • describe_tool → everything__echo, no call_with, annotations retained, and calling that id succeeds.
  • Invalid value → HTTP 400 with validation_errors naming the field; a valid PATCH still 200; config file untouched by the rejected value.
  • Log line: Failed to apply configuration patch {"error": "..."} — structured, accurate caller.
  • Nested and top-level stats agree (13/13 tools, Ready/Ready).

internal/{httpapi,runtime,config} green under -race; internal/server green; both editions build; golangci-lint v2 0 issues.

…; 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.
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.
@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: 08083ef
Status: ✅  Deploy successful!
Preview URL: https://5a64c1da.mcpproxy-docs.pages.dev
Branch Preview URL: https://fix-direct-surface-describe.mcpproxy-docs.pages.dev

View logs

…scribe-ids-and-config-errors

# Conflicts:
#	ROADMAP.md
#	roadmap.yaml
@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

❌ Patch coverage is 43.04636% with 86 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/httpapi/server.go 37.03% 85 Missing ⚠️
internal/server/mcp_describe_tool.go 92.85% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@github-actions

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: fix/direct-surface-describe-ids-and-config-errors

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

Note: Artifacts expire in 14 days.

@Dumbris
Dumbris merged commit 71e04e2 into main Aug 29, 2026
39 checks passed
@Dumbris
Dumbris deleted the fix/direct-surface-describe-ids-and-config-errors branch August 29, 2026 18:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants