Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(mcp): normalize JSON-encoded argument envelopes

wizardchen4b04cd83eef4
diff --git a/internal/agent/mcp_exposure_test.go b/internal/agent/mcp_exposure_test.go
index 5a412a3ed..fc36ad8ce 100644
--- a/internal/agent/mcp_exposure_test.go
+++ b/internal/agent/mcp_exposure_test.go
@@ -31,6 +31,7 @@ func TestMCPExposureWithoutMentionReachesProviderAndExecutes(t *testing.T) {
for _, variant := range []string{
"openai", "anthropic", "openai-deferred", "anthropic-deferred",
"openai-proxy-deferred", "anthropic-proxy-deferred",
+ "openai-string-proxy-deferred", "anthropic-string-proxy-deferred",
} {
t.Run(variant, func(t *testing.T) {
provider := strings.Split(variant, "-")[0]
@@ -192,8 +193,12 @@ func TestMCPExposureWithoutMentionReachesProviderAndExecutes(t *testing.T) {
assert.Contains(t, string(payload["tools"]), "Order IDs belong to the external customer system.")
if (!deferred && call == 1) || (deferred && call == 3) {
if proxyCall {
+ arguments := `{"tool_ref":"mt1","arguments":{"id":"42"}}`
+ if strings.Contains(variant, "-string-") {
+ arguments = `{"tool_ref":"mt1","arguments":"{\"id\":\"42\"}"}`
+ }
streamMCPTestCall(w, provider, agenttools.ToolCallMCPTool, "call_order",
- `{"tool_ref":"mt1","arguments":{"id":"42"}}`)
+ arguments)
return
}
if provider == "openai" {
diff --git a/internal/agent/mcp_proxy_test.go b/internal/agent/mcp_proxy_test.go
index 1c05111a5..560931a28 100644
--- a/internal/agent/mcp_proxy_test.go
+++ b/internal/agent/mcp_proxy_test.go
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"net/http/httptest"
+ "sync/atomic"
"testing"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
@@ -111,3 +112,86 @@ func TestAgentMCPProxyKeepsTargetEventsAndProtocolHistory(t *testing.T) {
require.Equal(t, "model-proxy-id", messages[1].ToolCallID)
require.Len(t, engine.buildToolsForLLM(), 2, "discovery must not advertise individual MCP schemas")
}
+
+func TestAgentMCPStringArgumentsKeepValidationAndAudit(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ var executions atomic.Int32
+ server := sdkserver.NewMCPServer("object-envelope", "1", sdkserver.WithToolCapabilities(false))
+ server.AddTool(sdkmcp.NewTool("币种列表"),
+ func(_ context.Context, request sdkmcp.CallToolRequest) (*sdkmcp.CallToolResult, error) {
+ executions.Add(1)
+ require.Empty(t, request.GetArguments())
+ return sdkmcp.NewToolResultText("CNY,USD"), nil
+ })
+ server.AddTool(sdkmcp.NewTool("convert", sdkmcp.WithString("currency", sdkmcp.Required())),
+ func(context.Context, sdkmcp.CallToolRequest) (*sdkmcp.CallToolResult, error) {
+ executions.Add(1)
+ return sdkmcp.NewToolResultText("converted"), nil
+ })
+ httpServer := httptest.NewServer(sdkserver.NewStreamableHTTPServer(server, sdkserver.WithStateLess(true)))
+ defer httpServer.Close()
+ manager := internalmcp.NewMCPManager(nil)
+ defer manager.Shutdown()
+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(7))
+ registry := agenttools.NewToolRegistry()
+ _, err := agenttools.RegisterMCPTools(ctx, registry, []*types.MCPService{{
+ ID: "currency", TenantID: 7, Name: "Currency", Enabled: true,
+ URL: &httpServer.URL, TransportType: types.MCPTransportHTTPStreamable,
+ }}, manager, nil, 0, nil, nil)
+ require.NoError(t, err)
+ engine := newTestEngine(t, &mockChat{})
+ engine.toolRegistry = registry
+ var starts []event.AgentToolCallData
+ engine.eventBus.On(event.EventAgentToolCall, func(_ context.Context, evt event.Event) error {
+ starts = append(starts, evt.Data.(event.AgentToolCallData))
+ return nil
+ })
+ describe := func(name string) string {
+ raw, _ := json.Marshal(map[string]any{"mode": "describe", "server_id": "currency", "tool_name": name})
+ result, err := registry.ExecuteTool(ctx, agenttools.ToolDiscoverMCPTools, raw)
+ require.NoError(t, err)
+ require.True(t, result.Success, result.Error)
+ modelResult := engine.modelContext.ModelToolResultForTool(agenttools.ToolDiscoverMCPTools, result)
+ var definition struct {
+ ToolRef string `json:"tool_ref"`
+ }
+ require.NoError(t, json.Unmarshal([]byte(modelResult), &definition))
+ return definition.ToolRef
+ }
+ emptyRef := describe("币种列表")
+ requiredRef := describe("convert")
+ for _, tc := range []struct {
+ ref string
+ arguments any
+ success bool
+ }{
+ {emptyRef, "{}", true},
+ {requiredRef, "{}", false},
+ {emptyRef, "null", false},
+ {emptyRef, "[]", false},
+ {emptyRef, `{"currency":`, false},
+ {"mt99", "{}", false},
+ } {
+ raw, err := json.Marshal(map[string]any{"tool_ref": tc.ref, "arguments": tc.arguments})
+ require.NoError(t, err)
+ calls := []types.LLMToolCall{{ID: "proxy", Function: types.FunctionCall{
+ Name: agenttools.ToolCallMCPTool, Arguments: string(raw),
+ }}}
+ engine.modelContext.DecodeToolCalls(calls)
+ result := engine.runToolCall(ctx, calls[0], 0, 1, 1, "session", "message")
+ require.Equal(t, tc.success, result.Result.Success, result.Result.Error)
+ if tc.success {
+ require.Equal(t, map[string]any{}, result.Args["arguments"])
+ require.Empty(t, starts[len(starts)-1].Arguments, "UI sees actual empty arguments, not a JSON string")
+ audit := buildToolSpanInput(calls[0], result.Args, false)
+ require.Equal(t, "{}", audit["model_arguments"].(map[string]any)["arguments"])
+ require.Equal(t, "resolved", audit["argument_resolution"])
+ require.Equal(t, result.Args, audit["resolved_arguments"])
+ } else if tc.ref == requiredRef {
+ require.Contains(t, result.Result.Error, "currency",
+ "target schema must still reject a missing required field")
+ }
+ }
+ require.EqualValues(t, 1, executions.Load(), "only the valid parameterless call may reach the MCP server")
+}
diff --git a/internal/agent/tools/mcp_catalog.go b/internal/agent/tools/mcp_catalog.go
index 42971dd7d..6d57b97e7 100644
--- a/internal/agent/tools/mcp_catalog.go
+++ b/internal/agent/tools/mcp_catalog.go
@@ -83,8 +83,8 @@ const mcpCallSchema = `{
"type": "string"
},
"arguments": {
- "description": "Original tool parameters as a JSON object matching input_schema, never a JSON-encoded string.",
- "examples": [{"order_id": "123"}],
+ "description": "JSON object matching input_schema. Use {} for no parameters; do not JSON-stringify it.",
+ "examples": [{}, {"order_id": "123"}],
"type": "object"
}
},
@@ -95,10 +95,10 @@ const mcpCallSchema = `{
"additionalProperties": false
}`
-const mcpCallArgumentsHint = ` Read the tool with discover_mcp_tools(mode="describe", ` +
- `server_id=..., tool_name=...) first. Use its tool_ref and pass arguments as a JSON object, ` +
- `not a JSON-encoded string; for example ` +
- `{"tool_ref":"<describe reference>","arguments":{"order_id":"123"}} (use the actual input_schema fields).`
+const mcpCallArgumentsHint = ` Pass arguments as a JSON object, not a JSON-encoded string. ` +
+ `For a tool with no parameters use {"tool_ref":"<describe reference>","arguments":{}}; ` +
+ `otherwise match its input_schema. If the definition is unavailable, use ` +
+ `discover_mcp_tools(mode="describe", server_id=..., tool_name=...).`
const maxMCPDefinitionChars = 256 * 1024
diff --git a/internal/agent/tools/mcp_catalog_test.go b/internal/agent/tools/mcp_catalog_test.go
index a850154ab..b906302d3 100644
--- a/internal/agent/tools/mcp_catalog_test.go
+++ b/internal/agent/tools/mcp_catalog_test.go
@@ -651,6 +651,6 @@ func TestMCPCallInvalidArgumentsExplainObjectEnvelope(t *testing.T) {
require.NoError(t, err)
require.False(t, result.Success)
require.Contains(t, result.Error, "JSON object, not a JSON-encoded string")
- require.Contains(t, result.Error, `"arguments":{"order_id":"123"}`)
+ require.Contains(t, result.Error, `"arguments":{}`)
}
}
diff --git a/internal/modelcontext/README.md b/internal/modelcontext/README.md
index bef758c8d..b8893b1d8 100644
--- a/internal/modelcontext/README.md
+++ b/internal/modelcontext/README.md
@@ -85,6 +85,13 @@ registered; `input_schema`, `call_mcp_tool.arguments`, and external execution
results remain opaque. Arguments are restored before authorization, validation,
execution, persistence and UI events. Unknown routing handles fail closed.
+For model-emitted `call_mcp_tool` calls, one extra JSON-string encoding of the
+`arguments` envelope is accepted only when it contains a complete JSON object
+(including `{}`). Normalization runs before resource-handle decoding; original
+model arguments are retained for tracing. Nested business strings are unchanged,
+and malformed JSON, arrays, `null`, and further encoding layers remain invalid.
+The canonical object still passes the existing routing, schema and approval checks.
+
## Wiki routing
`WikiRouteResolver` is intentionally separate. It stores server-side
diff --git a/internal/modelcontext/mcp.go b/internal/modelcontext/mcp.go
index 8cef0909a..8a649f4e3 100644
--- a/internal/modelcontext/mcp.go
+++ b/internal/modelcontext/mcp.go
@@ -6,8 +6,41 @@ import (
"strings"
"github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
)
+// normalizeMCPCallArguments tolerates one extra JSON encoding of the bridge's
+// arguments envelope. Run after preserving ModelArguments and before decoding
+// resource handles so audit/UI/execution all use the same canonical object.
+// This is not JSON repair: incomplete JSON, null, arrays and further string
+// layers remain invalid, and remote business fields are never coerced here.
+func normalizeMCPCallArguments(calls []types.LLMToolCall) {
+ for i := range calls {
+ if calls[i].Function.Name != "call_mcp_tool" {
+ continue
+ }
+ var envelope map[string]json.RawMessage
+ if json.Unmarshal([]byte(calls[i].Function.Arguments), &envelope) != nil {
+ continue
+ }
+ var wrapped string
+ if json.Unmarshal(envelope["arguments"], &wrapped) != nil {
+ continue
+ }
+ var object map[string]json.RawMessage
+ if json.Unmarshal([]byte(wrapped), &object) != nil || object == nil {
+ continue
+ }
+ // Retain raw number literals and nested values instead of round-tripping
+ // through float64 or recursively decoding business strings.
+ envelope["arguments"] = json.RawMessage(wrapped)
+ encoded, err := json.Marshal(envelope)
+ if err == nil {
+ calls[i].Function.Arguments = string(encoded)
+ }
+ }
+}
+
// MCP routing identities belong to our bridge, not to the remote tool schema.
// Rewrite only explicit envelope fields; never walk an external input_schema,
// call_mcp_tool.arguments, or a dynamic MCP tool's arguments/results.
diff --git a/internal/modelcontext/mcp_test.go b/internal/modelcontext/mcp_test.go
index 1a327df20..dde3d7171 100644
--- a/internal/modelcontext/mcp_test.go
+++ b/internal/modelcontext/mcp_test.go
@@ -125,3 +125,73 @@ func TestMCPUnknownRoutingHandlesFailClosedOnlyAtTheEnvelope(t *testing.T) {
require.Equal(t, ArgumentResolutionUnresolved, calls[0].ArgumentResolution)
require.Equal(t, ArgumentResolutionUnresolved, calls[1].ArgumentResolution)
}
+
+func TestMCPStringArgumentsNormalizeOnlyOneCompleteObject(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ arguments any
+ normalized bool
+ }{
+ {"empty object", "{}", true},
+ {"whitespace", " \n { } \t", true},
+ {"nested business string", `{"query":"{\"id\":1}","items":[{"enabled":true}]}`, true},
+ {"already an object", map[string]any{"query": "{}"}, false},
+ {"null", nil, false},
+ {"encoded null", "null", false},
+ {"array", "[]", false},
+ {"scalar", "123", false},
+ {"empty string", "", false},
+ {"malformed", `{"id":`, false},
+ {"trailing content", `{} {}`, false},
+ {"another encoding layer", `"{}"`, false},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ r := NewRegistry(false)
+ raw, err := json.Marshal(map[string]any{"tool_ref": mcpTestRef, "arguments": tc.arguments})
+ require.NoError(t, err)
+ calls := []types.LLMToolCall{{Function: types.FunctionCall{Name: "call_mcp_tool", Arguments: string(raw)}}}
+ r.DecodeToolCalls(calls)
+ require.Equal(t, string(raw), calls[0].ModelArguments)
+ if tc.normalized {
+ require.Equal(t, ArgumentResolutionResolved, calls[0].ArgumentResolution)
+ var envelope map[string]json.RawMessage
+ require.NoError(t, json.Unmarshal([]byte(calls[0].Function.Arguments), &envelope))
+ require.JSONEq(t, tc.arguments.(string), string(envelope["arguments"]))
+ } else {
+ require.JSONEq(t, string(raw), calls[0].Function.Arguments)
+ require.Equal(t, ArgumentResolutionUnchanged, calls[0].ArgumentResolution)
+ }
+ first := calls[0]
+ r.DecodeToolCalls(calls)
+ require.Equal(t, first, calls[0], "stream completion may decode the same call again")
+ })
+ }
+}
+
+func TestMCPStringArgumentsDecodeResourcesAndKeepOtherToolsOpaque(t *testing.T) {
+ r := NewRegistry(false)
+ const resource = "resource://AbCdEfGhIjKlMnOpQrStUv"
+ require.Equal(t, "res://0001", r.CompactKnownText(resource))
+ r.ModelToolResultForTool("discover_mcp_tools", &types.ToolResult{
+ Success: true, Output: `{"tool_ref":"` + mcpTestRef + `"}`,
+ })
+ raw := `{"tool_ref":"mt1","arguments":"{\"file\":\"res://0001\",\"knowledge_id\":\"d1\"}"}`
+ calls := []types.LLMToolCall{{Function: types.FunctionCall{Name: "call_mcp_tool", Arguments: raw}}}
+ r.DecodeToolCalls(calls)
+ require.JSONEq(t, `{"tool_ref":"`+mcpTestRef+`","arguments":{"file":"`+resource+`","knowledge_id":"d1"}}`,
+ calls[0].Function.Arguments)
+ require.Equal(t, raw, calls[0].ModelArguments)
+ require.Empty(t, calls[0].UnresolvedHandles)
+ for _, name := range []string{"mcp_external_tool", "discover_mcp_tools", "read_file"} {
+ original := `{"arguments":"{\"id\":1}"}`
+ calls := []types.LLMToolCall{{Function: types.FunctionCall{Name: name, Arguments: original}}}
+ r.DecodeToolCalls(calls)
+ require.JSONEq(t, original, calls[0].Function.Arguments)
+ }
+ unknown := []types.LLMToolCall{{Function: types.FunctionCall{
+ Name: "call_mcp_tool", Arguments: `{"tool_ref":"mt1","arguments":"{\"file\":\"res://9999\"}"}`,
+ }}}
+ r.DecodeToolCalls(unknown)
+ require.Equal(t, []string{"res://9999"}, unknown[0].UnresolvedHandles)
+ require.Equal(t, ArgumentResolutionPartiallyResolved, unknown[0].ArgumentResolution)
+}
diff --git a/internal/modelcontext/registry.go b/internal/modelcontext/registry.go
index 9feea7c97..744dd07e1 100644
--- a/internal/modelcontext/registry.go
+++ b/internal/modelcontext/registry.go
@@ -111,6 +111,7 @@ func (r *Registry) DecodeToolCalls(toolCalls []types.LLMToolCall) {
}
}
normalizeWebFetchItems(toolCalls)
+ normalizeMCPCallArguments(toolCalls)
r.resources.DecodeToolCalls(toolCalls)
r.sources.DecodeToolCallsWithPolicy(toolCalls, sourceArgumentAllowed)
for i := range toolCalls {