Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
62 commits
Select commit Hold shift + click to select a range
c01cdba
docs(specs): 102-schema-deferred implementation plan
Dumbris Aug 25, 2026
d4efaf9
docs(specs): 102-schema-deferred plan hardening from verified review …
Dumbris Aug 25, 2026
6b61eae
docs(specs): 102-schema-deferred — name the bench arm the SC-001/SC-0…
Dumbris Aug 25, 2026
0aacf12
docs(specs): 102-schema-deferred — pin the exact corpus gate name and…
Dumbris Aug 25, 2026
40747e4
docs(specs): 102-schema-deferred — exact corpus gate name in research.md
Dumbris Aug 25, 2026
de181f8
docs(specs): 102-schema-deferred — FR-018 covers the discovery-error …
Dumbris Aug 25, 2026
7000056
docs(specs): 102-schema-deferred — make the FR-015 byte-stability cap…
Dumbris Aug 25, 2026
daeadfd
docs(specs): 102-schema-deferred — pin what the appended signature ac…
Dumbris Aug 25, 2026
19bd4cd
docs(specs): 102-schema-deferred — one reference wording for the defe…
Dumbris Aug 25, 2026
5a38fe1
docs(specs): 102-schema-deferred — name the single mode-read helper
Dumbris Aug 25, 2026
1ff0ed0
docs(specs): 102-schema-deferred — close the fourth parity leak (defi…
Dumbris Aug 25, 2026
2b1b68d
docs(specs): 102-schema-deferred — name the real injection point for …
Dumbris Aug 25, 2026
05d5da7
docs(specs): 102-schema-deferred — sync the decision table and consti…
Dumbris Aug 25, 2026
1792458
docs(specs): 102-schema-deferred — fix all four cross-model review fi…
Dumbris Aug 25, 2026
1e27e3d
docs(specs): 102-schema-deferred — distinguish a nil catalog from an …
Dumbris Aug 25, 2026
aadb8b3
docs(specs): 102-schema-deferred — reference D14 from the summary and…
Dumbris Aug 25, 2026
b9c1abd
docs(specs): 102-schema-deferred — punctuation after the R4 legend po…
Dumbris Aug 25, 2026
c2bf8f1
docs(specs): 102-schema-deferred — cross-reference R13 from R9's atom…
Dumbris Aug 25, 2026
3d9c28d
docs(specs): 102-schema-deferred — fix all four round-3 cross-model f…
Dumbris Aug 25, 2026
9874151
docs(specs): 102-schema-deferred — R13 ordering table now matches the…
Dumbris Aug 25, 2026
12fca8a
docs(specs): 102-schema-deferred — spell out that the builder must no…
Dumbris Aug 25, 2026
e6defd8
docs(specs): 102-schema-deferred — propagate D13 and D16 into every d…
Dumbris Aug 25, 2026
9d8da18
docs(specs): 102-schema-deferred — declare the FR-017 atomicity narro…
Dumbris Aug 25, 2026
a0d0601
docs(specs): 102-schema-deferred — close same-name origin skew (round…
Dumbris Aug 25, 2026
b8b40d2
docs(specs): 102-schema-deferred — retract the over-broad discriminat…
Dumbris Aug 25, 2026
6fc3f2e
docs(specs): 102-schema-deferred — pin renderedDescription on the cat…
Dumbris Aug 25, 2026
1a80fd6
docs(specs): 102-schema-deferred — group the skew interleavings so th…
Dumbris Aug 25, 2026
3e95e3b
docs(specs): 102-schema-deferred — fix the tier source, the publicati…
Dumbris Aug 25, 2026
606a57d
docs(specs): 102-schema-deferred — enumerate the invisible-change res…
Dumbris Aug 25, 2026
060ffb1
docs(specs): 102-schema-deferred — split the invisible-change proof i…
Dumbris Aug 25, 2026
a3fe1f6
docs(specs): 102-schema-deferred — make the invisible-change partitio…
Dumbris Aug 25, 2026
60e14cc
docs(specs): 102-schema-deferred — fix the input-schema skew test rec…
Dumbris Aug 25, 2026
071bd52
docs(specs): close review gaps in the 102-schema-deferred plan
Dumbris Aug 26, 2026
501bdc6
docs(specs): 102-schema-deferred tasks
Dumbris Aug 26, 2026
b4f9f4b
docs(specs): close cross-model review findings in the 102 task list
Dumbris Aug 26, 2026
631793b
Merge origin/main into 102-schema-deferred-plan
Dumbris Aug 26, 2026
3862906
feat(102): config axis + non-compiling signature lookup (T004-T012)
Dumbris Aug 26, 2026
1b2ea5f
feat(102): directCatalog snapshot with collision withholding (T013-T014)
Dumbris Aug 26, 2026
1fc18b6
feat(102): catalog-backed direct filters, atomic publication (T015-T023)
Dumbris Aug 26, 2026
3beead1
refactor(102): simplify the no-catalog fallbacks and pin the startup …
Dumbris Aug 26, 2026
58c72eb
fix(102): distinct-origin collisions, serialize direct rebuilds
Dumbris Aug 26, 2026
d70474f
feat(102): describe_tool on the direct surface + initial rebuild (T01…
Dumbris Aug 26, 2026
4a683c1
docs(specs): accept the three FR-017 narrowings, amend the atomicity …
Dumbris Aug 27, 2026
5a79a9b
Merge 102-schema-deferred-plan (T001-T003 amendment) into impl
Dumbris Aug 27, 2026
5bf43ac
feat(102): deferred direct rendering + direct-surface instructions (T…
Dumbris Aug 27, 2026
8e1bf26
test(102): close the cross-model review findings on Phase 3
Dumbris Aug 27, 2026
c564c12
feat(102): surface-neutral describe_tool prose, both id forms (T037-T…
Dumbris Aug 27, 2026
ebbf616
feat(102): describe_tool on the direct surface (T042-T058)
Dumbris Aug 27, 2026
bcfb8cf
fix(102): close the cross-model review findings on Phase 4
Dumbris Aug 27, 2026
0b7a75b
feat(102): self-healing direct calls (T019a, T059-T064)
Dumbris Aug 27, 2026
99bed80
test(102): make the cross-mode self-healing claim actually test both …
Dumbris Aug 27, 2026
f591eb0
feat(102): operator opt-in, hot reload and the skew proof (T065-T072)
Dumbris Aug 28, 2026
f464a16
test(102): pin the SetTools-then-publish order with a real seam
Dumbris Aug 28, 2026
6cbba57
fix(102): close the cross-model review findings on Phase 6
Dumbris Aug 28, 2026
42ab19b
docs(102): direct built-ins gate, bench arm, and the Phase 7 docs (T0…
Dumbris Aug 28, 2026
8041069
test(102): E2E coverage and the final gate sweep (T077, T082, T083)
Dumbris Aug 28, 2026
27a9bf3
docs(102): correct a signature example that contradicted the real ord…
Dumbris Aug 28, 2026
15d222a
docs(102): stop overstating how the two SC-001 measurements relate
Dumbris Aug 28, 2026
1acd6e0
fix(102): close the seven Phase 7 review findings
Dumbris Aug 28, 2026
82f9767
Merge remote-tracking branch 'origin/main' into feat/102-schema-defer…
Dumbris Aug 28, 2026
f3ad9b7
fix(telemetry,ux): three pre-existing defects found while auditing sp…
Dumbris Aug 28, 2026
baa1291
fix(102): three HIGH bugs found by adversarial QA against a running p…
Dumbris Aug 28, 2026
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
5 changes: 3 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Only halt and ask a human IF:

MCPProxy is a Go desktop application that acts as a smart proxy for AI agents using the Model Context Protocol (MCP): intelligent tool discovery, massive token savings, and built-in security quarantine against malicious MCP servers.

**Stack**: Go 1.24 (backend) · TypeScript 5.9 / Vue 3.5 (frontend) · Swift 5.9 (macOS tray). Storage: BBolt (`config.db`) + Bleve (search index). Avoid new dependencies without clear need.
**Stack**: Go 1.25 (backend) · TypeScript 5.9 / Vue 3.5 (frontend) · Swift 5.9 (macOS tray). Storage: BBolt (`config.db`) + Bleve (search index). Avoid new dependencies without clear need.

## Editions (Personal & Server)

Expand Down Expand Up @@ -112,7 +112,7 @@ Env vars: `MCPPROXY_LISTEN`, `MCPPROXY_API_KEY`, `MCPPROXY_DEBUG`, `MCPPROXY_TEL

## MCP Protocol

**Built-in tools**: `retrieve_tools` (BM25 search across upstream tools; Spec 049 opt-in `include_disabled`; Spec 085 `detail` override + compact signatures under `tool_response_mode: compact`) · `describe_tool` (Spec 085: batch ≤5 ids → full schemas, retrieve_tools mode only) · `call_tool_read|write|destructive` (Spec 018 intent variants; operation type inferred from the variant; Spec 085 pre-dispatch arg validation with self-healing `invalid_params` errors) · `code_execution` (sandboxed JS, off by default) · `upstream_servers` (CRUD, Spec 049) · `quarantine_security` (Spec 032). **Tool format**: `<serverName>:<toolName>` (e.g. `github:create_issue`).
**Built-in tools**: `retrieve_tools` (BM25 search across upstream tools; Spec 049 opt-in `include_disabled`; Spec 085 `detail` override + compact signatures under `tool_response_mode: compact`) · `describe_tool` (Spec 085: batch ≤5 ids → full schemas; Spec 102: also on the direct surface, `server:tool` or `server__tool` ids) · `call_tool_read|write|destructive` (Spec 018 intent variants; operation type inferred from the variant; Spec 085 pre-dispatch arg validation with self-healing `invalid_params` errors) · `code_execution` (sandboxed JS, off by default) · `upstream_servers` (CRUD, Spec 049) · `quarantine_security` (Spec 032). **Tool format**: `<serverName>:<toolName>` (e.g. `github:create_issue`); the direct surface lists as `<serverName>__<toolName>` and accepts both.

**REST API** base `/api/v1`, auth via `X-API-Key` header or `?apikey=`. MCP endpoints (`/mcp`) stay unprotected for client compatibility; the REST API always requires a key (auto-generated if absent). All responses carry `X-Request-Id` (correlate with `mcpproxy activity list --request-id <id>`). Live updates via SSE at `/events`. Full endpoint list: `oas/swagger.yaml` + [docs/api/rest-api.md](docs/api/rest-api.md).

Expand Down Expand Up @@ -158,6 +158,7 @@ tail -f ~/Library/Logs/mcpproxy/main.log # main log (macOS; Linux: ~/.mcpproxy/
- **Windows installer**: [docs/github-actions-windows-wix-research.md](docs/github-actions-windows-wix-research.md). **Prerelease** (`next` branch + `v*-rc.*` tags, opt-in, off stable channels): [docs/prerelease-builds.md](docs/prerelease-builds.md).

## Recent Changes
- 102-schema-deferred: Go 1.25.5 module toolchain (`go.mod`), backend-only + existing only — mark3labs/mcp-go v0.57.0 (tool surface), santhosh-tekuri/jsonschema/v6 (Spec-085 validator reuse), zap, stdlib. **No new dependencies.**
- 101-tpa-db: Go 1.25.5 module toolchain (`go.mod`), backend-only + stdlib only for the new work — `crypto/ed25519`, `crypto/sha256`, `syscall` (no ed25519 usage in the tree before this); existing bbolt (state), zap, Cobra. **No new dependencies.**
- 098-tools-preflight: Added Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — chi (httpapi), bbolt (storage), Bleve (index), zap (logging), Cobra (CLI), swaggo/swag v2 (contract regen). **No new dependencies.**
- 097-stored-scripts: Added Go 1.25 (os.Root/Root.ReadFile available — R1) + stdlib only (os.Root). **No new dependencies.**
4 changes: 2 additions & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -740,7 +740,7 @@ 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 | — | [102-schema-deferred](./specs/102-schema-deferred/) | |
| 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 Down Expand Up @@ -882,4 +882,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
| [099-describe-check-mode](./specs/099-describe-check-mode/) | `in-flight` | 9/10 (90%) |
| [100-prompt-rugpull-baseline](./specs/100-prompt-rugpull-baseline/) | — | — |
| [101-tpa-db](./specs/101-tpa-db/) | — | — |
| [102-schema-deferred](./specs/102-schema-deferred/) | — | — |
| [102-schema-deferred](./specs/102-schema-deferred/) | `shipped` | 89/89 (100%) |
178 changes: 178 additions & 0 deletions bench/arms/directdeferred.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
package arms

import (
"encoding/json"
"fmt"
"strings"

"github.com/smart-mcp-proxy/mcpproxy-go/bench"
"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
"github.com/smart-mcp-proxy/mcpproxy-go/internal/server"
"github.com/smart-mcp-proxy/mcpproxy-go/internal/toolsig"
)

// DirectDeferredName is the registry key of the schema-deferred direct-surface
// arm (Spec 102).
const DirectDeferredName = "direct_deferred"

// directDeferredInputSchema is the minimal permissive schema every deferred
// entry advertises. It mirrors internal/server's deferredDirectInputSchema
// byte for byte (Spec 102 FR-004): the placeholder is deliberately NOT
// {"type":"object","properties":{},"required":[]}, because clients that prune
// arguments absent from the declared schema would then drop every argument —
// and those two extra members are also real tokens this arm must charge for
// exactly as the wire does, no more and no less.
const directDeferredInputSchema = `{"type":"object"}`

// directDeferredListingPrefix and directDeferredListingSuffix wrap the entry
// array into the tools/list result envelope. Both are paid once per listing,
// not per tool (contract rule 6).
const (
directDeferredListingPrefix = `{"tools":[`
directDeferredListingSuffix = `]}`
)

// DirectDeferredArm renders the DIRECT enumeration surface under Spec 102's
// deferred serialization: one `tools/list` payload, not a retrieve_tools
// result set.
//
// It is the first arm to leave the retrieve_tools shape, and that is the point:
// every other arm encodes what search RETURNS, so the profiler had no way to
// price what enumeration COSTS — the payload #971 is about, and the payload the
// direct surface serves on every connect. Measured against baseline_json (the
// full definition each entry would otherwise carry) it answers SC-001 directly.
//
// Each tool renders as the wire entry the direct surface registers under
// deferral (internal/server renderDeferredDirectTool): the "<server>__<tool>"
// display name, the "[server] description" the direct surface always prepends
// plus the tool's Spec 085 compact signature on its own line, the permissive
// placeholder input schema, and no outputSchema — stripped for the same reason
// the input schema is (FR-006).
//
// Two production fields are deliberately absent, because the frozen corpus
// carries no data for them and inventing it would price a fiction:
// `annotations` (bench.Tool has no annotation hints) and the upstream
// `outputSchema` deferral would strip anyway.
//
// The annotations omission is NOT neutral, and an earlier version of this
// comment wrongly claimed it "cancels in the comparison". It cancels from the
// byte DIFFERENCE, since the field is identical in both arms — but savings is a
// ratio, not a difference:
//
// savings = removed / full
//
// so adding an unchanged block to both columns grows the denominator and LOWERS
// the percentage. Omitting it therefore biases this arm's savings UPWARD
// relative to the real wire. Measured: this arm reports 29.5% where the
// in-process gate over the real marshalled mcp.Tool — annotations, `_meta` and
// all — reports 29.7% on the same corpus, so the two modelling gaps happen to
// nearly offset. Treat this arm as a comparative instrument for ranking
// encodings, not as an absolute wire model.
type DirectDeferredArm struct{}

// NewDirectDeferred returns the direct_deferred arm.
func NewDirectDeferred() *DirectDeferredArm { return &DirectDeferredArm{} }

// Name implements Arm.
func (*DirectDeferredArm) Name() string { return DirectDeferredName }

// IndexAltering implements Arm: deferral changes SERIALIZATION only (FR-008).
// The retrieval index still ingests the full input schema — indeed it must,
// since the signature cache this arm renders from is warmed at index time from
// exactly that text. Nothing the index sees changes, so retrieval quality
// cannot move and scoring it would only cost CI time.
func (*DirectDeferredArm) IndexAltering() bool { return false }

// LowerBound implements Arm: descriptions are preserved verbatim — the
// signature is appended to the full description, never substituted for it, so
// the measured listing size is exact rather than a floor. The schema is
// deferred, not dropped: its cost reappears as describe_tool round trips for
// the lossy share of the corpus, which the break-even model prices separately
// instead of hiding it in this arm's label.
func (*DirectDeferredArm) LowerBound() bool { return false }

// directDeferredDescription builds the description field of one deferred
// entry: the direct surface's "[server] " prefix, the upstream description,
// then a newline, the BARE tool name, and the compact signature.
//
// The tool name has to be prepended here because toolsig.Signature.Sig is the
// parenthesized parameter list alone and carries no name — appending Sig by
// itself would emit a dangling "(owner*:str, …)" with nothing to attach it to.
// internal/server's directSignatureSuffix prepends it for the same reason.
func directDeferredDescription(t bench.Tool, sig toolsig.Signature) string {
return "[" + t.Server + "] " + t.Description + "\n" + t.Name + sig.Sig
}

// directDeferredSignature compiles one tool's compact signature.
//
// toolsig.Render is fail-soft — on an unparseable schema it returns the "(~)"
// placeholder alongside its error, which is right for the serving path, where
// a listing must never fail. It is wrong HERE: "(~)" is three tokens, so an
// arm that swallowed the error would charge almost nothing for a tool whose
// full definition baseline_json still charges in full, quietly inflating the
// measured savings. The error is propagated instead, and the harness records
// the tool as an explicit skip (contract rule 2).
func directDeferredSignature(t bench.Tool) (toolsig.Signature, error) {
sig, err := toolsig.Render(string(t.Schema), t.Description)
if err != nil {
return toolsig.Signature{}, fmt.Errorf("tool %s: render compact signature: %w", t.ToolID, err)
}
return sig, nil
}

// EncodeTool implements Arm: one deferred `tools/list` entry as canonical JSON
// (sorted keys, compact, no HTML escaping — the same canonicalization every
// other schema-bearing arm renders through, so no arm's totals include another
// arm's whitespace).
func (*DirectDeferredArm) EncodeTool(t bench.Tool) (string, error) {
sig, err := directDeferredSignature(t)
if err != nil {
return "", err
}

entry := map[string]interface{}{
// server.FormatDirectToolName rather than a local "__" join: the
// display-name format is production's to define, and binding to it
// means a change there cannot silently desync the measurement.
"name": server.FormatDirectToolName(t.Server, t.Name),
"description": directDeferredDescription(t, sig),
"inputSchema": json.RawMessage(directDeferredInputSchema),
}

raw, err := json.Marshal(entry)
if err != nil {
return "", fmt.Errorf("tool %s: marshal deferred entry: %w", t.ToolID, err)
}
return bench.CanonicalJSON(raw)
}

// EncodeListing implements Arm: the entries joined into the tools/list result
// envelope. The envelope and the separating commas are concatenated around the
// per-tool encodings verbatim rather than re-marshaled, so a listing total
// decomposes exactly into per-tool costs plus a fixed, once-paid wrapper.
func (a *DirectDeferredArm) EncodeListing(ts []bench.Tool) (string, error) {
entries := make([]string, 0, len(ts))
for _, t := range ts {
enc, err := a.EncodeTool(t)
if err != nil {
return "", err
}
entries = append(entries, enc)
}
return directDeferredListingPrefix + strings.Join(entries, ",") + directDeferredListingSuffix, nil
}

// EncodeIndexMetadata implements Arm: the production index fields unchanged.
// Deferral never reaches the index — see IndexAltering.
func (*DirectDeferredArm) EncodeIndexMetadata(t bench.Tool) (config.ToolMetadata, error) {
return config.ToolMetadata{
Name: t.Name,
ServerName: t.Server,
Description: t.Description,
ParamsJSON: string(t.Schema),
}, nil
}

func init() {
MustRegister(NewDirectDeferred())
}
Loading
Loading