Docnav MCP

🚀 DocNav MCP 服務器

DocNav 是一個模型上下文協議（MCP）服務器，它使大語言模型代理能夠智能地閱讀、分析和管理長篇文檔，模擬人類般的理解和導航能力。

🚀 快速開始

DocNav 能助力大語言模型代理處理長篇文檔。下面為你介紹如何安裝和使用它。

✨ 主要特性

• 文檔導航：可在文檔的各個部分、標題和內容結構中進行導航。
• 內容提取：能提取並總結文檔的特定部分。
• 搜索與查詢：藉助智能搜索功能，在文檔中查找特定內容。
• 多格式支持：目前支持 Markdown（.md）文件，後續計劃支持 PDF 等其他格式。
• MCP 集成：可與兼容 MCP 的大語言模型和應用程序實現無縫集成。

🔧 技術細節

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 進行包管理
• 格式化和 linting 規則

添加新的文檔處理器

1. 創建一個繼承自 BaseProcessor 的新處理器類。
2. 實現所需的方法：can_process、process、extract_section、search。
3. 在 DocumentNavigator 中註冊處理器。
4. 添加全面的測試。

運行測試

# 運行所有測試
uv run tests/run_tests.py

代碼質量

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

# 檢查 linting
uv run --frozen ruff check .

# 類型檢查
uv run --frozen pyright

📄 許可證

本項目採用 Apache 2.0 許可證 - 詳情請參閱 LICENSE 文件。

🚧 路線圖

• [x] 完成 Markdown 處理器的實現
• [x] 添加 PDF 文檔支持（PyMuPDF）
• [x] 提高測試覆蓋率和質量
• [ ] 實現高級搜索功能
• [ ] 添加文檔摘要功能
• [ ] 支持其他文檔格式（DOCX、TXT 等）
• [ ] 優化大文檔的性能
• [ ] 為頻繁訪問的文檔添加緩存機制
• [ ] 為已加載的文檔添加持久化存儲

🤝 貢獻

1. 分叉倉庫。
2. 創建一個功能分支。
3. 遵循 CLAUDE.md 中的開發指南。
4. 為新功能添加測試。
5. 提交拉取請求。

🛠️ 支持

若有問題或疑問：

• 在 GitHub 上創建一個 issue。
• 查看 CLAUDE.md 中的文檔。
• 查看現有的 issue 和討論。