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_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 助手。
+开始使用
+在 AI 客户端中试：
+-
+
- 「列出我的数据库连接」 +
- 「demo 库有哪些表」 +
- 「查看 users 表结构并查前 5 行」 +
系统要求
+-
+
- Node.js 18+（若用 npm/npx 启动器） +
- 已安装 OpsxDB 桌面端并至少保存一个连接 +
- 已构建
opsxdb-mcpGo 二进制
+ - 在设置 → MCP 勾选连接白名单 +