内容
# RLM-MCP：用于Claude Code的递归语言模型服务器
**状态**: ✅ v0.2.2 - 团队环境的生产就绪版本
一个模型上下文协议（MCP）服务器，实现了来自 [Zhang et al. (2025)](https://arxiv.org/abs/2512.24601) 的递归语言模型模式，使得LLM能够通过将提示视为外部环境对象来处理任意长的上下文。
**v0.2.x 新增功能**：
- **v0.2.2**：精确的BM25文档ID过滤 • 高亮边界限制 • 服务器配置默认值 • 会话关闭的预算豁免
- **v0.2.1**：原子预算执行 • 分段索引持久性 • 截断警告 • 错误消息改进
- **v0.2.0**：持久索引 • 并发会话安全性 • 结构化日志 • 批量文档加载（2-3倍更快）
## 关键洞察
> 长提示不应直接输入神经网络，而是应视为LLM可以象征性交互的环境的一部分。
## 功能
### 核心能力
- **基于会话的文档管理** — 加载文件、目录或内联内容，支持批量处理
- **按需分段** — 固定、基于行或基于分隔符的策略，智能缓存
- **BM25搜索** — 延迟构建，持久缓存，服务器重启后仍然有效
- **工件存储** — 存储派生结果，完整跨度 provenance
### 生产功能（v0.2.0）
- **持久索引** — BM25索引保存到磁盘，原子写入，损坏恢复
- **并发会话安全性** — 每会话锁，防止多用户环境中的竞争条件
- **结构化日志** — JSON输出，相关ID，用于生产可观察性
- **批量文档加载** — 并发文件加载，内存限制信号量（2-3倍更快）
## 状态和验证
**v0.2.2** 生产就绪验证：
- ✅ **103/103 测试通过** （100% 功能 + 生产功能）
- ✅ **所有13个核心工具** 实现规范命名
- ✅ **MCP协议集成** 与真实客户端确认
- ✅ **大型语料库测试** — 1M+字符加载和索引
- ✅ **性能验证** — 亚秒级搜索，<100ms索引加载
- ✅ **并发测试** — 50并发操作，无竞争条件
- ✅ **内存安全性** — 有限信号量防止大批量OOM
- ✅ **生产日志** — JSON结构化日志，相关跟踪
### 测试覆盖率
- 错误处理：13个测试
- 并发安全性：9个测试
- 索引持久性：10个测试
- 集成工作流：14个测试
- 大型语料库性能：5个测试
- 结构化日志：13个测试
- 批量加载：7个测试
- 源跟踪：8个测试
- 存储层：11个测试
- v0.2.2错误修复：13个测试
参见 `MIGRATION_v0.1_to_v0.2.md` 获取升级指南。
## 安装
```bash
pip install rlm-mcp
```
或使用开发依赖：
```bash
pip install rlm-mcp[dev]
```
## 快速开始
```python
from rlm_mcp import run_server
# 启动MCP服务器
run_server()
```
## 工具
所有工具都使用规范命名：`rlm.<类别>.<操作>`
| 类别 | 工具 |
|----------|-------|
| `rlm.session` | `create`, `info`, `close` |
| `rlm.docs` | `load`, `list`, `peek` |
| `rlm.chunk` | `create` |
| `rlm.span` | `get` |
| `rlm.search` | `query` |
| `rlm.artifact` | `store`, `list`, `get` |
## 工作流模式
1. **初始化**：`rlm.session.create` 配置
2. **加载**：`rlm.docs.load` 文档
3. **探查**：`rlm.docs.peek` 结构
4. **搜索**：`rlm.search.query` 查找相关部分
5. **分段**：`rlm.chunk.create` 适当策略
6. **处理**：`rlm.span.get` + 客户端子调用
7. **存储**：`rlm.artifact.store` 结果和出处
8. **关闭**：`rlm.session.close`
## 配置
配置文件：`~/.rlm-mcp/config.yaml`
```yaml
# 数据存储
data_dir: ~/.rlm-mcp
# 会话限制（每会话可覆盖）
default_max_tool_calls: 500
default_max_chars_per_response: 50000
default_max_chars_per_peek: 10000
# 批量加载（v0.2.0）
max_concurrent_loads: 20 # 最大并发文件加载（内存安全）
max_file_size_mb: 100 # 拒绝大于此大小的文件
# 日志（v0.2.0）
log_level: "INFO" # DEBUG, INFO, WARNING, ERROR
structured_logging: true # JSON格式（true）vs人类可读（false）
log_file: null # 可选："/var/log/rlm-mcp.log"
# 工具命名：默认严格（如果SDK不支持规范名称，则失败）
# 仅为旧MCP SDK的实验设置此项
allow_noncanonical_tool_names: false
```
### 工具命名（严格模式 vs 兼容模式）
默认情况下，RLM-MCP需要支持显式工具命名的MCP SDK（例如FastMCP）。这确保工具可以作为 `rlm.session.create` 而不是 `rlm_session_create` 被发现。
- **严格模式（默认）**：如果SDK不支持 `tool(name=...)`，服务器启动失败
- **兼容模式**：如果SDK不支持，服务器启动失败
```yaml
# ~/.rlm-mcp/config.yaml
allow_noncanonical_tool_names: true # 启用兼容模式（不推荐）
```
## 日志（v0.2.0）
RLM-MCP生成结构化JSON日志，用于生产可观察性。每个操作都有一个唯一的关联ID，用于跟踪相关事件。
### JSON日志格式
```json
{
"timestamp": "2026-01-15T10:30:45.123456Z",
"level": "INFO",
"logger": "rlm_mcp.server",
"message": "Completed rlm.session.create",
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"session_id": "session-123",
"operation": "rlm.session.create",
"duration_ms": 42,
"success": true
}
```
### 过滤日志
```bash
# 按会话过滤
cat /var/log/rlm-mcp.log | jq 'select(.session_id == "session-123")'
# 按操作过滤
cat /var/log/rlm-mcp.log | jq 'select(.operation == "rlm.search.query")'
# 跟踪关联ID的操作
cat /var/log/rlm-mcp.log | jq 'select(.correlation_id == "a1b2c3d4...")'
# 只显示错误
cat /var/log/rlm-mcp.log | jq 'select(.level == "ERROR")'
```
参见 `docs/LOGGING.md` 获取详细日志指南。
## 会话配置
```python
{
"max_tool_calls": 500, # 预算执行
"max_chars_per_response": 50000, # DOS保护
"max_chars_per_peek": 10000, # DOS保护
"chunk_cache_enabled": True,
"model_hints": { # 客户端建议
"root_model": "claude-opus-4-5-20251101",
"subcall_model": "claude-sonnet-4-5-20250929",
"bulk_model": "claude-haiku-4-5-20251001"
}
}
```
## 架构
```
┌─────────────────────────────────────────┐
│ Claude Skills（策略层） │
├─────────────────────────────────────────┤
│ MCP服务器（RLM运行时） │
│ • 会话管理 + 并发 │
│ • 文档/跨度操作 │
│ • BM25搜索（延迟，持久） │
│ • 批量加载与信号量 │
│ • 响应大小限制 │
├─────────────────────────────────────────┤
│ 本地持久性（v0.2.0） │
│ • SQLite：会话，文档，跨度 │
│ • Blob存储：内容寻址 │
│ • 索引缓存：持久BM25 │
│ • 结构化日志：JSON + 关联 │
└─────────────────────────────────────────┘
```
## 设计原则
1. **本地优先** — 所有读取/写入操作都命中本地存储
2. **客户端管理的子调用** — MCP是“世界”，客户端进行LLM调用
3. **不可变文档** — 内容寻址，永不修改
4. **按需分段** — 查询时分段，缓存结果
5. **DOS保护** — 响应大小限制
## 开发
```bash
# 克隆并使用uv安装（推荐）
git clone https://github.com/yourorg/rlm-mcp.git
cd rlm-mcp
uv sync --extra dev
# 运行测试
uv run pytest
# 或使用pip（需要可编辑安装进行测试）
pip install -e ".[dev]"
pytest
# 类型检查
uv run mypy src/
# linting
uv run ruff check src/
```
### 使用MCP检查器进行烟雾测试
验证工具发现和真实客户端的模式：
```bash
# 启动服务器
uv run rlm-mcp
# 在另一个终端，使用MCP检查器
npx @anthropic/mcp-inspector
```
验证：
- 工具名称显示为 `rlm.session.create` 而不是 `rlm_session_create`
- 模式与预期输入/输出结构匹配
- 响应中出现 `truncated` 和 `index_built` 字段
## License
MIT
## 参考文献
- Zhang, A. L., Kraska, T., & Khattab, O. (2025). *递归语言模型*. arXiv:2512.24601
