logan
1513f4bc2d
借鉴 DBX：安装检测（Node/npm/包/Go 二进制）、只读与 allow_dangerous、 连接白名单、多客户端配置片段；GET/PUT /api/ai/mcp-policy、/mcp-install； 文档 /docs/mcp 与落地页 AI/MCP 块；对照 docs/16 勾选设置项、列仍未完清单。
110 lines
3.4 KiB
Markdown
110 lines
3.4 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_only`：仅 SELECT/SHOW/EXPLAIN 与 Redis 读命令 |
|
||
| 可写 | 设置中关闭「只读模式」→ `mode=read_write`；每次写仍须确认 |
|
||
| 危险 SQL | 「允许危险 SQL」对应 `allow_dangerous`；DROP/TRUNCATE/ALTER/无 WHERE 更新删除等 |
|
||
| 连接白名单 | `allowed_connection_ids`；**空=拒绝全部** |
|
||
| 审计 | `~/.opsxdb/logs/mcp-audit.jsonl`（含 tool、connection_id、run_id） |
|
||
|
||
外部客户端若在 `read_write` 下自行传 `confirm_danger`，视为操作者授权；桌面侧栏 Agent **不会**让模型静默带确认令牌。
|
||
|
||
## 工具列表
|
||
|
||
| 工具 | 说明 |
|
||
| --- | --- |
|
||
| `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 勾选连接白名单
|