Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(agent/tool): translate MCP tool inputSchema.properties in Info() (#19244)

mkaaadc51f44bab3ff
diff --git a/internal/agent/tool/mcp.go b/internal/agent/tool/mcp.go
index f7deabc820..424b53e044 100644
--- a/internal/agent/tool/mcp.go
+++ b/internal/agent/tool/mcp.go
@@ -34,6 +34,7 @@ import (
"github.com/cloudwego/eino/components/tool"
"github.com/cloudwego/eino/schema"
+ "github.com/eino-contrib/jsonschema"
)
// MCPToolAdapter wraps a single MCP-discovered tool descriptor as an
@@ -93,26 +94,33 @@ func NewMCPToolAdapterFull(t mcpclient.Tool, serverURL string, headers map[strin
// Name returns the underlying MCP tool name.
func (m *MCPToolAdapter) Name() string { return m.mcpTool.Name }
-// Info returns eino-compatible tool metadata. InputSchema is
-// translated from the MCP tool's JSON Schema.
+// Info returns eino-compatible tool metadata. The MCP client stores the
+// full inputSchema object ({"type":"object","properties":{...},"required":
+// [...]}) on mcpTool.InputSchema, so we pass it through to eino's
+// JSON Schema channel untouched. That keeps the real parameter names under
+// "properties" (never the schema's top-level keys like "type"/"properties"/
+// "required") together with each property's type/description/required flag
+// and any richer keywords (enum, default, items, nested objects, anyOf/oneOf,
+// ...). A tool with no inputSchema takes no parameters: ParamsOneOf is left
+// nil so callers emit an empty object schema instead of an invalid schema.
func (m *MCPToolAdapter) Info(_ context.Context) (*schema.ToolInfo, error) {
- // eino's schema.ParameterInfo shape: name → description.
- // We translate the MCP tool's inputSchema.properties into a
- // best-effort ParameterInfo map. For tools without a JSON schema
- // the params map is empty — eino falls back to free-form args.
- params := make(map[string]*schema.ParameterInfo, len(m.mcpTool.InputSchema))
- for name := range m.mcpTool.InputSchema {
- params[name] = &schema.ParameterInfo{
- Type: schema.String, // conservative default
- Desc: fmt.Sprintf("MCP tool parameter: %s", name),
- Required: false, // MCP doesn't surface required; we err permissive
- }
+ info := &schema.ToolInfo{
+ Name: m.mcpTool.Name,
+ Desc: m.mcpTool.Description,
}
- return &schema.ToolInfo{
- Name: m.mcpTool.Name,
- Desc: m.mcpTool.Description,
- ParamsOneOf: schema.NewParamsOneOfByParams(params),
- }, nil
+ if len(m.mcpTool.InputSchema) == 0 {
+ return info, nil
+ }
+ var js jsonschema.Schema
+ raw, err := json.Marshal(m.mcpTool.InputSchema)
+ if err != nil {
+ return nil, fmt.Errorf("encode MCP tool %q inputSchema: %w", m.mcpTool.Name, err)
+ }
+ if err := json.Unmarshal(raw, &js); err != nil {
+ return nil, fmt.Errorf("parse MCP tool %q inputSchema: %w", m.mcpTool.Name, err)
+ }
+ info.ParamsOneOf = schema.NewParamsOneOfByJSONSchema(&js)
+ return info, nil
}
// InvokableRun is the eino entry point. When the adapter was
diff --git a/internal/agent/tool/mcp_test.go b/internal/agent/tool/mcp_test.go
index 871813bf90..a67188a161 100644
--- a/internal/agent/tool/mcp_test.go
+++ b/internal/agent/tool/mcp_test.go
@@ -21,6 +21,7 @@ import (
"io"
"net/http"
"net/http/httptest"
+ "slices"
"strings"
"testing"
"time"
@@ -30,13 +31,27 @@ import (
// TestMCPToolAdapter_InfoReturnsMCPDescriptor: the eino ToolInfo
// surface matches the underlying MCP tool's name, description, and
-// input schema.
+// input schema. The input schema is fed in the real wire shape the
+// MCP client produces (full JSON Schema object) so the advertised
+// parameters come from "properties" — never the schema's top-level
+// keys ("type"/"properties"/"required").
func TestMCPToolAdapter_InfoReturnsMCPDescriptor(t *testing.T) {
mcp := mcpclient.Tool{
Name: "search_docs",
Description: "search internal docs",
InputSchema: map[string]any{
- "query": map[string]any{"type": "string"},
+ "type": "object",
+ "properties": map[string]any{
+ "query": map[string]any{
+ "type": "string",
+ "description": "the search query",
+ },
+ "limit": map[string]any{
+ "type": "integer",
+ "description": "max results",
+ },
+ },
+ "required": []any{"query"},
},
}
a := NewMCPToolAdapter(mcp)
@@ -54,7 +69,187 @@ func TestMCPToolAdapter_InfoReturnsMCPDescriptor(t *testing.T) {
t.Errorf("ToolInfo.Desc=%q, want 'search internal docs'", info.Desc)
}
if info.ParamsOneOf == nil {
- t.Error("expected non-nil ParamsOneOf")
+ t.Fatal("expected non-nil ParamsOneOf")
+ }
+ js, err := info.ParamsOneOf.ToJSONSchema()
+ if err != nil {
+ t.Fatalf("ToJSONSchema: %v", err)
+ }
+ if js.Type != "object" {
+ t.Errorf("schema type=%q, want object", js.Type)
+ }
+ if js.Properties == nil {
+ t.Fatal("expected non-nil properties")
+ }
+ if js.Properties.Len() != 2 {
+ t.Fatalf("expected 2 params, got %d", js.Properties.Len())
+ }
+ for _, leaked := range []string{"type", "properties", "required"} {
+ if _, ok := js.Properties.Get(leaked); ok {
+ t.Errorf("schema top-level key %q leaked into advertised params", leaked)
+ }
+ }
+
+ query, ok := js.Properties.Get("query")
+ if !ok {
+ t.Fatal("expected advertised param 'query'")
+ }
+ if query.Type != "string" {
+ t.Errorf("query.Type=%q, want string", query.Type)
+ }
+ if query.Description != "the search query" {
+ t.Errorf("query.Description=%q, want 'the search query'", query.Description)
+ }
+ if !slices.Contains(js.Required, "query") {
+ t.Errorf("query should be required per inputSchema.required; required=%v", js.Required)
+ }
+
+ limit, ok := js.Properties.Get("limit")
+ if !ok {
+ t.Fatal("expected advertised param 'limit'")
+ }
+ if limit.Type != "integer" {
+ t.Errorf("limit.Type=%q, want integer", limit.Type)
+ }
+ if slices.Contains(js.Required, "limit") {
+ t.Errorf("limit should not be required; required=%v", js.Required)
+ }
+}
+
+// TestMCPToolAdapter_InfoWithoutPropertiesFallsBackToFreeForm: a tool
+// whose schema has no "properties" map advertises no params (eino falls
+// back to free-form args) and does not leak schema top-level keys.
+func TestMCPToolAdapter_InfoWithoutPropertiesFallsBackToFreeForm(t *testing.T) {
+ mcp := mcpclient.Tool{
+ Name: "no_schema",
+ Description: "tool without property definitions",
+ InputSchema: map[string]any{"type": "object"},
+ }
+ a := NewMCPToolAdapter(mcp)
+ info, err := a.Info(t.Context())
+ if err != nil {
+ t.Fatalf("Info: %v", err)
+ }
+ if info.ParamsOneOf == nil {
+ t.Fatal("expected non-nil ParamsOneOf")
+ }
+ js, err := info.ParamsOneOf.ToJSONSchema()
+ if err != nil {
+ t.Fatalf("ToJSONSchema: %v", err)
+ }
+ if js.Properties != nil && js.Properties.Len() != 0 {
+ t.Errorf("expected no advertised params, got %d", js.Properties.Len())
+ }
+}
+
+// TestMCPToolAdapter_InfoWithoutInputSchema: an MCP tool with a missing or
+// empty inputSchema takes no parameters. ParamsOneOf must stay nil — a
+// non-nil empty jsonschema.Schema would serialize to `true`, which OpenAI
+// tool calls would read as `"parameters": true` and reject.
+func TestMCPToolAdapter_InfoWithoutInputSchema(t *testing.T) {
+ for name, inputSchema := range map[string]map[string]any{
+ "missing": nil,
+ "empty": {},
+ } {
+ t.Run(name, func(t *testing.T) {
+ a := NewMCPToolAdapter(mcpclient.Tool{Name: "no_params", InputSchema: inputSchema})
+ info, err := a.Info(t.Context())
+ if err != nil {
+ t.Fatalf("Info: %v", err)
+ }
+ if info.ParamsOneOf != nil {
+ t.Fatalf("expected nil ParamsOneOf for %s inputSchema, got non-nil", name)
+ }
+ raw, err := json.Marshal(info)
+ if err != nil {
+ t.Fatalf("Marshal ToolInfo: %v", err)
+ }
+ var got map[string]any
+ if err := json.Unmarshal(raw, &got); err != nil {
+ t.Fatalf("Unmarshal ToolInfo %s: %v", raw, err)
+ }
+ for _, leaked := range []string{"has_params_one_of", "json_schema"} {
+ if _, ok := got[leaked]; ok {
+ t.Fatalf("empty inputSchema must not advertise a parameters schema (key %q); got %s", leaked, raw)
+ }
+ }
+ })
+ }
+}
+
+// TestMCPToolAdapter_InfoPreservesRichJSONSchema: richer JSON Schema
+// keywords (enum, default, array items, nested objects) survive the
+// round-trip through eino's JSON Schema channel — the flat params form
+// would have dropped them.
+func TestMCPToolAdapter_InfoPreservesRichJSONSchema(t *testing.T) {
+ mcp := mcpclient.Tool{
+ Name: "rich",
+ Description: "tool with a rich input schema",
+ InputSchema: map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "mode": map[string]any{
+ "type": "string",
+ "enum": []any{"fast", "slow"},
+ "default": "fast",
+ },
+ "tags": map[string]any{
+ "type": "array",
+ "items": map[string]any{"type": "string"},
+ },
+ "filter": map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "year": map[string]any{"type": "integer"},
+ },
+ },
+ },
+ },
+ }
+ a := NewMCPToolAdapter(mcp)
+ info, err := a.Info(t.Context())
+ if err != nil {
+ t.Fatalf("Info: %v", err)
+ }
+ js, err := info.ParamsOneOf.ToJSONSchema()
+ if err != nil {
+ t.Fatalf("ToJSONSchema: %v", err)
+ }
+
+ mode, ok := js.Properties.Get("mode")
+ if !ok {
+ t.Fatal("expected param 'mode'")
+ }
+ if len(mode.Enum) != 2 || mode.Enum[0] != "fast" || mode.Enum[1] != "slow" {
+ t.Errorf("mode.Enum=%v, want [fast slow]", mode.Enum)
+ }
+ if mode.Default != "fast" {
+ t.Errorf("mode.Default=%v, want 'fast'", mode.Default)
+ }
+
+ tags, ok := js.Properties.Get("tags")
+ if !ok {
+ t.Fatal("expected param 'tags'")
+ }
+ if tags.Type != "array" {
+ t.Errorf("tags.Type=%q, want array", tags.Type)
+ }
+ if tags.Items == nil || tags.Items.Type != "string" {
+ t.Errorf("tags.Items=%+v, want element type string", tags.Items)
+ }
+
+ filter, ok := js.Properties.Get("filter")
+ if !ok {
+ t.Fatal("expected param 'filter'")
+ }
+ if filter.Type != "object" {
+ t.Errorf("filter.Type=%q, want object", filter.Type)
+ }
+ if filter.Properties == nil || filter.Properties.Len() != 1 {
+ t.Fatalf("filter.Properties.Len()=%d, want 1", filter.Properties.Len())
+ }
+ if _, ok := filter.Properties.Get("year"); !ok {
+ t.Error("expected nested param 'year'")
}
}