内容
<div align="center">
<img src="icon.jpeg" alt="RavenDB Doctor MCP" width="512" />
</div>
> *"难道智慧就像乌鸦一样出现在地球上，受到腐肉气味的启发？*
> — 弗里德里希·尼采
一个 [MCP](https://modelcontextprotocol.io/) 服务器，暴露 RavenDB 的调试和监控端点，作为 AI 助手工具。 将 Claude（或任何 MCP 客户端）连接到您的 RavenDB 集群，并要求它检查性能、健康、索引、复制、内存等 - 用简单的语言。
## 添加到 Claude
### 选项 1：Docker（推荐）
从 GitHub 容器注册表拉取预构建的镜像：
```bash
docker pull ghcr.io/gregolsky/ghcr.io/gregolsky/ravendb-doctor-mcp:latest
```
或者自己构建：
```bash
docker build -t ghcr.io/gregolsky/ghcr.io/gregolsky/ravendb-doctor-mcp:latest .
```
然后将服务器添加到您的 Claude MCP 配置中。 配置文件位置取决于客户端：
- **Claude Desktop** — `claude_desktop_config.json`（通过设置 → 开发者 → 编辑配置打开）
- **Claude Code** — 项目根目录下的 `.mcp.json`，或全局使用的 `~/.claude/mcp.json`
复制 `mcp-config.example.json` 作为起点，并填写您的值：
**未加密 / HTTP 集群：**
```json
{
"mcpServers": {
"ravendb-doctor": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "C:/ravendb-mcp-output:/data/output",
"-e", "RAVEN_NODE_URLS=http://localhost:8080",
"ghcr.io/gregolsky/ravendb-doctor-mcp:latest"
]
}
}
}
```
**带有 PFX 证书的安全集群（文件路径）：**
```json
{
"mcpServers": {
"ravendb-doctor": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "C:/ravendb-certs:/certs:ro",
"-v", "C:/ravendb-mcp-output:/data/output",
"-e", "RAVEN_NODE_URLS=https://a.your-cluster.ravendb.cloud,https://b.your-cluster.ravendb.cloud,https://c.your-cluster.ravendb.cloud",
"-e", "RAVEN_CERT_PFX=/certs/admin.client.certificate.pfx",
"-e", "RAVEN_CERT_PASSWORD",
"ghcr.io/gregolsky/ravendb-doctor-mcp:latest"
],
"env": {
"RAVEN_CERT_PASSWORD": "your-pfx-password-here"
}
}
}
}
```
**带有 PFX 证书的安全集群（内联 base64，无需卷挂载）：**
```json
{
"mcpServers": {
"ravendb-doctor": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "C:/ravendb-mcp-output:/data/output",
"-e", "RAVEN_NODE_URLS=https://a.your-cluster.ravendb.cloud,https://b.your-cluster.ravendb.cloud,https://c.your-cluster.ravendb.cloud",
"-e", "RAVEN_CERT_PFX_BASE64",
"-e", "RAVEN_CERT_PASSWORD",
"ghcr.io/gregolsky/ravendb-doctor-mcp:latest"
],
"env": {
"RAVEN_CERT_PFX_BASE64": "<base64-encoded PFX bytes>",
"RAVEN_CERT_PASSWORD": "your-pfx-password-here"
}
}
}
}
```
使用以下命令生成 base64 值：`base64 -w0 admin.client.certificate.pfx`（Linux/macOS）或 `[Convert]::ToBase64String([IO.File]::ReadAllBytes('admin.client.certificate.pfx'))`（PowerShell）。
> 通过 `env`（不在 `args` 中内联）传递凭证可将其排除在进程列表之外。
### 选项 2：直接节点（无 Docker）
```bash
npm install
npm run build
```
```json
{
"mcpServers": {
"ravendb-doctor": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/path/to/ravendb-doctor-mcp",
"env": {
"RAVEN_NODE_URLS": "http://localhost:8080",
"RAVEN_OUTPUT_DIR": "/tmp/ravendb-mcp-output",
"RAVEN_LOG_LEVEL": "warn"
}
}
}
}
```
## 一次性诊断会话
对于您不想永久配置的集群，包装脚本将 MCP 条目添加到 `.mcp.json` 中，仅在一次 `claude` 调用期间，然后在退出时删除它。 PFX 读取到 base64 环境变量中，因此不需要将证书文件挂载到 Docker 中。
```bash
./diagnose.sh --cert /path/to/admin.client.certificate.pfx \
--url https://a.your-cluster.ravendb.cloud \
--url https://b.your-cluster.ravendb.cloud
```
```powershell
.\diagnose.ps1 -Cert C:\certs\admin.client.certificate.pfx `
-Url 'https://a.your-cluster.ravendb.cloud','https://b.your-cluster.ravendb.cloud'
```
您将被提示输入 PFX 密码。 脚本注册一个名为 `ravendb-doctor-<slug>` 的服务器（slug 源自第一个 URL），因此针对不同集群的多个会话不会发生冲突。 溢出的响应文件位于 `./ravendb-mcp-output/<slug>/` 中。
需要 `docker`、`node`、`claude` 和已构建的 `ghcr.io/gregolsky/ravendb-doctor-mcp:latest` 镜像。
## 配置
所有选项都可以通过环境变量或 JSON 配置文件设置。
### 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `RAVEN_NODE_URLS` | 是 | 以逗号分隔的 RavenDB 节点 URL |
| `RAVEN_CERT_PFX` | 适用于安全集群 | PFX 客户端证书文件路径 |
| `RAVEN_CERT_PFX_BASE64` | `RAVEN_CERT_PFX` 的替代方案 | Base64 编码的 PFX 字节（无需文件挂载）；与 `RAVEN_CERT_PFX` 互斥 |
| `RAVEN_CERT_PASSWORD` | 如果 PFX 受密码保护 | PFX 密码 |
| `RAVEN_CERT_PEM` | PFX 的替代方案 | PEM 证书路径 |
| `RAVEN_CERT_KEY` | 与 PEM 配合使用 | 私钥文件路径 |
| `RAVEN_CERT_CA` | 可选 | 用于验证的 CA 证书路径 |
| `RAVEN_OUTPUT_DIR` | 否 | 大型响应文件目录（默认：`/data/output`） |
| `RAVEN_LOG_LEVEL` | 否 | `trace`/`debug`/`info`/`warn`/`error`（默认：`info`） |
| `RAVEN_SPILL_THRESHOLD_BYTES` | 否 | 大于此值的响应溢出到磁盘（默认：262144） |
| `RAVEN_CONFIG_FILE` | 否 | JSON 配置文件路径 |
### JSON 配置文件
自动从 `/etc/ravendb-mcp/config.json`、 `./ravendb-mcp.json` 或 `RAVEN_CONFIG_FILE` 中的路径加载。 环境变量覆盖文件值。
```json
{
"nodeUrls": ["https://a.example.ravendb.cloud"],
"cert": {
"pfx": "/certs/admin.client.certificate.pfx",
"password": "secret"
},
"outputDir": "/data/output",
"logLevel": "info",
"spillThresholdBytes": 262144
}
```
## 你可以问 Claude
连接后，Claude 可以访问 114 个诊断工具，按区域分组：
- **集群** — 拓扑结构、Raft 日志、观察者决策、节点 ping、维护统计信息
- **内存** — GC 统计信息、分配、堆碎片、内存不足日志
- **CPU / 线程** — 线程池、失控线程、争用、堆栈跟踪
- **索引** — 列表、统计信息、错误、性能、陈旧性、术语、合并建议
- **存储** — B-tree / FST 结构、压缩字典、可用空间、环境报告
- **复制** — 进度、传出失败、重新连接队列、传入活动
- **ETL** — 进度、统计信息、性能、调试信息
- **查询** — 运行查询、缓存的查询计划
- **文档** — 大型文档、修订、损坏的 ID、缺失附件
- **集合** — 带有修订和墓碑计数的统计信息
- **事务** — 服务器范围和每个数据库的事务信息
- **服务器信息** — 构建版本、数据库列表、路由、警报、通知
- **转储 / 包** — 内存转储、GC 转储、信息包（集群和每个数据库）
示例提示：
- *"集群健康吗？ 显示拓扑结构和任何警报。"*
- *"Orders 数据库中哪些索引已过时或有错误？"*
- *"内存情况如何？ 有任何碎片或 GC 压力吗？"*
- *"显示复制进度并标记任何失败。"*
- *"为 NorthWind 数据库获取一个信息包。"*
## 大型响应
大于 `spillThresholdBytes`（默认 256 KB）的响应被写入 `RAVEN_OUTPUT_DIR` 中的时间戳文件，Claude 接收到路径 + 预览。 将主机目录挂载到该路径，以便您可以打开文件：
```
-v C:/ravendb-mcp-output:/data/output
```
## 开发
```bash
npm install
npm run dev # 使用 tsx 运行，无需构建步骤
npm run build # 编译到 dist/
npm run typecheck # 类型检查，无需发出
npm run lint # ESLint
npm test # Vitest 单元测试
```
