金大哥 - docnav-mcp MCP 详情

article

README

🚀 DocNav MCP 服务器

DocNav 是一个模型上下文协议（MCP）服务器，它使大语言模型（LLM）智能体能够像人类一样理解和导航，从而智能地读取、分析和管理长篇文档。

🚀 快速开始

DocNav 可助力大语言模型智能体处理长篇文档，下面将为你介绍其安装和使用方法。

✨ 主要特性

文档导航：可在文档的各个部分、标题和内容结构中进行导航。
内容提取：提取并总结文档的特定部分。
搜索与查询：使用智能搜索功能在文档中查找特定内容。
多格式支持：目前支持 Markdown（.md）文件，计划后续支持 PDF 等其他格式。
MCP 集成：可与兼容 MCP 的大语言模型和应用程序实现无缝集成。

📦 安装指南

前提条件

Python 3.10 及以上版本
uv 包管理器

安装步骤

克隆仓库：

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

安装依赖：

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 进行包管理
格式化和代码检查规则

添加新的文档处理器

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

运行测试

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

代码质量

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

# 检查代码风格
uv run --frozen ruff check .

# 类型检查
uv run --frozen pyright

🔧 技术细节

DocNav 采用模块化、可扩展的架构：

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

📄 许可证

本项目采用 Apache 2.0 许可证，详情请参阅 LICENSE 文件。

🚧 路线图

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

🤝 贡献

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

🛠️ 支持

若有问题或疑问：

在 GitHub 上创建一个问题。
查看 CLAUDE.md 中的文档。
查看现有的问题和讨论。

docnav-mcp