Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/ChapterToolHandler.ts:823-887 (handler)

  Core handler implementation that reads the knowledge file, parses chapters, and returns titles, summaries, and indices without full content.

  async listChaptersAsync(params: { project_id: string; filename: string }): Promise<string> {
    const context = this.createContext('list_chapters', params);
  
    try {
      const { project_id, filename } = params;
      const projectInfo = await getProjectDirectoryAsync(this.storagePath, project_id);
  
      if (!projectInfo) {
        throw new MCPError(MCPErrorCode.PROJECT_NOT_FOUND, `Project ${project_id} not found`, {
          project_id,
          traceId: context.traceId,
        });
      }
  
      const [, projectPath] = projectInfo;
      const knowledgePath = join(projectPath, 'knowledge');
      const filePath = await validatePathAsync(knowledgePath, filename);
  
      // Check if file exists
      try {
        await access(filePath);
      } catch {
        throw new MCPError(
          MCPErrorCode.DOCUMENT_NOT_FOUND,
          `Knowledge file ${filename} not found`,
          { project_id, filename, traceId: context.traceId }
        );
      }
  
      // Read and parse the document
      const content = await readFile(filePath, 'utf8');
      const [, body] = parseDocument(content);
      const chapters = parseChapters(body);
  
      // Return lightweight chapter list
      const chapterList = chapters.map((chapter, index) => ({
        title: chapter.title,
        summary: chapter.summary,
        index,
      }));
  
      this.logSuccess('list_chapters', { project_id, filename }, context);
      return this.formatSuccessResponse({
        project_id,
        filename,
        total_chapters: chapters.length,
        chapters: chapterList,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.FILE_SYSTEM_ERROR,
              `Failed to list chapters: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                filename: params.filename,
                traceId: context.traceId,
              }
            );
      this.logError('list_chapters', params, mcpError, context);
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:428-448 (registration)

  Registers the 'list_chapters' MCP tool, defines input schema, description, and wrapper that delegates to ChapterToolHandler.listChaptersAsync

    'list_chapters',
    {
      title: 'List Chapters',
      description: TOOL_DESCRIPTIONS.list_chapters,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        filename: secureFilenameSchema.describe('Knowledge file name (must include .md extension)'),
      },
    },
    async ({ project_id, filename }) => {
      const result = await chapterHandler.listChaptersAsync({ project_id, filename });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/config/toolDescriptions.ts:369-397 (schema)

  Detailed tool description and usage guidelines for 'list_chapters' used during registration.

    list_chapters: `List all chapters in a knowledge document with titles and summaries only.
  
  When to use this tool:
  - Getting document overview without loading all content
  - Planning which chapters to read or update
  - Understanding document structure
  - Checking chapter organization
  - Finding specific chapters efficiently
  
  Key features:
  - Lightweight operation (no content loading)
  - Returns titles and summaries only
  - Shows chapter count and order
  - Enables informed navigation
  
  You should:
  1. Use this before get_knowledge_file for large documents
  2. Identify relevant chapters before reading
  3. Check document structure before modifications
  4. Use for navigation planning
  5. Include .md extension in filename
  
  DO NOT use when:
  - Need actual chapter content
  - Document is very small
  - Already know exact chapter needed
  
  Returns: {success: bool, project_id: str, filename: str, total_chapters: int, chapters: array}`,