docrag (Ryan M Bishop)

DocRAG-人工智能文档RAG系统

一个轻量级的、可安装的Python包，通过MCP（模型上下文协议）服务器提供RAG（检索增强生成）对技术文档的访问。这使LLM能够按需搜索和检索相关文档。

特性

• 🚀 带有CLI和MCP服务器的单点安装包
• 📚 基于项目的文档集合（BrightSign、Venafi、Qumu、web框架）
• 🔍 使用LanceDB高效嵌入的本地矢量数据库
• 📥 从本地文件或抓取的来源轻松获取文档
• 🤖 设计用于通过MCP与Claude Code一起使用

安装

先决条件

• Python 3.10+
• pipx（推荐）或pip
• git（用于更新）

推荐：使用pipx进行全局安装

# Install globally with pipx in editable mode (keeps dependencies isolated)
pipx install -e /opt/claude-ops/doc-rag

# Verify installation
docrag --help

# Optional: Install Playwright browsers (for scraping)
pipx runpip docrag install playwright
pipx run --spec docrag playwright install chromium

注： 这 -e 标志以“可编辑”模式安装，这意味着对源代码的更改会立即反映出来，而无需重新安装。

替代方案：从源代码安装（开发）

# Clone or navigate to the project directory
cd /opt/claude-ops/doc-rag

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Install Playwright browsers (for scraping)
playwright install chromium

更新DocRAG

选项1：使用更新脚本（推荐）

cd /opt/claude-ops/doc-rag
./update.sh

此脚本将：

• 从git中提取最新更改
• 检测您的安装方法（pipx或pip）
• 仅在必要时重新安装（不可编辑的安装）
• 自动处理可编辑的安装

选项2：使用Make

cd /opt/claude-ops/doc-rag
make update

选项3：手动更新

对于 可编辑安装 （已安装 -e):

cd /opt/claude-ops/doc-rag
git pull origin main
# No reinstall needed - changes are already active!

对于 定期安装 （未安装 -e):

cd /opt/claude-ops/doc-rag
git pull origin main
pipx uninstall docrag && pipx install -e .
# or for pip: pip install -e . --force-reinstall

验证更新

# Check git status
cd /opt/claude-ops/doc-rag
git log -1 --oneline

# Test the installation
docrag --version
docrag --help

快速开始

1.初始化DocRAG

docrag init

这将在以下位置创建配置目录 ~/.docrag/ 具有以下结构：

~/.docrag/
├── config.json           # Global configuration
├── collections/          # Documentation collections
└── vectordb/            # LanceDB storage

2.添加文档集合

# Add documentation from a local directory
docrag add brightsign --source /path/to/brightsign/docs --description "BrightSign player documentation"

# Or add without source initially
docrag add venafi --description "Venafi TPP API documentation"

3.列出收藏

docrag list

4.搜索文档（CLI测试）

# Search across all active collections
docrag search "how to initialize the player"

# Search a specific collection
docrag search "authentication methods" --collection venafi --limit 10

5.启动MCP服务器

docrag serve

服务器将在stdio上监听来自Claude Code的连接。

CLI命令

docrag init

初始化DocRAG配置目录。

docrag add

添加新的文档集合。

选项：

• -s, --source PATH -包含文档的源目录
• -d, --description TEXT -藏品描述

例子：

docrag add qumu --source ~/docs/qumu --description "Qumu video platform docs"

docrag list

列出所有文档集合及其状态。

docrag update

用新文档更新现有集合。

例子：

docrag update brightsign ~/docs/brightsign/updated

docrag remove

删除文档集合（确认后）。

docrag search

从CLI中搜索文档以进行测试。

选项：

• -c, --collection TEXT -要搜索的特定集合
• -l, --limit INTEGER -结果数（默认值：5）

例子：

docrag search "websocket connection" --collection brightsign

docrag serve

启动MCP服务器以进行Claude Code集成。

docrag scrape

从网站上删除文档。

选项：

• -o, --output PATH -输出目录（必填）
• --smart, --use-crawl4ai -使用AI驱动的Crawl4AI铲运机（推荐）
• --no-llm -禁用LLM提取（比基本提取更快，更好）
• --llm-provider TEXT -LLM提供程序（默认：openai/gpt-4o-mini）
• --playwright -使用Playwright制作动态内容（基本刮刀）
• --max-pages INTEGER -要抓取的最大页面数（默认值：1000）

示例：

# Basic scraping
docrag scrape https://docs.example.com --output ./docs

# Smart scraping with AI (recommended)
docrag scrape https://docs.example.com --output ./docs --smart

# Smart scraping without LLM (faster, no API key needed)
docrag scrape https://docs.example.com --output ./docs --smart --no-llm

# Limit pages
docrag scrape https://docs.example.com --output ./docs --max-pages 100

智能刮擦功能：

