使用说明

Whoosh RAG MCP-文档搜索服务器

一种模型上下文协议（MCP）服务器，使用Whoosh为文档提供全文搜索功能。这使得Cline和GitHub Copilot等人工智能助手能够搜索和检索相关文档。

依据

大型语言模型（LLM）通常基于过时的代码和文档进行训练，这可能会导致建议使用已弃用的函数或模式。此MCP服务器使用Whoosh对您的最新文档进行快速、精确和可解释的全文搜索，帮助AI助手和用户找到最新、权威的答案。这提高了编码的正确性和可靠性，特别是在技术环境中。Whoosh是轻量级的，CPU友好的，不需要嵌入式或GPU。为了获得最佳结果，请在查询中包含同义词以扩大覆盖范围。

特性

全文搜索 通过markdown（.md、.mdx）和reStructuredText（.rst）文档
基于章节的索引 用于细粒度搜索结果
干度分析仪 为了更好的搜索匹配
多种搜索模式：片段、完整内容或按部分

提供的工具

MCP服务器向AI助手公开以下工具：

search_documentation -使用全文搜索搜索索引文档
build_documentation_index -从文档文件构建/重建搜索索引
update_documentation_index -更新现有索引（当前正在执行完全重建）
get_index_info -获取有关当前索引状态的信息

安装

1.从PyPI安装

安装该软件包的最简单方法是从PyPI：

pip install whoosh-rag-mcp

或者，您可以直接从GitHub安装：

pip install git+https://github.com/jianlins/whoosh_rag_mcp.git

或用于开发（可编辑安装）：

git clone https://github.com/jianlins/whoosh_rag_mcp.git
cd whoosh_rag_mcp
pip install -e .

2.配置环境变量

服务器使用环境变量来查找文档：

DOCS_ROOT -文档目录的路径（默认： ./references)
INDEX_DIR -存储Whoosh索引的路径（默认值： ./whoosh_index)

3.配置MCP服务器

根据您的AI助手选择适当的配置方法：

选项A：适用于Cline（VS代码扩展）

将服务器配置添加到Cline MCP设置文件中：

视窗: %APPDATA%\Code - Insiders\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

macOS: ~/Library/Application Support/Code - Insiders/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Linux: ~/.config/Code - Insiders/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

将此配置添加到 mcpServers 对象：

