logan
2c0bfafd8d
- 补入库：server/internal/db/dump.go、redis 分页/扫描预算测试、opsxdb-mcp main_test、 packages/opsxdb-mcp package-lock、docs 审计与对比文档等 37 个新文件 - 含结构扁平化进行中的 80 处修改与 155 处旧结构删除（server/ src/ src-tauri/ 为当前有效源） - 构建产物（bin/target/dist）与签名私钥仍按规则排除
111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
# MCP 接入
|
||
|
||
把 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 勾选连接白名单
|