logan
40b9bdcc8c
- 落地页下载卡「Tauri 2」价格位改「原生桌面」；sidecar/Go 二进制/monorepo 脚手架等内部表述改用户语言 - 文档删「打印/导出 PDF」与「是否有帮助」摆设组件及未使用图标 - MCP 页 H1 与页面标题去重（npm 安装命令为用户操作步骤，保留） - homepage dist 同步重建
268 lines
11 KiB
HTML
268 lines
11 KiB
HTML
<!doctype html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>MCP 接入 · OpsxDB 文档</title>
|
||
<meta name="description" content="OpsxDB 桌面数据库工作台用户文档 — 连库、写 SQL、看结果；MySQL / PostgreSQL / SQL Server / Oracle / SQLite / Redis 内置驱动，SSH 隧道与 SSL 加密。">
|
||
<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2064%2064%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22g%22%20x1%3D%220%22%20y1%3D%220%22%20x2%3D%2264%22%20y2%3D%2264%22%20gradientUnits%3D%22userSpaceOnUse%22%3E%3Cstop%20offset%3D%220%22%20stop-color%3D%22%23059669%22%2F%3E%3Cstop%20offset%3D%221%22%20stop-color%3D%2206B6D4%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%2264%22%20height%3D%2264%22%20rx%3D%2214%22%20fill%3D%22url(%23g)%22%2F%3E%3Cg%20stroke%3D%22%23fff%22%20stroke-width%3D%224.5%22%20fill%3D%22none%22%20stroke-linecap%3D%22round%22%3E%3Cellipse%20cx%3D%2232%22%20cy%3D%2220%22%20rx%3D%2215%22%20ry%3D%226.5%22%2F%3E%3Cpath%20d%3D%22M17%2020v24c0%203.6%206.7%206.5%2015%206.5s15-2.9%2015-6.5V20%22%2F%3E%3Cpath%20d%3D%22M17%2032c0%203.6%206.7%206.5%2015%206.5s15-2.9%2015-6.5%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E">
|
||
<link rel="stylesheet" href="/docs/assets/docs.css">
|
||
</head>
|
||
<body>
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display:none" aria-hidden="true">
|
||
<symbol id="i-menu" viewBox="0 0 24 24"><path d="M4 5h16"/><path d="M4 12h16"/><path d="M4 19h16"/></symbol>
|
||
</svg>
|
||
<header class="topbar">
|
||
<div class="topbar-inner">
|
||
<button class="menu-btn" id="menu-btn" aria-label="打开导航"><svg class="i"><use href="#i-menu"/></svg></button>
|
||
<a class="brand" href="/docs">
|
||
<span class="brand-logo"><svg width="28" height="28" viewBox="0 0 64 64" aria-label="OpsxDB"><defs><linearGradient id="lg-docs" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#059669"/><stop offset="1" stop-color="#06B6D4"/></linearGradient></defs><rect width="64" height="64" rx="14" fill="url(#lg-docs)"/><g stroke="#fff" stroke-width="4.5" fill="none" stroke-linecap="round"><ellipse cx="32" cy="20" rx="15" ry="6.5"/><path d="M17 20v24c0 3.6 6.7 6.5 15 6.5s15-2.9 15-6.5V20"/><path d="M17 32c0 3.6 6.7 6.5 15 6.5s15-2.9 15-6.5"/></g></svg></span>
|
||
<span class="brand-name">OpsxDB <em>文档</em></span>
|
||
</a>
|
||
<span class="ver-badge">v0.1</span>
|
||
<div class="search">
|
||
<input id="search-input" type="search" placeholder="搜索文档…" autocomplete="off" spellcheck="false">
|
||
<div class="search-panel" id="search-panel" hidden></div>
|
||
</div>
|
||
<nav class="top-links">
|
||
<a href="/home">官网</a>
|
||
<a href="/docs/quickstart">快速开始</a>
|
||
</nav>
|
||
</div>
|
||
</header>
|
||
|
||
<div class="layout" id="layout">
|
||
<aside class="sidebar" id="sidebar">
|
||
|
||
<div class="nav-group">
|
||
<div class="nav-group-title">开始使用</div>
|
||
|
||
<a class="nav-link" href="/docs/intro">产品介绍</a>
|
||
|
||
<a class="nav-link" href="/docs/quickstart">快速开始</a>
|
||
|
||
<a class="nav-link" href="/docs/interface">界面导览</a>
|
||
|
||
</div>
|
||
|
||
<div class="nav-group">
|
||
<div class="nav-group-title">连接与驱动</div>
|
||
|
||
<a class="nav-link" href="/docs/connect">新建连接</a>
|
||
|
||
<a class="nav-link" href="/docs/drivers">驱动支持</a>
|
||
|
||
</div>
|
||
|
||
<div class="nav-group">
|
||
<div class="nav-group-title">SQL 工作台</div>
|
||
|
||
<a class="nav-link" href="/docs/workbench">SQL 工作台</a>
|
||
|
||
<a class="nav-link" href="/docs/results">结果与导出</a>
|
||
|
||
<a class="nav-link" href="/docs/redis">Redis 工作台</a>
|
||
|
||
</div>
|
||
|
||
<div class="nav-group">
|
||
<div class="nav-group-title">安全与 AI</div>
|
||
|
||
<a class="nav-link" href="/docs/security">安全设计</a>
|
||
|
||
<a class="nav-link" href="/docs/ai">AI 助手</a>
|
||
|
||
<a class="nav-link active" href="/docs/mcp">MCP 接入</a>
|
||
|
||
</div>
|
||
|
||
<div class="nav-group">
|
||
<div class="nav-group-title">参考</div>
|
||
|
||
<a class="nav-link" href="/docs/faq">常见问题</a>
|
||
|
||
<a class="nav-link" href="/docs/shortcuts">快捷键</a>
|
||
|
||
</div>
|
||
|
||
<div class="sidebar-foot">© 2026 OpsxDB · 本地优先的数据库工作台</div>
|
||
</aside>
|
||
|
||
<main class="content">
|
||
<div class="breadcrumb">文档 <span>/</span> 安全与 AI <span>/</span> MCP 接入</div>
|
||
<h1 class="page-title">MCP 接入</h1>
|
||
<div class="page-meta">更新于 2026-10-16</div>
|
||
<article class="md">
|
||
<p>把 Cursor、Claude Code、VS Code 等 AI 客户端接到 OpsxDB，即可用自然语言查看结构、查询白名单内的库，并与侧栏 Agent <strong>共用同一套工具与安全策略</strong>。</p>
|
||
<h2 id="sec-1">什么是 MCP？</h2>
|
||
<p>MCP（Model Context Protocol）让 AI 客户端调用本机工具。OpsxDB MCP 读取桌面已保存的连接（<code>~/.opsxdb/connections.json</code>），权限由 <code>~/.opsxdb/mcp.json</code> 统一约束。</p>
|
||
<pre><code>AI 助手 → opsxdb-mcp (stdio) → aitools Runtime → 你的数据库
|
||
↘ 审计 ~/.opsxdb/logs/mcp-audit.jsonl
|
||
</code></pre>
|
||
<h2 id="sec-2">安装</h2>
|
||
<h3 id="sec-3">1. Node 启动器（npm）</h3>
|
||
<pre><code class="language-bash">npm install -g @rlwj-lab/opsxdb-mcp@latest
|
||
# 或一次性
|
||
npx -y @rlwj-lab/opsxdb-mcp
|
||
</code></pre>
|
||
<h3 id="sec-4">2. Go 二进制（必需）</h3>
|
||
<p>npm 包只是启动器，真正的 MCP 服务是 Go 二进制：</p>
|
||
<pre><code class="language-bash">cd server && go build -o ../bin/opsxdb-mcp ./cmd/opsxdb-mcp
|
||
export OPSXDB_MCP_BIN=/绝对路径/opsxdb/bin/opsxdb-mcp
|
||
</code></pre>
|
||
<p>也可把该二进制放到 PATH（需排在 npm shim 之前）。</p>
|
||
<h3 id="sec-5">3. 桌面设置</h3>
|
||
<p>打开 <strong>设置 → MCP</strong>：</p>
|
||
<ul>
|
||
<li>查看 Node / npm / 包版本 / Go 二进制是否就绪</li>
|
||
<li>复制安装命令与各客户端配置片段</li>
|
||
<li>查看读写权限，并勾选允许访问的连接；新配置默认允许读写和危险 SQL</li>
|
||
</ul>
|
||
<h2 id="sec-6">配置 AI 客户端</h2>
|
||
<p>以 Cursor 为例（<code>~/.cursor/mcp.json</code> 或项目 <code>.cursor/mcp.json</code>）：</p>
|
||
<pre><code class="language-json">{
|
||
"mcpServers": {
|
||
"opsxdb": {
|
||
"command": "npx",
|
||
"args": ["-y", "@rlwj-lab/opsxdb-mcp"],
|
||
"env": {
|
||
"OPSXDB_MCP_BIN": "/绝对路径/opsxdb/bin/opsxdb-mcp"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
</code></pre>
|
||
<p>Claude Code 使用项目根目录 <code>.mcp.json</code>（结构相同）。VS Code / Windsurf / Codex / Claude Desktop 的片段可在 <strong>设置 → MCP</strong> 中按 Tab 复制。</p>
|
||
<blockquote>
|
||
<p>GUI 客户端不一定继承 shell 的 PATH；请使用 <code>OPSXDB_MCP_BIN</code> 绝对路径，不要只写 <code>opsxdb-mcp</code> 或 <code>~</code>。</p>
|
||
</blockquote>
|
||
<h2 id="sec-7">安全策略</h2>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>项</th>
|
||
<th>说明</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>默认读写</td>
|
||
<td>新配置使用 <code>mode=read_write</code>；Agent 每次写入前显示确认弹框</td>
|
||
</tr>
|
||
<tr>
|
||
<td>危险 SQL</td>
|
||
<td>新配置默认 <code>allow_dangerous=true</code>，DROP/TRUNCATE/ALTER/无 WHERE 更新删除等仍须确认</td>
|
||
</tr>
|
||
<tr>
|
||
<td>旧配置</td>
|
||
<td>沿用已保存的权限；设置中选择「使用默认权限」可启用读写与危险 SQL</td>
|
||
</tr>
|
||
<tr>
|
||
<td>连接白名单</td>
|
||
<td><code>allowed_connection_ids</code>；<strong>空=拒绝全部</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td>审计</td>
|
||
<td><code>~/.opsxdb/logs/mcp-audit.jsonl</code>（含 tool、connection_id、run_id）</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>外部客户端若在 <code>read_write</code> 下自行传 <code>confirm_danger</code>，视为操作者授权；桌面侧栏 Agent <strong>不会</strong>让模型静默带确认令牌。<br>
|
||
保存白名单或权限后，外部 MCP 进程在下一次工具调用时读取新策略，无需重启桌面或 AI 客户端；策略文件读取失败时该次调用会被拒绝。</p>
|
||
<h2 id="sec-8">工具列表</h2>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>工具</th>
|
||
<th>说明</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>opsxdb_list_connections</code></td>
|
||
<td>白名单内连接</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>opsxdb_list_databases</code></td>
|
||
<td>库列表</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>opsxdb_list_tables</code></td>
|
||
<td>表/视图</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>opsxdb_describe_table</code></td>
|
||
<td>列定义</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>opsxdb_get_schema_context</code></td>
|
||
<td>紧凑 schema 文本</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>opsxdb_execute_query</code></td>
|
||
<td>SQL（写入需确认，查询有行数上限）</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>opsxdb_execute_redis_command</code></td>
|
||
<td>Redis（写入需确认；FLUSH*/KEYS 永拒）</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h2 id="sec-9">侧栏 Ask | Agent</h2>
|
||
<ul>
|
||
<li><strong>Ask</strong>：生成/解释/优化，不调库</li>
|
||
<li><strong>Agent</strong>：多轮调用与 MCP 同源工具；支持 SSE 步骤时间线、「插入编辑器」「在结果区打开」</li>
|
||
</ul>
|
||
<p>详见 <a href="/docs/ai">AI 助手</a>。</p>
|
||
<h2 id="sec-10">开始使用</h2>
|
||
<p>在 AI 客户端中试：</p>
|
||
<ul>
|
||
<li>「列出我的数据库连接」</li>
|
||
<li>「demo 库有哪些表」</li>
|
||
<li>「查看 users 表结构并查前 5 行」</li>
|
||
</ul>
|
||
<h2 id="sec-11">系统要求</h2>
|
||
<ul>
|
||
<li>Node.js 18+（若用 npm/npx 启动器）</li>
|
||
<li>已安装 OpsxDB 桌面端并至少保存一个连接</li>
|
||
<li>已构建 <code>opsxdb-mcp</code> Go 二进制</li>
|
||
<li>在设置 → MCP 勾选连接白名单</li>
|
||
</ul>
|
||
|
||
</article>
|
||
|
||
<div class="pn-nav">
|
||
|
||
<a class="pn prev" href="/docs/ai"><span class="pn-label">← 上一页</span><span class="pn-title">AI 助手</span></a>
|
||
|
||
|
||
<a class="pn next" href="/docs/faq"><span class="pn-label">下一页 →</span><span class="pn-title">常见问题</span></a>
|
||
|
||
</div>
|
||
|
||
|
||
</main>
|
||
|
||
<aside class="toc">
|
||
<div class="toc-title">本页目录</div>
|
||
<nav class="toc-nav">
|
||
<a class="toc-l2" href="#sec-1">什么是 MCP？</a>
|
||
<a class="toc-l2" href="#sec-2">安装</a>
|
||
<a class="toc-l3" href="#sec-3">1. Node 启动器（npm）</a>
|
||
<a class="toc-l3" href="#sec-4">2. Go 二进制（必需）</a>
|
||
<a class="toc-l3" href="#sec-5">3. 桌面设置</a>
|
||
<a class="toc-l2" href="#sec-6">配置 AI 客户端</a>
|
||
<a class="toc-l2" href="#sec-7">安全策略</a>
|
||
<a class="toc-l2" href="#sec-8">工具列表</a>
|
||
<a class="toc-l2" href="#sec-9">侧栏 Ask | Agent</a>
|
||
<a class="toc-l2" href="#sec-10">开始使用</a>
|
||
<a class="toc-l2" href="#sec-11">系统要求</a>
|
||
|
||
</nav>
|
||
</aside>
|
||
</div>
|
||
|
||
<script src="/docs/assets/docs.js" defer></script>
|
||
</body>
|
||
</html>
|