AI导哈

文档导航服务

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

  • by shenyimings
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 shenyimings/DocNav-MCP

使用说明

DocNav MCP服务器

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

特性

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

建筑

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

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

安装

先决条件

设置

  1. 克隆存储库：
git clone https://github.com/shenyimings/DocNav-MCP.git
cd DocNav-MCP
  1. 安装依赖项：
uv sync

用法

启动MCP服务器

uv run server.py

连接到MCP服务器

{
  "mcpServers": {
    "docnav": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}",
        "run",
        "server.py"
      ]
    }
  }
}

可用工具

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

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

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

    • Args： doc_id （文档标识符）， max_depth （最大航向深度，默认值3）
    • 返回：格式化文档大纲
    • 提示：加载文档后先使用以了解结构

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

    • Args： doc_id （文档标识符）， section_id （例如，“h1_0”、“h2_1”）
    • 返回：包含子部分的部分内容

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

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

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

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

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

    • 返回：包含元数据的已加载文档列表

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

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

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

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

示例用法

# Load a document
result = await tools.load_document("path/to/document.md")

# Get document outline
outline = await tools.get_outline(doc_id)

# Get specific section content
section = await tools.read_section(doc_id, section_id)

# Search within document
results = await tools.search_document(doc_id, "search query")

发展

项目结构

docnav-mcp/
--- server.py             # Main MCP server
--- docnav/
------- __init__.py           # Package initialization
------- models.py             # Data models
------- navigator.py          # Document navigation engine
------- processors/
------- __init__.py       # Processor package
------- base.py           # Base processor interface
------- markdown.py       # Markdown processor
--- tests/
------- ...                   # Test files

开发指南

看 CLAUDE.md 详细的开发指南包括：

  • 代码质量标准
  • 测试要求
  • 使用uv进行包装管理
  • 格式化和linting规则

添加新的文档处理器

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

运行测试

# Run all tests
uv run tests/run_tests.py

代码质量

# Format code
uv run --frozen ruff format .

# Check linting
uv run --frozen ruff check .

# Type checking
uv run --frozen pyright

路线图

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

贡献

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

许可证

此项目在Apache-2.0许可证下获得许可-有关详细信息，请参阅License文件。

支持

对于问题和疑问：

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

相关 MCP