Skip to content

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

15.5 KB
Raw Blame
package mcpserver

import (
	"context"
	"encoding/json"
	"regexp"
	"strings"
	"unicode"

	"github.com/Tencent/WeKnora/internal/agent/tools"
	"github.com/Tencent/WeKnora/internal/types"
	"github.com/mark3labs/mcp-go/mcp"
)

const (
	defaultListPageSize = 20
	maxListPageSize     = 100
	defaultChunkLimit   = 20
	maxChunkLimit       = 100
)

// readOnlyEndpointAnnotations overrides mcp.NewTool's defaults. Those defaults
// set destructiveHint and openWorldHint to true, so a read-only hint alone
// still advertises the tool as destructive.
func readOnlyEndpointAnnotations() mcp.ToolOption {
	return func(t *mcp.Tool) {
		mcp.WithReadOnlyHintAnnotation(true)(t)
		mcp.WithDestructiveHintAnnotation(false)(t)
		mcp.WithIdempotentHintAnnotation(true)(t)
		mcp.WithOpenWorldHintAnnotation(false)(t)
	}
}

func listKnowledgeBasesTool() mcp.Tool {
	return mcp.NewTool(types.MCPEndpointToolListKnowledgeBases,
		mcp.WithDescription("List the knowledge bases this endpoint can access, with their id, name, description "+
			"and which retrieval modes (semantic, keyword, wiki) each supports. Call this first to learn what is in "+
			"scope; other tools accept either the id or the exact name."),
		readOnlyEndpointAnnotations(),
	)
}

func searchKnowledgeTool() mcp.Tool {
	return mcp.NewTool(types.MCPEndpointToolSearchKnowledge,
		mcp.WithDescription("Search the knowledge bases in scope and return the most relevant passages with their "+
			"document ids and titles. mode hybrid (default) combines semantic and keyword retrieval; semantic "+
			"ranks by meaning; keyword matches exact terms, identifiers, codes or names."),
		mcp.WithString("query", mcp.Required(), mcp.Description("A natural-language question, topic, or the exact "+
			"terms to match")),
		mcp.WithString("mode", mcp.Description("hybrid (default), semantic, or keyword"),
			mcp.Enum(tools.SearchModeHybrid, tools.SearchModeSemantic, tools.SearchModeKeyword)),
		mcp.WithNumber("limit", mcp.Description("Maximum passages to return, default 10, max 30")),
		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(),
	)
}

func grepChunksTool() mcp.Tool {
	return mcp.NewTool(types.MCPEndpointToolGrepChunks,
		mcp.WithDescription("Case-insensitive regular-expression search over the text chunks of the knowledge "+
			"bases in scope. Best for exact terms, identifiers, error codes or product names that semantic search "+
			"may miss. Candidates come from the keyword index (the semantic index for bases without one) using the "+
			"literal terms in the pattern, and every returned chunk matches the pattern."),
		mcp.WithString("query", mcp.Required(), mcp.Description("Regular expression (POSIX, case-insensitive) to "+
			"match against chunk text; text that is not a valid regular expression is matched literally")),
		mcp.WithNumber("limit", mcp.Description("Maximum passages to return, default 10, max 30")),
		mcp.WithArray("knowledge_base_ids", mcp.WithStringItems(),
			mcp.Description("Optional knowledge base ids or names to restrict the search")),
		readOnlyEndpointAnnotations(),
	)
}

func listDocumentsTool() mcp.Tool {
	return mcp.NewTool(types.MCPEndpointToolListDocuments,
		mcp.WithDescription("List the documents inside one knowledge base with pagination and an optional title "+
			"keyword filter. Returns document ids that read_document accepts."),
		mcp.WithString("knowledge_base_id", mcp.Required(), mcp.Description("Knowledge base id or exact name")),
		mcp.WithString("keyword", mcp.Description("Optional substring to filter document titles")),
		mcp.WithNumber("page", mcp.Description("1-based page number, default 1")),
		mcp.WithNumber("page_size", mcp.Description("Documents per page, default 20, max 100")),
		readOnlyEndpointAnnotations(),
	)
}

