文档导航服务

MCP服务器文档

一个模型上下文协议（MCP）服务器，提供工具用于阅读和浏览基于Markdown的文档仓库。

特点/特性

• 列出文档文件发现并浏览带有元数据的可用文档文件
• 目录生成可配置深度和标题限制控制的结构化目录表
• 目录部分在指定的父级部分中获取子部分，以便进行有针对性的探索
• 阅读章节通过文档ID阅读特定部分
• 搜索使用正则表达式跨文档文件查找文本模式，支持多行匹配
• 多目录支持配置多个文档目录并解决冲突
• 可配置的最大TOC深度限制目录标题深度（例如，仅显示 #， ##，和 ### 标题，默认：3)
• 可配置的最大头部数限制目录返回的标题总数（默认：25）
• 灵活配置支持命令行、环境变量和默认路径
• 全面错误处理清晰的错误信息和验证

安装

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> 

命令行参数

文档目录

使用 --docs-path 或者 -d 标志来指定您的文档目录或多个目录。您可以提供

# 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 限制目录中显示的标题级别（默认：3，显示 #， ##， ###)。

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

最大头部（或“最大请求头”）

使用 --max-headers 限制返回的头部信息总数（默认：25）。

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

典型的工作流程

这是代理通常应如何使用此MCP服务器的方式。

1. 代理呼叫 list_documentation_files 查看哪些 .md 文件可供阅读
2. 代理根据文件名和元数据（如果提供了元数据）推断出它想要读取的文件（可能为多个）
3. 代理呼叫 table_of_contents 对于它想要读取的文件
4. （可选）代理看到一个可能包含其想要阅读内容的部分，但不确定。该部分包含隐藏的子部分。因此，代理调用 section_table_of_contents 对于文件和章节，请使用点分隔的章节ID（例如，“2.1”）。
5. 代理使用点分隔的章节ID（例如，“1”、“2.1”、“3.4.1”）来推断它想要阅读的章节（标题及其下的文本）。
6. 代理请求提供该部分的内容 read_sections

可用的MCP工具

列出文档文件

列出所有可用的文档文件及其元数据，包括文件大小、修改时间以及前置内容信息。 无需参数。

目录

为Markdown文件提供一个结构化的目录表，显示带有ID的章节层级。

参数：

• filename （必填）- 要分析的文档文件

响应格式：

该工具返回的是用结构化标签包裹的类似XML的文本内容。响应中既包含目录，也包含使用说明。

示例回复：

<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>

响应结构：

• 目录包含带有ID和标题的格式化章节列表
• 说明/指示使用说明：解释如何使用部分ID以及解读隐藏子部分的方法

部分格式：

• 每一行显示： ID Title {hiddenSubsections: N} （可选）
• 部分ID点分隔格式（例如，“1.2.3”）表示层级级别
• 标题实际的节标题文本
• 隐藏子部分仅在子部分因（某种原因）被隐藏时出现 --max-toc-depth 或者 --max-headers 限制

段级计算： 段落级别由段落ID格式决定： (number of dots in ID) + 1

• "1" = 第1级（主部分）
• "1.1" = 第二级（子部分）
• "1.2.3" = 第三级（小节中的小节）

过滤参数： 这个（或那个，具体根据上下文确定） --max-toc-depth 并且 --max-headers 命令行参数控制显示的内容：

• --max-toc-depth限制显示的标题级别（默认：3，显示 #, ##, ###）
• --max-headers限制返回的头部总数（默认：25）

目录表（或：内容目录部分）

类似于 table_of_contents 工具，但不是从文档根部开始，而是从一个部分开始。

通常，对于大型文档来说——为了节省令牌（或标记）—— table_of_content 不会显示所有章节（所有标题）。相反，代理可以选择深入一个或多个章节，询问某个章节下的目录（子标题），该章节需在之前的结果中出现过 table_of_contents 或者另一个 section_table_of_contents 打电话。

参数：

• filename （必填）- 要分析的文档文件
• section_ids （必填）- 用于获取子部分的非空章节标识符数组

响应格式：

与……相同 table_of_contents.

这个（或“该”） --max-toc-depth 和 --max-headers 命令行参数控制目录表中显示的内容。

读取部分

根据ID从Markdown文件中读取特定部分。

参数：

• filename （必需）- 要读取的文档文件
• section_ids （必需）- 要读取的部分标识符数组（对于嵌套部分，请使用类似“1.2.3”的点分隔格式）

示例：

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

搜索

在文档文件中使用正则表达式搜索文本模式，并返回找到搜索模式的标题和部分ID。支持完整的正则表达式语法，包括多行匹配（自动启用“s”标志以实现dotAll行为）。

参数：

• query （必填）- 用于搜索的正则表达式模式（不区分大小写）。该模式自动包含“i”和“s”标志，以实现不区分大小写和多行匹配
• filename （可选）- 指定要搜索的特定文件。如果未提供，则搜索所有可用的文档文件

文档元数据支持

Markdown文件可以包含可选的YAML前置内容元数据，以便更好地发现文件。MCP服务器会自动解析并显示这些元数据 list_documentation_files 工具结果。

支持的字段（全部可选）

• title （字符串）- 文档标题，显示在文件列表中
• description (字符串) - 文件内容的简要描述
• keywords （字符串或数组）- 用于搜索和分类的关键词

格式

在你的Markdown文件顶部添加YAML前置内容，用以下符号括起来： --- 分隔符：

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