Skip to content

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

feat(mcp): add SDK-backed native Go MCP runtime (#19673)

Sbaaoui Idrissd36dc659ec3c
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.go
index 5137fc7a8c..6ece8a4c24 100644
--- a/cmd/ragflow_server.go
+++ b/cmd/ragflow_server.go
@@ -20,6 +20,7 @@ import (
"context"
"errors"
"fmt"
+ "net"
"net/http"
"os"
"os/signal"
@@ -59,14 +60,13 @@ import (
"syscall"
"time"
- "github.com/cloudwego/eino/schema"
"github.com/gin-gonic/gin"
"go.uber.org/zap"
"ragflow/internal/agent/component"
"ragflow/internal/common"
"ragflow/internal/dao"
- infnative "ragflow/internal/deepdoc/parser/pdf/inference/native_analyzer"
+ "ragflow/internal/deepdoc/parser/pdf/inference/native_analyzer"
"ragflow/internal/engine"
"ragflow/internal/engine/redis"
et "ragflow/internal/engine/types"
@@ -88,6 +88,14 @@ type serverArgs struct {
adminHost *string // Used by api, ingestor, syncer for heartbeat
adminPort *int // Used by api, ingestor, syncer for heartbeat, "ip:port"
name *string // server name
+ mcpEnabled bool
+ mcpHost string
+ mcpPort int
+ mcpMode string
+ mcpAPIKey string
+ mcpSSE bool
+ mcpStreamable bool
+ mcpJSON bool
}
// engineDocEngine is the small slice of the engine surface the doc-chunk pager
@@ -179,12 +187,39 @@ func (p *docChunkPager) DocChunks(ctx context.Context, req harness.DocChunksRequ
}
func parseArgs() (*serverArgs, error) {
- args := &serverArgs{}
+ args := &serverArgs{
+ mcpHost: "127.0.0.1",
+ mcpPort: 9382,
+ mcpMode: "self-host",
+ mcpSSE: true,
+ mcpStreamable: true,
+ mcpJSON: true,
+ }
var serverMode string
var configPath string
for i := 1; i < len(os.Args); i++ {
arg := os.Args[i]
+ if key, value, ok := strings.Cut(arg, "="); ok {
+ switch key {
+ case "--mcp-host":
+ args.mcpHost = value
+ continue
+ case "--mcp-port":
+ port, err := parsePort(value, "MCP")
+ if err != nil {
+ return nil, err
+ }
+ args.mcpPort = port
+ continue
+ case "--mcp-mode":
+ args.mcpMode = value
+ continue
+ case "--mcp-host-api-key":
+ args.mcpAPIKey = value
+ continue
+ }
+ }
switch arg {
case "--admin":
serverMode = "admin"
@@ -197,6 +232,20 @@ func parseArgs() (*serverArgs, error) {
case "--api":
serverMode = "api"
args.mode = &serverMode
+ case "--enable-mcpserver":
+ args.mcpEnabled = true
+ case "--transport-sse-enabled":
+ args.mcpSSE = true
+ case "--no-transport-sse-enabled":
+ args.mcpSSE = false
+ case "--transport-streamable-http-enabled":
+ args.mcpStreamable = true
+ case "--no-transport-streamable-http-enabled":
+ args.mcpStreamable = false
+ case "--json-response":
+ args.mcpJSON = true
+ case "--no-json-response":
+ args.mcpJSON = false
case "--syncer":
serverMode = "syncer"
args.mode = &serverMode
@@ -254,12 +303,84 @@ func parseArgs() (*serverArgs, error) {
return nil, fmt.Errorf("unknown parameter: %s", arg)
}
}
+
+ if err := applyMCPEnv(args); err != nil {
+ return nil, err
+ }
+ if err := validateMCPArgs(args); err != nil {
+ return nil, err
+ }
if args.migrateDB && args.mode != nil {
- return nil, errors.New("--migrate is a standalone action and cannot be combined with --api/--admin/--ingestor/--syncer")
+ return nil, errors.New("--migrate cannot be combined with a server mode")
}
return args, nil
}
+func applyMCPEnv(args *serverArgs) error {
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_HOST"); ok {
+ args.mcpHost = value
+ }
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_PORT"); ok {
+ port, err := parsePort(value, "MCP")
+ if err != nil {
+ return err
+ }
+ args.mcpPort = port
+ }
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_LAUNCH_MODE"); ok {
+ args.mcpMode = value
+ }
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_HOST_API_KEY"); ok {
+ args.mcpAPIKey = value
+ }
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_ENABLED"); ok {
+ args.mcpEnabled = parseMCPBool(value)
+ }
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_TRANSPORT_SSE_ENABLED"); ok {
+ args.mcpSSE = parseMCPBool(value)
+ }
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_TRANSPORT_STREAMABLE_ENABLED"); ok {
+ args.mcpStreamable = parseMCPBool(value)
+ }
+ if value, ok := os.LookupEnv("RAGFLOW_MCP_JSON_RESPONSE"); ok {
+ args.mcpJSON = parseMCPBool(value)
+ }
+ return nil
+}
+
+func validateMCPArgs(args *serverArgs) error {
+ if args.mcpMode != "self-host" && args.mcpMode != "host" {
+ return fmt.Errorf("invalid MCP mode: %s", args.mcpMode)
+ }
+ if !args.mcpStreamable && args.mcpJSON {
+ args.mcpJSON = false
+ }
+ if !args.mcpSSE && !args.mcpStreamable {
+ args.mcpStreamable = true
+ }
+ if args.mcpEnabled && args.mcpMode == "self-host" && args.mcpAPIKey == "" {
+ return errors.New("--mcp-host-api-key is required when --mcp-mode=self-host")
+ }
+ return nil
+}
+
+func parseMCPBool(value string) bool {
+ switch strings.ToLower(strings.TrimSpace(value)) {
+ case "1", "true", "yes", "on":
+ return true
+ default:
+ return false
+ }
+}
+
+func parsePort(value, name string) (int, error) {
+ port, err := strconv.Atoi(value)
+ if err != nil || port <= 0 || port > 65535 {
+ return 0, fmt.Errorf("invalid %s port: %s", name, value)
+ }
+ return port, nil
+}
+
// registerNativeDeepDoc wires the in-process (Go) DeepDoc backend as the local
// fallback used when no external DeepDoc HTTP service is configured. It is
// compiled into the server built with -tags cgo, which statically links the
@@ -349,10 +470,6 @@ func main() {
os.Exit(1)
}
- // --migrate is a standalone one-shot action: run the database migrations and
- // exit without selecting a server mode. It deliberately skips the
- // mode-specific startup (native DeepDoc, doc engine, Redis, storage, message
- // queue) so it can run independently, before any server boots.
if arguments.migrateDB {
if err = runMigrate(ctx, arguments); err != nil {
common.Fatal("Failed to run database migration", zap.Error(err))
@@ -477,17 +594,11 @@ func main() {
common.Info(fmt.Sprintf("Starting %s server: %s, mode: %s", *arguments.mode, serverName, globalConfig.GetMode()))
server.PrintAll()
- // Initialize database. Migrations are not run here: --migrate is a
- // standalone action, so a server-mode process only ensures the runtime
- // tables it needs (see InitDB).
+ // Initialize database
if err = dao.InitDB(ctx, false); err != nil {
common.Fatal("Failed to initialize database", zap.Error(err))
}
- // Refuse to start a server against a database that a newer version already
- // migrated: rolling the code back cannot roll the schema back. The
- // standalone --migrate action is exempt because advancing the database is
- // its job.
if err = checkDatabaseVersion(ctx); err != nil {
common.Fatal("Refusing to start: database was migrated by a newer version", zap.Error(err))
}
@@ -633,7 +744,6 @@ func runMigrate(ctx context.Context, args *serverArgs) error {
globalConfig := server.GetConfig()
server.SetServerName(serverName)
-
logConfig := globalConfig.GetLogConfig()
if logConfig.Level != "" {
logLevel = logConfig.Level
@@ -660,7 +770,6 @@ func runMigrate(ctx context.Context, args *serverArgs) error {
return fmt.Errorf("initialize database: %w", err)
}
common.Info("Database migrations completed")
-
return nil
}
@@ -716,7 +825,6 @@ func runAdmin(ctx context.Context, args *serverArgs) error {
Addr: addr,
Handler: ginEngine,
}
-
// Print RAGFlow Admin logo
common.Info("" +
"\n ____ ___ ______________ ___ __ _ \n" +
@@ -958,14 +1066,16 @@ func runAPI(ctx context.Context, args *serverArgs) error {
common.Fatal("Failed to initialize query builder", zap.Error(err))
}
- startServer(ctx)
+ if err := startServer(ctx, args); err != nil {
+ return err
+ }
common.Info("Server exited")
return nil
}
-func startServer(ctx context.Context) {
+func startServer(ctx context.Context, args *serverArgs) error {
globalConfig := server.GetConfig()
serverMode := globalConfig.GetMode()
@@ -1163,14 +1273,6 @@ func startServer(ctx context.Context) {
// uses min(chat_mdl.max_length, _EVIDENCE_BUDGET_TOKENS=8000),
// which EvidenceMaxTokens<=0 reproduces).
}
- for _, message := range req.Messages {
- content, err := service.NormalizeOpenAIMessageContent(message["content"])
- if err != nil {
- return service.HarnessResult{}, err
- }
- role, _ := message["role"].(string)
- deps.Messages = append(deps.Messages, schema.Message{Role: schema.RoleType(role), Content: content})
- }
// Diagnose WHY compiled expansion is disabled: NewCompiledExpander
// returns nil for three reasons (store==nil / no datasets / no tenant)
// and RAGTools.Expand==nil silences the whole channel with no other
@@ -1399,7 +1501,7 @@ func startServer(ctx context.Context) {
_, err := channels.Start(ctx)
if err != nil {
- common.Fatal("Fail to start chat-channel", zap.Error(err))
+ return fmt.Errorf("start chat-channel: %w", err)
}
apiServerConfig := globalConfig.GetAPIServerConfig()
@@ -1409,6 +1511,7 @@ func startServer(ctx context.Context) {
srv := &http.Server{
Addr: addr,
Handler: ginEngine,
+ BaseContext: func(net.Listener) context.Context { return ctx },
ReadHeaderTimeout: 10 * time.Second,
ReadTimeout: 60 * time.Second,
// WriteTimeout spans "request header read → response written", so it is a
@@ -1424,6 +1527,76 @@ func startServer(ctx context.Context) {
WriteTimeout: 180 * time.Second,
IdleTimeout: 120 * time.Second,
}
+ apiListener, err := net.Listen("tcp", addr)
+ if err != nil {
+ return fmt.Errorf("listen API server on %s: %w", addr, err)
+ }
+ defer apiListener.Close()
+
+ serveErr := make(chan error, 2)
+ serve := func(name string, srv *http.Server, listener net.Listener) {
+ if err := srv.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
+ serveErr <- fmt.Errorf("%s server failed: %w", name, err)
+ }
+ }
+
+ var mcpSrv *http.Server
+ var mcpCloser interface{ Close() error }
+ var mcpListener net.Listener
+ if args != nil && args.mcpEnabled {
+ resolveUser := func(ctx context.Context, authorization string) (string, error) {
+ if args.mcpMode == "self-host" {
+ authorization = args.mcpAPIKey
+ }
+ user, err := authHandler.ResolveMCPUser(ctx, authorization)
+ if err != nil {
+ return "", err
+ }
+ return user.ID, nil
+ }
+ if args.mcpMode == "self-host" {
+ authCtx, cancel := context.WithTimeout(ctx, 60*time.Second)
+ _, err := resolveUser(authCtx, "")
+ cancel()
+ if err != nil {
+ return errors.New("invalid configured MCP API key")
+ }
+ }
+ mcpHandler := handler.NewStandaloneMCPHandler(
+ resolveUser,
+ func(ctx context.Context, userID string, page, pageSize int, orderby string, desc bool) ([]map[string]interface{}, int64, error) {
+ return handler.MCPListDatasets(ctx, datasetsService, userID, page, pageSize, orderby, desc)
+ },
+ func(ctx context.Context, userID string, page, pageSize int, orderby string, desc bool) ([]map[string]interface{}, int64, error) {
+ return handler.MCPListChats(ctx, chatService, userID, page, pageSize, orderby, desc)
+ },
+ func(ctx context.Context, userID string, req mcp.RetrievalRequest) (string, error) {
+ return handler.MCPRetrieval(ctx, datasetsService, userID, req)
+ },
+ mcp.Options{SSE: args.mcpSSE, StreamableHTTP: args.mcpStreamable, JSONResponse: args.mcpJSON},
+ )
+ mcpCloser = mcpHandler
+ defer mcpHandler.Close()
+ mcpAddr := fmt.Sprintf("%s:%d", args.mcpHost, args.mcpPort)
+ mcpListener, err = net.Listen("tcp", mcpAddr)
+ if err != nil {
+ return fmt.Errorf("listen MCP server on %s: %w", mcpAddr, err)
+ }
+ defer mcpListener.Close()
+ mcpSrv = &http.Server{
+ Addr: mcpAddr,
+ Handler: mcpHandler,
+ BaseContext: func(net.Listener) context.Context { return ctx },
+ ReadHeaderTimeout: 10 * time.Second,
+ ReadTimeout: 60 * time.Second,
+ WriteTimeout: 0, // SSE streams outlive individual tool deadlines
+ IdleTimeout: 120 * time.Second,
+ }
+ go func() {
+ common.Info(fmt.Sprintf("MCP server starting on %s", mcpSrv.Addr))
+ serve("MCP", mcpSrv, mcpListener)
+ }()
+ }
// Start server in a goroutine
go func() {
@@ -1436,9 +1609,7 @@ func startServer(ctx context.Context) {
)
common.Info(fmt.Sprintf("RAGFlow Go Version: %s", common.GetRAGFlowVersion()))
common.Info(fmt.Sprintf("Server starting on port: %d", apiServerConfig.HTTPPort))
- if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
- common.Fatal("Failed to start server", zap.Error(err))
- }
+ serve("API", srv, apiListener)
}()
// Start heartbeat reporter to admin server
@@ -1451,20 +1622,42 @@ func startServer(ctx context.Context) {
defer hb.Stop()
}
- // Wait for shutdown signal from main's signal.NotifyContext
- <-ctx.Done()
-
- common.Info(fmt.Sprintf("Received shutdown signal"))
+ // Wait for either shutdown signal or serving failure.
+ var runErr error
+ select {
+ case <-ctx.Done():
+ common.Info("Received shutdown signal")
+ case err := <-serveErr:
+ runErr = err
+ common.Error("Server failed; shutting down", err)
+ }
common.Info("Shutting down server...")
- // Create context with timeout for graceful shutdown
shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)
defer shutdownCancel()
- // Shutdown server
- if err := srv.Shutdown(shutdownCtx); err != nil {
- common.Fatal("Server forced to shutdown", zap.Error(err))
+ if mcpCloser != nil {
+ if err := mcpCloser.Close(); err != nil {
+ common.Warn("Failed to close MCP handler", zap.Error(err))
+ }
+ }
+ if err := shutdownHTTPServer(shutdownCtx, "API", srv); err != nil {
+ return err
+ }
+ if mcpSrv != nil {
+ if err := shutdownHTTPServer(shutdownCtx, "MCP", mcpSrv); err != nil {
+ return err
+ }
}
+ return runErr
+}
+
+func shutdownHTTPServer(ctx context.Context, name string, srv *http.Server) error {
+ if err := srv.Shutdown(ctx); err != nil {
+ _ = srv.Close()
+ return fmt.Errorf("shutdown %s server: %w", name, err)
+ }
+ return nil
}
// agentRunOptions bundles the three optional injection slots the
diff --git a/cmd/ragflow_server_test.go b/cmd/ragflow_server_test.go
index 1ceed649be..a9c1005f4c 100644
--- a/cmd/ragflow_server_test.go
+++ b/cmd/ragflow_server_test.go
@@ -27,6 +27,123 @@ import (
"ragflow/internal/service"
)
+func withArgsAndEnv(t *testing.T, args []string, env map[string]string, fn func()) {
+ t.Helper()
+ oldArgs := os.Args
+ os.Args = append([]string{"ragflow_server"}, args...)
+ t.Cleanup(func() { os.Args = oldArgs })
+ keys := []string{
+ "RAGFLOW_MCP_HOST",
+ "RAGFLOW_MCP_PORT",
+ "RAGFLOW_MCP_LAUNCH_MODE",
+ "RAGFLOW_MCP_HOST_API_KEY",
+ "RAGFLOW_MCP_ENABLED",
+ "RAGFLOW_MCP_TRANSPORT_SSE_ENABLED",
+ "RAGFLOW_MCP_TRANSPORT_STREAMABLE_ENABLED",
+ "RAGFLOW_MCP_JSON_RESPONSE",
+ }
+ oldEnv := make(map[string]*string, len(keys))
+ for _, key := range keys {
+ if value, ok := os.LookupEnv(key); ok {
+ v := value
+ oldEnv[key] = &v
+ } else {
+ oldEnv[key] = nil
+ }
+ os.Unsetenv(key)
+ }
+ t.Cleanup(func() {
+ for key, value := range oldEnv {
+ if value == nil {
+ os.Unsetenv(key)
+ continue
+ }
+ os.Setenv(key, *value)
+ }
+ })
+ for key, value := range env {
+ os.Setenv(key, value)
+ }
+ fn()
+}
+
+func TestParseArgsMCPEnvOverridesCLI(t *testing.T) {
+ withArgsAndEnv(t,
+ []string{"--api", "--enable-mcpserver", "--mcp-host=cli", "--mcp-port=10001", "--mcp-mode=host", "--mcp-host-api-key=cli-key", "--no-transport-sse-enabled", "--no-transport-streamable-http-enabled", "--no-json-response"},
+ map[string]string{
+ "RAGFLOW_MCP_HOST": "env-host",
+ "RAGFLOW_MCP_PORT": "10002",
+ "RAGFLOW_MCP_LAUNCH_MODE": "self-host",
+ "RAGFLOW_MCP_HOST_API_KEY": "env-key",
+ "RAGFLOW_MCP_ENABLED": "yes",
+ "RAGFLOW_MCP_TRANSPORT_SSE_ENABLED": "true",
+ "RAGFLOW_MCP_TRANSPORT_STREAMABLE_ENABLED": "true",
+ "RAGFLOW_MCP_JSON_RESPONSE": "true",
+ }, func() {
+ args, err := parseArgs()
+ if err != nil {
+ t.Fatalf("parseArgs: %v", err)
+ }
+ if args.mcpHost != "env-host" || args.mcpPort != 10002 || args.mcpMode != "self-host" || args.mcpAPIKey != "env-key" {
+ t.Fatalf("env did not override CLI: %#v", args)
+ }
+ if !args.mcpEnabled || !args.mcpSSE || !args.mcpStreamable || !args.mcpJSON {
+ t.Fatalf("env bools did not resolve true: %#v", args)
+ }
+ })
+}
+
+func TestParseArgsMCPTransportFallbackMatchesPython(t *testing.T) {
+ withArgsAndEnv(t,
+ []string{"--api", "--enable-mcpserver", "--mcp-mode=host", "--no-transport-sse-enabled", "--no-transport-streamable-http-enabled"},
+ nil, func() {
+ args, err := parseArgs()
+ if err != nil {
+ t.Fatalf("parseArgs: %v", err)
+ }
+ if args.mcpSSE {
+ t.Fatal("SSE should stay disabled")
+ }
+ if !args.mcpStreamable {
+ t.Fatal("streamable HTTP should be re-enabled when both transports are disabled")
+ }
+ if args.mcpJSON {
+ t.Fatal("JSON response should be false because Python disables JSON before both-disabled fallback")
+ }
+ })
+}
+
+func TestParseArgsMCPValidation(t *testing.T) {
+ t.Run("invalid mode", func(t *testing.T) {
+ withArgsAndEnv(t, []string{"--api", "--mcp-mode=bogus"}, nil, func() {
+ if _, err := parseArgs(); err == nil {
+ t.Fatal("expected invalid mode error")
+ }
+ })
+ })
+ t.Run("invalid port", func(t *testing.T) {
+ withArgsAndEnv(t, []string{"--api", "--mcp-port=0"}, nil, func() {
+ if _, err := parseArgs(); err == nil {
+ t.Fatal("expected invalid port error")
+ }
+ })
+ })
+ t.Run("missing self-host key only when enabled", func(t *testing.T) {
+ withArgsAndEnv(t, []string{"--api", "--enable-mcpserver"}, nil, func() {
+ if _, err := parseArgs(); err == nil {
+ t.Fatal("expected missing self-host key error")
+ }
+ })
+ })
+ t.Run("self-host key not required while disabled", func(t *testing.T) {
+ withArgsAndEnv(t, []string{"--api"}, nil, func() {
+ if _, err := parseArgs(); err != nil {
+ t.Fatalf("parseArgs: %v", err)
+ }
+ })
+ })
+}
+
func kb(embdID string, tenantEmbdID string) *entity.Knowledgebase {
kb := &entity.Knowledgebase{EmbdID: embdID}
if tenantEmbdID != "" {
diff --git a/docker/entrypoint-go.sh b/docker/entrypoint-go.sh
index 0fe41f5b69..a1a85579dd 100755
--- a/docker/entrypoint-go.sh
+++ b/docker/entrypoint-go.sh
@@ -14,6 +14,7 @@ function usage() {
echo " --disable-webserver Disables the web server (nginx + ragflow_server)."
echo " --disable-taskexecutor Disables task executor workers."
echo " --disable-datasync Disables synchronization of datasource workers."
+ echo " --enable-mcpserver Enables the MCP server."
echo " --enable-adminserver Enables the Admin server."
echo " --init-model-provider-tables Run model provider table migrations and exit."
echo " --init-superuser Initializes the superuser (needs --enable-adminserver)."
@@ -21,11 +22,21 @@ function usage() {
echo " --consumer-no-end=<num> End range for consumers (if using range-based)."
echo " --workers=<num> Number of task executors to run (if range is not used)."
echo " --host-id=<string> Unique ID for the host (defaults to \`hostname\`)."
+ echo " --mcp-host=<string> Address the MCP server binds to (default: 127.0.0.1)."
+ echo " --mcp-port=<num> Port the MCP server listens on (default: 9382)."
+ echo " --mcp-mode=<self-host|host> MCP server mode (default: self-host)."
+ echo " --mcp-host-api-key=<string> API key required when --mcp-mode=self-host."
+ echo " --no-transport-sse-enabled Disables the MCP SSE transport."
+ echo " --no-transport-streamable-http-enabled Disables the MCP streamable HTTP transport. Disabling"
+ echo " both transports re-enables this one, since the server"
+ echo " requires at least one."
+ echo " --no-json-response Disables JSON responses from the MCP server."
echo
echo "Examples:"
echo " $0 --disable-taskexecutor"
echo " $0 --disable-webserver --consumer-no-beg=0 --consumer-no-end=5"
echo " $0 --disable-webserver --workers=2 --host-id=myhost123"
+ echo " $0 --enable-mcpserver"
echo " $0 --enable-adminserver"
echo " $0 --enable-adminserver --init-superuser"
exit 1
@@ -34,6 +45,7 @@ function usage() {
ENABLE_WEBSERVER=1 # Default to enable web server
ENABLE_TASKEXECUTOR=1 # Default to enable task executor
ENABLE_DATASYNC=1
+ENABLE_MCP_SERVER=0
ENABLE_ADMIN_SERVER=0 # Default close admin server
INIT_SUPERUSER_ARGS="" # Default to not initialize superuser
INIT_MODEL_PROVIDER_TABLES=0
@@ -41,6 +53,14 @@ CONSUMER_NO_BEG=0
CONSUMER_NO_END=0
WORKERS=1
+MCP_HOST="127.0.0.1"
+MCP_PORT=9382
+MCP_MODE="self-host"
+MCP_HOST_API_KEY=""
+MCP_TRANSPORT_SSE_FLAG="--transport-sse-enabled"
+MCP_TRANSPORT_STREAMABLE_HTTP_FLAG="--transport-streamable-http-enabled"
+MCP_JSON_RESPONSE_FLAG="--json-response"
+
# -----------------------------------------------------------------------------
# Host ID logic:
# 1. By default, use the system hostname if length <= 32
@@ -70,6 +90,10 @@ for arg in "$@"; do
ENABLE_DATASYNC=0
shift
;;
+ --enable-mcpserver)
+ ENABLE_MCP_SERVER=1
+ shift
+ ;;
--enable-adminserver)
ENABLE_ADMIN_SERVER=1
shift
@@ -82,6 +106,34 @@ for arg in "$@"; do
INIT_SUPERUSER_ARGS="--init-superuser"
shift
;;
+ --mcp-host=*)
+ MCP_HOST="${arg#*=}"
+ shift
+ ;;
+ --mcp-port=*)
+ MCP_PORT="${arg#*=}"
+ shift
+ ;;
+ --mcp-mode=*)
+ MCP_MODE="${arg#*=}"
+ shift
+ ;;
+ --mcp-host-api-key=*)
+ MCP_HOST_API_KEY="${arg#*=}"
+ shift
+ ;;
+ --transport-sse-enabled|--no-transport-sse-enabled)
+ MCP_TRANSPORT_SSE_FLAG="$arg"
+ shift
+ ;;
+ --transport-streamable-http-enabled|--no-transport-streamable-http-enabled)
+ MCP_TRANSPORT_STREAMABLE_HTTP_FLAG="$arg"
+ shift
+ ;;
+ --json-response|--no-json-response)
+ MCP_JSON_RESPONSE_FLAG="$arg"
+ shift
+ ;;
--consumer-no-beg=*)
CONSUMER_NO_BEG="${arg#*=}"
shift
@@ -218,7 +270,20 @@ if [[ "${ENABLE_WEBSERVER}" -eq 1 ]]; then
/usr/sbin/nginx -c /etc/nginx/nginx.conf
echo "Starting RAGFlow go server..."
- run_with_restart "RAGFlow go server" bin/ragflow_server --api &
+ MCP_ARGS=()
+ if [[ "${ENABLE_MCP_SERVER}" -eq 1 ]]; then
+ MCP_ARGS=(
+ --enable-mcpserver
+ --mcp-host="${MCP_HOST}"
+ --mcp-port="${MCP_PORT}"
+ --mcp-mode="${MCP_MODE}"
+ --mcp-host-api-key="${MCP_HOST_API_KEY}"
+ "${MCP_TRANSPORT_SSE_FLAG}"
+ "${MCP_TRANSPORT_STREAMABLE_HTTP_FLAG}"
+ "${MCP_JSON_RESPONSE_FLAG}"
+ )
+ fi
+ run_with_restart "RAGFlow go server" bin/ragflow_server --api "${MCP_ARGS[@]}" &
fi
# MCP needs no separate process: --api serves it in-process at POST /mcp on the
diff --git a/docs/develop/mcp/native_go_mcp.md b/docs/develop/mcp/native_go_mcp.md
new file mode 100644
index 0000000000..da623e1a2b
--- /dev/null
+++ b/docs/develop/mcp/native_go_mcp.md
@@ -0,0 +1,69 @@
+---
+sidebar_position: 4
+title: Native Go MCP Runtime
+sidebar_label: Native Go MCP Runtime
+slug: /native_go_mcp
+sidebar_custom_props: {
+ categoryIcon: SiModelcontextprotocol
+}
+---
+# Native Go MCP Runtime
+
+The Go API server can host RAGFlow's MCP runtime in-process. It does not launch `mcp/server/server.py` and does not need a RAGFlow base URL because MCP tool calls use Go services directly.
+
+## Docker
+
+Use the Go entrypoint with MCP enabled:
+
+```bash
+./entrypoint-go.sh --enable-mcpserver \
+ --mcp-host=0.0.0.0 \
+ --mcp-port=9382 \
+ --mcp-mode=self-host \
+ --mcp-host-api-key=ragflow-xxxxx
+```
+
+Host mode requires each client request to provide a credential:
+
+```bash
+./entrypoint-go.sh --enable-mcpserver --mcp-mode=host
+```
+
+Host-mode requests accept `Authorization: Bearer <key>`, `api_key`, `X-API-Key`, or `Api-Key`.
+
+## Transport flags
+
+Both legacy SSE (`/sse` and `/messages/`) and streamable HTTP (`/mcp`) are enabled by default. JSON responses for streamable HTTP are also enabled by default.
+
+```bash
+--no-transport-sse-enabled # disable legacy SSE
+--no-transport-streamable-http-enabled # disable streamable HTTP
+--no-json-response # use SSE-style streamable HTTP responses
+```
+
+If both transports are disabled, streamable HTTP is re-enabled and JSON responses stay disabled, matching the Python MCP server's flag resolution.
+
+The same settings can be supplied through environment variables. Environment values override CLI flags:
+
+```bash
+RAGFLOW_MCP_ENABLED=true
+RAGFLOW_MCP_HOST=0.0.0.0
+RAGFLOW_MCP_PORT=9382
+RAGFLOW_MCP_LAUNCH_MODE=self-host
+RAGFLOW_MCP_HOST_API_KEY=ragflow-xxxxx
+RAGFLOW_MCP_TRANSPORT_SSE_ENABLED=true
+RAGFLOW_MCP_TRANSPORT_STREAMABLE_ENABLED=true
+RAGFLOW_MCP_JSON_RESPONSE=true
+```
+
+## Streamable HTTP smoke example
+
+```bash
+curl -sS http://127.0.0.1:9382/mcp \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -H 'Authorization: Bearer ragflow-xxxxx' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
+```
+
+Then send the `notifications/initialized` notification before `tools/list` or `tools/call` when using a real MCP client.
diff --git a/go.mod b/go.mod
index f57c9f487c..a405d10d50 100644
--- a/go.mod
+++ b/go.mod
@@ -57,7 +57,6 @@ require (
github.com/signintech/gopdf v0.36.1
github.com/siongui/gojianfan v0.0.0-20210926212422-2f175ac615de
github.com/spf13/viper v1.18.2
- github.com/stretchr/testify v1.11.1
github.com/ucloud/ucloud-sandbox-sdk-go v0.0.0-20260807065450-08464aef9ed5
github.com/xuri/excelize/v2 v2.11.0
github.com/yfedoseev/office_oxide/go v0.1.9
@@ -89,13 +88,15 @@ require (
github.com/PuerkitoBio/goquery v1.9.2 // indirect
github.com/andybalholm/cascadia v1.3.2 // indirect
github.com/apache/arrow/go/v15 v15.0.2 // indirect
- github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6 // indirect
github.com/goccy/go-json v0.10.5 // indirect
github.com/google/flatbuffers v23.5.26+incompatible // indirect
+ github.com/google/jsonschema-go v0.4.3 // indirect
github.com/json-iterator/go v1.1.12 // indirect
github.com/pierrec/lz4/v4 v4.1.18 // indirect
- github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+ github.com/segmentio/asm v1.1.3 // indirect
+ github.com/segmentio/encoding v0.5.4 // indirect
+ github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
golang.org/x/mod v0.38.0 // indirect
golang.org/x/telemetry v0.0.0-20260708182218-49f421fb7959 // indirect
golang.org/x/tools v0.48.0 // indirect
@@ -193,6 +194,7 @@ require (
github.com/minio/highwayhash v1.0.4 // indirect
github.com/minio/md5-simd v1.1.2 // indirect
github.com/mitchellh/mapstructure v1.5.0 // indirect
+ github.com/modelcontextprotocol/go-sdk v1.8.0
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
github.com/modern-go/reflect2 v1.0.2 // indirect
github.com/nats-io/jwt/v2 v2.8.2 // indirect
diff --git a/go.sum b/go.sum
index 0826ca25f9..010aaa20df 100644
--- a/go.sum
+++ b/go.sum
@@ -317,6 +317,8 @@ github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX
github.com/google/go-tpm v0.9.8 h1:slArAR9Ft+1ybZu0lBwpSmpwhRXaa85hWtMinMyRAWo=
github.com/google/go-tpm v0.9.8/go.mod h1:h9jEsEECg7gtLis0upRBQU+GhYVH6jMjrFxI8u6bVUY=
github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
github.com/google/martian/v3 v3.3.3 h1:DIhPTQrbPkgs2yJYdXU/eNACCG5DVQjySNRNlflZ9Fc=
github.com/google/martian/v3 v3.3.3/go.mod h1:iEPrYcgCF7jA9OtScMFQyAlZZ4YXTKEtJ1E6RWzmBA0=
github.com/google/pprof v0.0.0-20221118152302-e6195bd50e26 h1:Xim43kblpZXfIBQsbuBVKCudVG457BR2GZFIz3uw3hQ=
@@ -417,6 +419,8 @@ github.com/minio/minio-go/v7 v7.0.99 h1:2vH/byrwUkIpFQFOilvTfaUpvAX3fEFhEzO+DR3D
github.com/minio/minio-go/v7 v7.0.99/go.mod h1:EtGNKtlX20iL2yaYnxEigaIvj0G0GwSDnifnG8ClIdw=
github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/modelcontextprotocol/go-sdk v1.8.0 h1:KIvahhYqwtbeniWVPs3TcXEA7b8jEtwfBpOTAI+Urx4=
+github.com/modelcontextprotocol/go-sdk v1.8.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -496,6 +500,10 @@ github.com/saintfish/chardet v0.0.0-20230101081208-5e3ef4b5456d h1:hrujxIzL1woJ7
github.com/saintfish/chardet v0.0.0-20230101081208-5e3ef4b5456d/go.mod h1:uugorj2VCxiV1x+LzaIdVa9b4S4qGAcH6cbhh4qVxOU=
github.com/sebdah/goldie/v2 v2.5.3 h1:9ES/mNN+HNUbNWpVAlrzuZ7jE+Nrczbj8uFRjM7624Y=
github.com/sebdah/goldie/v2 v2.5.3/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
github.com/sergi/go-diff v1.0.0/go.mod h1:0CfEIISq7TuYL3j771MWULgwwjU+GofnZX9QAmXWZgo=
github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
@@ -588,6 +596,8 @@ github.com/yfedoseev/office_oxide/go v0.1.9 h1:gvTMCvJDYEZNF4dKd1cdfvU+9SRDSpnbN
github.com/yfedoseev/office_oxide/go v0.1.9/go.mod h1:YLtMlKUkRCp/Q96wsy7D6yoBKDeJnP66UH+c9Bb+E+M=
github.com/yfedoseev/pdf_oxide/go v0.3.73 h1:hRad+X4W0ILW3bCQeCvdUKcoy8yMj2TFS6/XtoMk55I=
github.com/yfedoseev/pdf_oxide/go v0.3.73/go.mod h1:QbJ/nLbez0al2EnqEdEPIlGflFprWmiuUM4mo9rNNOI=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.1.30/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
diff --git a/internal/handler/auth.go b/internal/handler/auth.go
index cb3a6c788b..836a113eb6 100644
--- a/internal/handler/auth.go
+++ b/internal/handler/auth.go
@@ -33,6 +33,24 @@ type AuthHandler struct {
userService userTokenResolver
}
+// ResolveMCPUser applies the same API-key/JWT resolution used by the public
+// MCP route, for the standalone native MCP transport.
+func (h *AuthHandler) ResolveMCPUser(ctx context.Context, authorization string) (*entity.User, error) {
+ if authorization == "" {
+ return nil, fmt.Errorf("missing authorization header")
+ }
+ if u, code, err := h.userService.GetUserByToken(ctx, authorization); err == nil && code == common.CodeSuccess {
+ return u, nil
+ }
+ if u, code, err := h.userService.GetUserByAPIToken(ctx, authorization); err == nil && code == common.CodeSuccess {
+ return u, nil
+ }
+ if u, code, err := h.userService.GetUserByBetaAPIToken(ctx, authorization); err == nil && code == common.CodeSuccess {
+ return u, nil
+ }
+ return nil, fmt.Errorf("invalid authorization")
+}
+
// userTokenResolver is the subset of UserService the auth
// middleware actually depends on. We keep it as a small interface
// so the test suite can swap in a stub without spinning up the
diff --git a/internal/handler/mcp_retrieval.go b/internal/handler/mcp_retrieval.go
new file mode 100644
index 0000000000..78c05b0063
--- /dev/null
+++ b/internal/handler/mcp_retrieval.go
@@ -0,0 +1,240 @@
+package handler
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "maps"
+ "ragflow/internal/common"
+ "ragflow/internal/dao"
+ "ragflow/internal/mcp"
+ "ragflow/internal/service"
+ dataset "ragflow/internal/service/dataset"
+ "ragflow/internal/service/document"
+)
+
+// mcpRerankCandidatesCount is the fixed rerank candidate window sent with every
+// retrieval request, so the ranking cannot shift between pages of one
+// pagination sequence. Requests whose page * page_size exceeds it are rejected
+// up front. Keep in sync with _RERANK_CANDIDATES_COUNT in mcp/server/server.py.
+const mcpRerankCandidatesCount = 512
+
+// validateRetrievalWindow checks that the requested page fits inside the fixed
+// rerank candidate window. page/page_size default to the same values as the
+// Python MCP server (1/30) when unset. The comparison divides instead of
+// multiplying so a hostile page value cannot overflow page * pageSize.
+func validateRetrievalWindow(page, pageSize int) error {
+ if page <= 0 {
+ page = 1
+ }
+ if pageSize <= 0 {
+ pageSize = 30
+ }
+ if page > mcpRerankCandidatesCount/pageSize {
+ return fmt.Errorf("page (%d) * page_size (%d) exceeds the fixed rerank candidate window (%d); narrow page or page_size", page, pageSize, mcpRerankCandidatesCount)
+ }
+ return nil
+}
+
+// MCPRetrieval executes a retrieval request on behalf of the MCP tool handler.
+// It translates the mcp.RetrievalRequest into a service.SearchDatasetsRequest
+// and calls DatasetService.SearchDatasets. The result is serialized as JSON.
+func MCPRetrieval(ctx context.Context, ds *dataset.DatasetService, userID string, req mcp.RetrievalRequest) (string, error) {
+ if err := validateRetrievalWindow(req.Page, req.PageSize); err != nil {
+ return "", err
+ }
+ // Resolve dataset IDs: if none provided, fetch ALL accessible datasets
+ // across all pages (matching Python _fetch_all_datasets behaviour).
+ datasetIDs := req.DatasetIDs
+ if len(datasetIDs) == 0 {
+ const maxPageSize = 100
+ ids, err := fetchAllDatasetIDs(func(page, pageSize int) ([]map[string]interface{}, int64, error) {
+ data, total, _, err := ds.ListDatasets(ctx,
+ "", "", page, pageSize, []dao.OrderTerm{{Column: "create_time", Desc: true}},
+ "", nil, "", userID, nil,
+ )
+ return data, total, err
+ }, maxPageSize)
+ if err != nil {
+ return "", fmt.Errorf("cannot resolve accessible datasets: %w", err)
+ }
+ if len(ids) == 0 {
+ return "", fmt.Errorf("No accessible datasets found.")
+ }
+ datasetIDs = ids
+ }
+
+ searchReq := &service.SearchDatasetsRequest{
+ DatasetIDs: datasetIDs,
+ Question: req.Question,
+ DocumentIDs: req.DocumentIDs,
+ ForceRefresh: req.ForceRefresh,
+ }
+
+ if req.Page > 0 {
+ v := req.Page
+ searchReq.Page = &v
+ }
+ if req.PageSize > 0 {
+ v := req.PageSize
+ searchReq.PageSize = &v
+ }
+ if req.TopK > 0 {
+ v := req.TopK
+ searchReq.TopK = &v
+ }
+ {
+ v := req.SimilarityThreshold
+ searchReq.SimilarityThreshold = &v
+ }
+ {
+ v := req.VectorSimilarityWeight
+ searchReq.VectorSimilarityWeight = &v
+ }
+ if req.RerankID != "" {
+ v := req.RerankID
+ searchReq.RerankID = &v
+ }
+ {
+ v := mcpRerankCandidatesCount
+ searchReq.RerankCandidatesCount = &v
+ }
+ {
+ v := req.Keyword
+ searchReq.Keyword = &v
+ }
+
+ resp, err := ds.SearchDatasets(ctx, searchReq, userID)
+ if err != nil {
+ return "", err
+ }
+
+ // Metadata reads use the same authorized service paths as the REST API.
+ // No shared cache: force_refresh always sees current metadata, without
+ // cross-tenant cache state or a second metadata implementation.
+ documents := document.NewDocumentService()
+ datasetNames := make(map[string]string)
+ documentMetadata := make(map[string]map[string]any)
+ for _, id := range datasetIDs {
+ info, code, err := ds.GetDataset(ctx, id, userID)
+ if err != nil || code != common.CodeSuccess {
+ continue
+ }
+ name, _ := info["name"].(string)
+ datasetNames[id] = name
+ if !ds.Accessible(ctx, id, userID) {
+ continue
+ }
+ // Read only documents returned by retrieval, through the existing listing
+ // and metadata services. This avoids loading entire document collections.
+ for _, chunk := range resp.Chunks {
+ chunkDataset, _ := chunk["dataset_id"].(string)
+ docID, _ := chunk["document_id"].(string)
+ if chunkDataset != id || docID == "" {
+ continue
+ }
+ if _, ok := documentMetadata[docID]; ok {
+ continue
+ }
+ docs, _, err := documents.ListDocumentsByDatasetIDWithOptions(ctx, dao.DocumentListOptions{KbID: id, DocIDs: []string{docID}}, 1, 1)
+ if err != nil || len(docs) == 0 {
+ continue
+ }
+ fields, err := documents.GetDocumentMetadataByID(ctx, docID)
+ if err != nil {
+ fields = map[string]any{}
+ }
+ doc := mapDocumentListItem(docs[0], fields)
+ metadata := map[string]any{"document_id": docID}
+ for _, key := range []string{"name", "location", "type", "size", "chunk_count", "create_date", "update_date", "token_count", "thumbnail", "dataset_id", "meta_fields"} {
+ metadata[key] = doc[key]
+ }
+ documentMetadata[docID] = metadata
+ }
+ }
+ if err := ctx.Err(); err != nil {
+ return "", err
+ }
+ result, err := json.Marshal(mcpRetrievalResult(req, datasetIDs, resp, datasetNames, documentMetadata))
+ if err != nil {
+ return "", fmt.Errorf("failed to serialize retrieval result: %w", err)
+ }
+ return string(result), nil
+}
+
+// fetchAllDatasetIDs pages through listPage collecting dataset IDs until the
+// total reported by the service is reached, or a short or empty page arrives.
+// Stopping at the reported total avoids an extra empty-page request when the
+// dataset count is an exact multiple of pageSize.
+func fetchAllDatasetIDs(listPage func(page, pageSize int) ([]map[string]interface{}, int64, error), pageSize int) ([]string, error) {
+ var ids []string
+ seen := make(map[string]bool)
+ page := 1
+ fetched := 0
+ for {
+ data, total, err := listPage(page, pageSize)
+ if err != nil {
+ return nil, err
+ }
+ if len(data) == 0 {
+ break
+ }
+ fetched += len(data)
+ for _, d := range data {
+ if id, ok := d["id"].(string); ok && id != "" && !seen[id] {
+ seen[id] = true
+ ids = append(ids, id)
+ }
+ }
+ // Stop once the reported total is reached so exact multiples of
+ // pageSize do not pay an extra empty-page request.
+ if total > 0 && int64(fetched) >= total {
+ break
+ }
+ // A page smaller than pageSize is the last page.
+ if len(data) < pageSize {
+ break
+ }
+ page++
+ }
+ return ids, nil
+}
+
+// mcpRetrievalResult preserves REST chunk fields while adding the MCP envelope.
+func mcpRetrievalResult(req mcp.RetrievalRequest, datasetIDs []string, resp *service.SearchDatasetsResponse, names map[string]string, metadata map[string]map[string]any) map[string]any {
+ chunks := make([]map[string]any, 0, len(resp.Chunks))
+ for _, raw := range resp.Chunks {
+ chunk := maps.Clone(raw)
+ id, _ := chunk["dataset_id"].(string)
+ if id == "" {
+ id, _ = chunk["kb_id"].(string)
+ }
+ name, ok := names[id]
+ if !ok {
+ name = "Unknown"
+ }
+ chunk["dataset_name"] = name
+ documentName, ok := chunk["document_keyword"]
+ if !ok {
+ documentName = ""
+ }
+ chunk["document_name"] = documentName
+ docID, _ := chunk["document_id"].(string)
+ if doc, ok := metadata[docID]; ok {
+ chunk["document_metadata"] = doc
+ }
+ chunks = append(chunks, chunk)
+ }
+ page, size := req.Page, req.PageSize
+ if page <= 0 {
+ page = 1
+ }
+ if size <= 0 {
+ size = 30
+ }
+ return map[string]any{
+ "chunks": chunks,
+ "pagination": map[string]any{"page": page, "page_size": size, "total_chunks": resp.Total, "total_pages": (resp.Total + int64(size) - 1) / int64(size)},
+ "query_info": map[string]any{"question": req.Question, "similarity_threshold": req.SimilarityThreshold, "vector_weight": req.VectorSimilarityWeight, "keyword_search": req.Keyword, "dataset_count": len(datasetIDs)},
+ }
+}
diff --git a/internal/handler/mcp_retrieval_result_test.go b/internal/handler/mcp_retrieval_result_test.go
new file mode 100644
index 0000000000..5e3f5910dc
--- /dev/null
+++ b/internal/handler/mcp_retrieval_result_test.go
@@ -0,0 +1,43 @@
+package handler
+
+import (
+ "encoding/json"
+ "reflect"
+ "testing"
+
+ "ragflow/internal/mcp"
+ "ragflow/internal/service"
+)
+
+func TestMCPRetrievalResult(t *testing.T) {
+ req := mcp.RetrievalRequest{Question: "question", Page: 2, PageSize: 10, SimilarityThreshold: .2, VectorSimilarityWeight: .3, Keyword: true}
+ raw := map[string]any{"id": "chunk", "dataset_id": "dataset", "document_id": "doc", "document_keyword": "file.txt", "custom": 42}
+ metadata := map[string]map[string]any{"doc": {"document_id": "doc", "meta_fields": map[string]any{"author": "Ada"}}}
+ result := mcpRetrievalResult(req, []string{"dataset"}, &service.SearchDatasetsResponse{Chunks: []map[string]any{raw}, Total: 21}, map[string]string{"dataset": "Dataset"}, metadata)
+ b, err := json.Marshal(result)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var got map[string]any
+ if err := json.Unmarshal(b, &got); err != nil {
+ t.Fatal(err)
+ }
+ chunk := got["chunks"].([]any)[0].(map[string]any)
+ if chunk["dataset_name"] != "Dataset" || chunk["document_name"] != "file.txt" || chunk["custom"] != float64(42) || chunk["document_metadata"] == nil {
+ t.Fatalf("chunk: %s", b)
+ }
+ if _, ok := raw["dataset_name"]; ok {
+ t.Fatal("mutated service response")
+ }
+ if !reflect.DeepEqual(got["pagination"], map[string]any{"page": float64(2), "page_size": float64(10), "total_chunks": float64(21), "total_pages": float64(3)}) {
+ t.Fatalf("pagination: %s", b)
+ }
+ if got["query_info"].(map[string]any)["vector_weight"] != .3 {
+ t.Fatalf("query: %s", b)
+ }
+ empty := mcpRetrievalResult(req, []string{"dataset"}, &service.SearchDatasetsResponse{}, nil, nil)
+ b, _ = json.Marshal(empty)
+ if empty["chunks"] == nil || string(b) == "" {
+ t.Fatalf("empty: %s", b)
+ }
+}
diff --git a/internal/handler/mcp_server.go b/internal/handler/mcp_server.go
index fc7275f496..53633f269b 100644
--- a/internal/handler/mcp_server.go
+++ b/internal/handler/mcp_server.go
@@ -18,10 +18,6 @@ package handler
import (
"context"
- "encoding/json"
- "fmt"
- "io"
- "net/http"
"github.com/gin-gonic/gin"
@@ -32,13 +28,6 @@ import (
dataset "ragflow/internal/service/dataset"
)
-// MCPRetrievalService abstracts the dataset retrieval operations needed
-// by the MCP server handler.
-type MCPRetrievalService interface {
- SearchDatasets(req *service.SearchDatasetsRequest, userID string) (*service.SearchDatasetsResponse, error)
- ListDatasets(id, name string, page, pageSize int, orderby string, desc bool, keywords string, ownerIDs []string, parserID, userID string, ids []string) ([]map[string]interface{}, int64, common.ErrorCode, error)
-}
-
// MCPServerHandler handles MCP protocol requests (JSON-RPC over HTTP).
// It exposes RAGFlow capabilities as MCP tools to external AI clients.
type MCPServerHandler struct {
@@ -47,6 +36,19 @@ type MCPServerHandler struct {
retrievalFunc func(ctx context.Context, userID string, req mcp.RetrievalRequest) (string, error)
}
+// NewStandaloneMCPHandler exposes the native SDK transports.
+func NewStandaloneMCPHandler(
+ resolveUser func(context.Context, string) (string, error),
+ listDatasetsFunc func(context.Context, string, int, int, string, bool) ([]map[string]interface{}, int64, error),
+ listChatsFunc func(context.Context, string, int, int, string, bool) ([]map[string]interface{}, int64, error),
+ retrievalFunc func(context.Context, string, mcp.RetrievalRequest) (string, error),
+ opts mcp.Options,
+) *mcp.Handler {
+ return mcp.NewHandler(resolveUser, func(userID string) mcp.Connector {
+ return mcp.NewServiceConnector(userID, listDatasetsFunc, listChatsFunc, retrievalFunc)
+ }, opts)
+}
+
// NewMCPServerHandler creates a new MCPServerHandler.
// The service functions are passed as closures to avoid importing the service
// package directly from the handler layer.
@@ -79,39 +81,16 @@ func (h *MCPServerHandler) HandleMCP(c *gin.Context) {
return
}
- const maxMCPBodyBytes = 1 << 20 // 1 MiB
- c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxMCPBodyBytes)
- body, err := io.ReadAll(c.Request.Body)
- if err != nil {
- common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeBadRequest, nil, "Failed to read request body: "+err.Error())
- return
- }
-
- // Create a connector for this user. Each request gets its own connector
- // so that user context is always correct.
- connector := mcp.NewServiceConnector(
- user.ID,
- h.listDatasetsFunc,
- h.listChatsFunc,
- h.retrievalFunc,
- )
-
- ctx := c.Request.Context()
- server := mcp.NewServer(connector)
- respBody, hasResponse, err := server.HandleRequest(ctx, body)
- if err != nil {
- common.ResponseWithHttpCodeData(c, http.StatusInternalServerError, common.CodeBadRequest, nil, "MCP server error: "+err.Error())
- return
+ hdl := NewStandaloneMCPHandler(func(context.Context, string) (string, error) { return user.ID, nil }, h.listDatasetsFunc, h.listChatsFunc, h.retrievalFunc, mcp.Options{StreamableHTTP: true, JSONResponse: true})
+ defer hdl.Close()
+ request := c.Request.Clone(c.Request.Context())
+ request.URL.Path = "/mcp"
+ // Preserve the legacy REST contract: callers historically sent ordinary
+ // JSON without Streamable HTTP's dual Accept header.
+ if accept := request.Header.Get("Accept"); accept == "" || accept == "application/json" {
+ request.Header.Set("Accept", "application/json, text/event-stream")
}
-
- if !hasResponse {
- // Notification — no response per JSON-RPC spec.
- c.Status(http.StatusAccepted)
- return
- }
-
- // The MCP protocol uses application/json with JSON-RPC responses.
- c.Data(http.StatusOK, "application/json", respBody)
+ hdl.ServeHTTP(c.Writer, request)
}
// MCPListDatasets wraps DatasetService.ListDatasets for the MCP tool handler,
@@ -141,142 +120,3 @@ func MCPListChats(ctx context.Context, chatService *service.ChatService, userID
}
return chatList, resp.Total, nil
}
-
-// mcpRerankCandidatesCount is the fixed rerank candidate window sent with every
-// retrieval request, so the ranking cannot shift between pages of one
-// pagination sequence. Requests whose page * page_size exceeds it are rejected
-// up front. Keep in sync with _RERANK_CANDIDATES_COUNT in mcp/server/server.py.
-const mcpRerankCandidatesCount = 512
-
-// validateRetrievalWindow checks that the requested page fits inside the fixed
-// rerank candidate window. page/page_size default to the same values as the
-// Python MCP server (1/30) when unset. The comparison divides instead of
-// multiplying so a hostile page value cannot overflow page * pageSize.
-func validateRetrievalWindow(page, pageSize int) error {
- if page <= 0 {
- page = 1
- }
- if pageSize <= 0 {
- pageSize = 30
- }
- if page > mcpRerankCandidatesCount/pageSize {
- return fmt.Errorf("page (%d) * page_size (%d) exceeds the fixed rerank candidate window (%d); narrow page or page_size", page, pageSize, mcpRerankCandidatesCount)
- }
- return nil
-}
-
-// MCPRetrieval executes a retrieval request on behalf of the MCP tool handler.
-// It translates the mcp.RetrievalRequest into a service.SearchDatasetsRequest
-// and calls DatasetService.SearchDatasets. The result is serialized as JSON.
-func MCPRetrieval(ctx context.Context, ds *dataset.DatasetService, userID string, req mcp.RetrievalRequest) (string, error) {
- if err := validateRetrievalWindow(req.Page, req.PageSize); err != nil {
- return "", err
- }
- // Resolve dataset IDs: if none provided, fetch ALL accessible datasets
- // across all pages (matching Python _fetch_all_datasets behaviour).
- datasetIDs := req.DatasetIDs
- if len(datasetIDs) == 0 {
- const maxPageSize = 100
- ids, err := fetchAllDatasetIDs(func(page, pageSize int) ([]map[string]interface{}, int64, error) {
- data, total, _, err := ds.ListDatasets(ctx,
- "", "", page, pageSize, []dao.OrderTerm{{Column: "create_time", Desc: true}},
- "", nil, "", userID, nil,
- )
- return data, total, err
- }, maxPageSize)
- if err != nil {
- return "", fmt.Errorf("cannot resolve accessible datasets: %w", err)
- }
- if len(ids) == 0 {
- return "", fmt.Errorf("no accessible datasets found")
- }
- datasetIDs = ids
- }
-
- searchReq := &service.SearchDatasetsRequest{
- DatasetIDs: datasetIDs,
- Question: req.Question,
- DocumentIDs: req.DocumentIDs,
- ForceRefresh: req.ForceRefresh,
- }
-
- if req.Page > 0 {
- v := req.Page
- searchReq.Page = &v
- }
- if req.PageSize > 0 {
- v := req.PageSize
- searchReq.PageSize = &v
- }
- if req.TopK > 0 {
- v := req.TopK
- searchReq.TopK = &v
- }
- {
- v := req.SimilarityThreshold
- searchReq.SimilarityThreshold = &v
- }
- {
- v := req.VectorSimilarityWeight
- searchReq.VectorSimilarityWeight = &v
- }
- if req.RerankID != "" {
- v := req.RerankID
- searchReq.RerankID = &v
- }
- {
- v := mcpRerankCandidatesCount
- searchReq.RerankCandidatesCount = &v
- }
- {
- v := req.Keyword
- searchReq.Keyword = &v
- }
-
- resp, err := ds.SearchDatasets(ctx, searchReq, userID)
- if err != nil {
- return "", err
- }
-
- result, err := json.Marshal(resp)
- if err != nil {
- return "", fmt.Errorf("failed to serialize retrieval result: %w", err)
- }
- return string(result), nil
-}
-
-// fetchAllDatasetIDs pages through listPage collecting dataset IDs until the
-// total reported by the service is reached, or a short or empty page arrives.
-// Stopping at the reported total avoids an extra empty-page request when the
-// dataset count is an exact multiple of pageSize.
-func fetchAllDatasetIDs(listPage func(page, pageSize int) ([]map[string]interface{}, int64, error), pageSize int) ([]string, error) {
- var ids []string
- page := 1
- fetched := 0
- for {
- data, total, err := listPage(page, pageSize)
- if err != nil {
- return nil, err
- }
- if len(data) == 0 {
- break
- }
- fetched += len(data)
- for _, d := range data {
- if id, ok := d["id"].(string); ok && id != "" {
- ids = append(ids, id)
- }
- }
- // Stop once the reported total is reached so exact multiples of
- // pageSize do not pay an extra empty-page request.
- if total > 0 && int64(fetched) >= total {
- break
- }
- // A page smaller than pageSize is the last page.
- if len(data) < pageSize {
- break
- }
- page++
- }
- return ids, nil
-}
diff --git a/internal/mcp/connector.go b/internal/mcp/connector.go
index a03e713920..141d824bc6 100644
--- a/internal/mcp/connector.go
+++ b/internal/mcp/connector.go
@@ -19,7 +19,6 @@ package mcp
import (
"context"
"encoding/json"
- "fmt"
"strings"
)
@@ -49,83 +48,58 @@ func NewServiceConnector(
}
}
-// ListDatasets returns newline-delimited JSON, each line being
-// {"id": "...", "description": "..."} for a dataset.
+// ListDatasets fetches every page for discovery (-1), or one capped REST-sized page.
func (c *ServiceConnector) ListDatasets(ctx context.Context, page, pageSize int, orderby string, desc bool) (string, error) {
- data, _, err := c.listDatasets(ctx, c.userID, page, pageSize, orderby, desc)
- if err != nil {
- return "", fmt.Errorf("list datasets: %w", err)
- }
-
- var lines []string
- for _, d := range data {
- id, _ := d["id"].(string)
- name := ""
- if v, ok := d["name"]; ok {
- if s, ok := v.(string); ok {
- name = s
+ var data []map[string]any
+ if pageSize == -1 {
+ for page = 1; ; page++ {
+ items, total, err := c.listDatasets(ctx, c.userID, page, 100, orderby, desc)
+ if err != nil {
+ return "", err
}
- }
- desc := ""
- if v, ok := d["description"]; ok {
- if s, ok := v.(string); ok {
- desc = s
+ data = append(data, items...)
+ if len(items) == 0 || (total > 0 && int64(len(data)) >= total) {
+ break
+ }
+ if err := ctx.Err(); err != nil {
+ return "", err
}
}
- // Match Python output: {"id": "...", "name": "...", "description": "..."}
- item := map[string]interface{}{
- "id": id,
- "name": name,
- "description": desc,
- }
- b, err := json.Marshal(item)
+ } else {
+ var err error
+ data, _, err = c.listDatasets(ctx, c.userID, page, min(pageSize, 100), orderby, desc)
if err != nil {
- continue
+ return "", err
}
- lines = append(lines, string(b))
}
- return strings.Join(lines, "\n"), nil
+ return listText(data, false)
}
-// ListChats returns newline-delimited JSON, each line being
-// {"id": "...", "name": "...", "description": "..."} for a chat assistant.
func (c *ServiceConnector) ListChats(ctx context.Context, page, pageSize int, orderby string, desc bool) (string, error) {
data, _, err := c.listChats(ctx, c.userID, page, pageSize, orderby, desc)
if err != nil {
- return "", fmt.Errorf("list chats: %w", err)
+ return "", err
}
+ return listText(data, true)
+}
- var lines []string
+func listText(data []map[string]any, chats bool) (string, error) {
+ lines := make([]string, 0, len(data))
for _, d := range data {
- id, _ := d["id"].(string)
- name := ""
- if v, ok := d["name"]; ok {
- if s, ok := v.(string); ok {
- name = s
- }
- }
- description := ""
- if v, ok := d["description"]; ok {
- if s, ok := v.(string); ok {
- description = s
- }
- }
- item := map[string]interface{}{
- "id": id,
- "name": name,
- "description": description,
+ description, ok := d["description"]
+ if chats && !ok {
+ description = ""
}
+ item := map[string]any{"id": d["id"], "name": d["name"], "description": description}
b, err := json.Marshal(item)
if err != nil {
- continue
+ return "", err
}
lines = append(lines, string(b))
}
return strings.Join(lines, "\n"), nil
}
-// Retrieval executes a retrieval via the in-process service and returns
-// the result as a JSON string.
func (c *ServiceConnector) Retrieval(ctx context.Context, req RetrievalRequest) (string, error) {
return c.retrieval(ctx, c.userID, req)
}
diff --git a/internal/mcp/http.go b/internal/mcp/http.go
new file mode 100644
index 0000000000..f5489f62b3
--- /dev/null
+++ b/internal/mcp/http.go
@@ -0,0 +1,128 @@
+package mcp
+
+import (
+ "context"
+ "crypto/rand"
+ "mime"
+ "net/http"
+ "net/url"
+ "strings"
+ "sync"
+
+ sdk "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// Options selects the Python-equivalent transport and response modes.
+type Options struct{ SSE, StreamableHTTP, JSONResponse bool }
+
+type sseSession struct {
+ owner string
+ transport *sdk.SSEServerTransport
+}
+
+// Handler owns the transport sessions. Close cancels active requests and streams.
+type Handler struct {
+ handler http.Handler
+ cancel context.CancelFunc
+}
+
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) { h.handler.ServeHTTP(w, r) }
+func (h *Handler) Close() error { h.cancel(); return nil }
+
+// Credential extracts Python-supported credentials without accepting arbitrary
+// Authorization schemes. Self-host mode supplies its key in the resolver.
+func Credential(headers http.Header) string {
+ auth := strings.TrimSpace(headers.Get("Authorization"))
+ if len(auth) >= 7 && strings.EqualFold(auth[:7], "Bearer ") {
+ if token := strings.TrimSpace(auth[7:]); token != "" {
+ return token
+ }
+ }
+ for _, name := range []string{"api_key", "X-API-Key", "Api-Key"} {
+ if token := strings.TrimSpace(headers.Get(name)); token != "" {
+ return token
+ }
+ }
+ return ""
+}
+
+// NewHandler authenticates every request and binds legacy SSE sessions to their
+// owner. Wire framing, initialization and dispatch remain SDK responsibilities.
+func NewHandler(resolve func(context.Context, string) (string, error), connector func(string) Connector, opts Options) *Handler {
+ lifetime, cancel := context.WithCancel(context.Background())
+ var mu sync.Mutex
+ sessions := make(map[string]sseSession)
+ type identityKey struct{}
+ streamable := sdk.NewStreamableHTTPHandler(func(r *http.Request) *sdk.Server {
+ return newServer(r.Context(), connector(r.Context().Value(identityKey{}).(string)))
+ }, &sdk.StreamableHTTPOptions{Stateless: true, JSONResponse: opts.JSONResponse, MaxRequestBodyBytes: 1 << 20, PropagateRequestCancellation: true})
+ mux := http.NewServeMux()
+ if opts.StreamableHTTP {
+ mux.Handle("/mcp", streamable)
+ mux.Handle("/mcp/", streamable)
+ }
+ if opts.SSE {
+ mux.HandleFunc("GET /sse", func(w http.ResponseWriter, r *http.Request) {
+ id := rand.Text()
+ transport := &sdk.SSEServerTransport{Endpoint: "/messages/?session_id=" + url.QueryEscape(id), Response: w, MaxRequestBodyBytes: 1 << 20}
+ owner := r.Context().Value(identityKey{}).(string)
+ w.Header().Set("Content-Type", "text/event-stream")
+ w.Header().Set("Cache-Control", "no-cache")
+ // Hold the registry lock through Connect: it publishes the endpoint before
+ // returning, so a fast client's first POST must wait until it is ready.
+ mu.Lock()
+ session, err := newServer(r.Context(), connector(owner)).Connect(r.Context(), transport, nil)
+ if err == nil {
+ sessions[id] = sseSession{owner, transport}
+ }
+ mu.Unlock()
+ if err != nil {
+ return
+ }
+ defer func() { mu.Lock(); delete(sessions, id); mu.Unlock(); session.Close() }()
+ stop := context.AfterFunc(r.Context(), func() { session.Close() })
+ defer stop()
+ session.Wait()
+ })
+ mux.HandleFunc("POST /messages/", func(w http.ResponseWriter, r *http.Request) {
+ media, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
+ if err != nil || media != "application/json" {
+ http.Error(w, "Content-Type must be application/json", http.StatusUnsupportedMediaType)
+ return
+ }
+ id := r.URL.Query().Get("session_id")
+ if id == "" {
+ id = r.URL.Query().Get("sessionid")
+ }
+ mu.Lock()
+ session, ok := sessions[id]
+ mu.Unlock()
+ if !ok || session.owner != r.Context().Value(identityKey{}).(string) {
+ http.Error(w, "session not found", http.StatusNotFound)
+ return
+ }
+ session.transport.ServeHTTP(w, r)
+ })
+ }
+ protected := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ // Reject cross-origin browser access, including GET streams.
+ if origin := r.Header.Get("Origin"); origin != "" {
+ u, err := url.Parse(origin)
+ if err != nil || u.Host != r.Host || (u.Scheme != "http" && u.Scheme != "https") {
+ http.Error(w, "invalid origin", http.StatusForbidden)
+ return
+ }
+ }
+ ctx, stop := context.WithCancel(r.Context())
+ defer stop()
+ detach := context.AfterFunc(lifetime, stop)
+ defer detach()
+ userID, err := resolve(ctx, Credential(r.Header))
+ if err != nil || userID == "" {
+ http.Error(w, "invalid authorization", http.StatusUnauthorized)
+ return
+ }
+ mux.ServeHTTP(w, r.WithContext(context.WithValue(ctx, identityKey{}, userID)))
+ })
+ return &Handler{handler: protected, cancel: cancel}
+}
diff --git a/internal/mcp/http_test.go b/internal/mcp/http_test.go
new file mode 100644
index 0000000000..1e7fa00428
--- /dev/null
+++ b/internal/mcp/http_test.go
@@ -0,0 +1,310 @@
+package mcp
+
+import (
+ "bufio"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "reflect"
+ "strings"
+ "testing"
+ "time"
+
+ sdk "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type headerTransport struct {
+ base http.RoundTripper
+ key string
+}
+
+func (t headerTransport) RoundTrip(r *http.Request) (*http.Response, error) {
+ r = r.Clone(r.Context())
+ r.Header.Set("Authorization", "Bearer "+t.key)
+ return t.base.RoundTrip(r)
+}
+func clientSession(t *testing.T, url, transport, key string) *sdk.ClientSession {
+ t.Helper()
+ client := sdk.NewClient(&sdk.Implementation{Name: "parity-test", Version: "1"}, nil)
+ hc := &http.Client{Transport: headerTransport{http.DefaultTransport, key}}
+ var tr sdk.Transport
+ if transport == "sse" {
+ tr = &sdk.SSEClientTransport{Endpoint: url + "/sse", HTTPClient: hc}
+ } else {
+ tr = &sdk.StreamableClientTransport{Endpoint: url + "/mcp", HTTPClient: hc}
+ }
+ ctx, cancel := context.WithTimeout(t.Context(), 10*time.Second)
+ t.Cleanup(cancel)
+ ss, err := client.Connect(ctx, tr, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { ss.Close() })
+ return ss
+}
+func TestSDKTransportsAndTools(t *testing.T) {
+ for _, mode := range []string{"json", "stream", "sse"} {
+ t.Run(mode, func(t *testing.T) {
+ var retrieval RetrievalRequest
+ factory := func(user string) Connector {
+ return NewServiceConnector(user,
+ func(ctx context.Context, user string, page, size int, _ string, _ bool) ([]map[string]any, int64, error) {
+ if user == "empty" {
+ return nil, 0, nil
+ }
+ return []map[string]any{{"id": user, "name": "Dataset", "description": nil}}, 1, nil
+ }, func(context.Context, string, int, int, string, bool) ([]map[string]any, int64, error) {
+ return nil, 0, nil
+ },
+ func(ctx context.Context, user string, req RetrievalRequest) (string, error) {
+ retrieval = req
+ return `{"chunks":[],"query_info":{"question":"hello"}}`, nil
+ })
+ }
+ h := NewHandler(func(_ context.Context, key string) (string, error) {
+ if key == "" || key == "invalid" {
+ return "", fmt.Errorf("denied")
+ }
+ return key, nil
+ }, factory, Options{true, true, mode == "json"})
+ hs := httptest.NewServer(h)
+ defer hs.Close()
+ defer h.Close()
+ ss := clientSession(t, hs.URL, mode, "alice")
+ tools, err := ss.ListTools(t.Context(), nil)
+ if err != nil || len(tools.Tools) != 3 {
+ t.Fatalf("tools=%v err=%v", tools, err)
+ }
+ var expected []*sdk.Tool
+ if err := json.Unmarshal(toolsJSON, &expected); err != nil {
+ t.Fatal(err)
+ }
+ for i, tool := range tools.Tools {
+ got, _ := json.Marshal(tool.InputSchema)
+ want, _ := json.Marshal(expected[i].InputSchema)
+ if string(got) != string(want) {
+ t.Fatalf("schema mismatch: %s vs %s", got, want)
+ }
+ }
+ result, err := ss.CallTool(t.Context(), &sdk.CallToolParams{Name: "ragflow_retrieval", Arguments: map[string]any{"question": "hello"}})
+ if err != nil || result.IsError {
+ t.Fatalf("retrieval: %v %v", result, err)
+ }
+ if retrieval.Page != 1 || retrieval.PageSize != 10 || retrieval.TopK != 1024 || retrieval.SimilarityThreshold != .2 || retrieval.VectorSimilarityWeight != .3 {
+ t.Fatalf("defaults: %+v", retrieval)
+ }
+ for _, name := range []string{"ragflow_list_datasets", "ragflow_list_chats"} {
+ result, err := ss.CallTool(t.Context(), &sdk.CallToolParams{Name: name})
+ if err != nil || result.IsError {
+ t.Fatalf("%s: %v %v", name, result, err)
+ }
+ if name == "ragflow_list_chats" {
+ b, _ := json.Marshal(result)
+ if !strings.Contains(string(b), `"text":""`) {
+ t.Fatalf("empty text missing: %s", b)
+ }
+ }
+ }
+ for _, args := range []map[string]any{{}, {"question": 3}, {"question": "x", "page": 0}, {"question": "x", "page": 1.5}, {"question": "x", "page_size": 101}, {"question": "x", "top_k": 1025}, {"question": "x", "keyword": "true"}, {"question": "x", "dataset_ids": []any{3}}, {"question": "x", "similarity_threshold": -1}} {
+ result, err := ss.CallTool(t.Context(), &sdk.CallToolParams{Name: "ragflow_retrieval", Arguments: args})
+ if err != nil || !result.IsError {
+ t.Fatalf("invalid input accepted: %v result=%v err=%v", args, result, err)
+ }
+ }
+ empty := clientSession(t, hs.URL, mode, "empty")
+ result, err = empty.CallTool(t.Context(), &sdk.CallToolParams{Name: "ragflow_list_datasets"})
+ if err != nil || result.IsError || result.Content[0].(*sdk.TextContent).Text != "" {
+ t.Fatalf("empty: %v %v", result, err)
+ }
+ })
+ }
+}
+func TestCredential(t *testing.T) {
+ for _, header := range []string{"Authorization", "api_key", "X-API-Key", "Api-Key"} {
+ h := http.Header{}
+ value := " secret "
+ if header == "Authorization" {
+ value = " bEaReR secret "
+ }
+ h.Set(header, value)
+ if got := Credential(h); got != "secret" {
+ t.Fatalf("%s=%q", header, got)
+ }
+ }
+ if Credential(http.Header{"Authorization": []string{"Basic secret"}}) != "" {
+ t.Fatal("accepted Basic")
+ }
+}
+func TestConnectorPaginationAndNulls(t *testing.T) {
+ var pages, sizes []int
+ c := NewServiceConnector("tenant", func(_ context.Context, user string, page, size int, _ string, _ bool) ([]map[string]any, int64, error) {
+ pages = append(pages, page)
+ sizes = append(sizes, size)
+ return []map[string]any{{"id": fmt.Sprint(page)}}, 2, nil
+ }, nil, nil)
+ text, err := c.ListDatasets(t.Context(), 1, -1, "create_time", true)
+ if err != nil || !reflect.DeepEqual(pages, []int{1, 2}) || !strings.Contains(text, `"description":null`) {
+ t.Fatalf("pages=%v text=%s err=%v", pages, text, err)
+ }
+ _, err = c.ListDatasets(t.Context(), 3, 1000, "create_time", true)
+ if err != nil || sizes[len(sizes)-1] != 100 {
+ t.Fatalf("cap: %v %v", sizes, err)
+ }
+}
+
+func TestConcurrentTenantsAndSSEOwnership(t *testing.T) {
+ h := NewHandler(func(_ context.Context, key string) (string, error) {
+ if key != "alice" && key != "bob" {
+ return "", fmt.Errorf("denied")
+ }
+ return key, nil
+ }, func(user string) Connector {
+ return NewServiceConnector(user, func(_ context.Context, user string, _, _ int, _ string, _ bool) ([]map[string]any, int64, error) {
+ return []map[string]any{{"id": user}}, 1, nil
+ }, func(context.Context, string, int, int, string, bool) ([]map[string]any, int64, error) {
+ return nil, 0, nil
+ }, nil)
+ }, Options{true, true, true})
+ hs := httptest.NewServer(h)
+ defer hs.Close()
+ defer h.Close()
+ for _, transport := range []string{"sse", "json"} {
+ a := clientSession(t, hs.URL, transport, "alice")
+ b := clientSession(t, hs.URL, transport, "bob")
+ errs := make(chan error, 2)
+ for i, ss := range []*sdk.ClientSession{a, b} {
+ go func() {
+ expected := []string{"alice", "bob"}[i]
+ for range 5 {
+ res, err := ss.CallTool(t.Context(), &sdk.CallToolParams{Name: "ragflow_list_datasets"})
+ if err != nil {
+ errs <- err
+ return
+ }
+ if res.IsError || !strings.Contains(res.Content[0].(*sdk.TextContent).Text, expected) {
+ errs <- fmt.Errorf("identity leak: %v", res)
+ return
+ }
+ }
+ errs <- nil
+ }()
+ }
+ for range 2 {
+ if err := <-errs; err != nil {
+ t.Fatal(err)
+ }
+ }
+ a.Close()
+ b.Close()
+ }
+ ctx, cancel := context.WithCancel(t.Context())
+ defer cancel()
+ req, _ := http.NewRequestWithContext(ctx, "GET", hs.URL+"/sse", nil)
+ req.Header.Set("X-API-Key", "alice")
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer resp.Body.Close()
+ reader := bufio.NewReader(resp.Body)
+ var endpoint string
+ for endpoint == "" {
+ line, err := reader.ReadString('\n')
+ if err != nil {
+ t.Fatal(err)
+ }
+ if strings.HasPrefix(line, "data: ") {
+ endpoint = strings.TrimSpace(strings.TrimPrefix(line, "data: "))
+ }
+ }
+ for _, key := range []string{"bob", "invalid", "alice"} {
+ request, _ := http.NewRequestWithContext(t.Context(), "POST", hs.URL+endpoint, strings.NewReader(`{"jsonrpc":"2.0","method":"notifications/initialized"}`))
+ request.Header.Set("Authorization", "Bearer "+key)
+ request.Header.Set("Content-Type", "application/json")
+ r, err := http.DefaultClient.Do(request)
+ if err != nil {
+ t.Fatal(err)
+ }
+ r.Body.Close()
+ want := map[string]int{"bob": 404, "invalid": 401, "alice": 202}[key]
+ if r.StatusCode != want {
+ t.Fatalf("%s got %d want %d", key, r.StatusCode, want)
+ }
+ }
+ h.Close()
+ done := make(chan error, 1)
+ go func() { _, err := io.Copy(io.Discard, reader); done <- err }()
+ select {
+ case <-done:
+ case <-time.After(2 * time.Second):
+ t.Fatal("shutdown did not close SSE")
+ }
+}
+
+func TestProtocolErrorsAndCancellation(t *testing.T) {
+ started := make(chan context.Context, 1)
+ h := NewHandler(func(_ context.Context, key string) (string, error) { return key, nil }, func(user string) Connector {
+ return NewServiceConnector(user, func(context.Context, string, int, int, string, bool) ([]map[string]any, int64, error) {
+ return nil, 0, nil
+ }, func(context.Context, string, int, int, string, bool) ([]map[string]any, int64, error) {
+ return nil, 0, nil
+ }, func(ctx context.Context, _ string, _ RetrievalRequest) (string, error) {
+ started <- ctx
+ <-ctx.Done()
+ return "", ctx.Err()
+ })
+ }, Options{true, true, true})
+ hs := httptest.NewServer(h)
+ defer hs.Close()
+ defer h.Close()
+ for _, tc := range []struct {
+ method, path, body, accept, content string
+ status int
+ }{
+ {"GET", "/mcp", "", "application/json", "application/json", 405},
+ {"DELETE", "/mcp", "", "application/json", "application/json", 405},
+ {"POST", "/mcp", `{"jsonrpc":"2.0","method":"notifications/initialized"}`, "application/json, text/event-stream", "application/json", 202},
+ {"POST", "/mcp", `{`, "application/json, text/event-stream", "application/json", 400},
+ {"POST", "/mcp", `{}`, "application/json, text/event-stream", "text/plain", 415},
+ } {
+ req, _ := http.NewRequest(tc.method, hs.URL+tc.path, strings.NewReader(tc.body))
+ req.Header.Set("Authorization", "Bearer alice")
+ req.Header.Set("Accept", tc.accept)
+ req.Header.Set("Content-Type", tc.content)
+ res, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatal(err)
+ }
+ body, _ := io.ReadAll(res.Body)
+ res.Body.Close()
+ if res.StatusCode != tc.status {
+ t.Fatalf("%s %s: %d %s", tc.method, tc.path, res.StatusCode, body)
+ }
+ }
+ ss := clientSession(t, hs.URL, "json", "alice")
+ ctx, cancel := context.WithCancel(t.Context())
+ done := make(chan struct{})
+ go func() {
+ defer close(done)
+ ss.CallTool(ctx, &sdk.CallToolParams{Name: "ragflow_retrieval", Arguments: map[string]any{"question": "x"}})
+ }()
+ var callctx context.Context
+ select {
+ case callctx = <-started:
+ case <-time.After(2 * time.Second):
+ t.Fatal("call did not start")
+ }
+ if deadline, ok := callctx.Deadline(); !ok || time.Until(deadline) > 60*time.Second {
+ t.Fatal("missing tool deadline")
+ }
+ cancel()
+ select {
+ case <-callctx.Done():
+ case <-time.After(2 * time.Second):
+ t.Fatal("cancellation did not reach service")
+ }
+ <-done
+}
diff --git a/internal/mcp/server.go b/internal/mcp/server.go
index dd73e4ee96..3014b065e5 100644
--- a/internal/mcp/server.go
+++ b/internal/mcp/server.go
@@ -1,46 +1,23 @@
-//
-// 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 mcp exposes native RAGFlow services through the official MCP SDK.
package mcp
import (
"context"
+ _ "embed"
"encoding/json"
"fmt"
- "strings"
+ "time"
+
+ sdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
-// Connector provides the data-access operations the MCP tools need.
-// It abstracts the RAGFlow backend so that tool implementations can use
-// either in-process service calls or out-of-process HTTP calls.
+// Connector is the service boundary shared by both MCP transports.
type Connector interface {
- // ListDatasets returns newline-delimited JSON lines, each containing
- // at minimum {"id": "...", "description": "..."}.
- ListDatasets(ctx context.Context, page, pageSize int, orderby string, desc bool) (string, error)
-
- // ListChats returns newline-delimited JSON lines, each containing
- // at minimum {"id": "...", "name": "...", "description": "..."}.
- ListChats(ctx context.Context, page, pageSize int, orderby string, desc bool) (string, error)
-
- // Retrieval executes a retrieval request and returns the result as
- // a JSON string.
- Retrieval(ctx context.Context, req RetrievalRequest) (string, error)
+ ListDatasets(context.Context, int, int, string, bool) (string, error)
+ ListChats(context.Context, int, int, string, bool) (string, error)
+ Retrieval(context.Context, RetrievalRequest) (string, error)
}
-// RetrievalRequest carries all parameters for a retrieval query.
type RetrievalRequest struct {
DatasetIDs []string `json:"dataset_ids"`
DocumentIDs []string `json:"document_ids"`
@@ -55,392 +32,81 @@ type RetrievalRequest struct {
ForceRefresh bool `json:"force_refresh"`
}
-// Server handles MCP JSON-RPC requests.
-type Server struct {
- connector Connector
- version string
-}
-
-// NewServer creates a new MCP Server.
-func NewServer(connector Connector) *Server {
- return &Server{
- connector: connector,
- version: "1.0.0",
- }
-}
-
-// HandleRequest dispatches a raw JSON-RPC request body and returns the
-// serialized JSON-RPC response. Returns nil if the request is a
-// notification (no id) and requires no response.
-func (s *Server) HandleRequest(ctx context.Context, body []byte) ([]byte, bool, error) {
- // Try to decode as a request (with an id) first.
- var req JSONRPCRequest
- if err := json.Unmarshal(body, &req); err != nil {
- resp := NewParseError()
- data, _ := json.Marshal(resp)
- return data, true, nil
- }
-
- // Notifications have no id — do not send a response.
- if req.ID == nil || string(req.ID) == "null" {
- return nil, false, nil
- }
-
- // Validate jsonrpc field.
- if req.JSONRPC != JSONRPCVersion {
- resp := NewInvalidRequestError(req.ID, "jsonrpc must be \"2.0\"")
- data, _ := json.Marshal(resp)
- return data, true, nil
- }
-
- var resp JSONRPCResponse
-
- switch req.Method {
- case "initialize":
- resp = s.handleInitialize(req.ID)
- case "tools/list":
- resp = s.handleListTools(ctx, req.ID)
- case "tools/call":
- resp = s.handleCallTool(ctx, req.ID, req.Params)
- case "ping":
- resp = s.handlePing(req.ID)
- default:
- resp = NewErrorResponse(req.ID, ErrCodeMethodNotFound,
- fmt.Sprintf("Method not found: %s", req.Method))
- }
-
- data, err := json.Marshal(resp)
- if err != nil {
- return nil, true, fmt.Errorf("failed to marshal response: %w", err)
- }
- return data, true, nil
-}
-
-func (s *Server) handleInitialize(id json.RawMessage) JSONRPCResponse {
- result := InitializeResult{
- ProtocolVersion: MCPProtocolVersion,
- Capabilities: Capabilities{
- Tools: &ToolsCapability{ListChanged: false},
- },
- ServerInfo: ServerInfo{
- Name: ServerName,
- Version: s.version,
- },
- }
- return NewSuccessResponse(id, result)
-}
-
-func (s *Server) handlePing(id json.RawMessage) JSONRPCResponse {
- return NewSuccessResponse(id, struct{}{})
-}
-
-func (s *Server) handleListTools(ctx context.Context, id json.RawMessage) JSONRPCResponse {
- // Fetch dataset and chat descriptions for embedding into tool descriptions,
- // matching the Python MCP server behavior.
- datasetDescription, err := s.connector.ListDatasets(ctx, 1, 100, "create_time", true)
- if err != nil {
- datasetDescription = ""
- }
- chatDescription, err := s.connector.ListChats(ctx, 1, 30, "create_time", true)
- if err != nil {
- chatDescription = ""
- }
-
- tools := []Tool{
- {
- Name: "ragflow_retrieval",
- Description: "Retrieve relevant chunks from the RAGFlow retrieve interface based on the question. You can optionally specify dataset_ids to search only specific datasets, or omit dataset_ids entirely to search across ALL available datasets. You can also optionally specify document_ids to search within specific documents. When dataset_ids is not provided or is empty, the system will automatically search across all available datasets. Below is the list of all available datasets, including their descriptions and IDs:" + datasetDescription,
- InputSchema: InputSchema{
- Type: "object",
- Properties: map[string]Property{
- "dataset_ids": {
- Type: "array",
- Description: "Optional array of dataset IDs to search. If not provided or empty, all datasets will be searched.",
- Items: &Items{Type: "string"},
- },
- "document_ids": {
- Type: "array",
- Description: "Optional array of document IDs to search within.",
- Items: &Items{Type: "string"},
- },
- "question": {
- Type: "string",
- Description: "The question or query to search for.",
- },
- "page": {
- Type: "integer",
- Description: "Page number for pagination",
- Default: 1,
- Minimum: float64Ptr(1),
- },
- "page_size": {
- Type: "integer",
- Description: "Number of results to return per page (default: 10, max recommended: 50 to avoid token limits)",
- Default: 10,
- Minimum: float64Ptr(1),
- Maximum: float64Ptr(100),
- },
- "similarity_threshold": {
- Type: "number",
- Description: "Minimum similarity threshold for results",
- Default: 0.2,
- Minimum: float64Ptr(0),
- Maximum: float64Ptr(1),
- },
- "vector_similarity_weight": {
- Type: "number",
- Description: "Weight for vector similarity vs term similarity",
- Default: 0.3,
- Minimum: float64Ptr(0),
- Maximum: float64Ptr(1),
- },
- "keyword": {
- Type: "boolean",
- Description: "Enable keyword-based search",
- Default: false,
- },
- "top_k": {
- Type: "integer",
- Description: "Maximum results to consider before ranking",
- Default: 1024,
- Minimum: float64Ptr(1),
- Maximum: float64Ptr(1024),
- },
- "rerank_id": {
- Type: "string",
- Description: "Optional reranking model identifier",
- },
- "force_refresh": {
- Type: "boolean",
- Description: "Set to true only if fresh dataset and document metadata is explicitly required. Otherwise, cached metadata is used (default: false).",
- Default: false,
- },
- },
- Required: []string{"question"},
- },
- },
- {
- Name: "ragflow_list_datasets",
- Description: "List all accessible datasets (knowledge bases) in RAGFlow. Returns dataset IDs, names, and descriptions. Use this tool to discover which datasets are available before performing retrieval." + datasetDescription,
- InputSchema: InputSchema{
- Type: "object",
- Properties: map[string]Property{
- "page": {
- Type: "integer",
- Description: "Page number",
- Default: 1,
- Minimum: float64Ptr(1),
- },
- "page_size": {
- Type: "integer",
- Description: "Results per page",
- Default: 100,
- Minimum: float64Ptr(1),
- Maximum: float64Ptr(1000),
- },
- },
- },
- },
- {
- Name: "ragflow_list_chats",
- Description: "List all accessible chat assistants in RAGFlow. Returns chat assistant IDs, names, and descriptions. Use this tool to discover available chat assistants that can be used for conversations." + chatDescription,
- InputSchema: InputSchema{
- Type: "object",
- Properties: map[string]Property{
- "page": {
- Type: "integer",
- Description: "Page number",
- Default: 1,
- Minimum: float64Ptr(1),
- },
- "page_size": {
- Type: "integer",
- Description: "Results per page",
- Default: 30,
- Minimum: float64Ptr(1),
- Maximum: float64Ptr(100),
- },
- },
- },
- },
- }
-
- return NewSuccessResponse(id, ListToolsResult{Tools: tools})
-}
-
-func (s *Server) handleCallTool(ctx context.Context, id json.RawMessage, rawParams json.RawMessage) JSONRPCResponse {
- var params CallToolParams
- if err := json.Unmarshal(rawParams, &params); err != nil {
- return NewErrorResponse(id, ErrCodeInvalidParams,
- fmt.Sprintf("Invalid params: %s", err.Error()))
- }
-
- if params.Arguments == nil {
- params.Arguments = make(map[string]interface{})
- }
-
- switch params.Name {
- case "ragflow_retrieval":
- return s.callRagflowRetrieval(ctx, id, params.Arguments)
- case "ragflow_list_datasets":
- return s.callListDatasets(ctx, id, params.Arguments)
- case "ragflow_list_chats":
- return s.callListChats(ctx, id, params.Arguments)
- default:
- return NewErrorResponse(id, ErrCodeMethodNotFound,
- fmt.Sprintf("Tool not found: %s", params.Name))
- }
-}
-
-func (s *Server) callRagflowRetrieval(ctx context.Context, id json.RawMessage, args map[string]interface{}) JSONRPCResponse {
- req := RetrievalRequest{
- Page: getBoundedIntArg(args, "page", 1, 1, 1_000_000),
- PageSize: getBoundedIntArg(args, "page_size", 10, 1, 100),
- SimilarityThreshold: getBoundedFloat64Arg(args, "similarity_threshold", 0.2, 0, 1),
- VectorSimilarityWeight: getBoundedFloat64Arg(args, "vector_similarity_weight", 0.3, 0, 1),
- Keyword: getBoolArg(args, "keyword", false),
- TopK: getBoundedIntArg(args, "top_k", 1024, 1, 1024),
- ForceRefresh: getBoolArg(args, "force_refresh", false),
- Question: getStringArg(args, "question", ""),
- RerankID: getStringArg(args, "rerank_id", ""),
- }
-
- if v, ok := args["dataset_ids"]; ok {
- req.DatasetIDs = toStringSlice(v)
- }
- if v, ok := args["document_ids"]; ok {
- req.DocumentIDs = toStringSlice(v)
- }
-
- if strings.TrimSpace(req.Question) == "" {
- return NewSuccessResponse(id, NewErrorResult("question is required"))
- }
-
- result, err := s.connector.Retrieval(ctx, req)
- if err != nil {
- return NewSuccessResponse(id, NewErrorResult(err.Error()))
- }
- return NewSuccessResponse(id, NewTextResult(result))
-}
-
-func (s *Server) callListDatasets(ctx context.Context, id json.RawMessage, args map[string]interface{}) JSONRPCResponse {
- page := getBoundedIntArg(args, "page", 1, 1, 1_000_000)
- pageSize := getBoundedIntArg(args, "page_size", 100, 1, 1000)
-
- result, err := s.connector.ListDatasets(ctx, page, pageSize, "create_time", true)
- if err != nil {
- return NewSuccessResponse(id, NewErrorResult(err.Error()))
- }
- return NewSuccessResponse(id, NewTextResult(result))
-}
-
-func (s *Server) callListChats(ctx context.Context, id json.RawMessage, args map[string]interface{}) JSONRPCResponse {
- page := getBoundedIntArg(args, "page", 1, 1, 1_000_000)
- pageSize := getBoundedIntArg(args, "page_size", 30, 1, 100)
-
- result, err := s.connector.ListChats(ctx, page, pageSize, "create_time", true)
- if err != nil {
- return NewSuccessResponse(id, NewErrorResult(err.Error()))
- }
- return NewSuccessResponse(id, NewTextResult(result))
-}
-
-// --- argument extraction helpers ---
-
-func getStringArg(args map[string]interface{}, key, defaultVal string) string {
- if v, ok := args[key]; ok {
- if s, ok := v.(string); ok {
- return s
- }
- }
- return defaultVal
-}
-
-func getIntArg(args map[string]interface{}, key string, defaultVal int) int {
- if v, ok := args[key]; ok {
- switch n := v.(type) {
- case float64:
- return int(n)
- case int:
- return n
- case int64:
- return int(n)
- case json.Number:
- if i, err := n.Int64(); err == nil {
- return int(i)
- }
- }
- }
- return defaultVal
-}
-
-func getBoundedIntArg(args map[string]interface{}, key string, defaultVal, minVal, maxVal int) int {
- v := getIntArg(args, key, defaultVal)
- if v < minVal {
- return minVal
- }
- if v > maxVal {
- return maxVal
- }
- return v
-}
-
-func getFloat64Arg(args map[string]interface{}, key string, defaultVal float64) float64 {
- if v, ok := args[key]; ok {
- switch f := v.(type) {
- case float64:
- return f
- case int:
- return float64(f)
- case int64:
- return float64(f)
- case json.Number:
- if fl, err := f.Float64(); err == nil {
- return fl
+// toolsJSON contains the schemas and base descriptions from mcp/server/server.py.
+//
+//go:embed tools.json
+var toolsJSON []byte
+
+func textResult(text string) *sdk.CallToolResult {
+ return &sdk.CallToolResult{Content: []sdk.Content{&sdk.TextContent{Text: text}}}
+}
+
+func newServer(ctx context.Context, connector Connector) *sdk.Server {
+ server := sdk.NewServer(&sdk.Implementation{Name: "ragflow-mcp-server", Version: "1.0.0"}, &sdk.ServerOptions{
+ Capabilities: &sdk.ServerCapabilities{Tools: &sdk.ToolCapabilities{}},
+ SupportedProtocolVersions: []string{"2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"},
+ })
+ var tools []*sdk.Tool
+ if err := json.Unmarshal(toolsJSON, &tools); err != nil {
+ panic(err)
+ }
+ sdk.AddTool(server, tools[0], func(ctx context.Context, _ *sdk.CallToolRequest, input RetrievalRequest) (*sdk.CallToolResult, any, error) {
+ text, err := connector.Retrieval(ctx, input)
+ return textResult(text), nil, err
+ })
+ type pageInput struct {
+ Page int `json:"page"`
+ PageSize int `json:"page_size"`
+ }
+ sdk.AddTool(server, tools[1], func(ctx context.Context, _ *sdk.CallToolRequest, input pageInput) (*sdk.CallToolResult, any, error) {
+ text, err := connector.ListDatasets(ctx, input.Page, input.PageSize, "create_time", true)
+ return textResult(text), nil, err
+ })
+ sdk.AddTool(server, tools[2], func(ctx context.Context, _ *sdk.CallToolRequest, input pageInput) (*sdk.CallToolResult, any, error) {
+ text, err := connector.ListChats(ctx, input.Page, input.PageSize, "create_time", true)
+ return textResult(text), nil, err
+ })
+ requestContext := ctx
+ server.AddReceivingMiddleware(func(next sdk.MethodHandler) sdk.MethodHandler {
+ return func(ctx context.Context, method string, req sdk.Request) (sdk.Result, error) {
+ ctx, cancel := context.WithTimeout(ctx, 60*time.Second)
+ defer cancel()
+ stop := context.AfterFunc(requestContext, cancel)
+ defer stop()
+ if method == "tools/list" {
+ datasets, err := connector.ListDatasets(ctx, 1, -1, "create_time", true)
+ if err != nil {
+ return nil, err
+ }
+ chats, err := connector.ListChats(ctx, 1, 30, "create_time", true)
+ if err != nil {
+ return nil, err
+ }
+ // Descriptions are built for this request, never stored on a shared server.
+ result := &sdk.ListToolsResult{Tools: make([]*sdk.Tool, len(tools))}
+ for i, tool := range tools {
+ copy := *tool
+ if i == 2 {
+ copy.Description += chats
+ } else {
+ copy.Description += datasets
+ }
+ result.Tools[i] = &copy
+ }
+ return result, nil
}
- }
- }
- return defaultVal
-}
-
-func getBoundedFloat64Arg(args map[string]interface{}, key string, defaultVal, minVal, maxVal float64) float64 {
- v := getFloat64Arg(args, key, defaultVal)
- if v < minVal {
- return minVal
- }
- if v > maxVal {
- return maxVal
- }
- return v
-}
-
-func getBoolArg(args map[string]interface{}, key string, defaultVal bool) bool {
- if v, ok := args[key]; ok {
- if b, ok := v.(bool); ok {
- return b
- }
- if s, ok := v.(string); ok {
- switch strings.ToLower(s) {
- case "true", "1", "yes":
- return true
- case "false", "0", "no":
- return false
+ if method == "tools/call" {
+ call := req.(*sdk.CallToolRequest)
+ switch call.Params.Name {
+ case "ragflow_retrieval", "ragflow_list_datasets", "ragflow_list_chats":
+ default:
+ result := textResult(fmt.Sprintf("Tool not found: %s", call.Params.Name))
+ result.IsError = true
+ return result, nil
+ }
}
+ return next(ctx, method, req)
}
- }
- return defaultVal
-}
-
-// toStringSlice converts an interface{} value (expected to be a JSON array)
-// into a []string. Values are converted via fmt.Sprintf.
-func toStringSlice(v interface{}) []string {
- arr, ok := v.([]interface{})
- if !ok {
- return nil
- }
- result := make([]string, 0, len(arr))
- for _, item := range arr {
- result = append(result, fmt.Sprintf("%v", item))
- }
- return result
+ })
+ return server
}
diff --git a/internal/mcp/tools.json b/internal/mcp/tools.json
new file mode 100644
index 0000000000..4c8dc0cd1e
--- /dev/null
+++ b/internal/mcp/tools.json
@@ -0,0 +1,124 @@
+[
+ {
+ "name": "ragflow_retrieval",
+ "description": "Retrieve relevant chunks from the RAGFlow retrieve interface based on the question. You can optionally specify dataset_ids to search only specific datasets, or omit dataset_ids entirely to search across ALL available datasets. You can also optionally specify document_ids to search within specific documents. When dataset_ids is not provided or is empty, the system will automatically search across all available datasets. Below is the list of all available datasets, including their descriptions and IDs:",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "dataset_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Optional array of dataset IDs to search. If not provided or empty, all datasets will be searched."
+ },
+ "document_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Optional array of document IDs to search within."
+ },
+ "question": {
+ "type": "string",
+ "description": "The question or query to search for."
+ },
+ "page": {
+ "type": "integer",
+ "description": "Page number for pagination",
+ "default": 1,
+ "minimum": 1
+ },
+ "page_size": {
+ "type": "integer",
+ "description": "Number of results to return per page (default: 10, max recommended: 50 to avoid token limits)",
+ "default": 10,
+ "minimum": 1,
+ "maximum": 100
+ },
+ "similarity_threshold": {
+ "type": "number",
+ "description": "Minimum similarity threshold for results",
+ "default": 0.2,
+ "minimum": 0.0,
+ "maximum": 1.0
+ },
+ "vector_similarity_weight": {
+ "type": "number",
+ "description": "Weight for vector similarity vs term similarity",
+ "default": 0.3,
+ "minimum": 0.0,
+ "maximum": 1.0
+ },
+ "keyword": {
+ "type": "boolean",
+ "description": "Enable keyword-based search",
+ "default": false
+ },
+ "top_k": {
+ "type": "integer",
+ "description": "Maximum results to consider before ranking",
+ "default": 1024,
+ "minimum": 1,
+ "maximum": 1024
+ },
+ "rerank_id": {
+ "type": "string",
+ "description": "Optional reranking model identifier"
+ },
+ "force_refresh": {
+ "type": "boolean",
+ "description": "Set to true only if fresh dataset and document metadata is explicitly required. Otherwise, cached metadata is used (default: false).",
+ "default": false
+ }
+ },
+ "required": [
+ "question"
+ ]
+ }
+ },
+ {
+ "name": "ragflow_list_datasets",
+ "description": "List all accessible datasets (knowledge bases) in RAGFlow. Returns dataset IDs, names, and descriptions. Use this tool to discover which datasets are available before performing retrieval.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "page": {
+ "type": "integer",
+ "description": "Page number",
+ "default": 1,
+ "minimum": 1
+ },
+ "page_size": {
+ "type": "integer",
+ "description": "Results per page",
+ "default": 100,
+ "minimum": 1,
+ "maximum": 1000
+ }
+ }
+ }
+ },
+ {
+ "name": "ragflow_list_chats",
+ "description": "List all accessible chat assistants in RAGFlow. Returns chat assistant IDs, names, and descriptions. Use this tool to discover available chat assistants that can be used for conversations.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "page": {
+ "type": "integer",
+ "description": "Page number",
+ "default": 1,
+ "minimum": 1
+ },
+ "page_size": {
+ "type": "integer",
+ "description": "Results per page",
+ "default": 30,
+ "minimum": 1,
+ "maximum": 100
+ }
+ }
+ }
+ }
+]
diff --git a/internal/mcp/types.go b/internal/mcp/types.go
deleted file mode 100644
index fa7d407e31..0000000000
--- a/internal/mcp/types.go
+++ /dev/null
@@ -1,225 +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 mcp implements the MCP (Model Context Protocol) server embedded in
-// the RAGFlow Go backend. It exposes RAGFlow capabilities (retrieval, dataset
-// listing, chat listing) as MCP tools that external AI clients can discover
-// and invoke via JSON-RPC over HTTP.
-package mcp
-
-import (
- "encoding/json"
- "fmt"
-)
-
-// JSONRPCVersion is the protocol version string.
-const JSONRPCVersion = "2.0"
-
-// MCPProtocolVersion is the MCP protocol version this server implements.
-const MCPProtocolVersion = "2024-11-05"
-
-// ServerName identifies this MCP server instance.
-const ServerName = "ragflow-mcp-server"
-
-// JSONRPCRequest represents a JSON-RPC 2.0 request.
-type JSONRPCRequest struct {
- JSONRPC string `json:"jsonrpc"`
- ID json.RawMessage `json:"id"`
- Method string `json:"method"`
- Params json.RawMessage `json:"params,omitempty"`
-}
-
-// JSONRPCResponse represents a JSON-RPC 2.0 response.
-type JSONRPCResponse struct {
- JSONRPC string `json:"jsonrpc"`
- ID json.RawMessage `json:"id"`
- Result interface{} `json:"result,omitempty"`
- Error *JSONRPCError `json:"error,omitempty"`
-}
-
-// JSONRPCNotification represents a JSON-RPC 2.0 notification
-// (a request without an id, which requires no response).
-type JSONRPCNotification struct {
- JSONRPC string `json:"jsonrpc"`
- Method string `json:"method"`
- Params json.RawMessage `json:"params,omitempty"`
-}
-
-// JSONRPCError represents a JSON-RPC 2.0 error object.
-type JSONRPCError struct {
- Code int `json:"code"`
- Message string `json:"message"`
- Data interface{} `json:"data,omitempty"`
-}
-
-// Predefined JSON-RPC error codes.
-const (
- ErrCodeParseError = -32700
- ErrCodeInvalidRequest = -32600
- ErrCodeMethodNotFound = -32601
- ErrCodeInvalidParams = -32602
- ErrCodeInternalError = -32603
-)
-
-// InitializeResult is the response payload for the "initialize" method.
-type InitializeResult struct {
- ProtocolVersion string `json:"protocolVersion"`
- Capabilities Capabilities `json:"capabilities"`
- ServerInfo ServerInfo `json:"serverInfo"`
-}
-
-// Capabilities describes the set of MCP capabilities this server supports.
-type Capabilities struct {
- Tools *ToolsCapability `json:"tools,omitempty"`
-}
-
-// ToolsCapability indicates that the server supports tools and optionally
-// whether tool list changes are notified.
-type ToolsCapability struct {
- ListChanged bool `json:"listChanged,omitempty"`
-}
-
-// ServerInfo provides identifying information about the MCP server.
-type ServerInfo struct {
- Name string `json:"name"`
- Version string `json:"version"`
-}
-
-// Tool represents an MCP tool definition.
-type Tool struct {
- Name string `json:"name"`
- Description string `json:"description"`
- InputSchema InputSchema `json:"inputSchema"`
-}
-
-// InputSchema is the JSON Schema for a tool's input parameters.
-type InputSchema struct {
- Type string `json:"type"`
- Properties map[string]Property `json:"properties,omitempty"`
- Required []string `json:"required,omitempty"`
-}
-
-// Property describes a single parameter in a tool's InputSchema.
-type Property struct {
- Type string `json:"type"`
- Description string `json:"description,omitempty"`
- Default interface{} `json:"default,omitempty"`
- Minimum *float64 `json:"minimum,omitempty"`
- Maximum *float64 `json:"maximum,omitempty"`
- Items *Items `json:"items,omitempty"`
-}
-
-// Items describes the expected element type for array-typed properties.
-type Items struct {
- Type string `json:"type"`
-}
-
-// ListToolsResult is the result of the "tools/list" method.
-type ListToolsResult struct {
- Tools []Tool `json:"tools"`
-}
-
-// CallToolParams is the params payload for the "tools/call" method.
-type CallToolParams struct {
- Name string `json:"name"`
- Arguments map[string]interface{} `json:"arguments,omitempty"`
-}
-
-// CallToolResult is the result of the "tools/call" method.
-type CallToolResult struct {
- Content []ContentItem `json:"content"`
- IsError bool `json:"isError,omitempty"`
-}
-
-// ContentItem is a single item in a CallToolResult's content array.
-type ContentItem struct {
- Type string `json:"type"`
- Text string `json:"text,omitempty"`
- Data string `json:"data,omitempty"`
- // MIME Type of the data, if present.
- MIMEType string `json:"mimeType,omitempty"`
-}
-
-// NewErrorResponse creates a JSONRPCResponse with an error.
-func NewErrorResponse(id json.RawMessage, code int, message string) JSONRPCResponse {
- return JSONRPCResponse{
- JSONRPC: JSONRPCVersion,
- ID: id,
- Error: &JSONRPCError{
- Code: code,
- Message: message,
- },
- }
-}
-
-// NewSuccessResponse creates a JSONRPCResponse with a result.
-func NewSuccessResponse(id json.RawMessage, result interface{}) JSONRPCResponse {
- return JSONRPCResponse{
- JSONRPC: JSONRPCVersion,
- ID: id,
- Result: result,
- }
-}
-
-// NewTextContent creates a ContentItem of type "text".
-func NewTextContent(text string) ContentItem {
- return ContentItem{Type: "text", Text: text}
-}
-
-// NewTextResult creates a CallToolResult with a single text content item.
-func NewTextResult(text string) *CallToolResult {
- return &CallToolResult{
- Content: []ContentItem{NewTextContent(text)},
- }
-}
-
-// NewErrorResult creates a CallToolResult indicating a tool execution error.
-func NewErrorResult(errMsg string) *CallToolResult {
- return &CallToolResult{
- Content: []ContentItem{NewTextContent(errMsg)},
- IsError: true,
- }
-}
-
-// NewParseError creates a standard Parse Error response (id is set to null).
-func NewParseError() JSONRPCResponse {
- return JSONRPCResponse{
- JSONRPC: JSONRPCVersion,
- ID: nil,
- Error: &JSONRPCError{
- Code: ErrCodeParseError,
- Message: "Parse error",
- },
- }
-}
-
-// NewInvalidRequestError creates a standard Invalid Request response.
-func NewInvalidRequestError(id json.RawMessage, msg string) JSONRPCResponse {
- return JSONRPCResponse{
- JSONRPC: JSONRPCVersion,
- ID: id,
- Error: &JSONRPCError{
- Code: ErrCodeInvalidRequest,
- Message: fmt.Sprintf("Invalid Request: %s", msg),
- },
- }
-}
-
-// float64Ptr returns a pointer to a float64 value, used for Property
-// minimum/maximum defaults.
-func float64Ptr(v float64) *float64 {
- return &v
-}