# mcp-dbwatch

**DBA 值守与根因报告** · MCP Server

> 客户还没给你任何数据时，就能出一份带检查清单的事故报告 —— 这是 Tier0 的立身之本。

## 安装（按需，不必装其他 MCP）

```bash
pip install mcp-dbwatch                        # 从 PyPI
pip install "./mcp-dbwatch[mysql]"             # 从源码（在工具链根目录执行）；要连库就补驱动，或 [postgres]
```

会自动带上它需要的共享库：`sqltk-core`（只读连库）、`sqltk-store`（观测/基线/事故）、`sqltk-know`（阈值/指标字典/18 种故障指纹）。**不会**带其他 MCP。

## 挂到 MCP 客户端

```json
{
  "mcpServers": {
    "dbwatch": {
      "command": "python",
      "args": ["-m", "dbwatch"],
      "env": { "DBT_STORE": "~/.dbtoolchain" }
    }
  }
}
```

按你的客户端（Claude Desktop / Cursor / Cline 等）说明，把这段合并到对应的 `mcpServers` 配置里。

命令行调试（不挂客户端也能用）：

```bash
mcp-dbwatch tools
mcp-dbwatch call <tool> --args '{"sql": "SELECT 1"}'
```

## 工具（15）

| 工具 | 作用 |
|---|---|
| `analyze_lock` | 锁等待链：谁阻塞谁。**kill 前必须评估回滚耗时** |
| `analyze_slow_log` | ★ Tier0：贴一段慢日志文本就能聚合 TOP SQL，不需要连库。 |
| `anomaly_report` | 与自身历史基线比对发现异常。**没有历史时退化为静态阈值告警，并明确说明** |
| `capacity_forecast` | 基于历史趋势做容量预测。**样本不足时明确拒绝，不编造趋势** |
| `capture_snapshot` | 一次性采集现场信息。这是把 Tier0 升到 Tier1/2 的唯一动作。 |
| `check_replication` | 复制状态检查：延迟 / 线程状态 / 错误码 → 修复顺序 |
| `classify_load` | 判断当前是 CPU / IO / 锁 / 连接 / 复制 哪类压力。处置方向完全不同，第一步必须分清。 |
| `detect_blocking_chain` | 递归阻塞检测：找出真正的源头（被 kill 的应该是源头，不是中间受害者）。 |
| `diagnose` | ★ 根因推理。给 instance_id 用档案，给 snapshot 用快照，什么都没有就用症状文本（Tier0）。 |
| `explain_symptom` | ★ Tier0：只给一句症状描述，就能输出检查清单 + 成因 + 处置。零历史依赖。 |
| `health_score` | 实例健康评分（维度树）+ 违规明细。 |
| `incident_report` | 渲染成可交付的事故报告（markdown）。 |
| `list_metrics` | 列出该引擎支持的逻辑指标（便于客户理解采集了什么）。 |
| `oncall_checklist` | ★ Tier0：故障时的标准排查顺序（静态知识，随时可用）。 |
| `record_observation` | 把一次观测写入共享档案。这是让 Tier0 → Tier2 升级的唯一写入点。 |

## 闭环

`capture_snapshot`（或直接粘贴采集文本）→ `classify_load` 定级 → `diagnose` 根因 → `incident_report` 出报告 → 归档为 `incident`

## Tier（冷启动保证）

三层渐进，**任何一层都不伪造结论**：
- `tier0`：只有症状文本 → 指纹库给出检查清单 + 成因假设 + 处置建议 + 升级标准
- `tier1`：一次只读快照 → 假设收敛，置信度提升
- `tier2`：≥2 次观测跨 ≥7 天 → 才有趋势与容量预测；样本不足显式报 `E_NOT_TIER2` 并给升级指引

## 边界：这个仓不做什么

只做「现在怎么了、为什么、怎么处理」。改 SQL 归 `mcp-sql-review`，改结构归 `mcp-change-risk`。

## 开发

```bash
python tests/test_dbwatch.py      # 不需要 pytest，也不需要数据库
```

## 许可

MIT © 2026 罗文星 —— 见 [LICENSE](LICENSE)。