内容
# 近似过滤器使用 MCP 服务器
## 概述
本项目比较了几种近似过滤器数据结构，使用 MCP 服务器和 LLM 工具调用。
近似过滤器通过存储压缩摘要而不是完整键来减少内存使用。
由于这种权衡，一些过滤器可能会返回假阳性或支持有限操作。
项目比较了：
- 布隆过滤器（Bloom Filter）
- 计数布隆过滤器（Counting Bloom Filter）
- 布谷鸟过滤器（Cuckoo Filter）
- 简化 SuRF（Simplified SuRF）
一个精确的哈希集服务器也被包含作为比较的基准。
## 已实现的 MCP 服务器
| MCP 服务器 | 数据结构 | 描述 |
|---|---|---|
| `filter-naive` | 精确集 / 哈希表 | 精确成员资格基准 |
| `filter-bloom` | 布隆过滤器 | 内存高效的近似成员资格过滤器 |
| `filter-counting-bloom` | 计数布隆过滤器 | 支持删除的布隆过滤器 |
| `filter-cuckoo` | 布谷鸟过滤器 | 基于指纹的近似过滤器 |
| `filter-surf` | 简化 SuRF | 近似前缀/范围过滤器 |
## 项目目标
本项目的目标是比较不同过滤器结构在相同工作负载下的行为。
比较关注：
- 成员资格查询准确性
- 假阳性率
- 内存使用
- 查询延迟
- 插入和删除支持
- 前缀和范围查询能力
所有服务器通过 MCP 工具提供相同的 ADT 接口，以便可以一致地测试它们。
## 场景
### 搜索关键词字典管理
服务器模拟关键词搜索系统。
示例：
- 搜索自动补全
- 关键词查找
- 阻止词检查
- 字典成员资格测试
相同的关键词数据集和查询用于所有过滤器来比较性能和行为。
## ADT
所有 MCP 服务器提供以下工具：
| 工具 | 描述 |
|---|---|
| `build(items)` | 从数据集构建过滤器 |
| `insert(x)` | 插入键 |
| `contains(x)` | 成员资格查询 |
| `delete(x)` | 删除键（如果支持） |
| `range_query(lo, hi)` | 范围查询 |
| `prefix_query(prefix)` | 前缀查询 |
| `memory_usage()` | 返回估计的内存使用 |
| `false_positive_rate()` | 测量假阳性率 |
## 理论 / 定性结构比较
| 结构 | 假阳性 | 删除支持 | 前缀/范围查询 | 内存效率 |
|---|---|---|---|---|
| 精确集 | 否 | 是 | 是 | 低 |
| 布隆过滤器 | 是 | 否 | 否 | 非常高 |
| 计数布隆过滤器 | 是 | 是 | 否 | 高 |
| 布谷鸟过滤器 | 是 | 是 | 否 | 高 |
| 简化 SuRF | 是 | 否 | 是 | 中等 |
此表格描述了每种结构的预期定性行为。它不是测量的基准测试结果。
## 基准测试结果
基准测试结果可在 [docs/benchmark_results.md](docs/benchmark_results.md) 中找到。
基准测试使用 `src/membership_filters/benchmark.py` 中的固定综合工作负载，并使用相同的构建项和缺失查询探测比较所有过滤器。它报告了 `memory_usage()` 估计的内存、`false_positive_rate()` 测量的假阳性率和平均本地 `contains()` 延迟。
本地运行：
```bash
PYTHONPATH=src python -m membership_filters.benchmark
```
```powershell
$env:PYTHONPATH='src'; python -m membership_filters.benchmark
```
运行冒烟测试：
```bash
PYTHONPATH=src python -m unittest discover -s tests
```
```powershell
$env:PYTHONPATH='src'; python -m unittest discover -s tests
```
## 备注
- `filter-naive` 被包含作为精确基准。
- SuRF 服务器是简化的教育实现，而不是基于 LOUDS 的生产 SuRF。
- 项目专注于比较和实验，而不是生产优化。
## 示例 Claude Desktop MCP 配置
```json
{
"mcpServers": {
"filter-naive": {
"command": "python",
"args": ["src/filter_/filter_naive_server.py"]
},
"filter-bloom": {
"command": "python",
"args": ["src/filter_/filter_bloom_server.py"]
},
"filter-counting-bloom": {
"command": "python",
"args": ["src/filter_/filter_counting_bloom_server.py"]
},
"filter-cuckoo": {
"command": "python",
"args": ["src/filter_/filter_cuckoo_server.py"]
},
"filter-surf": {
"command": "python",
"args": ["src/filter_/filter_surf_server.py"]
}
}
}
```
## 系统流程
```text
Claude / LLM
↓
MCP 工具调用
↓
mcp_server.py
↓
registry.py
↓
选定的过滤器类
↓
布隆 / 计数布隆 / 布谷鸟 / SuRF / 精确集
```
### 流程描述
1. LLM 发送 MCP 工具请求。
2. `mcp_server.py` 公开公共 ADT 接口。
3. `registry.py` 选择请求的过滤器实现。
4. 选定的过滤器处理查询。
5. 结果通过 MCP 服务器返回。
此设计允许所有过滤器通过相同的接口和工作负载进行测试。
## 仓库结构
```text
src/
├── filter_/
│ ├── filter_naive_server.py
│ ├── filter_bloom_server.py
│ ├── filter_counting_bloom_server.py
│ ├── filter_cuckoo_server.py
│ └── filter_surf_server.py
│
└── membership_filters/
├── base.py
├── hashing.py
├── mcp_server.py
├── registry.py
└── filters/
```
