DocNav MCP Server

DocNav 是一个模型上下文协议（MCP）服务器，它使LLM代理能够智能地阅读、分析和管理长文档，模仿人类的理解和导航能力。

功能

• 文档导航：浏览文档的部分、标题和内容结构
• 内容提取：提取并总结特定的文档部分
• 搜索与查询：使用智能搜索在文档中查找特定内容
• 多格式支持：当前支持Markdown（.md）文件，计划支持PDF和其他格式
• MCP集成：无缝集成到兼容MCP的LLM和应用程序

架构

DocNav 遵循模块化、可扩展的架构：

• 核心MCP服务器：使用MCP协议实现的主要服务器
• 文档处理器：用于不同文件类型的插件式处理器
• 导航引擎：处理文档结构分析和导航
• 内容提取器：从文档中提取和格式化内容
• 搜索引擎：提供跨文档的搜索和查询功能

安装

先决条件

• Python 3.10+
• uv 包管理器

设置

1. 克隆仓库：

git clone https://github.com/shenyimings/DocNav-MCP.git
cd DocNav-MCP

2. 安装依赖项：

uv sync

使用

启动MCP服务器

uv run server.py

连接到MCP服务器

{
  "mcpServers": {
    "docnav": {
      "command": "{{PATH_TO_UV}}", // 运行 `which uv` 并在此处放置输出
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}",
        "run",
        "server.py"
      ]
    }
  }
}

可用工具

• load_document：加载一个文档以进行导航和分析

  • 参数：file_path（文档文件路径）
  • 返回值：带有自动生成文档ID的成功消息

• get_outline：获取文档大纲/目录

  • 参数：doc_id（文档标识符），max_depth（最大标题深度，默认3）
  • 返回值：格式化的文档大纲
  • 提示：加载文档后首先使用此功能以了解其结构

• read_section：读取特定文档部分的内容

  • 参数：doc_id（文档标识符），section_id（例如，'h1_0'，'h2_1'）
  • 返回值：包含子部分的部分内容

• search_document：在文档中搜索特定内容

  • 参数：doc_id（文档标识符），query（搜索词或短语）
  • 返回值：带上下文的格式化搜索结果

• navigate_section：获取部分的导航上下文

  • 参数：doc_id（文档标识符），section_id（要导航的部分）
  • 返回值：带有父级、兄弟级和子级的导航上下文

• list_documents：列出所有已加载的文档

  • 返回值：带有元数据的已加载文档列表

• get_document_stats：获取已加载文档的统计信息

  • 参数：doc_id（文档标识符）
  • 返回值：文档统计信息和结构信息

• remove_document：从导航器中移除文档

  • 参数：doc_id（文档标识符）
  • 返回值：成功或错误消息

示例用法

# 加载一个文档
result = await tools.load_document("path/to/document.md")

# 获取文档大纲
outline = await tools.get_outline(doc_id)

# 获取特定部分的内容
section = await tools.read_section(doc_id, section_id)

# 在文档中搜索
results = await tools.search_document(doc_id, "search query")

开发

项目结构

docnav-mcp/
--- server.py             # 主MCP服务器
--- docnav/
------- __init__.py           # 包初始化
------- models.py             # 数据模型
------- navigator.py          # 文档导航引擎
------- processors/
------- __init__.py       # 处理器包
------- base.py           # 基础处理器接口
------- markdown.py       # Markdown处理器
--- tests/
------- ...                   # 测试文件

开发指南

参见 CLAUDE.md 以获取详细的开发指南，包括：

• 代码质量标准
• 测试要求
• 使用uv的包管理
• 格式化和lint规则

添加新的文档处理器

1. 创建一个新的继承自BaseProcessor的处理器类
2. 实现所需的方法：can_process，process，extract_section，search
3. 在DocumentNavigator中注册处理器
4. 添加全面的测试

运行测试

# 运行所有测试
uv run tests/run_tests.py

代码质量

# 格式化代码
uv run --frozen ruff format .

# 检查lint
uv run --frozen ruff check .

# 类型检查
uv run --frozen pyright

发展路线图

• 完成Markdown处理器的实现
• 添加PDF文档支持（PyMuPDF）
• 改进测试覆盖率和质量
• 实现高级搜索功能
• 添加文档摘要功能
• 支持其他文档格式（DOCX，TXT等）
• 对大型文档进行性能优化
• 经常访问文档的缓存机制
• 为加载的文档添加持久存储

贡献

1. 分叉仓库
2. 创建功能分支
3. 遵循CLAUDE.md中的开发指南
4. 为新功能添加测试
5. 提交拉取请求

许可证

本项目根据Apache-2.0许可证发布 - 查看LICENSE文件以获取详细信息。

支持

对于问题和疑问：

• 在GitHub上打开一个问题
• 查看CLAUDE.md中的文档
• 查阅现有问题和讨论