Markdown Navigator MCP

Markdown 导航 MCP 服务器

高效浏览大型Markdown文件（2000行以上），无需将整个文档加载到上下文中。在处理文档、规划文件和技术规范时，可减少50%-80%的令牌使用量。

快速入门

先决条件Universal Ctags 和 Go 1.21+

# Install ctags
brew install universal-ctags         # macOS
sudo apt install universal-ctags     # Ubuntu/Debian
sudo dnf install universal-ctags     # Fedora

# Build and install
git clone 
cd markdown-mcp
go build -o mdnav-server ./cmd/server
sudo cp mdnav-server /usr/local/bin/

配置Claude代码 (~/claude.json):

{
  "mcpServers": {
    "markdown-nav": {
      "command": "mdnav-server"
    }
  }
}

特性/特点

• 零配置按需自动执行 ctags
• 智能缓存重复查询的亚微秒级响应
• 自动失效当文件更改时更新缓存
• 选择性阅读仅加载您需要的部分
• 树形导航查看文档结构而不阅读内容
• 模式匹配通过正则表达式模式查找部分
• 深度控制限制聚焦视图中的树/部分深度

工具

Markdown 树结构

以树状结构（ASCII或JSON格式）显示文档结构。

关键参数：

• file_pathMarkdown文件的路径
• format“ascii”或“json”（默认：“json”）
• max_depth限制树的深度为1-6（默认：2，显示H1+H2）
• section_name_pattern用于过滤部分的正则表达式

Markdown段落边界

获取特定部分的行号边界。

关键参数：

• file_pathMarkdown文件的路径
• section_heading准确的标题文本（不含#符号）

读取Markdown部分

从特定部分读取内容。

关键参数：

• file_pathMarkdown文件的路径
• section_heading确切的标题文本（不含#符号）
• max_subsection_levels限制子部分深度（全部省略）

Markdown列表部分

列出所有部分并应用过滤器。

关键参数：

• file_pathMarkdown文件的路径
• max_depth要显示的最大标题级别（默认：2）
• section_name_pattern用于过滤章节名称的正则表达式

使用示例

查找并阅读特定任务

User: "Review Task 4 from the planning document"

Claude uses:
1. markdown_tree to see document structure
2. markdown_section_bounds to find Task 4 location
3. markdown_read_section to read only Task 4 content

Result: Complete task analysis using only relevant section (~200 lines instead of 2000)

发现文档部分

User: "What testing strategies are documented?"

Claude uses:
1. markdown_list_sections with pattern="test" to find testing sections
2. markdown_read_section for each relevant section

Result: Comprehensive overview without loading entire document

如需查看包含真实输出结果的更详细工具使用示例，请参阅 示例/EXAMPLES.md（或可译为：例子/示例文件.md，具体根据上下文调整）。

配置

自定义 ctags 路径

如果ctags不在PATH中，请指定其位置：

{
  "mcpServers": {
    "markdown-nav": {
      "command": "mdnav-server",
      "args": ["-ctags-path", "/custom/path/to/ctags"]
    }
  }
}

故障排除

“在PATH中未找到ctags”

• 安装Universal Ctags或使用 -ctags-path 旗帜

“未找到部分”

• 使用确切的标题文本（区分大小写，不使用#符号）
• 跑 markdown_list_sections 查看可用部分

“未找到条目”

• 确保文件包含Markdown标题（#、##、###、####）
• 验证是否已安装通用 Ctags（而非 Exuberant Ctags）

缓存问题

• 重启MCP服务器以清除缓存（文件更改时自动失效）

发展

有关实施细节、架构和贡献指南，请参阅 CLAUDE.md（文件名可译为“克劳德.md”，其中“.md”通常表示Markdown格式的文件）。

快速开发命令：

go test ./...              # Run tests
golangci-lint run         # Lint code
go build ./cmd/server     # Build server

许可证

\[在此处输入您的许可证\]