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
1 parent 5416e86379
commit 1513f4bc2d
@@ -30,10 +30,14 @@ Agent 支持 openai-chat（DeepSeek 等）、Anthropic messages、OpenAI respons
 把同一套工具暴露给 Cursor / Claude / Codex：

 ```bash
-npx @rlwj-lab/opsxdb-mcp
+npm install -g @rlwj-lab/opsxdb-mcp@latest
+# 另需 Go 二进制，见 MCP 接入文档
+npx -y @rlwj-lab/opsxdb-mcp
 ```

-配置示例见仓库 `docs/mcp-cursor.example.json`。白名单写在 `~/.opsxdb/mcp.json` 的 `allowed_connection_ids`；空白名单拒绝全部连接。审计：`~/.opsxdb/logs/mcp-audit.jsonl`。
+在桌面 **设置 → MCP** 可检测安装、切换只读/危险 SQL、勾选连接白名单，并复制 Cursor / Claude Code / VS Code 等配置片段。完整说明见 [MCP 接入](/docs/mcp)。
+
+白名单写在 `~/.opsxdb/mcp.json` 的 `allowed_connection_ids`；空白名单拒绝全部连接。审计：`~/.opsxdb/logs/mcp-audit.jsonl`。

 侧栏标题旁仅在外部 MCP **近期有调用**时显示绿色「MCP」点；悬停/点击可看最近摘要。

@@ -0,0 +1,109 @@
+# 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 勾选连接白名单
@@ -4,37 +4,98 @@
    {
      "name": "开始使用",
      "pages": [
-        { "file": "01-intro.md", "slug": "intro", "title": "产品介绍", "updated": "2026-09-20" },
-        { "file": "02-quickstart.md", "slug": "quickstart", "title": "快速开始", "updated": "2026-09-20" },
-        { "file": "03-interface.md", "slug": "interface", "title": "界面导览", "updated": "2026-09-20" }
+        {
+          "file": "01-intro.md",
+          "slug": "intro",
+          "title": "产品介绍",
+          "updated": "2026-09-20"
+        },
+        {
+          "file": "02-quickstart.md",
+          "slug": "quickstart",
+          "title": "快速开始",
+          "updated": "2026-09-20"
+        },
+        {
+          "file": "03-interface.md",
+          "slug": "interface",
+          "title": "界面导览",
+          "updated": "2026-09-20"
+        }
      ]
    },
    {
      "name": "连接与驱动",
      "pages": [
-        { "file": "04-connect.md", "slug": "connect", "title": "新建连接", "updated": "2026-09-20" },
-        { "file": "05-drivers.md", "slug": "drivers", "title": "驱动支持", "updated": "2026-09-20" }
+        {
+          "file": "04-connect.md",
+          "slug": "connect",
+          "title": "新建连接",
+          "updated": "2026-09-20"
+        },
+        {
+          "file": "05-drivers.md",
+          "slug": "drivers",
+          "title": "驱动支持",
+          "updated": "2026-09-20"
+        }
      ]
    },
    {
      "name": "SQL 工作台",
      "pages": [
-        { "file": "06-workbench.md", "slug": "workbench", "title": "SQL 工作台", "updated": "2026-09-20" },
-        { "file": "07-results.md", "slug": "results", "title": "结果与导出", "updated": "2026-09-20" },
-        { "file": "08-redis.md", "slug": "redis", "title": "Redis 工作台", "updated": "2026-09-20" }
+        {
+          "file": "06-workbench.md",
+          "slug": "workbench",
+          "title": "SQL 工作台",
+          "updated": "2026-09-20"
+        },
+        {
+          "file": "07-results.md",
+          "slug": "results",
+          "title": "结果与导出",
+          "updated": "2026-09-20"
+        },
+        {
+          "file": "08-redis.md",
+          "slug": "redis",
+          "title": "Redis 工作台",
+          "updated": "2026-09-20"
+        }
      ]
    },
    {
      "name": "安全与 AI",
      "pages": [
-        { "file": "09-security.md", "slug": "security", "title": "安全设计", "updated": "2026-09-20" },
-        { "file": "10-ai.md", "slug": "ai", "title": "AI 助手", "updated": "2026-09-20" }
+        {
+          "file": "09-security.md",
+          "slug": "security",
+          "title": "安全设计",
+          "updated": "2026-09-20"
+        },
+        {
+          "file": "10-ai.md",
+          "slug": "ai",
+          "title": "AI 助手",
+          "updated": "2026-10-15"
+        },
+        {
+          "file": "12-mcp.md",
+          "slug": "mcp",
+          "title": "MCP 接入",
+          "updated": "2026-10-15"
+        }
      ]
    },
    {
      "name": "参考",
      "pages": [
-        { "file": "11-faq.md", "slug": "faq", "title": "常见问题", "updated": "2026-09-20" }
+        {
+          "file": "11-faq.md",
+          "slug": "faq",
+          "title": "常见问题",
+          "updated": "2026-09-20"
+        }
      ]
    }
  ]