把 Cursor、Claude Code、VS Code 等 AI 客户端接到 OpsxDB，即可用自然语言查看结构、查询白名单内的库，并与侧栏 Agent **共用同一套工具与安全策略**。

## 什么是 MCP？

MCP（Model Context Protocol）让 AI 客户端调用本机工具。OpsxDB MCP 读取桌面已保存的连接（`~/.opsxdb/connections.json`），权限由 `~/.opsxdb/mcp.json` 统一约束。

```
AI 助手 → opsxdb-mcp (stdio) → aitools Runtime → 你的数据库
                                    ↘ 审计 ~/.opsxdb/logs/mcp-audit.jsonl
```

## 安装

### 1. Node 启动器（npm）

```bash
npm install -g @rlwj-lab/opsxdb-mcp@latest
# 或一次性
npx -y @rlwj-lab/opsxdb-mcp
```

### 2. Go 二进制（必需）

npm 包只是启动器，真正的 MCP 服务是 Go 二进制：

```bash
cd server && go build -o ../bin/opsxdb-mcp ./cmd/opsxdb-mcp
export OPSXDB_MCP_BIN=/绝对路径/opsxdb/bin/opsxdb-mcp
```

也可把该二进制放到 PATH（需排在 npm shim 之前）。

### 3. 桌面设置

打开 **设置 → MCP**：

- 查看 Node / npm / 包版本 / Go 二进制是否就绪
- 复制安装命令与各客户端配置片段
- 查看读写权限，并勾选允许访问的连接；新配置默认允许读写和危险 SQL

## 配置 AI 客户端

以 Cursor 为例（`~/.cursor/mcp.json` 或项目 `.cursor/mcp.json`）：

```json
{
  "mcpServers": {
    "opsxdb": {
      "command": "npx",
      "args": ["-y", "@rlwj-lab/opsxdb-mcp"],
      "env": {
        "OPSXDB_MCP_BIN": "/绝对路径/opsxdb/bin/opsxdb-mcp"
      }
    }
  }
}
```

Claude Code 使用项目根目录 `.mcp.json`（结构相同）。VS Code / Windsurf / Codex / Claude Desktop 的片段可在 **设置 → MCP** 中按 Tab 复制。

> GUI 客户端不一定继承 shell 的 PATH；请使用 `OPSXDB_MCP_BIN` 绝对路径，不要只写 `opsxdb-mcp` 或 `~`。

## 安全策略

| 项 | 说明 |
| --- | --- |
| 默认读写 | 新配置使用 `mode=read_write`；Agent 每次写入前显示确认弹框 |
| 危险 SQL | 新配置默认 `allow_dangerous=true`，DROP/TRUNCATE/ALTER/无 WHERE 更新删除等仍须确认 |
| 旧配置 | 沿用已保存的权限；设置中选择「使用默认权限」可启用读写与危险 SQL |
| 连接白名单 | `allowed_connection_ids`；**空=拒绝全部** |
| 审计 | `~/.opsxdb/logs/mcp-audit.jsonl`（含 tool、connection_id、run_id） |

外部客户端若在 `read_write` 下自行传 `confirm_danger`，视为操作者授权；桌面侧栏 Agent **不会**让模型静默带确认令牌。
保存白名单或权限后，外部 MCP 进程在下一次工具调用时读取新策略，无需重启桌面或 AI 客户端；策略文件读取失败时该次调用会被拒绝。

## 工具列表

| 工具 | 说明 |
| --- | --- |
| `opsxdb_list_connections` | 白名单内连接 |
| `opsxdb_list_databases` | 库列表 |
| `opsxdb_list_tables` | 表/视图 |
| `opsxdb_describe_table` | 列定义 |
| `opsxdb_get_schema_context` | 紧凑 schema 文本 |
| `opsxdb_execute_query` | SQL（写入需确认，查询有行数上限） |
| `opsxdb_execute_redis_command` | Redis（写入需确认；FLUSH*/KEYS 永拒） |

## 侧栏 Ask | Agent

- **Ask**：生成/解释/优化，不调库
- **Agent**：多轮调用与 MCP 同源工具；支持 SSE 步骤时间线、「插入编辑器」「在结果区打开」

详见 [AI 助手](/docs/ai)。

## 开始使用

在 AI 客户端中试：

- 「列出我的数据库连接」
- 「demo 库有哪些表」
- 「查看 users 表结构并查前 5 行」

## 系统要求

- Node.js 18+（若用 npm/npx 启动器）
- 已安装 OpsxDB 桌面端并至少保存一个连接
- 已构建 `opsxdb-mcp` Go 二进制
- 在设置 → MCP 勾选连接白名单