• ✨ 基于AI的内容提取
• 🎯 自动删除导航和样板
• 📊 更好地处理复杂的布局
• 🧠 文档结构的语义理解
• ⚡ 比基本刮擦更快、更准确

要启用智能抓取，请执行以下操作：

# Install Crawl4AI
pipx inject docrag crawl4ai

# Optional: Set OpenAI API key for LLM-powered extraction
export OPENAI_API_KEY='your-key-here'

使用Claude代码

1.配置克劳德代码MCP设置

将DocRAG添加到您的Claude Code MCP配置中(~/.config/claude-code/mcp_settings.json 或类似）：

{
  "mcpServers": {
    "docrag": {
      "command": "docrag",
      "args": ["serve"],
      "env": {}
    }
  }
}

如果使用完整路径：

{
  "mcpServers": {
    "docrag": {
      "command": "/home/claude-admin/.local/bin/docrag",
      "args": ["serve"],
      "env": {}
    }
  }
}

2.重新启动克劳德代码

添加配置后，重新启动Claude Code以加载MCP服务器。

3.在克劳德代码中使用

一旦连接，Claude Code可以使用两个工具：

search_docs：搜索索引文档集

Query: "how to handle authentication in BrightSign"
Collection: (optional) "brightsign"
Limit: (optional) 5

list_collections：列出所有可用的文档集合

Claude在处理需要文档访问权限的项目时会自动使用这些工具。

建筑

核心组件

1. 配置管理器 (config.py)-管理配置和收集元数据
2. 嵌入式生成器 (embeddings.py)-使用句子变换器生成嵌入
3. 矢量数据库 (vectordb.py)LanceDB包装器，用于矢量存储和搜索
4. 文档索引器 (indexer.py)-智能文档分块和索引
5. DocRAG服务器 (server.py)-MCP服务器实施
6. 命令行界面 (cli.py)-命令行界面

技术栈

• MCP框架：官方Anthropic MCP包
• 向量数据库：LanceDB（轻量级、基于文件、高性能）
• 嵌入：全MiniLM-L6-v2型号的句子转换器（384调光，快速，本地）
• 文本处理：用于智能分块的langchain文本拆分器
• 命令行界面：单击以获取用户友好的命令
• Web剪贴：剧作家+美女搜刮4

数据结构

~/.docrag/
├── config.json                 # Global configuration
│   └── {
│         "active_collections": ["brightsign", "venafi"],
│         "embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
│         "chunk_size": 512,
│         "chunk_overlap": 50
│       }
├── collections/
│   ├── brightsign/
│   │   ├── metadata.json       # Collection metadata
│   │   └── source_docs/        # Original documents
│   ├── venafi/
│   └── qumu/
└── vectordb/
    └── lancedb/                # Vector storage (one table per collection)

配置

全局配置存储在 ~/.docrag/config.json:

{
  "active_collections": ["brightsign", "venafi"],
  "embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
  "chunk_size": 512,
  "chunk_overlap": 50
}

集合元数据存储在 ~/.docrag/collections//metadata.json:

{
  "name": "brightsign",
  "source_type": "local",
  "source_path": "/path/to/docs",
  "created_at": "2025-10-28T10:00:00",
  "updated_at": "2025-10-28T10:00:00",
  "doc_count": 150,
  "description": "BrightSign player documentation"
}

发展

项目结构

docrag/
├── docrag/
│   ├── __init__.py
│   ├── cli.py              # CLI commands
│   ├── server.py           # MCP server
│   ├── indexer.py          # Document indexing
│   ├── vectordb.py         # Vector database
│   ├── embeddings.py       # Embeddings
│   ├── config.py           # Configuration
│   └── scrapers/           # Web scrapers
│       ├── __init__.py
│       ├── base.py
│       └── generic.py
├── tests/
├── pyproject.toml
├── README.md
└── DOCRAG_MVP_BUILD_GUIDE.md

运行测试

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

代码格式化

# Format with black
black docrag/

# Lint with ruff
ruff check docrag/

故障排除

“DocRAG未初始化”

跑 docrag init 首先创建配置目录。

“未找到收藏”

添加一个收藏 docrag add --source .

“模型下载失败”

第一次运行DocRAG时，它将下载句子转换器模型（~100MB）。确保你有互联网连接。

“未安装剧作家”

如果使用刮刀，请运行 playwright install chromium.

未来的增强功能

• \[\]Web scraper CLI命令
• \[\]支持更多文件类型（PDF、HTML、RST）
• \[\]增量索引（仅索引更改的文件）
• \[\]收款激活/停用
• \[\]收集统计数据和健康检查
• \[\]进出口收款
• \[\]集合的云同步
• \[\]高级搜索筛选器

许可证

麻省理工学院

作者

Ryan-专为家庭实验室和Claude Code集成而构建