func readDocumentTool() mcp.Tool {
	return mcp.NewTool(types.MCPEndpointToolReadDocument,
		mcp.WithDescription("Read a document's metadata and its text chunks in order. Page through long documents "+
			"with offset and limit, or pass query to find chunks containing every whitespace-separated word, "+
			"case-insensitively and in any order. Query mode returns at most 20 matches plus one chunk of "+
			"context on each side, subject to the output size budget; limit does not apply. If truncated, "+
			"continue with offset=next_offset from the response."),
		mcp.WithString("knowledge_id", mcp.Required(),
			mcp.Description("Document id from search results or list_documents")),
		mcp.WithNumber("offset", mcp.Description("0-based position in document reading order, default 0; "+
			"use returned next_offset to continue")),
		mcp.WithNumber("limit", mcp.Description("Chunks per page without query, default 20, max 100; "+
			"ignored in query mode; output size budget may reduce the page")),
		mcp.WithString("query", mcp.Description("Optional case-insensitive keywords split on whitespace; "+
			"every word must occur in the chunk, in any order (not an exact phrase)")),
		readOnlyEndpointAnnotations(),
	)
}

type knowledgeBaseSummary struct {
	ID           string   `json:"id"`
	Name         string   `json:"name"`
	Description  string   `json:"description,omitempty"`
	Type         string   `json:"type"`
	Capabilities []string `json:"capabilities"`
}

func summarizeKnowledgeBase(kb *types.KnowledgeBase) knowledgeBaseSummary {
	caps := []string{}
	if kb.IsVectorEnabled() {
		caps = append(caps, "semantic")
	}
	if kb.IsKeywordEnabled() {
		caps = append(caps, "keyword")
	}
	if kb.IsWikiEnabled() {
		caps = append(caps, "wiki")
	}
	return knowledgeBaseSummary{
		ID:           kb.ID,
		Name:         kb.Name,
		Description:  kb.Description,
		Type:         kb.Type,
		Capabilities: caps,
	}
}

func (s *Server) handleListKnowledgeBases(ctx context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	ep, err := endpointFromContext(ctx)
	if err != nil {
		return mcp.NewToolResultError("unauthorized"), nil
	}
	kbs, err := s.allowedKnowledgeBases(ctx, ep)
	if err != nil {
		return mcp.NewToolResultErrorFromErr("failed to list knowledge bases", err), nil
	}
	out := make([]knowledgeBaseSummary, 0, len(kbs))
	for _, kb := range kbs {
		out = append(out, summarizeKnowledgeBase(kb))
	}
	return jsonResult(map[string]any{"knowledge_bases": out, "total": len(out)})
}

func (s *Server) handleSearchKnowledge(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	ep, err := endpointFromContext(ctx)
	if err != nil {
		return mcp.NewToolResultError("unauthorized"), nil
	}
	query, err := req.RequireString("query")
	if err != nil || strings.TrimSpace(query) == "" {
		return mcp.NewToolResultError("query is required"), nil
	}
	selectors, err := optionalKnowledgeBaseSelectors(req)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	kbs, err := s.selectKnowledgeBases(ctx, ep, selectors)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	kbs = retrievableKnowledgeBases(kbs)
	if len(kbs) == 0 {
		return mcp.NewToolResultError(
			"none of the selected knowledge bases supports semantic or keyword retrieval"), nil
	}
	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)
}

