From 167fc2d405ace6fecf970805e81a3a027ca71b0f Mon Sep 17 00:00:00 2001 From: "Logan.Li" Date: Fri, 16 Oct 2026 11:22:31 +0800 Subject: [PATCH] =?UTF-8?q?refactor(homepage):=20=E5=AE=98=E7=BD=91?= =?UTF-8?q?=E8=90=BD=E5=9C=B0=E9=A1=B5/=E6=96=87=E6=A1=A3/=E5=AE=9A?= =?UTF-8?q?=E4=BB=B7/=E6=8E=88=E6=9D=83=E6=BA=90=E7=A0=81=E8=BF=81?= =?UTF-8?q?=E5=85=A5=20homepage/=20=E5=B9=B6=E4=B8=8E=E5=90=8E=E7=AB=AF?= =?UTF-8?q?=E8=A7=A3=E8=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 原 server/internal/{site,docs} 的模板与资源迁移到 homepage/(index/docs/pricing/license + assets/docs-assets/content) - 新增构建入口 scripts/build-homepage.sh + tools/homepage-build,从 homepage/ 源码生成 homepage/dist - Go 侧改为托管 homepage/dist;go build ./... 与 go test ./... 通过;src/ 未改动 --- homepage/dist/docs/mcp/index.html | 271 ++++++++++++++++++++++++++++++ 1 file changed, 271 insertions(+) create mode 100644 homepage/dist/docs/mcp/index.html diff --git a/homepage/dist/docs/mcp/index.html b/homepage/dist/docs/mcp/index.html new file mode 100644 index 0000000..3f51fd7 --- /dev/null +++ b/homepage/dist/docs/mcp/index.html @@ -0,0 +1,271 @@ + + + + + +MCP 接入 · OpsxDB 文档 + + + + + + +
+
+ + + + OpsxDB 文档 + + v0.1 +
+ + +
+ +
+
+ +
+ + +
+
文档 / 安全与 AI / MCP 接入
+

MCP 接入

+
更新于 2026-10-15
+
+

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_querySQL（写入需确认，查询有行数上限）
opsxdb_execute_redis_commandRedis（写入需确认；FLUSH*/KEYS 永拒）
+

侧栏 Ask | Agent

+
    +
  • Ask：生成/解释/优化，不调库
    • +
  • Agent：多轮调用与 MCP 同源工具；支持 SSE 步骤时间线、「插入编辑器」「在结果区打开」
    • +
+

详见 AI 助手。

+

开始使用

+

在 AI 客户端中试：

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

系统要求

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