local-dev-docs-reader-mcp

Documentation MCP Server

A Model Context Protocol (MCP) server that provides tools for reading and navigating markdown-based documentation repositories.

Features

• List Documentation Files: Discover and browse available documentation files with metadata
• Table of Contents: Generate structured table of contents with configurable depth and header limit control
• Section Table of Contents: Get subsections within specified parent sections for targeted exploration
• Read Sections: Read specific sections of documentation by their IDs
• Search: Find text patterns using regular expressions across documentation files with multiline matching support
• Multi-Directory Support: Configure multiple documentation directories with conflict resolution
• Configurable Max TOC Depth: Limit table of contents header depth (e.g., only show #, ##, and ### headers, default: 3)
• Configurable Max Headers: Limit total number of headers returned by table of contents (default: 25)
• Flexible Configuration: Support for command line, environment variables, and default paths
• Comprehensive Error Handling: Clear error messages and validation

Installation

Claude Code (Mac, Linux)

claude mcp add docs-reader -- npx local-dev-docs-reader-mcp@latest -d <documentation_directory> 

Claud Code (Windows)

claude mcp add docs-reader -- cmd /c -- npx local-dev-docs-reader-mcp@latest -d <documentation_directory> 

Command Line Arguments

Documentation directories

Use the --docs-path or -d flag to specify your documentation directory or directories. You can provide

# Single directory
npm start -- -d /path/to/your/docs

# Multiple directories
npm start -- -d /path/to/docs1 -d /path/to/docs2 -d /path/to/docs3

Max ToC Depth

Use --max-toc-depth to limit the header levels shown in table of contents (default: 3, shows #, ##, ###).

npm start -- --max-toc-depth 2  # Only show # and ## headers

Max Headers

Use --max-headers to limit the total number of headers returned (default: 25).

npm start -- --max-headers 50  # Return up to 50 headers

Typical workflow

This is how the agent should typically use this MCP server.

• Agent calls list_documentation_files to see which .md files are available for reading
• Agent deduces which file(s) it would like to read based on file name and metadata (if metadata provided)
• Agent calls table_of_contents for the file it wants to read
• (optional) Agent sees a section that might contain what it wants to read, but is not sure. The section has hidden subsections. Therefore, Agent calls section_table_of_contents for the file and section using dot-separated section IDs (e.g., "2.1").
• Agent deduces which sections (header + text under it) it wants to read using dot-separated section IDs (e.g., "1", "2.1", "3.4.1").
• Agent asks for the section contents with read_sections

Available MCP Tools

list_documentation_files

Lists all available documentation files with metadata including file size, modification time, and front matter information. No parameters required.

table_of_contents

Provides a structured table of contents for a markdown file, showing section hierarchy with IDs.

Parameters:

• filename (required) - The documentation file to analyze

Response Format:

The tool returns XML-like text content wrapped in structured tags. The response contains both the table of contents and usage instructions.

Example Response:

<TableOfContents>
1 Getting Started
1.1 Installation
1.2 Configuration
1.3 Basic Usage
2 Advanced Topics
2.1 Customization
2.2 Performance
2.2.1 Caching
2.2.2 Optimization
3 API Reference
3.1 Endpoints
3.2 Authentication
</TableOfContents>
<Instructions>
The number before each section title is the section ID (e.g., "1.1.1"). Use these section IDs with the read_sections tool to read specific sections. When you see sections marked with {hiddenSubsections: N}, it indicates that N child sections are not shown due to filtering limits.
</Instructions>

Response Structure:

• TableOfContents: Contains the formatted list of sections with their IDs and titles
• Instructions: Usage instructions explaining how to use section IDs and interpret hidden subsections

Section Format:

• Each line shows: ID Title {hiddenSubsections: N} (optional)
• Section ID: Dot-separated format (e.g., "1.2.3") representing hierarchy level
• Title: The actual section header text
• hiddenSubsections: Only appears when child sections are hidden due to --max-toc-depth or --max-headers limits

Section Level Calculation: Section level is determined by the section ID format: (number of dots in ID) + 1

• "1" = Level 1 (main section)
• "1.1" = Level 2 (subsection)
• "1.2.3" = Level 3 (subsubsection)

Filtering Parameters: The --max-toc-depth and --max-headers command line parameters control what is shown:

• --max-toc-depth: Limits header levels shown (default: 3, shows #, ##, ###)
• --max-headers: Limits total number of headers returned (default: 25)

section_table_of_contents

Similar to table_of_contents tool, but instead of starting from document root, starts from a section.

Typically for a large document - to save tokens - table_of_content will not show all sections (all headers). Instead, the agent can choose to go deeper under one or more sections asking the table of contents (the subheaders) under a section that was in the results of a table_of_contents or another section_table_of_contents call.

Parameters:

• filename (required) - The documentation file to analyze
• section_ids (required) - Non-empty array of section identifiers to get subsections for

Response Format:

Same as for table_of_contents.

The --max-toc-depth and --max-headers command line parameters control what is shown in the table of contents.

read_sections

Reads specific sections from a markdown file by their IDs.

Parameters:

• filename (required) - The documentation file to read from
• section_ids (required) - Array of section identifiers to read (use dot-separated format like "1.2.3" for nested sections)

Example:

{
  "filename": "guide.md",
  "section_ids": ["1", "2.1", "3.4.1"]
}

search

Searches for text patterns using regular expressions in documentation files, returning headers and section IDs where the search pattern is found. Supports full regular expression syntax with multiline matching (the "s" flag is enabled automatically for dotAll behavior).

Parameters:

• query (required) - The regular expression pattern to search for (case-insensitive). The pattern automatically includes the "i" and "s" flags for case-insensitive and multiline matching
• filename (optional) - Specific file to search in. If not provided, searches all available documentation files

Document Metadata Support

Markdown files can include optional YAML front matter metadata for better file discovery. The MCP server automatically parses and displays this metadata in the list_documentation_files tool results.

Supported Fields (all optional)

• title (string) - Document title, displayed in file listings
• description (string) - Brief description of the document's content
• keywords (string or array) - Keywords for searchability and categorization

Format

Add YAML front matter at the top of your markdown file, enclosed in --- delimiters:

---

title: "User Guide"
description: "Comprehensive guide for getting started with the application"
keywords: ["tutorial", "setup", "configuration", "getting started"]
---