// runSearchKnowledgeWithFilter executes the shared search_knowledge agent tool for
// both the search_knowledge and grep_chunks endpoint tools.
func (s *Server) runSearchKnowledgeWithFilter(
	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, targets, nil, s.cfg,
	)
	if pattern != nil {
		tool.WithPatternFilter(pattern)
	}
	callArgs := map[string]any{
		"query":              query,
		"mode":               mode,
		"knowledge_base_ids": targets.GetAllKnowledgeBaseIDs(),
	}
	if limit > 0 {
		callArgs["limit"] = limit
	}
	args, _ := json.Marshal(callArgs)
	res, execErr := tool.Execute(ctx, args)
	return toolResultFromAgentTool(res, execErr), nil
}

func (s *Server) handleGrepChunks(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	ep, err := endpointFromContext(ctx)
	if err != nil {
		return mcp.NewToolResultError("unauthorized"), nil
	}
	query, err := req.RequireString("query")
	if err != nil || strings.TrimSpace(query) == "" {
		return mcp.NewToolResultError("query is required"), nil
	}
	selectors, err := optionalKnowledgeBaseSelectors(req)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	kbs, err := s.selectKnowledgeBases(ctx, ep, selectors)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	kbs = retrievableKnowledgeBases(kbs)
	if len(kbs) == 0 {
		return mcp.NewToolResultError(
			"none of the selected knowledge bases has a chunk index (vector or keyword)"), nil
	}
	pattern, terms := grepPatternAndTerms(strings.TrimSpace(query))
	if terms == "" {
		return mcp.NewToolResultError("the pattern contains no literal text to look up; include at least one " +
			"word, identifier or phrase (for example \"timeout|deadline\" instead of \"^\\d+$\")"), nil
	}
	return s.runSearchKnowledgeWithFilter(
		ctx, searchTargetsFor(kbs), terms, tools.SearchModeKeyword, req.GetInt("limit", 0), pattern,
	)
}

var grepEscapeRE = regexp.MustCompile(`\\[A-Za-z]`)

// grepPatternAndTerms keeps grep_chunks' regular-expression contract on top
// of index-backed retrieval. The pattern compiles case-insensitively (text
// that is not a valid expression is escaped and matched literally, as it
// would have failed in the database before). The literal runs inside the
// pattern become the keyword query that fetches candidates; results are then
// verified against the pattern itself.
func grepPatternAndTerms(query string) (*regexp.Regexp, string) {
	re, err := regexp.Compile("(?i)" + query)
	source := query
	if err != nil {
		re = regexp.MustCompile("(?i)" + regexp.QuoteMeta(query))
	} else {
		// Escapes such as \d, \b or \s carry no literal text.
		source = grepEscapeRE.ReplaceAllString(query, " ")
	}
	fields := strings.FieldsFunc(source, func(r rune) bool {
		return !unicode.IsLetter(r) && !unicode.IsDigit(r) && r != '_' && r != '-'
	})
	seen := make(map[string]bool, len(fields))
	terms := make([]string, 0, len(fields))
	for _, f := range fields {
		key := strings.ToLower(f)
		if seen[key] {
			continue
		}
		seen[key] = true
		terms = append(terms, f)
	}
	return re, strings.Join(terms, " ")
}

type documentSummary struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	FileName    string `json:"file_name,omitempty"`
	FileType    string `json:"file_type,omitempty"`
	Source      string `json:"source,omitempty"`
	ParseStatus string `json:"parse_status"`
	Description string `json:"description,omitempty"`
	CreatedAt   string `json:"created_at"`
	UpdatedAt   string `json:"updated_at"`
}

func summarizeKnowledge(k *types.Knowledge) documentSummary {
	return documentSummary{
		ID:          k.ID,
		Title:       k.Title,
		FileName:    k.FileName,
		FileType:    k.FileType,
		Source:      k.Source,
		ParseStatus: k.ParseStatus,
		Description: k.Description,
		CreatedAt:   k.CreatedAt.Format("2006-01-02T15:04:05Z07:00"),
		UpdatedAt:   k.UpdatedAt.Format("2006-01-02T15:04:05Z07:00"),
	}
}

