Skip to content

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

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.go
new file mode 100644
index 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.go
index 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, 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
@@ -197,6 +223,10 @@ func MCPRetrieval(ctx context.Context, ds *dataset.DatasetService, userID string
v := req.RerankID
searchReq.RerankID = &v
}
+ {
+ v := mcpRerankCandidatesCount
+ searchReq.RerankCandidatesCount = &v
+ }
{
v := req.Keyword
searchReq.Keyword = &v
diff --git a/mcp/server/server.py b/mcp/server/server.py
index 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.py
new file mode 100644
index 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