AI导哈

Markdown导航工具

一款高效浏览大型Markdown文件的技术工具，通过按需加载文档部分内容，减少50-80%的令牌使用量，适用于文档处理和技术规范查看。

  • by yoseforb
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 yoseforb/markdown-navigator-mcp

使用说明

Markdown导航MCP服务器

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

快速开始

先决条件：通用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 <repo-url>
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_tree

将文档结构显示为树（ASCII或JSON格式）。

关键参数：

  • file_path：markdown文件的路径
  • format：“ascii”或“json”（默认值：“json”）
  • max_depth：限制树深度1-6（默认值：2表示H1+H2）
  • section_name_pattern：用于筛选节的正则表达式

markdown_section_bounds

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

关键参数：

  • file_path：markdown文件的路径
  • section_heading：精确的标题文本（不带#符号）

markdown_read_section

阅读特定章节的内容。

关键参数：

  • file_path：markdown文件的路径
  • section_heading：精确的标题文本（不带#符号）
  • max_subsection_levels：限制分段深度（全部省略）

markdown_list_sections

列出所有带过滤器的部分。

关键参数：

  • file_path：markdown文件的路径
  • 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.

配置

自定义ctags路径

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

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

故障排除

“在PATH中找不到ctags”

  • 安装通用标签或使用 -ctags-path 旗帜

“未找到部分”

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

“未找到条目”

  • 确保文件有标记标题（#、##、###、####）
  • 验证是否安装了通用Ctag（不是Exuberant）

缓存问题

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

发展

有关实现细节、架构和贡献指南，请参阅 CLAUDE.md.

快速开发命令：

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

许可证

该项目根据 GNU通用公共许可证v3.0.

相关 MCP