0 Fork 0

Files

T

logan 1513f4bc2d feat(mcp): 设置 → MCP 子页 + 策略 API + 官网/文档接入

借鉴 DBX：安装检测（Node/npm/包/Go 二进制）、只读与 allow_dangerous、
连接白名单、多客户端配置片段；GET/PUT /api/ai/mcp-policy、/mcp-install；
文档 /docs/mcp 与落地页 AI/MCP 块；对照 docs/16 勾选设置项、列仍未完清单。

2026-10-15 14:13:20 +08:00

3.4 KiB

Raw Blame History

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）

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

2. Go 二进制（必需）

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

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）：

{
  "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 助手。

开始使用

在 AI 客户端中试：

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

系统要求

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

3.4 KiB Raw Blame History Unescape Escape