{
  "mcpServers": {
    "whoosh-rag-docs": {
      "command": "python",
      "args": ["-m", "whoosh_rag_mcp.mcp_server"],
      "env": {
        "DOCS_ROOT": "c:/Users/YourUsername/Projects/whoosh_rag_mcp/references",
        "INDEX_DIR": "c:/Users/YourUsername/Projects/whoosh_rag_mcp/whoosh_index"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

重要：将路径替换为实际的项目目录路径。

临床MCP配置示例：

选项B：用于GitHub Copilot聊天（VS代码扩展）

GitHub Copilot使用与Cline不同的配置格式。您将创建一个 mcp.json 文件而不是编辑 settings.json.

方法1：使用命令面板（推荐）

打开命令选项板(Ctrl+Shift+P 在Windows/Linux或 Cmd+Shift+P 在macOS上）
运行命令： MCP：添加服务器
出现提示时，选择标准作为服务器类型
填写服务器详细信息：
- 服务器名称: whoosh-rag-docs
- 命令: python （如果不在path中，则为Python的完整路径）
- 参数:
  - 点击“添加参数”并输入 -m
  - 再次单击“添加参数”并输入 whoosh_rag_mcp.mcp_server
添加环境变量：
- 点击“添加环境变量”
- 名字: DOCS_ROOT, 价值: c:/Users/YourUsername/Projects/whoosh_rag_mcp/references
- 再次点击“添加环境变量”
- 名字: INDEX_DIR, 价值: c:/Users/YourUsername/Projects/whoosh_rag_mcp/whoosh_index
选择保存位置：选择全球（适用于所有工作区）或 工作区 （仅限当前项目）

方法2：手动配置

创建MCP配置文件:
- 对于 全球的 （所有工作区）：运行 MCP：打开用户配置 从命令选项板
- 对于 工作区 （当前项目）：创建 .vscode/mcp.json 在您的项目中
添加服务器配置:

{
  "servers": {
    "whoosh-rag-docs": {
      "command": "python",
      "args": ["-m", "whoosh_rag_mcp.mcp_server"],
      "env": {
        "DOCS_ROOT": "c:/Users/YourUsername/Projects/whoosh_rag_mcp/references",
        "INDEX_DIR": "c:/Users/YourUsername/Projects/whoosh_rag_mcp/whoosh_index"
      }
    }
  }
}

备注：使用 python -m whoosh_rag_mcp.mcp_server 比指定直接文件路径更便携。确保已安装该包，或者您的Python路径包含项目目录。

如果Python不在你的PATH中，使用完整路径：

"command": "c:/Users/YourUsername/AppData/Local/Programs/Python/Python311/python.exe"

启动MCP服务器:
- 跑 MCP：列出服务器 从命令选项板
- 选择 whoosh-rag-docs 然后单击 启动服务器
- 或启用自动启动：设置 chat.mcp.autostart 到 true 在VS代码设置中
验证连接:
- 打开GitHub Copilot聊天
- 点击工具聊天输入中的按钮，查看可用工具
- 您应该看到以下工具 whoosh-rag-docs 上市

4.建立指数

在搜索之前，您需要构建索引。您可以：

选项A：使用Cline构建索引：

问Cline：“使用build_documentation_index工具为我的文档编制索引”

选项B：从命令行手动生成：

python -m whoosh_rag_mcp.doc_retriever --build

安全特性：如果索引已存在，系统将提示您在覆盖它之前进行确认。这可以防止现有索引意外丢失。

CLI选项:
- --build：如果索引存在，则提示确认
```
python -m whoosh_rag_mcp.doc_retriever --build
```
- --build-force：跳过确认并立即重建
```
python -m whoosh_rag_mcp.doc_retriever --build-force
```
MCP工具：通话时 build_documentation_index，如果存在索引，则必须设置 force 参数到 true:
```
{
  "force": true
}
```

用法

配置后，AI助手可以自动使用这些工具。

与Cline一起使用

以下是一些示例提示：

“使用search_document工具查找有关任务重试的信息”
“在文档中搜索流装饰器”
“在文档中查找部署配置”
“获取索引信息，查看有多少文档被索引”
“构建文档索引”

使用GitHub Copilot聊天

您可以通过多种方式与MCP服务器交互：

方法1：使用@participent语法 （如果支持）：

@whoosh-rag-docs search for information about task retries

方法2：直接调用工具 （推荐）：

Can you search the documentation for "flow decorators"?

方法3：自然语言请求:

I need help understanding deployment configuration. Can you search the docs?

Copilot聊天交互示例:

“在索引文档中搜索错误处理示例”
“在文档中查找有关异步/等待模式的信息”
“文档对配置选项有什么说明？”
在文档中搜索“身份验证”

项目结构

whoosh_rag_mcp/
├── src/
│   └── whoosh_rag_mcp/
│       ├── __init__.py        # Package initialization
│       ├── mcp_server.py      # MCP server implementation
│       └── doc_retriever.py   # Core search and indexing logic
├── references/                # Your documentation files go here
│   ├── dask_docs/
│   ├── prefect_docs/
│   └── setuptools_docs/
├── whoosh_index/              # Search index (auto-generated)
├── pyproject.toml             # Package configuration (setuptools)
├── requirements.txt           # Python dependencies
└── README.md                  # This file

运作原理

MCP服务器作为子进程运行，并通过stdio进行通信
AI助手通过MCP协议发现可用工具
当您要求搜索文档时，助理会致电 search_documentation 工具
服务器使用Whoosh对索引文档执行全文搜索
结果将返回给助手，然后助手可以用它们来回答您的问题

手动使用（可选）

您还可以直接从命令行使用搜索功能：

# Build the index (will prompt for confirmation if index exists)
python -m whoosh_rag_mcp.doc_retriever --build

# Force rebuild the index (skips confirmation prompt)
python -m whoosh_rag_mcp.doc_retriever --build-force

# Update the index (currently same as --build, will prompt if index exists)
python -m whoosh_rag_mcp.doc_retriever --update

# Search documentation
python -m whoosh_rag_mcp.doc_retriever --query "your search terms" --json

# Search by section
python -m whoosh_rag_mcp.doc_retriever --query "your search terms" --section --json

# Get full content
python -m whoosh_rag_mcp.doc_retriever --query "your search terms" --full --json

故障排除

服务器未连接（Cline）

检查Python是否在您的PATH中
验证MCP设置中的路径是否正确（使用绝对路径）
检查是否安装了依赖项： pip install -r requirements.txt
在Cline的MCP服务器日志中查找错误消息

视觉参考：

GitHub Copilot聊天问题

MCP服务器未出现或未启动：

验证配置文件:
- GitHub Copilot使用 mcp.json，不 settings.json
- 打开MCP配置：运行 MCP：打开用户配置 （全局）或检查 .vscode/mcp.json （用于工作空间）
- 验证文件是否存在并包含有效的JSON

检查配置格式:

必须使用 "servers" 密钥（不是 "mcpServers" 像克莱恩）
配置必须是有效的JSON（没有尾随逗号，正确转义）

有效配置示例：

{
  "servers": {
    "whoosh-rag-docs": {
      "command": "python",
      "args": ["-m", "whoosh_rag_mcp.mcp_server"],
      "env": {
        "DOCS_ROOT": "c:/path/to/references",
        "INDEX_DIR": "c:/path/to/whoosh_index"
      }
    }
  }
}

启动MCP服务器:
- 跑 MCP：列出服务器 从命令选项板
- 找到 whoosh-rag-docs 并选择 启动服务器
- 检查输出中是否有任何错误消息
验证Python路径:
- 开放式终端： python --version
- 如果找不到命令，请在 "command" 领域
- 窗户： "c:/Users/YourUsername/AppData/Local/Programs/Python/Python311/python.exe"
- macOS/Linux： "/usr/local/bin/python3" 或 "/usr/bin/python3"
检查VS代码输出面板:
- 打开输出面板： View > Output
- 从下拉列表中选择“GitHub Copilot Chat”
- 查找与MCP相关的错误消息
完全重新启动VS代码:
- 关闭所有VS代码窗口
- 重新打开VS代码
- 等待几秒钟，让扩展初始化
手动测试MCP服务器:
```
python -m whoosh_rag_mcp.mcp_server
```
- 服务器应无错误启动
- 按 Ctrl+C 停止

副驾驶未使用MCP工具：

先建立索引 （搜索工作前需要）：
```
python -m whoosh_rag_mcp.doc_retriever --build
```
明确你的要求:
- 而不是：“告诉我任务重试的情况”
- Try：“在文档中搜索任务重试次数”
- 或者：“使用search_documentation工具查找有关任务重试的信息”
检查GitHub Copilot Chat是否支持MCP:
- GitHub Copilot Chat中的MCP支持是一个新功能
- 确保您拥有GitHub Copilot扩展的最新版本
- 检查扩展更新： Extensions > Search for "GitHub Copilot" > Update if available

没有搜索结果

确保索引已建立：让Cline运行 get_index_info
如果索引不存在，请使用 build_documentation_index
检查一下 DOCS_ROOT 指向包含.md、.mdx或.rst文件的目录

索引构建失败

验证 DOCS_ROOT 目录存在并包含文档文件
检查文件权限-确保服务器可以读取文档文件
确保的写入权限 INDEX_DIR

许可证

MIT许可证-有关详细信息，请参阅许可证文件