func (s *Server) handleListDocuments(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	ep, err := endpointFromContext(ctx)
	if err != nil {
		return mcp.NewToolResultError("unauthorized"), nil
	}
	selector, err := req.RequireString("knowledge_base_id")
	if err != nil {
		return mcp.NewToolResultError("knowledge_base_id is required"), nil
	}
	kbs, err := s.selectKnowledgeBases(ctx, ep, []string{selector})
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	kb := kbs[0]
	// Documents live under the knowledge base owner; run the listing there.
	ctx, err = s.scopedKBContext(ctx, kb, types.OrgRoleViewer)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	page := req.GetInt("page", 1)
	if page < 1 {
		page = 1
	}
	pageSize := req.GetInt("page_size", defaultListPageSize)
	if pageSize < 1 {
		pageSize = defaultListPageSize
	}
	if pageSize > maxListPageSize {
		pageSize = maxListPageSize
	}
	result, err := s.knowledgeService.ListPagedKnowledgeByKnowledgeBaseID(
		ctx, kb.ID,
		&types.Pagination{Page: page, PageSize: pageSize},
		types.KnowledgeListFilter{Keyword: strings.TrimSpace(req.GetString("keyword", ""))},
	)
	if err != nil {
		return mcp.NewToolResultErrorFromErr("failed to list documents", err), nil
	}
	docs := []documentSummary{}
	if rows, ok := result.Data.([]*types.Knowledge); ok {
		for _, k := range rows {
			docs = append(docs, summarizeKnowledge(k))
		}
	}
	return jsonResult(map[string]any{
		"knowledge_base_id": kb.ID,
		"total":             result.Total,
		"page":              result.Page,
		"page_size":         result.PageSize,
		"documents":         docs,
	})
}

func (s *Server) handleReadDocument(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
	ep, err := endpointFromContext(ctx)
	if err != nil {
		return mcp.NewToolResultError("unauthorized"), nil
	}
	knowledgeID, err := req.RequireString("knowledge_id")
	if err != nil {
		return mcp.NewToolResultError("knowledge_id is required"), nil
	}
	k, kb, err := s.knowledgeInScope(ctx, ep, knowledgeID)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	ctx, err = s.scopedKBContext(ctx, kb, types.OrgRoleViewer)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}
	limit := req.GetInt("limit", defaultChunkLimit)
	if limit < 1 {
		limit = defaultChunkLimit
	}
	if limit > maxChunkLimit {
		limit = maxChunkLimit
	}
	offset := req.GetInt("offset", 0)
	if offset < 0 {
		offset = 0
	}
	tool := tools.NewReadDocumentTool(
		s.knowledgeService, s.chunkService, searchTargetsFor([]*types.KnowledgeBase{kb}),
	)
	callArgs := map[string]any{
		"id":     k.ID,
		"limit":  limit,
		"offset": offset,
	}
	if query := strings.TrimSpace(req.GetString("query", "")); query != "" {
		callArgs["query"] = query
	}
	args, _ := json.Marshal(callArgs)
	res, execErr := tool.Execute(ctx, args)
	if execErr != nil || res == nil || !res.Success {
		return toolResultFromAgentTool(res, execErr), nil
	}
	if res.Data == nil {
		res.Data = map[string]interface{}{}
	}
	res.Data["document"] = summarizeKnowledge(k)
	res.Data["knowledge_base"] = map[string]any{"id": kb.ID, "name": kb.Name}
	return toolResultFromAgentTool(res, nil), nil
}

// jsonResult renders structured data both as text (for clients that only
// read content) and as structuredContent.
func jsonResult(v any) (*mcp.CallToolResult, error) {
	raw, err := json.MarshalIndent(v, "", "  ")
	if err != nil {
		return mcp.NewToolResultErrorFromErr("failed to encode result", err), nil
	}
	return mcp.NewToolResultStructured(v, string(raw)), nil
}