Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/SearchToolHandler.ts:90-160 (handler)

  Primary handler function for the search_knowledge tool. Handles input validation, project lookup, keyword parsing, delegates to searchDocumentsAsync, transforms results to match expected output format (total_documents, total_matches, results with document and chapters), and formats the MCP response with logging.

  async searchKnowledgeAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    query: z.infer<typeof secureSearchQuerySchema>;
  }): Promise<string> {
    const context = this.createContext('search_knowledge', params);
  
    try {
      const { project_id, query } = params;
      const projectInfo = await getProjectDirectoryAsync(this.storagePath, project_id);
  
      // Project doesn't exist - return empty results without creating ghost entry
      if (!projectInfo) {
        this.logSuccess('search_knowledge', { project_id }, context);
        return this.formatSuccessResponse({
          total_documents: 0,
          total_matches: 0,
          results: [],
        });
      }
  
      const [, projectPath] = projectInfo;
  
      // Parse search keywords
      const keywords = query
        .toLowerCase()
        .split(/\s+/)
        .filter((k) => k.length > 0);
  
      // Search documents - pass projectPath, not knowledgePath
      const results = await searchDocumentsAsync(projectPath, keywords.join(' '));
  
      // Transform results for response - matching test expectations
      const transformedResults = results.map((result: SearchResult) => ({
        document: result.file,
        chapters: result.matching_chapters.map((ch) => ({
          title: ch.chapter || '(Document Introduction)',
          matches: ch.keywords_found.length,
        })),
      }));
  
      this.logSuccess('search_knowledge', { project_id }, context);
      return this.formatSuccessResponse({
        total_documents: transformedResults.length,
        total_matches: results.reduce((sum, r) => sum + r.match_count, 0),
        results: transformedResults,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.INTERNAL_ERROR,
              `Search failed: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                query: params.query,
                traceId: context.traceId,
              }
            );
      this.logError(
        'search_knowledge',
        {
          project_id: params.project_id,
          query: params.query,
        },
        mcpError,
        context
      );
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/documents.ts:487-732 (helper)

  Core search helper function called by the handler. Performs full-text keyword search across all knowledge documents in a project, parsing MD files, extracting chapters, finding matches with context, and grouping results by document and chapter.

  export async function searchDocumentsAsync(
    projectPath: string,
    query: string
  ): Promise<SearchResult[]> {
    if (!query) {
      return [];
    }
  
    const knowledgeDir = join(projectPath, 'knowledge');
    try {
      await access(knowledgeDir);
    } catch {
      return [];
    }
  
    // Split query into individual keywords
    const keywords = query
      .split(/\s+/)
      .map((kw) => kw.trim().toLowerCase())
      .filter((kw) => kw);
  
    if (keywords.length === 0) {
      return [];
    }
  
    // Structure to aggregate results by document
    const documentResults: Record<
      string,
      {
        metadata: DocumentMetadata;
        matching_chapters: Record<
          string,
          {
            chapter: string;
            keywords_found: Set<string>;
            match_context: Record<string, string[]>;
            chapter_summary: string;
          }
        >;
      }
    > = {};
  
    // Search through all markdown files
    const files = await readdir(knowledgeDir);
    const mdFiles = files.filter((f) => f.endsWith('.md'));
  
    for (const mdFile of mdFiles) {
      try {
        const filePath = join(knowledgeDir, mdFile);
        const content = await readFile(filePath, 'utf8');
  
        // Parse document
        const [metadata, body] = parseDocument(content);
        const chapters = parseChapters(body);
  
        // Search each keyword
        for (const keyword of keywords) {
          const bodyLower = body.toLowerCase();
  
          // If no chapters, search entire body
          if (chapters.length === 0 && bodyLower.includes(keyword)) {
            const contexts: string[] = [];
            let startPos = 0;
  
            let index = bodyLower.indexOf(keyword, startPos);
            while (index !== -1) {
              // Extract context
              const ctxStart = Math.max(0, index - 50);
              const ctxEnd = Math.min(body.length, index + keyword.length + 50);
              let context = body.slice(ctxStart, ctxEnd).trim();
  
              if (ctxStart > 0) context = '...' + context;
              if (ctxEnd < body.length) context = context + '...';
  
              contexts.push(context);
              startPos = index + 1;
              index = bodyLower.indexOf(keyword, startPos);
            }
  
            if (contexts.length > 0) {
              // Initialize document entry if needed
              if (!(mdFile in documentResults)) {
                documentResults[mdFile] = {
                  metadata,
                  matching_chapters: {},
                };
              }
  
              // Add body-level match as a special chapter
              if (!('_document_body' in documentResults[mdFile].matching_chapters)) {
                documentResults[mdFile].matching_chapters['_document_body'] = {
                  chapter: '',
                  keywords_found: new Set(),
                  match_context: {},
                  chapter_summary: '',
                };
              }
  
              const chapterData = documentResults[mdFile].matching_chapters['_document_body'];
              chapterData.keywords_found.add(keyword);
              if (!(keyword in chapterData.match_context)) {
                chapterData.match_context[keyword] = [];
              }
              chapterData.match_context[keyword].push(...contexts);
            }
          }
  
          // Search in chapters
          for (const chapter of chapters) {
            if (chapter.content.toLowerCase().includes(keyword)) {
              const contexts: string[] = [];
              const chapterLower = chapter.content.toLowerCase();
              let startPos = 0;
  
              let index = chapterLower.indexOf(keyword, startPos);
              while (index !== -1) {
                // Extract context
                const ctxStart = Math.max(0, index - 50);
                const ctxEnd = Math.min(chapter.content.length, index + keyword.length + 50);
                let context = chapter.content.slice(ctxStart, ctxEnd).trim();
  
                if (ctxStart > 0) context = '...' + context;
                if (ctxEnd < chapter.content.length) context = context + '...';
  
                contexts.push(context);
                startPos = index + 1;
                index = chapterLower.indexOf(keyword, startPos);
              }
  
              if (contexts.length > 0) {
                // Initialize document entry if needed
                if (!(mdFile in documentResults)) {
                  documentResults[mdFile] = {
                    metadata,
                    matching_chapters: {},
                  };
                }
  
                // Initialize chapter entry if needed
                if (!(chapter.title in documentResults[mdFile].matching_chapters)) {
                  documentResults[mdFile].matching_chapters[chapter.title] = {
                    chapter: chapter.title,
                    keywords_found: new Set(),
                    match_context: {},
                    chapter_summary: chapter.summary,
                  };
                }
  
                const chapterData = documentResults[mdFile].matching_chapters[chapter.title];
                chapterData.keywords_found.add(keyword);
                if (!(keyword in chapterData.match_context)) {
                  chapterData.match_context[keyword] = [];
                }
                chapterData.match_context[keyword].push(...contexts);
              }
            }
          }
  
          // If chapters exist, also search for pre-chapter content
          if (chapters.length > 0 && bodyLower.includes(keyword)) {
            // Get the content before the first chapter
            const firstChapterStart = body.indexOf('\n##');
            if (firstChapterStart > 0) {
              const preChapterContent = body.slice(0, firstChapterStart);
              if (preChapterContent.toLowerCase().includes(keyword)) {
                const contexts: string[] = [];
                const contentLower = preChapterContent.toLowerCase();
                let startPos = 0;
  
                let index = contentLower.indexOf(keyword, startPos);
                while (index !== -1) {
                  // Extract context
                  const ctxStart = Math.max(0, index - 50);
                  const ctxEnd = Math.min(preChapterContent.length, index + keyword.length + 50);
                  let context = preChapterContent.slice(ctxStart, ctxEnd).trim();
  
                  if (ctxStart > 0) context = '...' + context;
                  if (ctxEnd < preChapterContent.length) context = context + '...';
  
                  contexts.push(context);
                  startPos = index + 1;
                  index = contentLower.indexOf(keyword, startPos);
                }
  
                if (contexts.length > 0) {
                  // Initialize document entry if needed
                  if (!(mdFile in documentResults)) {
                    documentResults[mdFile] = {
                      metadata,
                      matching_chapters: {},
                    };
                  }
  
                  // Add pre-chapter content as a special chapter
                  if (!('_pre_chapter' in documentResults[mdFile].matching_chapters)) {
                    documentResults[mdFile].matching_chapters['_pre_chapter'] = {
                      chapter: '',
                      keywords_found: new Set(),
                      match_context: {},
                      chapter_summary: '',
                    };
                  }
  
                  const chapterData = documentResults[mdFile].matching_chapters['_pre_chapter'];
                  chapterData.keywords_found.add(keyword);
                  if (!(keyword in chapterData.match_context)) {
                    chapterData.match_context[keyword] = [];
                  }
                  chapterData.match_context[keyword].push(...contexts);
                }
              }
            }
          }
        }
      } catch {
        // Skip files that can't be read
        continue;
      }
    }
  
    // Convert to document-centric format
    const results: SearchResult[] = [];
  
    for (const [filename, docData] of Object.entries(documentResults)) {
      // Convert matching chapters to array
      const matchingChapters: MatchingChapter[] = [];
  
      for (const [, chapterData] of Object.entries(docData.matching_chapters)) {
        matchingChapters.push({
          chapter: chapterData.chapter,
          keywords_found: Array.from(chapterData.keywords_found).sort(),
          match_context: chapterData.match_context,
          chapter_summary: chapterData.chapter_summary,
        });
      }
  
      results.push({
        file: filename,
        match_count: matchingChapters.length,
        metadata: docData.metadata,
        matching_chapters: matchingChapters,
      });
    }
  
    return results;
  }

• src/knowledge-mcp/server.ts:302-323 (registration)

  MCP tool registration for 'search_knowledge', defining title, description, input schema (project_id, query), and handler that invokes SearchToolHandler.searchKnowledgeAsync and wraps response in MCP content format.

  server.registerTool(
    'search_knowledge',
    {
      title: 'Search Knowledge',
      description: TOOL_DESCRIPTIONS.search_knowledge,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        query: secureSearchQuerySchema.describe('Space-separated keywords to search for'),
      },
    },
    async ({ project_id, query }) => {
      const result = await searchHandler.searchKnowledgeAsync({ project_id, query });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/config/toolDescriptions.ts:457-488 (schema)

  Detailed tool description and usage instructions for search_knowledge, including when to use, key features, best practices, return format, used in registration.

    search_knowledge: `Search project knowledge documents for keywords with intelligent result grouping.
  
  When to use this tool:
  - Finding information across multiple documents
  - Locating specific technical details
  - Discovering related content
  - Checking if topic is already documented
  - Researching before creating new content
  
  Key features:
  - Case-insensitive full-text search
  - Searches document body, titles, and content
  - Groups results by document
  - Returns matching chapters with context
  - Space-separated keyword support
  
  You should:
  1. Use specific keywords for better results
  2. Try multiple search terms if needed
  3. Search before creating new documents
  4. Use 2-3 word phrases for precision
  5. Review all results before concluding
  6. Consider variations of technical terms
  7. Check both titles and content matches
  
  DO NOT use when:
  - Know exact document and chapter
  - Need complete document listing
  - Searching for project main content
  
  Returns: {success: bool, total_documents: int, total_matches: int, results: [...], error?: str}`,