内容
# bm-25
一个用于查询 Markdown 文件夹的轻量级 BM25 搜索服务器，作为 [MCP](https://modelcontextprotocol.io) 服务器公开。
## 仓库布局
```
bm-25/
├── mcp_server.py # 通过 stdio 公开 `search` 工具的 MCP 服务器
├── search.py # BM25 索引 + 搜索逻辑（也可作为 CLI 使用）
├── requirements.txt # Python 依赖项
└── data/ # 将您的 .md 文件放在此处
├── information_retrieval.md
├── machine_learning.md
└── python_intro.md
```
## 设置
1. **安装 Python 3.9+**（如果尚未安装）。
2. **安装依赖项：**
```bash
pip install -r requirements.txt
```
## 用法
### MCP 服务器
通过 stdio 运行服务器：
```bash
python mcp_server.py
```
它注册了一个名为 `search(query: str, top_n: int = 3)` 的工具，该工具返回 `data/` 中 markdown 文档库的 top-N BM25 匹配项（分数、路径、行范围和块文本）。OpenTelemetry 跨度会输出到 stderr，因此 stdout 保持干净以用于 JSON-RPC。
示例客户端配置（例如 `~/.config/claude/mcp.json` 或等效）：
```json
{
"mcpServers": {
"bm25-search": {
"command": "python",
"args": ["/absolute/path/to/bm-25/mcp_server.py"]
}
}
}
```
### Docker
构建镜像：
```bash
docker build -t bm25-mcp-server .
```
配置 Claude Desktop 以使用容器化服务器（在 `claude_desktop_config.json` 中）：
```json
{
"mcpServers": {
"bm25-search": {
"command": "docker",
"args": ["run", "-i", "--rm", "bm25-mcp-server"]
}
}
}
```
### CLI：交互模式
不带参数运行脚本以进入交互式查询循环：
```bash
python search.py
```
```
正在从 '.../data' 加载文档 …
已索引 3 个文档：['information_retrieval.md', 'machine_learning.md', 'python_intro.md']
输入搜索查询（或输入 'quit' 退出）：
> machine learning algorithms
1. machine_learning.md （分数：0.4210）
2. python_intro.md （分数：0.1898）
3. information_retrieval.md （分数：0.0751）
> quit
```
### CLI：单查询模式
直接在命令行上传递查询：
```bash
python search.py "BM25 ranking"
```
```
正在从 '.../data' 加载文档 …
已索引 3 个文档：['information_retrieval.md', 'machine_learning.md', 'python_intro.md']
查询：'BM25 ranking'
1. information_retrieval.md （分数：1.6854）
```
## 添加您自己的文档
将任意 `.md` 文件放入 `data/` 目录中。
它们将在下次运行 `search.py` 时自动被发现和索引。
## 工作原理
1. `data/` 中的所有 `.md` 文件都被读取并标记化（小写，标点符号剥离）。
2. 在标记列表上构建 [BM25Okapi](https://github.com/dorianbrown/rank_bm25) 索引。
3. 每个查询都以相同的方式标记化，并返回得分最高的文档。
BM25 关键参数（可在 `search.py` 中调整）：
| 参数 | 默认值 | 效果 |
|-----------|---------|--------|
| `k1` | 1.5 | 词频饱和度 |
| `b` | 0.75 | 文档长度归一化 |
