RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
refactor(mcp): move MCP client out of utility into internal/mcp/client (#21150)
xugangqiang838cbf451d5a
diff --git a/internal/agent/component/agent_mcp.go b/internal/agent/component/agent_mcp.goindex 633d781178..d05aad18ca 100644--- a/internal/agent/component/agent_mcp.go+++ b/internal/agent/component/agent_mcp.go@@ -14,8 +14,9 @@ import ("ragflow/internal/agent/runtime"agenttool "ragflow/internal/agent/tool""ragflow/internal/dao"+ mcpclient "ragflow/internal/mcp/client""ragflow/internal/permission"- "ragflow/internal/utility"+ servercfg "ragflow/internal/server")// buildAgentMCPTools binds the saved tool selection to servers the canvas can use.@@ -25,8 +26,8 @@ func buildAgentMCPTools(ctx context.Context, db *gorm.DB, raw any, timeout time.return nil, nil}var selections []struct {- ID string `json:"mcp_id"`- Tools map[string]utility.Tool `json:"tools"`+ ID string `json:"mcp_id"`+ Tools map[string]mcpclient.Tool `json:"tools"`}data, err := json.Marshal(raw)if err != nil {@@ -82,11 +83,13 @@ func buildAgentMCPTools(ctx context.Context, db *gorm.DB, raw any, timeout time.for key, value := range server.Variables {variables[key] = fmt.Sprint(value)}+ allowPrivateHosts := servercfg.MCPAllowPrivateHosts()for _, name := range slices.Sorted(maps.Keys(selection.Tools)) {descriptor := selection.Tools[name]descriptor.Name = name- adapter := agenttool.NewMCPToolAdapterWithOptions(descriptor, utility.CallOptions{+ adapter := agenttool.NewMCPToolAdapterWithOptions(descriptor, mcpclient.CallOptions{URL: server.URL, ServerType: server.ServerType, Headers: headers, Variables: variables, Timeout: timeout,+ AllowPrivateHosts: allowPrivateHosts,})adapter.SetVisibleName(fmt.Sprintf("%s_%d", name, toolIndex))toolIndex++diff --git a/internal/agent/component/agent_mcp_test.go b/internal/agent/component/agent_mcp_test.goindex b0cea77fc3..2b03d3408b 100644--- a/internal/agent/component/agent_mcp_test.go+++ b/internal/agent/component/agent_mcp_test.go@@ -10,6 +10,7 @@ import ("ragflow/internal/common""ragflow/internal/entity""ragflow/internal/entity/models"+ mcpclient "ragflow/internal/mcp/client""ragflow/internal/utility""strings""sync/atomic"@@ -80,7 +81,7 @@ func TestAgentMCPModelDispatch(t *testing.T) {pinned := utility.PinnedHTTPClientutility.PinnedHTTPClient = func(string, string, time.Duration) *http.Client { return mcp.Client() }t.Cleanup(func() { utility.PinnedHTTPClient = pinned })- if err := db.Create(&entity.MCPServer{ID: "mcp", TenantID: "tenant", Name: "route server", URL: mcp.URL, ServerType: utility.TransportStreamableHTTP, Headers: entity.JSONMap{"Authorization": "Bearer ${authorization_token}"}, Variables: entity.JSONMap{"authorization_token": authToken}}).Error; err != nil {+ if err := db.Create(&entity.MCPServer{ID: "mcp", TenantID: "tenant", Name: "route server", URL: mcp.URL, ServerType: mcpclient.TransportStreamableHTTP, Headers: entity.JSONMap{"Authorization": "Bearer ${authorization_token}"}, Variables: entity.JSONMap{"authorization_token": authToken}}).Error; err != nil {t.Fatal(err)}addAgentMCPPermissionFixtures(t, db)@@ -177,7 +178,7 @@ func TestAgentMCPToolNamesDoNotCollide(t *testing.T) {}pushComponentDB(t, db)for _, id := range []string{"first", "second"} {- if err := db.Create(&entity.MCPServer{ID: id, TenantID: "tenant", Name: id, URL: "https://example.com/mcp", ServerType: utility.TransportStreamableHTTP}).Error; err != nil {+ if err := db.Create(&entity.MCPServer{ID: id, TenantID: "tenant", Name: id, URL: "https://example.com/mcp", ServerType: mcpclient.TransportStreamableHTTP}).Error; err != nil {t.Fatal(err)}}diff --git a/internal/agent/tool/mcp.go b/internal/agent/tool/mcp.goindex ebb62052a3..bf4370c040 100644--- a/internal/agent/tool/mcp.go+++ b/internal/agent/tool/mcp.go@@ -16,9 +16,10 @@// Package tool — MCP (Model Context Protocol) wrapper.//-// Wraps a single MCP-server-discovered tool (utility/mcpclient.Tool) as+// Wraps a single MCP-server-discovered tool (mcpclient.Tool) as// an eino BaseTool so it can be invoked from inside the Agent's-// ReAct loop. Discovery and invocation use the utility MCP client.+// ReAct loop. Discovery and invocation use the MCP client+// (ragflow/internal/mcp/client).package toolimport (@@ -28,7 +29,7 @@ import ("net/http""time"- mcpclient "ragflow/internal/utility"+ mcpclient "ragflow/internal/mcp/client""github.com/cloudwego/eino/components/tool""github.com/cloudwego/eino/schema"@@ -48,14 +49,15 @@ import (// a URL (legacy callers) fall back to the "not yet wired"// sentinel so existing call sites don't break.type MCPToolAdapter struct {- mcpTool mcpclient.Tool- visibleName string- serverType string- variables map[string]string- serverURL string- headers map[string]string- timeout time.Duration- httpClient *http.Client+ mcpTool mcpclient.Tool+ visibleName string+ serverType string+ variables map[string]string+ serverURL string+ headers map[string]string+ timeout time.Duration+ httpClient *http.Client+ allowPrivateHosts bool}// NewMCPToolAdapter constructs a wrapper for a single MCP tool.@@ -94,7 +96,7 @@ func NewMCPToolAdapterFull(t mcpclient.Tool, serverURL string, headers map[strin// NewMCPToolAdapterWithOptions preserves the server transport and header variables.func NewMCPToolAdapterWithOptions(t mcpclient.Tool, opts mcpclient.CallOptions) *MCPToolAdapter {- return &MCPToolAdapter{mcpTool: t, serverURL: opts.URL, serverType: opts.ServerType, headers: opts.Headers, variables: opts.Variables, timeout: opts.Timeout, httpClient: opts.HTTPClient}+ return &MCPToolAdapter{mcpTool: t, serverURL: opts.URL, serverType: opts.ServerType, headers: opts.Headers, variables: opts.Variables, timeout: opts.Timeout, httpClient: opts.HTTPClient, allowPrivateHosts: opts.AllowPrivateHosts}}// Name returns the underlying MCP tool name.@@ -148,14 +150,15 @@ func (m *MCPToolAdapter) InvokableRun(ctx context.Context, argumentsInJSON strinreturn "", mErr}res, err := mcpclient.CallTool(ctx, mcpclient.CallOptions{- URL: m.serverURL,- ServerType: m.serverType,- Variables: m.variables,- Headers: m.headers,- ToolName: m.mcpTool.Name,- Arguments: argsJSON,- Timeout: m.timeout,- HTTPClient: m.httpClient,+ URL: m.serverURL,+ ServerType: m.serverType,+ Variables: m.variables,+ Headers: m.headers,+ ToolName: m.mcpTool.Name,+ Arguments: argsJSON,+ Timeout: m.timeout,+ HTTPClient: m.httpClient,+ AllowPrivateHosts: m.allowPrivateHosts,})if err != nil {return "", errdiff --git a/internal/agent/tool/mcp_test.go b/internal/agent/tool/mcp_test.goindex 4c7e04b7e0..c1da943f0b 100644--- a/internal/agent/tool/mcp_test.go+++ b/internal/agent/tool/mcp_test.go@@ -27,7 +27,7 @@ import ("testing""time"- mcpclient "ragflow/internal/utility"+ mcpclient "ragflow/internal/mcp/client")// TestMCPToolAdapter_InfoReturnsMCPDescriptor: the eino ToolInfo@@ -430,7 +430,7 @@ func TestMCPToolAdapter_InvokableRunIsError(t *testing.T) {// mcpLoopbackOverride swaps the SSRF guard's resolver for the// duration of the test so httptest's 127.0.0.1 server is// accepted. The pattern mirrors the one used by-// utility/mcp_client_test.go's allowLoopbackForTests helper.+// internal/mcp/client/mcp_client_test.go's allowLoopbackForTests helper.func mcpLoopbackOverride(t *testing.T) func() {t.Helper()orig := common.LookupHostdiff --git a/internal/utility/mcp_call.go b/internal/mcp/client/mcp_call.gosimilarity index 92%rename from internal/utility/mcp_call.gorename to internal/mcp/client/mcp_call.goindex bbe9f9cb2a..2ed234ad34 100644--- a/internal/utility/mcp_call.go+++ b/internal/mcp/client/mcp_call.go@@ -14,7 +14,7 @@// limitations under the License.//-package utility+package mcpclientimport ("context"@@ -22,6 +22,7 @@ import ("errors""fmt""net/http"+ "ragflow/internal/utility""time")@@ -38,6 +39,11 @@ type CallOptions struct {Arguments json.RawMessage // JSON-encoded argument objectTimeout time.DurationHTTPClient *http.Client+ // AllowPrivateHosts relaxes the public-routability requirement so+ // self-hosted MCP servers on private/docker networks work. Callers source+ // it from the deployment flag (RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS); scheme+ // validation, DNS resolution, and IP pinning still apply.+ AllowPrivateHosts bool}// CallResult is the parsed tools/call response. The MCP spec@@ -72,12 +78,12 @@ func CallTool(ctx context.Context, opts CallOptions) (*CallResult, error) {if opts.Timeout <= 0 {opts.Timeout = 10 * time.Second}- hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL)+ hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL, opts.AllowPrivateHosts)if err != nil {return nil, err}if opts.HTTPClient == nil {- opts.HTTPClient = PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)+ opts.HTTPClient = utility.PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)}headers, headerErr := renderHeaders(opts.Headers, opts.Variables)if headerErr != nil {@@ -95,7 +101,7 @@ func CallTool(ctx context.Context, opts CallOptions) (*CallResult, error) {case TransportSSE:result, err := requestSSE(connectCtx, opts.URL, headers, opts.HTTPClient, "tools/call", map[string]any{"name": opts.ToolName, "arguments": opts.Arguments,- })+ }, opts.AllowPrivateHosts)if err != nil {return nil, err}diff --git a/internal/utility/mcp_call_test.go b/internal/mcp/client/mcp_call_test.gosimilarity index 99%rename from internal/utility/mcp_call_test.gorename to internal/mcp/client/mcp_call_test.goindex e2e9049780..0c21046ae1 100644--- a/internal/utility/mcp_call_test.go+++ b/internal/mcp/client/mcp_call_test.go@@ -14,7 +14,7 @@// limitations under the License.//-package utility+package mcpclientimport ("context"diff --git a/internal/utility/mcp_client.go b/internal/mcp/client/mcp_client.gosimilarity index 95%rename from internal/utility/mcp_client.gorename to internal/mcp/client/mcp_client.goindex 91fe3ff577..ae59edb0be 100644--- a/internal/utility/mcp_client.go+++ b/internal/mcp/client/mcp_client.go@@ -14,7 +14,7 @@// limitations under the License.//-// Package utility mcp client is a minimal Model Context Protocol (MCP) client used by+// Package mcpclient is a minimal Model Context Protocol (MCP) client used by// the Go MCP-management endpoints to list a remote server's tools during// import and the "test" endpoint. It implements just enough of the spec to// negotiate a session and call tools/list:@@ -28,7 +28,7 @@//// The full Python implementation lives in common/mcp_tool_call_conn.py; this// is a reduced port focused on tools/list discovery.-package utility+package mcpclientimport ("bufio"@@ -40,6 +40,7 @@ import ("io""net/http""net/url"+ "ragflow/internal/utility""strings""sync""time"@@ -70,14 +71,19 @@ type Tool struct {// FetchOptions controls a single tools/list discovery call.type FetchOptions struct {- URL string- ServerType string- Headers map[string]string- Variables map[string]string- Timeout time.Duration- HTTPClient *http.Client- pinHostname string- pinIP string+ URL string+ ServerType string+ Headers map[string]string+ Variables map[string]string+ Timeout time.Duration+ HTTPClient *http.Client+ // AllowPrivateHosts relaxes the public-routability requirement so+ // self-hosted MCP servers on private/docker networks work. Callers source+ // it from the deployment flag (RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS); scheme+ // validation, DNS resolution, and IP pinning still apply.+ AllowPrivateHosts bool+ pinHostname string+ pinIP string}// FetchTools opens a connection to the MCP server described by opts and@@ -92,14 +98,14 @@ func FetchTools(ctx context.Context, opts FetchOptions) ([]Tool, error) {opts.Timeout = 10 * time.Second}- hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL)+ hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL, opts.AllowPrivateHosts)if err != nil {return nil, err}opts.pinHostname = hostnameopts.pinIP = resolvedIPif opts.HTTPClient == nil {- opts.HTTPClient = PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)+ opts.HTTPClient = utility.PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)}headers, headerErr := renderHeaders(opts.Headers, opts.Variables)@@ -114,7 +120,7 @@ func FetchTools(ctx context.Context, opts FetchOptions) ([]Tool, error) {case TransportStreamableHTTP:return fetchToolsStreamableHTTP(connectCtx, opts.URL, headers, opts.HTTPClient, opts.Timeout)case TransportSSE:- return fetchToolsSSE(connectCtx, opts.URL, headers, opts.HTTPClient)+ return fetchToolsSSE(connectCtx, opts.URL, headers, opts.HTTPClient, opts.AllowPrivateHosts)default:return nil, fmt.Errorf("unsupported MCP server type: %s", opts.ServerType)}@@ -304,7 +310,7 @@ func terminateStreamableSessionBestEffort(ctx context.Context, client *http.Cliereturn http.ErrUseLastResponse}- BestEffort("terminate MCP streamable HTTP session", func() error {+ utility.BestEffort("terminate MCP streamable HTTP session", func() error {req, err := http.NewRequestWithContext(cleanupCtx, http.MethodDelete, endpoint, nil)if err != nil {return fmt.Errorf("build MCP session termination request: %w", err)@@ -405,8 +411,8 @@ func streamableSend(ctx context.Context, client *http.Client, endpoint, sessionI// ---------- SSE transport -----------func fetchToolsSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client) ([]Tool, error) {- result, err := requestSSE(ctx, endpoint, headers, client, "tools/list", nil)+func fetchToolsSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client, allowPrivateHosts bool) ([]Tool, error) {+ result, err := requestSSE(ctx, endpoint, headers, client, "tools/list", nil, allowPrivateHosts)if err != nil {return nil, err}@@ -414,7 +420,7 @@ func fetchToolsSSE(ctx context.Context, endpoint string, headers map[string]stri}// requestSSE initializes a session and performs one JSON-RPC request.-func requestSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client, method string, params any) (json.RawMessage, error) {+func requestSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client, method string, params any, allowPrivateHosts bool) (json.RawMessage, error) {streamReq, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)if err != nil {return nil, fmt.Errorf("build SSE request: %w", err)@@ -455,11 +461,11 @@ func requestSSE(ctx context.Context, endpoint string, headers map[string]string,// Private targets are accepted only when they match the configured// SSE endpoint host, preventing unrelated internal redirection.postClient := client- if postHost, postIP, vErr := AssertMCPURLSafeSameOrigin(postURL, endpoint); vErr != nil {+ if postHost, postIP, vErr := AssertMCPURLSafeSameOrigin(postURL, endpoint, allowPrivateHosts); vErr != nil {return nil, vErr} else if u, perr := url.Parse(postURL); perr == nil && u.Hostname() != "" {- if u.Hostname() != originalHost(endpoint) {- postClient = PinnedHTTPClient(postHost, postIP, sseTimeoutFrom(ctx))+ if !strings.EqualFold(u.Hostname(), originalHost(endpoint)) {+ postClient = utility.PinnedHTTPClient(postHost, postIP, sseTimeoutFrom(ctx))}}diff --git a/internal/utility/mcp_client_test.go b/internal/mcp/client/mcp_client_test.gosimilarity index 99%rename from internal/utility/mcp_client_test.gorename to internal/mcp/client/mcp_client_test.goindex d24f5d3571..c93ee16cfc 100644--- a/internal/utility/mcp_client_test.go+++ b/internal/mcp/client/mcp_client_test.go@@ -14,7 +14,7 @@// limitations under the License.//-package utility+package mcpclientimport ("encoding/json"diff --git a/internal/utility/mcp_ssrf.go b/internal/mcp/client/mcp_ssrf.gosimilarity index 55%rename from internal/utility/mcp_ssrf.gorename to internal/mcp/client/mcp_ssrf.goindex fa227f492a..2cc63ee8c2 100644--- a/internal/utility/mcp_ssrf.go+++ b/internal/mcp/client/mcp_ssrf.go@@ -14,19 +14,45 @@// limitations under the License.//-package utility+package mcpclientimport ("net/url""ragflow/internal/common"- "ragflow/internal/server""strings")+// effectivePort returns the explicit port, or the scheme's default port when+// omitted, so http://h and http://h:80 are treated as the same origin.+func effectivePort(u *url.URL) string {+ if p := u.Port(); p != "" {+ return p+ }+ switch strings.ToLower(u.Scheme) {+ case "http":+ return "80"+ case "https":+ return "443"+ }+ return ""+}++// sameOrigin reports whether two URLs share scheme, port, and host. DNS+// hostnames are case-insensitive, so the hostname is compared with+// strings.EqualFold; scheme is already lowercased by url.Parse and compared+// case-insensitively for safety; port is normalized so the default-port form+// (http://h) and the explicit form (http://h:80) match.+func sameOrigin(a, b *url.URL) bool {+ return strings.EqualFold(a.Scheme, b.Scheme) &&+ effectivePort(a) == effectivePort(b) &&+ strings.EqualFold(a.Hostname(), b.Hostname())+}+// AssertMCPURLSafe validates an MCP server URL. It delegates to-// common.AssertURLSafe by default. When the deployment sets-// RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS=true (a deployment-level operator decision),-// the public-routability requirement is relaxed so self-hosted MCP servers on+// common.AssertURLSafe by default. When allowPrivateHosts is true (a+// deployment-level operator decision, sourced from+// RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS at the call site), the+// public-routability requirement is relaxed so self-hosted MCP servers on// private/docker networks work — scheme validation, DNS resolution, and// connection pinning to the resolved IP still apply.//@@ -34,10 +60,9 @@ import (// direct tool calls). For URLs advertised by an SSE endpoint event, use// AssertMCPURLSafeSameOrigin so a malicious server cannot redirect POSTs to an// unrelated internal host.-func AssertMCPURLSafe(rawURL string) (hostname, resolvedIP string, err error) {- globalConfig := server.GetConfig()+func AssertMCPURLSafe(rawURL string, allowPrivateHosts bool) (hostname, resolvedIP string, err error) {hostname, resolvedIP, err = common.AssertURLSafe(rawURL)- if err == nil || !globalConfig.GetMCPAllowPrivateHosts() {+ if err == nil || !allowPrivateHosts {return hostname, resolvedIP, err}strictErr := err@@ -58,16 +83,15 @@ func AssertMCPURLSafe(rawURL string) (hostname, resolvedIP string, err error) {// AssertMCPURLSafeSameOrigin validates a server-advertised URL (e.g., the POST// URL from an SSE endpoint event). Public URLs are accepted. Private URLs are-// accepted only when RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS is enabled AND the-// advertised host matches originURL's host, so the server cannot bounce POSTs-// to an unrelated internal target.-func AssertMCPURLSafeSameOrigin(rawURL, originURL string) (hostname, resolvedIP string, err error) {+// accepted only when allowPrivateHosts is true AND the advertised URL shares the+// same origin (scheme, port, and host) as originURL, so the server cannot bounce+// POSTs to another service on the same host but a different port or scheme.+func AssertMCPURLSafeSameOrigin(rawURL, originURL string, allowPrivateHosts bool) (hostname, resolvedIP string, err error) {hostname, resolvedIP, err = common.AssertURLSafe(rawURL)if err == nil {return hostname, resolvedIP, nil}- globalConfig := server.GetConfig()- if !globalConfig.GetMCPAllowPrivateHosts() {+ if !allowPrivateHosts {return "", "", err}origin, perr := url.Parse(strings.TrimSpace(originURL))@@ -78,8 +102,8 @@ func AssertMCPURLSafeSameOrigin(rawURL, originURL string) (hostname, resolvedIPif perr != nil {return "", "", err}- if parsed.Hostname() != origin.Hostname() {+ if !sameOrigin(parsed, origin) {return "", "", err}- return AssertMCPURLSafe(rawURL)+ return AssertMCPURLSafe(rawURL, allowPrivateHosts)}diff --git a/internal/mcp/client/mcp_ssrf_test.go b/internal/mcp/client/mcp_ssrf_test.gonew file mode 100644index 0000000000..8b5a1bdaf8--- /dev/null+++ b/internal/mcp/client/mcp_ssrf_test.go@@ -0,0 +1,160 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package mcpclient++import (+ "ragflow/internal/common"+ "testing"+)++// stubLookupHost pins DNS resolution for the duration of a test without+// touching the server config singleton — the allowPrivateHosts decision is+// now an explicit parameter instead of a global read.+func stubLookupHost(t *testing.T, ips []string) {+ t.Helper()+ original := common.LookupHost+ common.LookupHost = func(string) ([]string, error) { return ips, nil }+ t.Cleanup(func() { common.LookupHost = original })+}++func TestAssertMCPURLSafePrivateHostAllowed(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})++ host, ip, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp", true)+ if err != nil {+ t.Fatalf("expected allowed private MCP host to pass, got %v", err)+ }+ if host != "navigo-mcp" || ip != "172.18.0.5" {+ t.Fatalf("expected pinning to resolved IP, got host=%q ip=%q", host, ip)+ }+}++func TestAssertMCPURLSafeRejectsPrivateHostWhenDisabled(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})++ if _, _, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp", false); err == nil {+ t.Fatal("expected private host to be rejected when allowPrivateHosts is false")+ }+}++func TestAssertMCPURLSafePublicHostUnaffected(t *testing.T) {+ stubLookupHost(t, []string{"93.184.216.34"})++ host, ip, err := AssertMCPURLSafe("https://mcp.example.com/mcp", false)+ if err != nil {+ t.Fatalf("expected public MCP host to pass, got %v", err)+ }+ if host != "mcp.example.com" || ip != "93.184.216.34" {+ t.Fatalf("unexpected host/ip: %q %q", host, ip)+ }+}++func TestAssertMCPURLSafeSameOriginAllowsPrivateAdvertisedURL(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})++ host, ip, err := AssertMCPURLSafeSameOrigin("http://navigo-mcp:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse", true)+ if err != nil {+ t.Fatalf("expected same-origin private advertised URL to pass, got %v", err)+ }+ if host != "navigo-mcp" || ip != "172.18.0.5" {+ t.Fatalf("unexpected host/ip: %q %q", host, ip)+ }+}++func TestAssertMCPURLSafeSameOriginRejectsCrossOriginPrivateAdvertisedURL(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.6"})++ if _, _, err := AssertMCPURLSafeSameOrigin("http://other-internal:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse", true); err == nil {+ t.Fatal("expected cross-origin private advertised URL to be rejected")+ }+}++// ---- corner cases for the parameterized guards ----++func TestAssertMCPURLSafeEmptyURL(t *testing.T) {+ stubLookupHost(t, []string{"8.8.8.8"})+ if _, _, err := AssertMCPURLSafe("", true); err == nil {+ t.Fatal("expected empty URL to be rejected")+ }+}++func TestAssertMCPURLSafeMalformedURL(t *testing.T) {+ stubLookupHost(t, []string{"8.8.8.8"})+ // Unparseable / scheme-less input must error, never panic.+ if _, _, err := AssertMCPURLSafe("://nonsense", true); err == nil {+ t.Fatal("expected malformed URL to be rejected")+ }+}++func TestAssertMCPURLSafeUnsupportedSchemeRejectedEvenWhenPrivateAllowed(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})+ // allowPrivateHosts relaxes routability, NOT the scheme check; a non+ // http(s) scheme must still be rejected via the strict path.+ if _, _, err := AssertMCPURLSafe("ftp://navigo-mcp:8765/mcp", true); err == nil {+ t.Fatal("expected unsupported scheme to be rejected even with allowPrivateHosts")+ }+}++func TestAssertMCPURLSafeSameOriginRejectsPrivateWhenDisabled(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})+ // Same-origin relaxation is gated on allowPrivateHosts; when false a+ // private advertised URL must be rejected even on the same origin.+ if _, _, err := AssertMCPURLSafeSameOrigin("http://navigo-mcp:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse", false); err == nil {+ t.Fatal("expected same-origin private advertised URL to be rejected when disabled")+ }+}++func TestAssertMCPURLSafePrivateHostWithEmptyLookupRejected(t *testing.T) {+ stubLookupHost(t, nil) // resolver returns no addresses+ if _, _, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp", true); err == nil {+ t.Fatal("expected empty DNS resolution to be rejected")+ }+}++// Same host, different port must be rejected: an SSE server must not be able to+// bounce an admitted POST to another service listening on the same host but a+// different port.+func TestAssertMCPURLSafeSameOriginRejectsDifferentPort(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})+ if _, _, err := AssertMCPURLSafeSameOrigin(+ "http://navigo-mcp:9000/mcp/messages",+ "http://navigo-mcp:8080/mcp/sse", true); err == nil {+ t.Fatal("expected same-host-different-port advertised URL to be rejected")+ }+}++// Same host and port, different scheme must be rejected: http vs https is a+// different origin and must not be accepted as same-origin.+func TestAssertMCPURLSafeSameOriginRejectsDifferentScheme(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})+ if _, _, err := AssertMCPURLSafeSameOrigin(+ "https://navigo-mcp:8765/mcp/messages",+ "http://navigo-mcp:8765/mcp/sse", true); err == nil {+ t.Fatal("expected same-host-different-scheme advertised URL to be rejected")+ }+}++// DNS hostnames are case-insensitive, so a server-advertised URL on the same+// host spelled with a different case must still be accepted as same-origin.+func TestAssertMCPURLSafeSameOriginAcceptsMixedCaseHost(t *testing.T) {+ stubLookupHost(t, []string{"172.18.0.5"})+ if _, _, err := AssertMCPURLSafeSameOrigin(+ "http://Example.COM:8765/mcp/messages",+ "http://example.com:8765/mcp/sse", true); err != nil {+ t.Fatalf("expected mixed-case same-host advertised URL to be accepted, got %v", err)+ }+}diff --git a/internal/server/config.go b/internal/server/config.goindex be68b1a5d6..149d7b7e07 100644--- a/internal/server/config.go+++ b/internal/server/config.go@@ -169,6 +169,17 @@ func GetConfig() *config.Config {return globalConfig}+// MCPAllowPrivateHosts reports whether self-hosted MCP servers on private+// networks are permitted (RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS). It is nil-safe:+// an uninitialized global config yields false so callers fail closed instead+// of panicking on a nil *config.Config.+func MCPAllowPrivateHosts() bool {+ if globalConfig == nil {+ return false+ }+ return globalConfig.GetMCPAllowPrivateHosts()+}+// GetAllConfigs collects backend connection settings for administrator inspection.// ExportConfigs intentionally retains plaintext credentials; the admin configuration// endpoint restricts access to superusers, while PrintAll masks credentials in logs.diff --git a/internal/server/mcp_allow_private_hosts_test.go b/internal/server/mcp_allow_private_hosts_test.gonew file mode 100644index 0000000000..cfd5cdd335--- /dev/null+++ b/internal/server/mcp_allow_private_hosts_test.go@@ -0,0 +1,33 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package server++import "testing"++// TestMCPAllowPrivateHostsNilConfigFailsClosed guards the nil-safe accessor:+// when the global config has not been initialized (e.g. unit tests that never+// call Init), reading the MCP private-hosts flag must fail closed (false)+// instead of panicking on a nil *config.Config.+func TestMCPAllowPrivateHostsNilConfigFailsClosed(t *testing.T) {+ orig := globalConfig+ globalConfig = nil+ t.Cleanup(func() { globalConfig = orig })++ if MCPAllowPrivateHosts() {+ t.Fatal("expected nil global config to fail closed (false)")+ }+}diff --git a/internal/service/mcp.go b/internal/service/mcp.goindex 9d6ce8b905..4fd8bcab41 100644--- a/internal/service/mcp.go+++ b/internal/service/mcp.go@@ -30,9 +30,10 @@ import ("ragflow/internal/common""ragflow/internal/dao""ragflow/internal/entity"+ mcpclient "ragflow/internal/mcp/client""ragflow/internal/permission"permissionresponse "ragflow/internal/permission/response"- "ragflow/internal/utility"+ "ragflow/internal/server")const (@@ -198,12 +199,13 @@ func fetchMCPTools(ctx context.Context, url, serverType string, headers, variabl}timeout := time.Duration(timeoutSeconds * float64(time.Second))- tools, err := utility.FetchTools(ctx, utility.FetchOptions{- URL: url,- ServerType: serverType,- Headers: jsonMapHeaderValues(headers),- Variables: jsonMapStringValues(variables),- Timeout: timeout,+ tools, err := mcpclient.FetchTools(ctx, mcpclient.FetchOptions{+ URL: url,+ ServerType: serverType,+ Headers: jsonMapHeaderValues(headers),+ Variables: jsonMapStringValues(variables),+ Timeout: timeout,+ AllowPrivateHosts: server.MCPAllowPrivateHosts(),})if err != nil {return nil, err@@ -760,12 +762,13 @@ func (s *MCPService) ImportServers(ctx context.Context, userID string, servers mstringVars := jsonMapStringValues(entity.JSONMap(variables))mcpCtx, cancel := context.WithTimeout(ctx, timeout)- tools, fetchErr := utility.FetchTools(mcpCtx, utility.FetchOptions{- URL: url,- ServerType: stype,- Headers: headers,- Variables: stringVars,- Timeout: timeout,+ tools, fetchErr := mcpclient.FetchTools(mcpCtx, mcpclient.FetchOptions{+ URL: url,+ ServerType: stype,+ Headers: headers,+ Variables: stringVars,+ Timeout: timeout,+ AllowPrivateHosts: server.MCPAllowPrivateHosts(),})cancel()if fetchErr != nil {@@ -853,7 +856,7 @@ func (s *MCPService) TestServer(ctx context.Context, userID, mcpID string, req *// ErrMCPInvalidURL data errors instead of being swallowed inside the// generic FetchTools error and re-classified by the handler as a 500.// FetchTools repeats the check internally; the second call is cheap.- if _, _, err := utility.AssertMCPURLSafe(req.URL); err != nil {+ if _, _, err := mcpclient.AssertMCPURLSafe(req.URL, server.MCPAllowPrivateHosts()); err != nil {return nil, fmt.Errorf("%w: %w", ErrMCPInvalidURL, err)}@@ -873,12 +876,13 @@ func (s *MCPService) TestServer(ctx context.Context, userID, mcpID string, req *mcpCtx, cancel := context.WithTimeout(ctx, timeout)defer cancel()- tools, err := utility.FetchTools(mcpCtx, utility.FetchOptions{- URL: req.URL,- ServerType: req.ServerType,- Headers: headers,- Variables: vars,- Timeout: timeout,+ tools, err := mcpclient.FetchTools(mcpCtx, mcpclient.FetchOptions{+ URL: req.URL,+ ServerType: req.ServerType,+ Headers: headers,+ Variables: vars,+ Timeout: timeout,+ AllowPrivateHosts: server.MCPAllowPrivateHosts(),})if err != nil {return nil, fmt.Errorf("%w: Test MCP error (id=%s): %w", ErrMCPTestFailed, mcpID, err)@@ -902,7 +906,7 @@ func (s *MCPService) TestServer(ctx context.Context, userID, mcpID string, req *return out, nil}-func toolsAsMap(tools []utility.Tool) map[string]interface{} {+func toolsAsMap(tools []mcpclient.Tool) map[string]interface{} {m := map[string]interface{}{}for _, t := range tools {if t.Raw != nil {diff --git a/internal/utility/mcp_ssrf_test.go b/internal/utility/mcp_ssrf_test.godeleted file mode 100644index a8d92511f3..0000000000--- a/internal/utility/mcp_ssrf_test.go+++ /dev/null@@ -1,90 +0,0 @@-//-// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.-//-// Licensed under the Apache License, Version 2.0 (the "License");-// you may not use this file except in compliance with the License.-// You may obtain a copy of the License at-//-// http://www.apache.org/licenses/LICENSE-2.0-//-// Unless required by applicable law or agreed to in writing, software-// distributed under the License is distributed on an "AS IS" BASIS,-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.-// See the License for the specific language governing permissions and-// limitations under the License.-//--package utility--import (- "ragflow/internal/common"- "ragflow/internal/server"- "testing"-)--func stubLookupHost(t *testing.T, ips []string) {- t.Helper()- original := common.LookupHost- common.LookupHost = func(string) ([]string, error) { return ips, nil }- t.Cleanup(func() { common.LookupHost = original })- err := server.Init("")- if err != nil {- t.Fatalf("failed to init server: %v", err)- }-}--func TestAssertMCPURLSafePrivateHostAllowed(t *testing.T) {- t.Setenv(common.EnvMCPAllowPrivateHosts, "true")- stubLookupHost(t, []string{"172.18.0.5"})-- host, ip, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp")- if err != nil {- t.Fatalf("expected allowed private MCP host to pass, got %v", err)- }- if host != "navigo-mcp" || ip != "172.18.0.5" {- t.Fatalf("expected pinning to resolved IP, got host=%q ip=%q", host, ip)- }-}--func TestAssertMCPURLSafeRejectsPrivateHostWhenDisabled(t *testing.T) {- t.Setenv(common.EnvMCPAllowPrivateHosts, "")- stubLookupHost(t, []string{"172.18.0.5"})-- if _, _, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp"); err == nil {- t.Fatal("expected private host to be rejected when disabled")- }-}--func TestAssertMCPURLSafePublicHostUnaffected(t *testing.T) {- stubLookupHost(t, []string{"93.184.216.34"})-- host, ip, err := AssertMCPURLSafe("https://mcp.example.com/mcp")- if err != nil {- t.Fatalf("expected public MCP host to pass, got %v", err)- }- if host != "mcp.example.com" || ip != "93.184.216.34" {- t.Fatalf("unexpected host/ip: %q %q", host, ip)- }-}--func TestAssertMCPURLSafeSameOriginAllowsPrivateAdvertisedURL(t *testing.T) {- t.Setenv(common.EnvMCPAllowPrivateHosts, "true")- stubLookupHost(t, []string{"172.18.0.5"})-- host, ip, err := AssertMCPURLSafeSameOrigin("http://navigo-mcp:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse")- if err != nil {- t.Fatalf("expected same-origin private advertised URL to pass, got %v", err)- }- if host != "navigo-mcp" || ip != "172.18.0.5" {- t.Fatalf("unexpected host/ip: %q %q", host, ip)- }-}--func TestAssertMCPURLSafeSameOriginRejectsCrossOriginPrivateAdvertisedURL(t *testing.T) {- t.Setenv(common.EnvMCPAllowPrivateHosts, "true")- stubLookupHost(t, []string{"172.18.0.6"})-- if _, _, err := AssertMCPURLSafeSameOrigin("http://other-internal:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse"); err == nil {- t.Fatal("expected cross-origin private advertised URL to be rejected")- }-}