RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
fix(mcp): send rerank_candidates_count so retrieval paging works past 64 results (#19018)
xu jiaming3dab5db31510
diff --git a/internal/handler/mcp_retrieval_window_test.go b/internal/handler/mcp_retrieval_window_test.gonew file mode 100644index 0000000000..cc913fc917--- /dev/null+++ b/internal/handler/mcp_retrieval_window_test.go@@ -0,0 +1,53 @@+package handler++import (+ "math"+ "strings"+ "testing"+)++func TestValidateRetrievalWindow(t *testing.T) {+ tests := []struct {+ name string+ page int+ pageSize int+ wantErr string+ }{+ {name: "defaults fit the window", page: 0, pageSize: 0}, // treated as 1 x 30+ {name: "first page at schema max", page: 1, pageSize: 100},+ {name: "paging stays inside the window", page: 5, pageSize: 100},+ {name: "exact boundary is allowed", page: 8, pageSize: 64}, // 8 * 64 == 512+ {+ name: "one past the boundary is rejected",+ page: 9,+ pageSize: 64,+ wantErr: "exceeds the fixed rerank candidate window",+ },+ {+ name: "window past the fixed candidates is rejected",+ page: mcpRerankCandidatesCount/100 + 1,+ pageSize: 100,+ wantErr: "exceeds the fixed rerank candidate window",+ },+ {+ name: "max int page cannot overflow the check",+ page: math.MaxInt,+ pageSize: math.MaxInt,+ wantErr: "exceeds the fixed rerank candidate window",+ },+ }+ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ err := validateRetrievalWindow(tt.page, tt.pageSize)+ if tt.wantErr == "" {+ if err != nil {+ t.Fatalf("validateRetrievalWindow(%d, %d) = %v, want nil", tt.page, tt.pageSize, err)+ }+ return+ }+ if err == nil || !strings.Contains(err.Error(), tt.wantErr) {+ t.Fatalf("validateRetrievalWindow(%d, %d) = %v, want error containing %q", tt.page, tt.pageSize, err, tt.wantErr)+ }+ })+ }+}diff --git a/internal/handler/mcp_server.go b/internal/handler/mcp_server.goindex 9346363bb3..0b1fc943b8 100644--- a/internal/handler/mcp_server.go+++ b/internal/handler/mcp_server.go@@ -141,10 +141,36 @@ func MCPListChats(ctx context.Context, chatService *service.ChatService, userIDreturn 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@@ -197,6 +223,10 @@ func MCPRetrieval(ctx context.Context, ds *dataset.DatasetService, userID stringv := req.RerankIDsearchReq.RerankID = &v}+ {+ v := mcpRerankCandidatesCount+ searchReq.RerankCandidatesCount = &v+ }{v := req.KeywordsearchReq.Keyword = &vdiff --git a/mcp/server/server.py b/mcp/server/server.pyindex 2b94c2a037..1fafcf857b 100644--- a/mcp/server/server.py+++ b/mcp/server/server.py@@ -63,6 +63,12 @@ class RAGFlowConnector:_CACHE_TTL = 300# Keep in sync with api.utils.pagination_utils.REST_API_MAX_PAGE_SIZE._REST_API_MAX_PAGE_SIZE = 100+ # Fixed rerank candidate window sent with every retrieval request, so the+ # ranking cannot shift between pages of one pagination sequence (the backend+ # reranks this many candidates before slicing the requested page). Requests+ # whose page * page_size exceeds it are rejected up front. Keep in sync with+ # mcpRerankCandidatesCount in internal/handler/mcp_server.go.+ _RERANK_CANDIDATES_COUNT = 512_dataset_metadata_cache: OrderedDict[str, tuple[dict, float | int]] = OrderedDict() # "dataset_id" -> (metadata, expiry_ts)_document_metadata_cache: OrderedDict[str, tuple[list[tuple[str, dict]], float | int]] = OrderedDict() # "dataset_id" -> ([(document_id, doc_metadata)], expiry_ts)@@ -294,6 +300,19 @@ class RAGFlowConnector:logging.info("MCP retrieval found no accessible datasets for current user")raise Exception([types.TextContent(type="text", text="No accessible datasets found.")])+ if page * page_size > self._RERANK_CANDIDATES_COUNT:+ # Fail here rather than letting the backend reject the request: a+ # window past the fixed candidate pool cannot be served with a+ # stable ranking anyway.+ raise Exception(+ [+ types.TextContent(+ type="text",+ text=(f"page * page_size ({page * page_size}) exceeds the fixed rerank candidate window ({self._RERANK_CANDIDATES_COUNT}); narrow page or page_size."),+ )+ ]+ )+data_json = {"page": page,"page_size": page_size,@@ -301,6 +320,10 @@ class RAGFlowConnector:"vector_similarity_weight": vector_similarity_weight,"top_k": top_k,"rerank_id": rerank_id,+ # A fixed window (not page * page_size) keeps the rerank pool — and+ # therefore the ranking — identical on every page of a pagination+ # sequence, so pages cannot drift, duplicate, or skip results.+ "rerank_candidates_count": self._RERANK_CANDIDATES_COUNT,"keyword": keyword,"question": question,"dataset_ids": dataset_ids,diff --git a/test/unit_test/mcp/test_server_retrieval.py b/test/unit_test/mcp/test_server_retrieval.pynew file mode 100644index 0000000000..7008e83b80--- /dev/null+++ b/test/unit_test/mcp/test_server_retrieval.py@@ -0,0 +1,113 @@+#+# 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.+#++import importlib.util+from pathlib import Path++import pytest+++def _load_mcp_server():+ server_path = Path(__file__).resolve().parents[3] / "mcp" / "server" / "server.py"+ spec = importlib.util.spec_from_file_location("ragflow_mcp_server_unit", server_path)+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++class _FakeResponse:+ status_code = 200++ def __init__(self, payload):+ self._payload = payload++ def json(self):+ return self._payload+++def mcp_server():+ return _load_mcp_server()+++def _stub_retrieval(monkeypatch, connector):+ captured = {}++ async def _post(path, json=None, api_key=""):+ captured["path"] = path+ captured["payload"] = dict(json)+ return _FakeResponse({"code": 0, "data": {"chunks": [], "total": 0, "doc_aggs": []}})++ async def _get_document_metadata_cache(*args, **kwargs):+ return {}, {}++ monkeypatch.setattr(connector, "_post", _post)+ monkeypatch.setattr(connector, "_get_document_metadata_cache", _get_document_metadata_cache)+ return captured+++ "page,page_size",+ [+ (1, 10), # default page_size+ (1, 50), # recommended page_size+ (2, 50), # paging keeps the same candidate window+ (7, 10), # default page_size paged past the backend's default 64+ (1, 100), # schema maximum+ ],+)+async def test_retrieval_sends_fixed_rerank_candidates_window(monkeypatch, mcp_server, page, page_size):+ """The candidate window is a fixed constant rather than page * page_size, so+ the rerank pool — and therefore the ranking — stays identical on every page+ of a pagination sequence; a growing window could reorder results between+ pages, duplicating or skipping chunks."""+ connector = mcp_server.RAGFlowConnector(base_url=mcp_server.BASE_URL)+ captured = _stub_retrieval(monkeypatch, connector)++ await connector.retrieval(+ api_key="unit-key",+ dataset_ids=["dataset-1"],+ question="unit question",+ page=page,+ page_size=page_size,+ )++ assert captured["path"] == "/retrieval"+ payload = captured["payload"]+ assert payload["rerank_candidates_count"] == mcp_server.RAGFlowConnector._RERANK_CANDIDATES_COUNT+ assert payload["rerank_candidates_count"] >= page * page_size+++async def test_retrieval_rejects_window_beyond_fixed_candidates(monkeypatch, mcp_server):+ """Requests that cannot fit inside the fixed candidate window fail up front+ with an actionable message instead of surfacing the backend's rejection (or+ worse, silently serving drifting pages)."""+ connector = mcp_server.RAGFlowConnector(base_url=mcp_server.BASE_URL)+ captured = _stub_retrieval(monkeypatch, connector)++ window = mcp_server.RAGFlowConnector._RERANK_CANDIDATES_COUNT+ with pytest.raises(Exception, match="exceeds the fixed rerank candidate window"):+ await connector.retrieval(+ api_key="unit-key",+ dataset_ids=["dataset-1"],+ question="unit question",+ page=window // 100 + 1,+ page_size=100,+ )++ assert "payload" not in captured # rejected before any request was sent