Ragdocs (Vector Documentation Search)

🚀 RAG 文档 MCP 服务器

本项目是一个 MCP 服务器实现，它提供基于向量搜索的工具，用于文档的检索与处理，能让 AI 助手借助相关文档上下文来增强其响应内容，为用户提供更精准、全面的信息。

✨ 主要特性

• 基于向量的文档搜索与检索：利用向量技术高效搜索和检索文档。
• 支持多个文档来源：可从多个源头获取文档进行处理。
• 语义搜索功能：实现基于语义的精准搜索。
• 自动化文档处理：自动完成文档的处理流程。
• 实时上下文增强 LLM（大语言模型）：实时为大语言模型提供上下文支持。

📦 安装指南

文档中未提及安装步骤，故跳过此章节。

💻 使用示例

基础用法

1. search_documentation

# 通过自然语言查询在存储的文档中进行搜索
# 输入：query 为要搜索的文本，limit 为可选参数，指定返回的最大结果数
# 例如，搜索包含 "技术细节" 的文档，最多返回 3 个结果
result = search_documentation(query="技术细节", limit=3)
print(result)

2. list_sources

# 列出当前系统中存储的所有文档来源
sources = list_sources()
print(sources)

3. extract_urls

# 从指定网页中提取并分析所有 URL
# 输入：url 为要分析的网页 URL，add_to_queue 为可选参数，指定是否将提取的 URL 添加到处理队列
# 例如，分析 https://example.com 网页，并将提取的 URL 添加到处理队列
urls = extract_urls(url="https://example.com", add_to_queue=True)
print(urls)

4. remove_documentation

# 通过其 URL 永久移除特定文档来源
# 输入：urls 为要移除的 URL 列表
# 例如，移除 https://example1.com 和 https://example2.com 这两个文档来源
remove_documentation(urls=["https://example1.com", "https://example2.com"])

5. list_queue

# 列出当前在文档处理队列中等待的所有 URL
queue = list_queue()
print(queue)

6. run_queue

# 处理并索引文档队列中的所有 URL
run_queue()

7. clear_queue

# 从文档处理队列中移除所有待处理的 URL
clear_queue()

高级用法

文档中未提及高级用法相关代码示例，故不展示高级用法部分。

📚 详细文档

工具详情

search_documentation

通过自然语言查询在存储的文档中进行搜索。返回匹配的摘录及其上下文，按相关性排序。 输入：

• query (字符串)：要在文档中搜索的文本。可以是自然语言查询、特定术语或代码片段。
• limit (数字，可选)：要返回的最大结果数（1 - 20，默认值：5）。较大的限制会提供更全面的结果，但可能会导致处理时间更长。

list_sources

列出当前系统中存储的所有文档来源。返回所有索引文档的综合列表，包括源 URL、标题和最后更新时间。使用此工具了解可用以搜索的文档内容或验证特定来源是否已索引。

extract_urls

从指定网页中提取并分析所有 URL。此工具会爬取指定网页，识别其中的所有超链接，并可选地将它们添加到处理队列中。 输入：

• url (字符串)：要分析的完整网页 URL（必须包含协议，例如 https://）。该页面必须是公开可访问的。
• add_to_queue (布尔值，可选)：如果为 true，则自动将提取的 URL 添加到处理队列中以供后续索引。在大型网站上使用时要谨慎以免队列过多。

remove_documentation

通过其 URL 永久移除特定文档来源。此操作会影响未来的搜索结果。 输入：

• urls (字符串数组)：要从数据库中移除的 URL 列表。每个 URL 必须与添加文档时使用的 URL 完全匹配。

list_queue

列出当前在文档处理队列中等待的所有 URL。显示待处理的文档来源，这些将在调用 run_queue 时进行处理。使用此工具监控队列状态、验证 URL 是否正确添加或检查处理 backlog。

run_queue

处理并索引文档队列中的所有 URL。每个 URL 将按顺序处理，并提供错误处理和重试逻辑。在处理过程中会提供进度更新。长时间运行的操作将在队列为空或发生不可恢复的错误之前继续进行。

clear_queue

从文档处理队列中移除所有待处理的 URL。使用此工具当需要重新开始、移除不需要的 URL 或取消待处理操作时清空队列。此操作是立即且永久性的 - 如果需要以后再次处理，将需要重新添加这些 URL。

使用场景

RAG 文档工具适用于：

• 增强 AI 响应的相关文档上下文
• 构建具有文档意识的 AI 助手
• 创建上下文感知工具以供开发人员使用
• 实现语义文档搜索
• 增强现有知识库

配置

与 Claude Desktop 一起使用

在 claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "rag-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@hannesrudolph/mcp-ragdocs"
      ],
      "env": {
        "OPENAI_API_KEY": "",
        "QDRANT_URL": "",
        "QDRANT_API_KEY": ""
      }
    }
  }
}

需要设置以下环境变量：

• OPENAI_API_KEY：用于与 OpenAI API 通信的密钥
• QDRANT_URL：Qdrant 向量数据库服务的 URL
• QDRANT_API_KEY：访问 Qdrant 服务所需的 API 密钥

🔧 技术细节

文档中未提及技术实现细节，故跳过此章节。

📄 许可证

项目采用MIT License许可。

致谢

感谢Hannes RAG为这个项目奠定的基础。

📋 待办事项

• [ ] 实现文档加载和索引功能
• [ ] 添加搜索结果排序选项
• [ ] 支持更多文档格式
• [ ] 增加错误处理和日志记录