Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
36 changes: 36 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,24 @@ Releases follow [Semantic Versioning](https://semver.org/).

### Features

- **mcp:** schema-deferred direct mode — a new `direct_tool_response_mode` key (`full` | `deferred`,
**default `full`, so this is opt-in and changes nothing until you turn it on**). In `deferred`,
the direct enumeration surface (`/mcp/all`, and `/mcp` under `routing_mode: "direct"`) lists every
tool with its name, description, annotations and a compact Spec-085 signature, advertising
`inputSchema` as exactly `{"type":"object"}` and dropping `outputSchema`; agents recover a full
schema on demand via `describe_tool`, and a call whose arguments do not fit is rejected
**before** it reaches the upstream, with the schema attached so the agent can self-correct.
Hot-reloadable — flipping it rebuilds the listing and notifies connected clients, no restart.
**Measured token saving is ~30%** (29.7% on the 45-tool reference corpus, 34.8% on a 527-tool
snapshot) — materially less than the ~88% originally projected, because names, descriptions and
annotations, not schemas, dominate the payload. (spec 102, [#971](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/971))
- **settings:** both serialization modes are now reachable from the UI — Settings → General →
"Detail in tool-search results" (`tool_response_mode`) and "Detail in Direct-mode listings"
(`direct_tool_response_mode`), in the Web UI and the macOS tray. They previously had four ways to
set them (config file, env var, serve flag, REST) and no UI at all, so a tray-only user could not
reach `direct_tool_response_mode`. Neither carries a restart badge — both hot-reload, unlike
`routing_mode` above them.

- **mcp:** `describe_tool` check mode — an optional `check: true` returns one availability
verdict per id (up to 50) from the spec-098 preflight evaluator instead of schemas, so an
agent can gate a multi-step plan without leaving the MCP session. Optional `filters`
Expand All @@ -31,6 +49,24 @@ Releases follow [Semantic Versioning](https://semver.org/).

### Bug Fixes

- **mcp/describe_tool:** on the direct surface, the returned definition named the tool
`<server>:<tool>` and recommended a `call_with` intent variant — neither of which that surface
can be asked for, so an agent following the response verbatim got "tool not found". It now
echoes the registered `<server>__<tool>` name and omits `call_with` (the permission signal
remains in `annotations`, which it was derived from). Both id spellings still work as input.
([#1083](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1083))
- **api:** a config value the validator rejects now returns **400** with the offending field in a
structured `validation_errors` payload, instead of 500. 500 is reserved for genuine failures to
persist a valid config. ([#1084](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1084))
- **api:** `/api/v1/status` embedded a status snapshot whose `upstream_stats` and `tools_indexed`
were never refreshed — reporting `"Connecting"` and `0` for the life of a process whose servers
were long ready, while the sibling top-level field was correct. Both now come from one live
source, on the REST poll and on the SSE stream.
([#1084](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1084))
- **logging:** ~97 log calls in the REST API passed key/value pairs to a sugared logger method that
concatenates them, producing runs like `patcherrorconfiguration...` instead of structured fields.
([#1084](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/1084))

- **homebrew:** One-line install in docs + guard tap job against pre-release tags (#486) ([#486](https://github.com/smart-mcp-proxy/mcpproxy-go/pull/486)) ([`1098701`](https://github.com/smart-mcp-proxy/mcpproxy-go/commit/109870116fe17aa1ce7ecfd603962c1d3de21ba0))

### CI/Build
Expand Down
2 changes: 1 addition & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -726,7 +726,7 @@ graph LR
<details>
<summary>🟢 Deferred-schema serialization for the direct tools/list surface (spec 102) — Done · P1</summary>

> Direct mode enumerates every upstream tool but always ships full inputSchema (~30K tokens for a 100-tool fleet; Spec 083 profiling put ~77% of the payload in schemas agents rarely read). Deferred serialization keeps every tool name, description and annotation and appends the Spec 085 compact signature instead of the schema (~88% smaller listing), with describe_tool on the direct surface to recover it and the shipped pre-dispatch validation turning a wrong guess into one self-healing retry. Not a new routing_mode — a serialization mode of the direct surface, on the same tool_response_mode axis that already governs retrieve_tools. Spec merged in #1035 (issue #971, maintainer-accepted direction). COMPLETE: all 89 tasks shipped in #1063; the settings UI for both serialization axes followed in #1082. MEASURED SAVINGS FELL WELL SHORT OF THE ~88% PROJECTION ABOVE: 29.7% on the frozen reference corpus and 34.8% on a 527-tool snapshot, against SC-001's >=70% target, with 38.9% the arithmetic ceiling even if both the schema and the signature were deleted. The projection assumed schemas dominate the payload; names, descriptions and annotations turn out to carry most of it. SC-001 is knowingly unmet and awaits a maintainer decision (restate per corpus shape, or re-target at a schema-heavy corpus) — see specs/102-schema-deferred/tasks.md T035a. Unblocks token-bench — and that measured shortfall is now the first thing token-bench has to explain.
> Direct mode enumerates every upstream tool but always ships full inputSchema (~30K tokens for a 100-tool fleet; Spec 083 profiling put ~77% of the payload in schemas agents rarely read). Deferred serialization keeps every tool name, description and annotation and appends the Spec 085 compact signature instead of the schema, with describe_tool on the direct surface to recover it and the shipped pre-dispatch validation turning a wrong guess into one self-healing retry. Not a new routing_mode — a serialization mode of the direct surface, on the same tool_response_mode axis that already governs retrieve_tools. Spec merged in #1035 (issue #971, maintainer-accepted direction). COMPLETE: all 89 tasks shipped in #1063; the settings UI for both serialization axes followed in #1082; #1083/#1084 fixed in #1086. MEASURED SAVINGS FELL WELL SHORT OF THE ~88% ORIGINALLY PROJECTED: 29.7% on the frozen 45-tool reference corpus and 34.8% on a 527-tool snapshot, with 38.9% the arithmetic ceiling even if both the schema and the signature were deleted. The projection assumed schemas dominate the payload; names, descriptions and annotations turn out to carry most of it. SC-001 was RESTATED per corpus shape (maintainer decision 2026-08-29): now >=25% on the 45-tool corpus and >=30% at fleet scale, both asserted in internal/server/mcp_routing_deferred_tokens_test.go, with the original 70% kept as an upper tripwire. Unblocks token-bench — and that measured shortfall is the first thing token-bench has to explain.

Spec: [102-schema-deferred](./specs/102-schema-deferred/) · PR: #1063

Expand Down
102 changes: 102 additions & 0 deletions internal/httpapi/config_apply_error_status_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
package httpapi

import (
"bytes"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"testing"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"go.uber.org/zap"

"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
runtime "github.com/smart-mcp-proxy/mcpproxy-go/internal/runtime"
)

// #1084: PATCH /api/v1/config answered 500 for a value the config validator
// rejected — e.g. {"direct_tool_response_mode":"bogus"}. The behaviour was safe
// (the file was left untouched) but the status class was wrong, and the status
// class is what tells a client whether retrying could ever help.
type applyErrController struct {
baseController
result *runtime.ConfigApplyResult
err error
}

func (m *applyErrController) GetCurrentConfig() any { return &config.Config{APIKey: "k"} }
func (m *applyErrController) GetConfig() (*config.Config, error) {
return &config.Config{Listen: "127.0.0.1:8080"}, nil
}
func (m *applyErrController) GetConfigPath() string { return "/tmp/mcp_config.json" }
func (m *applyErrController) ApplyConfig(*config.Config, string) (*runtime.ConfigApplyResult, error) {
return m.result, m.err
}

func patchConfigWith(t *testing.T, ctrl *applyErrController, body map[string]any) *httptest.ResponseRecorder {
t.Helper()
srv := NewServer(ctrl, zap.NewNop().Sugar(), nil)
raw, err := json.Marshal(body)
require.NoError(t, err)
req := httptest.NewRequest(http.MethodPatch, "/api/v1/config", bytes.NewReader(raw))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "k")
w := httptest.NewRecorder()
srv.ServeHTTP(w, req)
return w
}

// A rejected value is the operator's mistake: 400, with the offending field
// named in a structured payload rather than only inside the prose message.
func TestPatchConfig_RejectedValueIs400WithValidationErrors(t *testing.T) {
w := patchConfigWith(t, &applyErrController{
result: &runtime.ConfigApplyResult{
Success: false,
ValidationErrors: []config.ValidationError{
{Field: "direct_tool_response_mode", Message: `invalid direct tool response mode: bogus (must be "full" or "deferred")`},
},
},
err: errors.New(`configuration validation failed: direct_tool_response_mode: invalid direct tool response mode: bogus`),
}, map[string]any{"direct_tool_response_mode": "bogus"})

require.Equal(t, http.StatusBadRequest, w.Code, "body=%s", w.Body.String())

var envelope map[string]interface{}
require.NoError(t, json.Unmarshal(w.Body.Bytes(), &envelope))
assert.Equal(t, false, envelope["success"])

data, ok := envelope["data"].(map[string]interface{})
require.True(t, ok, "the 400 must carry a structured payload, not just prose: %s", w.Body.String())
errs, ok := data["validation_errors"].([]interface{})
require.True(t, ok, "validation_errors must be present")
require.Len(t, errs, 1)

first, ok := errs[0].(map[string]interface{})
require.True(t, ok)
assert.Equal(t, "direct_tool_response_mode", first["field"],
"a client must be able to point at the offending field without parsing the message")
}

// A failure with no validation errors is a genuine server fault and must stay
// in the 500 class — otherwise the fix would mislabel real outages as bad input.
func TestPatchConfig_PersistFailureStays500(t *testing.T) {
w := patchConfigWith(t, &applyErrController{
result: &runtime.ConfigApplyResult{Success: false},
err: errors.New("failed to write config file: disk full"),
}, map[string]any{"tools_limit": 20})

require.Equal(t, http.StatusInternalServerError, w.Code, "body=%s", w.Body.String())
assert.NotContains(t, w.Body.String(), "validation_errors")
}

// A nil result alongside an error must not panic the classifier.
func TestPatchConfig_NilResultWithErrorStays500(t *testing.T) {
w := patchConfigWith(t, &applyErrController{
result: nil,
err: errors.New("controller exploded"),
}, map[string]any{"tools_limit": 20})

require.Equal(t, http.StatusInternalServerError, w.Code, "body=%s", w.Body.String())
}
Loading
Loading