list_chapters
Quickly extract chapter titles and summaries from a knowledge document to gain an overview, plan navigation, or check structure without loading full content.
Instructions
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:
Use this before get_knowledge_file for large documents
Identify relevant chapters before reading
Check document structure before modifications
Use for navigation planning
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}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Knowledge file name (must include .md extension) | |
| project_id | Yes | The project identifier |
Implementation Reference
- 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, }, ], }; } );
- 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}`,