Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(mcp): support document-scoped knowledge search (#4463)

Jarvis7438142cf808
diff --git a/internal/mcpserver/scope.go b/internal/mcpserver/scope.go
index 1c7b7f7b1..d48aa7c4f 100644
--- a/internal/mcpserver/scope.go
+++ b/internal/mcpserver/scope.go
@@ -172,6 +172,51 @@ func searchTargetsFor(kbs []*types.KnowledgeBase) types.SearchTargets {
return targets
}
+// maxSearchKnowledgeDocuments bounds validation lookups and backend filter size.
+const maxSearchKnowledgeDocuments = 100
+
+// documentSearchTargets narrows an already authorized KB selection to explicit
+// documents. Never leave whole-KB targets for bases with no selected documents.
+func (s *Server) documentSearchTargets(
+ ctx context.Context, kbs []*types.KnowledgeBase, knowledgeIDs []string,
+) (types.SearchTargets, error) {
+ if len(knowledgeIDs) == 0 {
+ return nil, fmt.Errorf("knowledge_ids must contain at least one document id; " +
+ "omit it to search whole knowledge bases")
+ }
+ if len(knowledgeIDs) > maxSearchKnowledgeDocuments {
+ return nil, fmt.Errorf("knowledge_ids must contain at most %d document ids", maxSearchKnowledgeDocuments)
+ }
+ targets := make(types.SearchTargets, 0)
+ byKB := make(map[string]*types.SearchTarget)
+ seen := make(map[string]bool, len(knowledgeIDs))
+ for _, id := range knowledgeIDs {
+ id = strings.TrimSpace(id)
+ if id == "" {
+ return nil, fmt.Errorf("knowledge_ids must not contain blank document ids")
+ }
+ if seen[id] {
+ continue
+ }
+ k, kb, err := s.knowledgeInKnowledgeBases(ctx, kbs, id)
+ if err != nil {
+ return nil, err
+ }
+ target := byKB[kb.ID]
+ if target == nil {
+ target = &types.SearchTarget{
+ Type: types.SearchTargetTypeKnowledge, KnowledgeBaseID: kb.ID, TenantID: kb.TenantID,
+ DisableRecallThresholds: true,
+ }
+ byKB[kb.ID] = target
+ targets = append(targets, target)
+ }
+ target.KnowledgeIDs = append(target.KnowledgeIDs, k.ID)
+ seen[id] = true
+ }
+ return targets, nil
+}
+
func knowledgeBaseIDs(kbs []*types.KnowledgeBase) []string {
ids := make([]string, 0, len(kbs))
for _, kb := range kbs {
@@ -213,6 +258,18 @@ func wikiScopesFor(kbs []*types.KnowledgeBase) []tools.WikiScope {
// then match an allowed knowledge base and that knowledge base's tenant.
func (s *Server) knowledgeInScope(
ctx context.Context, ep *types.MCPEndpoint, knowledgeID string,
+) (*types.Knowledge, *types.KnowledgeBase, error) {
+ allowed, err := s.allowedKnowledgeBases(ctx, ep)
+ if err != nil {
+ return nil, nil, err
+ }
+ return s.knowledgeInKnowledgeBases(ctx, allowed, knowledgeID)
+}
+
+// knowledgeInKnowledgeBases applies the same document/owner checks to either
+// the full endpoint scope or a narrower, already authorized KB selection.
+func (s *Server) knowledgeInKnowledgeBases(
+ ctx context.Context, kbs []*types.KnowledgeBase, knowledgeID string,
) (*types.Knowledge, *types.KnowledgeBase, error) {
knowledgeID = strings.TrimSpace(knowledgeID)
if knowledgeID == "" {
@@ -222,13 +279,16 @@ func (s *Server) knowledgeInScope(
if err != nil || k == nil {
return nil, nil, fmt.Errorf("document %q was not found", knowledgeID)
}
- allowed, err := s.allowedKnowledgeBases(ctx, ep)
- if err != nil {
- return nil, nil, err
+ var kb *types.KnowledgeBase
+ for _, candidate := range kbs {
+ if candidate.ID == k.KnowledgeBaseID {
+ kb = candidate
+ break
+ }
}
- kb := matchKnowledgeBase(allowed, k.KnowledgeBaseID)
if kb == nil || kb.TenantID != k.TenantID {
- return nil, nil, fmt.Errorf("document %q is outside this endpoint's scope", knowledgeID)
+ return nil, nil, fmt.Errorf("document %q is outside this endpoint's scope or the selected knowledge bases",
+ knowledgeID)
}
return k, kb, nil
}
diff --git a/internal/mcpserver/tools_retrieve.go b/internal/mcpserver/tools_retrieve.go
index 4b8228486..074e324f2 100644
--- a/internal/mcpserver/tools_retrieve.go
+++ b/internal/mcpserver/tools_retrieve.go
@@ -53,6 +53,11 @@ func searchKnowledgeTool() mcp.Tool {
mcp.WithArray("knowledge_base_ids", mcp.WithStringItems(),
mcp.Description("Optional knowledge base ids or names to restrict the search; defaults to every "+
"knowledge base in scope")),
+ mcp.WithArray("knowledge_ids",
+ mcp.MinItems(1), mcp.MaxItems(maxSearchKnowledgeDocuments), mcp.WithStringItems(mcp.MinLength(1)),
+ mcp.Description("Optional list of 1 to 100 document ids from list_documents or search results. "+
+ "Restricts retrieval before ranking; every document must be in scope and belong to the selected "+
+ "knowledge bases. Omit to search whole knowledge bases; invalid or conflicting ids return an error.")),
readOnlyEndpointAnnotations(),
)
}
@@ -165,23 +170,28 @@ func (s *Server) handleSearchKnowledge(ctx context.Context, req mcp.CallToolRequ
return mcp.NewToolResultError(
"none of the selected knowledge bases supports semantic or keyword retrieval"), nil
}
- return s.runSearchKnowledge(ctx, kbs, strings.TrimSpace(query),
- req.GetString("mode", tools.SearchModeHybrid), req.GetInt("limit", 0))
+ targets := searchTargetsFor(kbs)
+ if _, supplied := req.GetArguments()["knowledge_ids"]; supplied {
+ ids, err := req.RequireStringSlice("knowledge_ids")
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ targets, err = s.documentSearchTargets(ctx, kbs, ids)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ }
+ return s.runSearchKnowledgeWithFilter(ctx, targets, strings.TrimSpace(query),
+ req.GetString("mode", tools.SearchModeHybrid), req.GetInt("limit", 0), nil)
}
-// runSearchKnowledge executes the shared search_knowledge agent tool for
+// runSearchKnowledgeWithFilter executes the shared search_knowledge agent tool for
// both the search_knowledge and grep_chunks endpoint tools.
-func (s *Server) runSearchKnowledge(
- ctx context.Context, kbs []*types.KnowledgeBase, query, mode string, limit int,
-) (*mcp.CallToolResult, error) {
- return s.runSearchKnowledgeWithFilter(ctx, kbs, query, mode, limit, nil)
-}
-
func (s *Server) runSearchKnowledgeWithFilter(
- ctx context.Context, kbs []*types.KnowledgeBase, query, mode string, limit int, pattern *regexp.Regexp,
+ ctx context.Context, targets types.SearchTargets, query, mode string, limit int, pattern *regexp.Regexp,
) (*mcp.CallToolResult, error) {
tool := tools.NewSearchKnowledgeTool(
- s.kbService, s.knowledgeService, s.chunkService, searchTargetsFor(kbs), nil, s.cfg,
+ s.kbService, s.knowledgeService, s.chunkService, targets, nil, s.cfg,
)
if pattern != nil {
tool.WithPatternFilter(pattern)
@@ -189,7 +199,7 @@ func (s *Server) runSearchKnowledgeWithFilter(
callArgs := map[string]any{
"query": query,
"mode": mode,
- "knowledge_base_ids": knowledgeBaseIDs(kbs),
+ "knowledge_base_ids": targets.GetAllKnowledgeBaseIDs(),
}
if limit > 0 {
callArgs["limit"] = limit
@@ -223,7 +233,7 @@ func (s *Server) handleGrepChunks(ctx context.Context, req mcp.CallToolRequest)
"word, identifier or phrase (for example \"timeout|deadline\" instead of \"^\\d+$\")"), nil
}
return s.runSearchKnowledgeWithFilter(
- ctx, kbs, terms, tools.SearchModeKeyword, req.GetInt("limit", 0), pattern,
+ ctx, searchTargetsFor(kbs), terms, tools.SearchModeKeyword, req.GetInt("limit", 0), pattern,
)
}
diff --git a/internal/mcpserver/tools_search_documents_test.go b/internal/mcpserver/tools_search_documents_test.go
new file mode 100644
index 000000000..5ca03c406
--- /dev/null
+++ b/internal/mcpserver/tools_search_documents_test.go
@@ -0,0 +1,338 @@
+package mcpserver
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "slices"
+ "sync"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/config"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/gin-gonic/gin"
+ "github.com/mark3labs/mcp-go/mcp"
+ "github.com/stretchr/testify/require"
+)
+
+type documentSearchCall struct {
+ kbID string
+ params types.SearchParams
+}
+
+type documentSearchKBService struct {
+ *stubKBService
+ mu sync.Mutex
+ calls []documentSearchCall
+ rows []*types.SearchResult
+}
+
+func (s *documentSearchKBService) GetKnowledgeBasesByIDsOnly(
+ _ context.Context, ids []string,
+) ([]*types.KnowledgeBase, error) {
+ var kbs []*types.KnowledgeBase
+ for _, id := range ids {
+ kbs = append(kbs, s.kbs[id])
+ }
+ return kbs, nil
+}
+
+func (s *documentSearchKBService) ResolveEmbeddingModelKeys(
+ _ context.Context, kbs []*types.KnowledgeBase,
+) map[string]string {
+ keys := make(map[string]string, len(kbs))
+ for _, kb := range kbs {
+ keys[kb.ID] = "fixture-model"
+ }
+ return keys
+}
+
+func (s *documentSearchKBService) GetQueryEmbedding(context.Context, string, string) ([]float32, error) {
+ return []float32{1, 0}, nil
+}
+
+func (s *documentSearchKBService) HybridSearch(
+ _ context.Context, kbID string, params types.SearchParams,
+) ([]*types.SearchResult, error) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.calls = append(s.calls, documentSearchCall{kbID: kbID, params: params})
+ var rows []*types.SearchResult
+ for _, row := range s.rows {
+ inKB := row.KnowledgeBaseID == kbID
+ if len(params.KnowledgeBaseIDs) > 0 {
+ inKB = slices.Contains(params.KnowledgeBaseIDs, row.KnowledgeBaseID)
+ }
+ passesThreshold := (!params.DisableVectorMatch && row.Score >= params.VectorThreshold) ||
+ (!params.DisableKeywordsMatch && row.Score >= params.KeywordThreshold)
+ inDocumentScope := len(params.KnowledgeIDs) == 0 || slices.Contains(params.KnowledgeIDs, row.KnowledgeID)
+ if inKB && passesThreshold && inDocumentScope {
+ rows = append(rows, row)
+ }
+ }
+ // Model the storage boundary: document filtering must precede candidate truncation.
+ return rows[:min(len(rows), params.MatchCount)], nil
+}
+
+func newDocumentSearchFixture(t *testing.T) (*Server, *gin.Engine, *documentSearchKBService, *types.MCPEndpoint) {
+ t.Helper()
+ kbs := map[string]*types.KnowledgeBase{}
+ for _, kb := range []*types.KnowledgeBase{
+ {ID: "kb-own", Name: "Own", TenantID: 1},
+ {ID: "kb-other", Name: "Other", TenantID: 1},
+ {ID: "kb-shared", Name: "Shared", TenantID: 2},
+ {ID: "kb-foreign", TenantID: 3},
+ {ID: "kb-wiki", TenantID: 1},
+ } {
+ kb.IndexingStrategy.VectorEnabled = kb.ID != "kb-wiki"
+ kb.IndexingStrategy.KeywordEnabled = kb.ID != "kb-wiki"
+ kbs[kb.ID] = kb
+ }
+ docs := map[string]*types.Knowledge{}
+ for id, kbID := range map[string]string{
+ "doc-a": "kb-own", "doc-b": "kb-own", "doc-other": "kb-other",
+ "doc-shared": "kb-shared", "doc-foreign": "kb-foreign", "doc-wiki": "kb-wiki",
+ } {
+ docs[id] = &types.Knowledge{ID: id, KnowledgeBaseID: kbID, TenantID: kbs[kbID].TenantID}
+ }
+ docs["doc-spoof"] = &types.Knowledge{ID: "doc-spoof", KnowledgeBaseID: "kb-shared", TenantID: 1}
+ kbService := &documentSearchKBService{stubKBService: &stubKBService{kbs: kbs}}
+ // A newer, higher-ranked same-topic document must not crowd doc-a out of the result limit.
+ for i, id := range []string{"doc-b", "doc-a", "doc-other", "doc-shared"} {
+ kbService.rows = append(kbService.rows, &types.SearchResult{
+ ID: "chunk-" + id, KnowledgeID: id, KnowledgeBaseID: docs[id].KnowledgeBaseID,
+ KnowledgeTitle: id, Content: id + " contract price", Score: 1 - float64(i)*0.1,
+ ChunkType: string(types.ChunkTypeText),
+ })
+ }
+ srv := NewServer(kbService, &stubKnowledgeService{docs: docs}, nil, nil, nil, nil, nil,
+ &stubKBShareService{shared: map[string]types.OrgMemberRole{"kb-shared": types.OrgRoleViewer}},
+ nil, nil, nil, &config.Config{Conversation: &config.ConversationConfig{
+ EmbeddingTopK: 1, VectorThreshold: 0.95, KeywordThreshold: 0.95,
+ }},
+ nil, nil, nil, nil)
+ ep := &types.MCPEndpoint{
+ ID: "ep-1", TenantID: 1, Enabled: true,
+ KnowledgeBaseIDs: types.StringArray{"kb-own", "kb-other", "kb-shared", "kb-wiki"},
+ Tools: types.StringArray{types.MCPEndpointToolSearchKnowledge, types.MCPEndpointToolGrepChunks},
+ }
+ r := gin.New()
+ r.POST("/mcp/:endpoint_id", func(c *gin.Context) {
+ c.Request = c.Request.WithContext(mcpCallContext(1, ep))
+ c.Next()
+ }, gin.WrapH(srv.Handler()))
+ return srv, r, kbService, ep
+}
+
+func TestMCPSearchKnowledgeDocumentScopeBeforeRetrieval(t *testing.T) {
+ for _, mode := range []string{"hybrid", "semantic", "keyword"} {
+ t.Run(mode, func(t *testing.T) {
+ _, r, kbService, _ := newDocumentSearchFixture(t)
+ response := rpc(t, r, "tools/call", map[string]any{
+ "name": types.MCPEndpointToolSearchKnowledge,
+ "arguments": map[string]any{
+ "query": "contract price", "mode": mode, "limit": 1,
+ "knowledge_ids": []string{" doc-a ", "doc-a"},
+ },
+ })
+ require.NotContains(t, response, "error")
+ raw, err := json.Marshal(response["result"])
+ require.NoError(t, err)
+ var result struct {
+ IsError bool `json:"isError"`
+ Content []struct{ Text string } `json:"content"`
+ Data struct {
+ Results []struct {
+ KnowledgeID string `json:"knowledge_id"`
+ } `json:"results"`
+ } `json:"structuredContent"`
+ }
+ require.NoError(t, json.Unmarshal(raw, &result))
+ require.False(t, result.IsError, "%s", raw)
+ require.Len(t, result.Data.Results, 1)
+ require.Equal(t, "doc-a", result.Data.Results[0].KnowledgeID)
+ require.Contains(t, result.Content[0].Text, `knowledge_id="doc-a"`)
+ require.NotContains(t, result.Content[0].Text, `knowledge_id="doc-b"`)
+ require.Len(t, kbService.calls, 1)
+ call := kbService.calls[0]
+ require.Equal(t, "kb-own", call.kbID)
+ require.Equal(t, []string{"doc-a"}, call.params.KnowledgeIDs)
+ require.Empty(t, call.params.KnowledgeBaseIDs)
+ require.Equal(t, 1, call.params.MatchCount)
+ require.Equal(t, mode == "keyword", call.params.DisableVectorMatch)
+ require.Equal(t, mode == "semantic", call.params.DisableKeywordsMatch)
+ require.Zero(t, call.params.VectorThreshold)
+ require.Zero(t, call.params.KeywordThreshold)
+ })
+ }
+}
+
+func TestMCPSearchKnowledgeMultipleDocumentsAndSharedScope(t *testing.T) {
+ _, r, kbService, _ := newDocumentSearchFixture(t)
+ response := rpc(t, r, "tools/call", map[string]any{
+ "name": types.MCPEndpointToolSearchKnowledge,
+ "arguments": map[string]any{
+ "query": "contract", "knowledge_base_ids": []string{"Own", "Shared", "Other"},
+ "knowledge_ids": []string{"doc-a", "doc-b", "doc-shared", "doc-a"},
+ },
+ })
+ require.NotContains(t, response, "error")
+ result := response["result"].(map[string]any)
+ require.NotEqual(t, true, result["isError"], "%+v", result)
+ var ids []string
+ for _, raw := range result["structuredContent"].(map[string]any)["results"].([]any) {
+ ids = append(ids, raw.(map[string]any)["knowledge_id"].(string))
+ }
+ require.ElementsMatch(t, []string{"doc-a", "doc-b", "doc-shared"}, ids)
+ require.Len(t, kbService.calls, 2)
+ byKB := map[string][]string{}
+ for _, call := range kbService.calls {
+ byKB[call.kbID] = call.params.KnowledgeIDs
+ }
+ require.Equal(t, map[string][]string{
+ "kb-own": {"doc-a", "doc-b"}, "kb-shared": {"doc-shared"},
+ }, byKB)
+}
+
+func TestMCPSearchKnowledgeRejectsInvalidDocumentScope(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ ids any
+ kbs []string
+ }{
+ {name: "missing document", ids: []string{"missing"}},
+ {name: "foreign document", ids: []string{"doc-foreign"}},
+ {name: "tenant mismatch", ids: []string{"doc-spoof"}},
+ {name: "empty intersection", ids: []string{"doc-a"}, kbs: []string{"Shared"}},
+ {name: "partial conflict", ids: []string{"doc-a", "doc-shared"}, kbs: []string{"Own"}},
+ {name: "non-retrievable document", ids: []string{"doc-wiki"}},
+ {name: "empty array", ids: []string{}},
+ {name: "null", ids: nil},
+ {name: "string", ids: "doc-a"},
+ {name: "mixed types", ids: []any{"doc-a", 42}},
+ {name: "null entry", ids: []any{"doc-a", nil}},
+ {name: "blank entry", ids: []string{"doc-a", " "}},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ srv, _, kbService, ep := newDocumentSearchFixture(t)
+ args := map[string]any{"query": "contract", "knowledge_ids": tc.ids}
+ if tc.kbs != nil {
+ args["knowledge_base_ids"] = tc.kbs
+ }
+ result, err := srv.handleSearchKnowledge(mcpCallContext(1, ep), mcp.CallToolRequest{
+ Params: mcp.CallToolParams{Arguments: args},
+ })
+ require.NoError(t, err)
+ require.True(t, result.IsError, "%+v", result)
+ require.Empty(t, kbService.calls, "invalid scope must never fall back to whole-KB retrieval")
+ })
+ }
+}
+
+func TestMCPSearchKnowledgeOmittedDocumentScopeAndGrepKeepWholeKBTargets(t *testing.T) {
+ for _, tool := range []string{types.MCPEndpointToolSearchKnowledge, types.MCPEndpointToolGrepChunks} {
+ t.Run(tool, func(t *testing.T) {
+ _, r, kbService, _ := newDocumentSearchFixture(t)
+ response := rpc(t, r, "tools/call", map[string]any{
+ "name": tool, "arguments": map[string]any{
+ "query": "contract", "knowledge_base_ids": []string{"Own"},
+ },
+ })
+ require.NotContains(t, response, "error")
+ require.Len(t, kbService.calls, 1)
+ require.Empty(t, kbService.calls[0].params.KnowledgeIDs)
+ require.Equal(t, []string{"kb-own"}, kbService.calls[0].params.KnowledgeBaseIDs)
+ require.Equal(t, 0.95, kbService.calls[0].params.VectorThreshold)
+ require.Equal(t, 0.95, kbService.calls[0].params.KeywordThreshold)
+ })
+ }
+}
+
+func TestMCPSearchKnowledgeDocumentScopeSchema(t *testing.T) {
+ _, r, _, _ := newDocumentSearchFixture(t)
+ response := rpc(t, r, "tools/list", map[string]any{})
+ result := response["result"].(map[string]any)
+ for _, raw := range result["tools"].([]any) {
+ tool := raw.(map[string]any)
+ if tool["name"] != types.MCPEndpointToolSearchKnowledge {
+ continue
+ }
+ schema := tool["inputSchema"].(map[string]any)
+ property := schema["properties"].(map[string]any)["knowledge_ids"].(map[string]any)
+ require.Equal(t, "array", property["type"])
+ require.EqualValues(t, 1, property["minItems"])
+ require.EqualValues(t, 100, property["maxItems"])
+ require.Equal(t, "string", property["items"].(map[string]any)["type"])
+ require.NotContains(t, schema["required"], "knowledge_ids")
+ return
+ }
+ t.Fatal("search_knowledge is missing from tools/list")
+}
+
+func TestMCPSearchKnowledgeRechecksEndpointAndShareRestrictions(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ shared bool
+ }{
+ {name: "endpoint restriction"},
+ {name: "revoked share", shared: true},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ srv, r, kbService, ep := newDocumentSearchFixture(t)
+ id := "doc-other"
+ if tc.shared {
+ id = "doc-shared"
+ srv.kbShareService = &stubKBShareService{shared: map[string]types.OrgMemberRole{}}
+ } else {
+ ep.KnowledgeBaseIDs = types.StringArray{"kb-own"}
+ }
+ response := rpc(t, r, "tools/call", map[string]any{
+ "name": types.MCPEndpointToolSearchKnowledge,
+ "arguments": map[string]any{"query": "contract", "knowledge_ids": []string{id}},
+ })
+ require.NotContains(t, response, "error")
+ require.Equal(t, true, response["result"].(map[string]any)["isError"])
+ require.Empty(t, kbService.calls)
+ })
+ }
+}
+
+// Count lookups to ensure oversized requests are rejected before any document I/O.
+type countingDocumentService struct {
+ *stubKnowledgeService
+ lookups int
+}
+
+func (s *countingDocumentService) GetKnowledgeByIDOnly(ctx context.Context, id string) (*types.Knowledge, error) {
+ s.lookups++
+ return s.stubKnowledgeService.GetKnowledgeByIDOnly(ctx, id)
+}
+
+func TestMCPSearchKnowledgeDocumentScopeSizeLimit(t *testing.T) {
+ for _, count := range []int{100, 101} {
+ t.Run(fmt.Sprint(count), func(t *testing.T) {
+ srv, _, kbService, ep := newDocumentSearchFixture(t)
+ service := &countingDocumentService{stubKnowledgeService: srv.knowledgeService.(*stubKnowledgeService)}
+ srv.knowledgeService = service
+ ids := make([]string, count)
+ for i := range ids {
+ ids[i] = fmt.Sprintf("selected-%d", i)
+ service.docs[ids[i]] = &types.Knowledge{ID: ids[i], KnowledgeBaseID: "kb-own", TenantID: 1}
+ }
+ result, err := srv.handleSearchKnowledge(mcpCallContext(1, ep), mcp.CallToolRequest{
+ Params: mcp.CallToolParams{Arguments: map[string]any{"query": "contract", "knowledge_ids": ids}},
+ })
+ require.NoError(t, err)
+ if count == 100 {
+ require.False(t, result.IsError)
+ require.Equal(t, count, service.lookups)
+ require.Len(t, kbService.calls, 1)
+ require.Len(t, kbService.calls[0].params.KnowledgeIDs, count)
+ } else {
+ require.True(t, result.IsError)
+ require.Zero(t, service.lookups)
+ require.Empty(t, kbService.calls)
+ }
+ })
+ }
+}
diff --git a/website-docs/03-features/08-mcp.md b/website-docs/03-features/08-mcp.md
index b52a5320e..7cd9f7e9d 100644
--- a/website-docs/03-features/08-mcp.md
+++ b/website-docs/03-features/08-mcp.md
@@ -55,6 +55,24 @@ MCP 管理页支持按服务名称和卡片显示的用途说明搜索。搜索
| Wiki | `wiki_search`、`wiki_read_page`、`wiki_index` | 只对开启了 Wiki 的知识库生效;`wiki_search` 的 `query` 保持原有的正则语义(大小写不敏感),不是合法正则的文本按字面匹配;`regex=false` 强制字面匹配,`regex=true` 要求合法正则 |
| 写入 | `add_document`、`update_document`、`delete_document` | 默认关闭;支持 Markdown 文本或 URL 导入 |
+`search_knowledge` 可通过可选的 `knowledge_ids` 字符串数组限定文档范围,三种 `mode` 均支持。先用 `list_documents` 或搜索结果取得真实文档 ID,再传入这些 ID;文档过滤在召回和候选数截断之前生效,同库其他文档不会参与此次检索。省略该参数时沿用整库检索。传入时数组必须非空,且不能包含空白 ID;ID 两端空白会被去除,重复 ID 自动去重。
+
+若同时传入 `knowledge_base_ids`,每个文档都必须属于所选知识库;仅检索这些文档,不会额外搜索所选库里的其他文档。不存在的文档、越权文档、与知识库选择冲突的文档或没有向量/关键词索引的文档都会返回错误,整次调用不会退回整库检索。共享知识库沿用端点授权和所属空间校验。
+
+例如,假设 `list_documents` 已返回 `doc-a` 和 `doc-b`,`tools/call` 的参数可以写为:
+
+```json
+{
+ "name": "search_knowledge",
+ "arguments": {
+ "query": "合同价格",
+ "mode": "hybrid",
+ "knowledge_ids": ["doc-a", "doc-b"],
+ "limit": 10
+ }
+}
+```
+
`search_knowledge` 的结构化结果 `results[].chunk_type` 和文本结果的 `chunk_type` 属性保留命中片段的原始类型,例如 `text`、`summary`、`image_ocr`、`image_caption` 或 `image_vector`。空字符串表示类型未知,不能据此认定为原文;客户端可据类型决定是否补读文档正文。
现有 MCP 工具的返回结果会复用 REST/IM 的资源链接转换:正文、Wiki 内容以及结构化数据中的图片引用,都会在权限校验后转换为可直接访问的 HTTP(S) 链接,不需要新增工具或修改端点工具清单。`ask` 的 `references[].images` 保留图片 URL、caption 和 OCR 文本,文本引用列表也包含图片链接,避免正文摘要截断后丢失图片信息。