dsh-db-mcp 0.6.10 → 0.7.1

package/README.md

@@ -28,9 +28,14 @@ twice: import the connections DBeaver already knows, then just ask.
 ## Run
 
 ```sh
-dsh plugin add dsh-db-mcp@latest
+dsh plugin --profile desktop add dsh-db-mcp   # desktop app
+dsh plugin --profile web add dsh-db-mcp       # web UI
 ```
 
+`--profile` picks the profile to install into (`desktop` and `web` ship with DSH;
+any other name is created on first use). Remove with
+`dsh plugin --profile desktop remove dsh-db-mcp`.
+
 Then:
 
 1. Sidebar → **Database**.
@@ -52,7 +57,7 @@ Prefer to start from scratch? **New data source** takes one connection string
 | `mcp__db__list_tables` | tables and views of a source |
 | `mcp__db__describe_table` | columns, types, nullability, primary key |
 | `mcp__db__sample_rows` | a few rows of a table |
-| `mcp__db__run_query` | run one statement |
+| `mcp__db__execute_sql` | execute one statement — a query, or a write when that is allowed |
 | `mcp__db__explain_query` | query plan |
 | `mcp__db__get_ddl` | `CREATE TABLE` statement |
 | `mcp__db__test_connection` | real login, `select 1`, server/user/schema |

package/README.zh.md

@@ -18,9 +18,13 @@
 ## 运行
 
 ```sh
-dsh plugin add dsh-db-mcp@latest
+dsh plugin --profile desktop add dsh-db-mcp   # 桌面端
+dsh plugin --profile web add dsh-db-mcp       # Web 端
 ```
 
+`--profile` 指定装进哪个 profile（随 DSH 提供的是 `desktop` 与 `web`，其它名字首次使用时自动创建）。卸载用
+`dsh plugin --profile desktop remove dsh-db-mcp`。
+
 然后：
 
 1. 侧栏 → **数据库**。
@@ -39,7 +43,7 @@ dsh plugin add dsh-db-mcp@latest
 | `mcp__db__list_tables` | 某个源里的表与视图 |
 | `mcp__db__describe_table` | 列、类型、可空、主键 |
 | `mcp__db__sample_rows` | 取几行样本 |
-| `mcp__db__run_query` | 执行一条语句 |
+| `mcp__db__execute_sql` | 执行一条语句——查询，或在允许写入时执行写入 |
 | `mcp__db__explain_query` | 执行计划 |
 | `mcp__db__get_ddl` | `CREATE TABLE` 语句 |
 | `mcp__db__test_connection` | 真实登录 + `select 1`，回报服务器/用户/schema |
@@ -57,7 +61,7 @@ dsh plugin add dsh-db-mcp@latest
 
 | 文档 | 内容 |
 | ---- | ---- |
-| [docs/guide.md](docs/guide.md) | 面板操作、连接串、分组、Docker 测试库、排错（英文） |
+| [docs/guide.zh.md](docs/guide.zh.md) | 面板操作、连接串、分组、Docker 测试库、排错（中文） |
 | [docs/reference.md](docs/reference.md) | HTTP 接口、工具契约、注册表与设置文件、插件配置（英文） |
 | [docs/development.md](docs/development.md) | 目录结构、热重载、测试套件、发布流程（英文） |
 | [docs/design-notes.md](docs/design-notes.md) | 设计日志（P1 → P7）与决策记录（英文） |

package/docs/development.md

@@ -38,8 +38,8 @@ The Cordis Loader imports a plugin entry **once per process**, so editing
   button) replaces it. Tool registrations stay in place — disposing and re-registering
   them makes the agent's tool catalog go stale and report `unknown tool`.
 
-A profile that links this directory (`dsh plugin add <path>`) reflects edits
-immediately; one installed from npm needs a release.
+A profile that links this directory (`dsh plugin --profile desktop add <path>`)
+reflects edits immediately; one installed from npm needs a release.
 
 ## Tests
 
@@ -52,7 +52,7 @@ npm run test:engines  # server/engines.py against a stub DB-API connection
 
 | Suite | Covers |
 | ----- | ------ |
-| `dev/engines.test.mjs` + `engines.test.py` | commit/rollback and `affectedRows` contract of `run_query`, no database needed |
+| `dev/engines.test.mjs` + `engines.test.py` | commit/rollback and `affectedRows` contract of `execute_sql`, no database needed |
 | `dev/selftest.mjs` | mounts `src/host.js` on a throwaway port: registry, validation, groups, bulk, schema route, DBeaver scan, probes |
 | `dev/shims.test.mjs` | mounts `index.js`, checks both routes, `/reload`, tool publication, and that `package.json` has no BOM |
 | `dev/parse.test.mjs` | the connection-string parser (DSN, JDBC, TNS, SID, paths) |
@@ -72,10 +72,10 @@ The package publishes from GitHub Actions with
 publish credential, so no `NPM_TOKEN` secret exists.
 
 ```sh
-node dev/bump.mjs 0.6.10     # package.json + src/host.js, both
-git commit -am "chore: release 0.6.10"
+node dev/bump.mjs 0.7.0     # package.json + src/host.js, both
+git commit -am "chore: release 0.7.0"
 git push origin main
-git tag v0.6.10 && git push origin v0.6.10
+git tag v0.7.0 && git push origin v0.7.0
 ```
 
 The workflow refuses to publish when the tag and `package.json` disagree, runs
@@ -86,6 +86,36 @@ a trusted publisher exists.
 Keep `src/host.js`'s `PLUGIN_VERSION` in step with `package.json` — the panel and
 `/health` read it, and a mismatch ships a package that reports the previous version.
 
+Installing that release into a profile (the profile name is required, the verb is
+pnpm's):
+
+```sh
+dsh plugin --profile desktop add dsh-db-mcp@0.7.0
+dsh plugin --profile desktop remove dsh-db-mcp
+```
+
+Expect pnpm to print `Added 1 entry to minimumReleaseAgeExclude …` when the version
+is younger than its 1440-minute cooldown: that line is pnpm recording a per-version
+exception so the explicit pin may install. See
+[guide.md](guide.md#install-and-upgrade) for the policy knobs.
+
+## When git says "not a git repository"
+
+Three times on this machine `git status` answered `fatal: not a git repository` while
+`.git/objects` still held every commit: `HEAD`, `config` and `index` had vanished,
+and git refuses to run at all without `HEAD` (even with an explicit `--git-dir`).
+The history was never lost, so it can be rebuilt from the refs:
+
+```sh
+node dev/git-repair.mjs --check   # report what is missing
+node dev/git-repair.mjs           # write HEAD + config, then git reset to rebuild the index
+```
+
+The remote URL comes from `package.json`'s `repository`, and the branch is the one
+with the newest ref, so the script stays machine independent. It is a repair, not a
+backup: if `.git/objects` itself is missing, restore from a bundle instead
+(`git bundle create backup.bundle --all` in a healthy checkout, then `git clone`).
+
 ## Adding an engine
 
 1. `server/engines.py`: extend `connect()` and the dialect tables (`_quote`,

package/docs/guide.md

@@ -1,3 +1,5 @@
+English | [中文](guide.zh.md)
+
 # Guide
 
 Everything the panel can do, in the order you meet it. For the wire protocol and
@@ -6,24 +8,42 @@ file formats see [reference.md](reference.md); for build and release see
 
 ## Install and upgrade
 
+`dsh plugin` forwards its arguments to pnpm inside the profile directory, so it
+needs `--profile` before the pnpm verb:
+
 ```sh
-dsh plugin add dsh-db-mcp@latest     # fresh install
-dsh plugin add dsh-db-mcp@0.6.10     # pin a version (skips dist-tag and cache games)
+dsh plugin --profile desktop add dsh-db-mcp     # fresh install, desktop app
+dsh plugin --profile web add dsh-db-mcp         # the web UI's profile
+dsh plugin --profile desktop add dsh-db-mcp@0.7.0     # pin a version
+dsh plugin --profile desktop remove dsh-db-mcp         # uninstall
+dsh plugin --profile desktop why dsh-db-mcp            # which version is installed
 ```
 
+`desktop` and `web` ship with DSH; any other name is initialized on first use
+(`--profile scratch add dsh-db-mcp`). Check what a profile has with
+`dsh plugin --profile desktop list dsh-db-mcp`.
+
 From a source checkout, install the directory instead — the profile then links it,
 so edits are live:
 
 ```sh
-dsh plugin add C:\path\to\dsh-db-mcp
+dsh plugin --profile desktop add C:\path\to\dsh-db-mcp
 ```
 
-Two things to know about upgrades:
-
-- pnpm caches a package's metadata. A version published minutes ago may still be
-  invisible to `@latest`; naming the version sidesteps it.
-- DSH applies a supply-chain cooldown to freshly published releases. Pinning is
-  also the way around that.
+Three things to know about upgrades:
+
+- pnpm caches a package's metadata. A version published minutes ago may be
+  invisible to the dist-tag; naming the version sidesteps it.
+- pnpm holds new releases behind a cooldown (`minimumReleaseAge`, 1440 minutes by
+  default) so a freshly published — possibly compromised — version is not resolved
+  automatically. Asking for an exact version makes pnpm record that version in
+  `minimumReleaseAgeExclude` inside the profile's `pnpm-workspace.yaml`; that is the
+  `Added 1 entry to minimumReleaseAgeExclude …` line you will see. Nothing is broken:
+  the exclusion is per version and only lets *that* pin through. To be asked instead,
+  set `minimumReleaseAgeStrict: true` in the profile's `pnpm-workspace.yaml`; to drop
+  stale entries, set `minimumReleaseAgeExcludePrune: true`.
+- Upgrading needs either an exact version or a removed lock entry: `add` will not
+  move a dependency that still satisfies its existing range.
 
 If the sidebar entry disappears after a restart, see [Troubleshooting](#troubleshooting).
 
@@ -213,7 +233,7 @@ oracle://system:dbmcp-demo@127.0.0.1:1521/FREEPDB1
 
 | Symptom | Cause | Fix |
 | ------- | ----- | --- |
-| Sidebar entry gone, plugin card says *not installed* | `package.json` carries a UTF-8 BOM, so the host's `JSON.parse` fails and the bundle is skipped silently | rewrite the file without a BOM; re-apply with `plugin_manager set_bundle` |
+| Sidebar entry gone, plugin card says *not installed* | `package.json` carries a UTF-8 BOM, so the host's `JSON.parse` fails and the bundle is skipped silently | rewrite the file without a BOM (any editor's "UTF-8 without BOM"), then toggle the plugin off and on in the **Plugins** panel |
 | Panel says *Host interface disconnected* | the Host half is not mounted (plugin disabled, or bundle failed to load) | check the plugin card, then reload the page |
 | Edited `src/host.js` but nothing changed | the Cordis entry is imported once per process | `POST /plugins/db-mcp/api/reload`, or restart DSH after changing `index.js` |
 | Tools missing from the agent | the Python server never started | *Runtime* → tools count and error; then **Restart MCP** |

package/docs/guide.zh.md

@@ -0,0 +1,178 @@
+[English](guide.md) | 中文
+
+# 使用指南
+
+面板能做的事，按你会遇到的顺序排列。协议与文件格式见 [reference.md](reference.md)（英文）；构建与发布见 [development.md](development.md)（英文）。
+
+## 安装与升级
+
+`dsh plugin` 会把参数原样转给 profile 目录里的 pnpm，所以 `--profile` 必须写在 pnpm 动词之前：
+
+```sh
+dsh plugin --profile desktop add dsh-db-mcp     # 全新安装，桌面端
+dsh plugin --profile web add dsh-db-mcp         # Web 界面的 profile
+dsh plugin --profile desktop add dsh-db-mcp@0.7.0     # 锁定某个版本
+dsh plugin --profile desktop remove dsh-db-mcp         # 卸载
+dsh plugin --profile desktop why dsh-db-mcp            # 当前装的是哪个版本
+```
+
+`desktop` 与 `web` 随 DSH 自带；其它名字会在首次使用时自动创建（`--profile scratch add dsh-db-mcp`）。查看某个 profile 装了什么：`dsh plugin --profile desktop list dsh-db-mcp`。
+
+从源码目录安装则传目录路径，profile 会以链接方式接入，改代码即时生效：
+
+```sh
+dsh plugin --profile desktop add C:\path\to\dsh-db-mcp
+```
+
+升级有三点要注意：
+
+- pnpm 会缓存包的元数据。刚发布几分钟的版本可能还不在 dist-tag 里；直接写出版本号可以绕过。
+- pnpm 对新版本有冷却期（`minimumReleaseAge`，默认 1440 分钟），避免刚发布、可能已被投毒的新版本被自动解析。点名具体版本时，pnpm 会把该版本记进 profile 的 `pnpm-workspace.yaml` 里的 `minimumReleaseAgeExclude`，这就是你看到的 `Added 1 entry to minimumReleaseAgeExclude …`。这不是错误：豁免只针对那一个版本，只放行这一次 pin。想改成先询问，在 profile 的 `pnpm-workspace.yaml` 里设 `minimumReleaseAgeStrict: true`；想清理过期条目，设 `minimumReleaseAgeExcludePrune: true`。
+- 升级要么写精确版本，要么先删掉 lock 条目：只要依赖还满足原有范围，`add` 不会动它。
+
+如果重启后侧栏入口消失，见 [排错](#排错)。
+
+## 面板
+
+侧栏 → **数据库**。页头有 **‹ 返回会话**、标题，以及连接状态和版本两个药丸。下面五个标签：
+
+| 标签 | 作用 |
+| ---- | ---- |
+| 数据源列表 | 注册表：按分组标签分行的列表、批量操作、刷新、重启 MCP |
+| 新建数据源 | 一条连接串、用户、口令；编辑也复用这个表单 |
+| 从 DBeaver 导入 | 扫描、勾选、导入 |
+| 运行时诊断 | Host 信息、工具数量、全局写开关、venv 与驱动版本 |
+| 审计日志 | 最近十几次工具调用，按你的时区显示 |
+
+**新建数据源** 与 **从 DBeaver 导入** 只替换标签下方那张卡片——页头和标签保持不动，之前所在的位置始终只隔一个标签。
+
+## 新增数据源
+
+表单和 DBeaver 的连接对话框一样精简：**连接串**、**用户**、**口令**（带 *保存密码* 勾选）。粘贴连接串会自动填出类型、主机、端口、库名/服务名、显示名称与标识符；推导出来的值只出现在 **更多设置** 里，那里还有模式、SID、SSL 模式、字符集和只读开关。
+
+可接受的写法——DSN、JDBC URL、Oracle TNS 描述符、JDBC thin 描述符，或者干脆一个数据库文件路径：
+
+```
+postgresql://alice:secret@db.example.com:6543/orders?sslmode=require
+jdbc:postgresql://localhost:5432/appdb
+mysql://root:pw@127.0.0.1:3306/shop?charset=utf8mb4
+jdbc:mariadb://10.0.0.5:3307/legacy
+oracle://system:oracle@localhost:1521/XEPDB1
+jdbc:oracle:thin:@//ora:1521/ORCLPDB1        # 服务名
+jdbc:oracle:thin:@ora:1521:ORCL              # SID
+(DESCRIPTION=(ADDRESS=(HOST=tns-host)(PORT=1522))(CONNECT_DATA=(SERVICE_NAME=svc1)))
+jdbc:sqlite:C:\data\app.db
+sqlite:///C:/data/chinook.db
+C:\data\app.db          /  /var/lib/app.sqlite3
+```
+
+连接串里带的密码只发送一次，之后仅保存，永远不会回显。`id` 创建后不可修改——要改的是 *显示名称*（双击行上的名字）。
+
+## 从 DBeaver 导入
+
+导入器会在 `%APPDATA%\DBeaverData\workspace*\General\.dbeaver\` 下找 `data-sources.json`，同时兼容 `General` 布局与 Linux/macOS 布局。同目录存在 `credentials-config.json` 时，会用 DBeaver 内置密钥解密（AES-128-CBC、零 IV、前 16 字节前缀——参考 [Tatsh/dbeaver-creds](https://github.com/Tatsh/dbeaver-creds)）。勾选的连接被复制进注册表，口令写入 `secrets.json`。
+
+两个细节让真实的 DBeaver 工作区可用：
+
+- 通过驱动对话框创建的连接常常只有一条 JDBC URL（`configurationType: URL`），既没有 `database` 字段也没有 `user`。导入器会从 URL 里解析表单缺失的部分，用户名则取自解密后的凭据。
+- 已经配置过的连接不会重复出现。数据源按 类型 + 主机 + 端口 + 库名/服务名/SID + 用户 识别（SQLite 用文件路径）；命中时返回 `alreadyImported`，复选框被禁用，行上写着 *已作为 … 添加*。
+
+从未保存过口令的工作区也没问题：连接会以空口令导入，行上显示 **无密码**。补填一次就会一直保留。
+
+## 测试连接
+
+**测试** 执行的是真实登录：SQLite 通过 `node:sqlite` 以只读方式打开，其它引擎走 Python 驱动，完成认证并执行 `select 1`（Oracle 是 `select 1 from dual`）。之后行上会显示版本横幅、用户、数据库，以及登录耗时：
+
+```
+Oracle AI Database 26ai Free Release 23.26.3.0.0 · DEMO@FREEPDB1 · select 1 from dual ok
+PostgreSQL 15.19 · demo@demo · select version() ok
+MySQL 8.0.46 · demo@%@demo · select version() ok
+```
+
+口令错误现在会直接显示驱动自己的报错（`ORA-01017`、`DPY-6005`、`password authentication failed`），而不是笼统的「端口可达」。还没保存的表单也能测试。Python 服务起不来时，探测会退化成 TCP 检查，并明确说明这一点。
+
+## 分组与批量操作
+
+每个数据源都可以带一个可选的 **分组** 标签，在 *更多设置* 里编辑。
+
+- **新建** —— 在 **新建分组** 里输入名字。
+- **重命名** —— 双击组名；**删除** 只解除该组下成员的标签。
+- **移动** —— 把数据源行拖到某个分组上，拖到 **未分组** 即清除标签。
+- **重命名数据源** —— 双击它的名字；`id` 永远不变。
+- **选择** —— 每个组头都有全选框，分组内的数据源和散落的一样能参与批量操作。
+
+选中之后，批量条可以测试、切换只读、移入分组，或删除（两步确认）。
+
+## 结构浏览
+
+数据源行上的 **结构** 会打开只读视图：左边是表和视图，右边是所选表的列（名称、类型、可空、默认值、主键标记）。它由 `GET /schema` 提供，该接口只把 `list_tables` / `describe_table` 转发给 MCP 服务——页面无法执行 SQL，也不做缓存。
+
+## 两道安全闸门
+
+两条独立的闸门决定一条语句能不能写入：
+
+1. **全局开关** —— `<runtime>/settings.json` 里的 `allowWrite`，在 *运行时诊断* 标签切换。默认关闭；关闭期间所有写入都会以 `user_error` 拒绝，并提示去打开开关。
+2. **单源开关** —— 数据源上的 `readOnly`，默认开启。点行上的 *只读* / *读写* 药丸可一键切换；该源允许写入时药丸变成琥珀色。
+
+Python 服务在启动时读取全局开关，开关一动 Host 就重启它。在引擎允许的地方，只读还会在驱动层再拦一次（SQLite 用 `mode=ro`，PostgreSQL 用 `default_transaction_read_only`，MySQL 用 `SET SESSION TRANSACTION READ ONLY`）。
+
+## 审计日志
+
+每次 MCP 工具调用都会往 `<runtime>/logs/audit.jsonl`（0600）追加一行 JSON：时间、工具、数据源、耗时、行数、截断到 2000 字符的 SQL，以及失败时的错误。结果行本身从不记录。文件到 512 KiB 会轮转为 `audit.1.jsonl`，日志可用 `auditLog: false` 关闭。
+
+面板按 **你本机的时钟** 显示最近十几次记录；文件里保存的是 UTC，以便跨机器比较。每条记录的时间戳在悬停时会显示完整的本地时间。
+
+## 运行时目录
+
+```
+$DSH_HOME/db-mcp/
+  datasources.json   # 数据源与分组，从不含口令，0600
+  secrets.json       # 每个数据源的口令，0600，仅 Host 可读
+  settings.json      # 全局写开关 + 审计开关，0600
+  logs/mcp.log       # 脱敏日志
+  logs/audit.jsonl   # 每次 MCP 工具调用一行，512 KiB 轮转
+  .venv/             # 插件内 venv：mcp、psycopg、PyMySQL、oracledb
+```
+
+## 用 Docker 起测试库
+
+本机什么都不用装；下面每个引擎都是一个用完即弃的容器，带演示账号（`demo` / `dbmcp-demo`）。
+
+```sh
+# PostgreSQL —— 镜像最小、启动最快，推荐先试它
+docker run -d --name dbmcp-pg -p 5432:5432 \
+  -e POSTGRES_USER=demo -e POSTGRES_PASSWORD=dbmcp-demo -e POSTGRES_DB=demo \
+  postgres:15-alpine
+
+# MySQL
+docker run -d --name dbmcp-mysql -p 3306:3306 \
+  -e MYSQL_USER=demo -e MYSQL_PASSWORD=dbmcp-demo -e MYSQL_DATABASE=demo \
+  -e MYSQL_ROOT_PASSWORD=dbmcp-root mysql:8.0-debian
+
+# Oracle Free —— 几个 GB，需要一两分钟才健康
+docker run -d --name dbmcp-oracle -p 1521:1521 -e ORACLE_PASSWORD=dbmcp-demo \
+  gvenzl/oracle-free:23-slim
+```
+
+在 Windows 上，1521 常常落在 Hyper-V 的保留端口段里，`docker run` 会报 *"An attempt was made to access a socket in a way forbidden by its access permissions"*。用 `netsh interface ipv4 show excludedportrange protocol=tcp` 确认，然后映射到别的宿主端口，例如 `-p 11521:1521`，再把数据源指向 11521。
+
+然后用对应的连接串导入或新建数据源：
+
+```
+postgresql://demo:dbmcp-demo@127.0.0.1:5432/demo
+mysql://demo:dbmcp-demo@127.0.0.1:3306/demo
+oracle://system:dbmcp-demo@127.0.0.1:1521/FREEPDB1
+```
+
+## 排错
+
+| 现象 | 原因 | 处理 |
+| ---- | ---- | ---- |
+| 侧栏入口消失，插件卡片显示 *未安装* | `package.json` 带 UTF-8 BOM，Host 的 `JSON.parse` 失败，整个 bundle 被静默跳过 | 用编辑器另存为「UTF-8 无 BOM」，再到 **插件** 面板把插件关掉再打开 |
+| 面板显示 *Host 接口未连接* | Host 半边没挂载（插件被禁用，或 bundle 加载失败） | 检查插件卡片，然后刷新页面 |
+| 改了 `src/host.js` 但没有变化 | Cordis 入口在每个进程里只导入一次 | `POST /plugins/db-mcp/api/reload`；改过 `index.js` 则需重启 DSH |
+| 智能体看不到工具 | Python 服务没起来 | *运行时诊断* 里看工具数与错误，然后点 **重启 MCP** |
+| 重启后立刻报 `unknown tool "mcp__db__…"` | 工具注册随旧进程被释放 | 重启一次 DSH，之后的重启都用 **重启 MCP** |
+| Oracle 登录报 `DPY-6005` | 监听不可达，或主机/端口不对 | `docker ps` 确认容器，再点 *测试* |
+| 首次写入报 `ORA-01950` | Oracle 用户没有表空间配额 | `alter user <用户> quota unlimited on users` |
+| 导入行标红：*incomplete host/database* | 该 DBeaver 条目既没有字段也没有可解析的 URL | 先用 DBeaver 打开一次这个连接，或手工新建数据源 |

package/docs/reference.md

@@ -56,7 +56,7 @@ Row limits come from the server: `DB_MCP_MAX_ROWS` (default 200) per call, cappe
 | `list_tables` | `datasource?`, `schema?` | `{ datasource, tables: [{ schema, name, type }] }` |
 | `describe_table` | `table`, `datasource?`, `schema?` | `{ columns: [{ name, type, nullable, default, primaryKey }] }` |
 | `sample_rows` | `table`, `datasource?`, `limit=20`, `schema?` | `{ columns, rows, rowCount, truncated }` |
-| `run_query` | `sql`, `datasource?`, `max_rows?` | `{ columns, rows, rowCount, truncated, elapsedMs }` |
+| `execute_sql` | `sql`, `datasource?`, `max_rows?` | `{ columns, rows, rowCount, truncated, elapsedMs }`, or `{ affectedRows }` for a write |
 | `explain_query` | `sql`, `datasource?` | `{ plan }` (engine-specific text) |
 | `get_ddl` | `table`, `datasource?`, `schema?` | `{ ddl, source: 'sqlite_master' \| 'columns' }` |
 | `test_connection` | `datasource?` or `kind`+`config`+`password?`, `read_only?` | `{ ok, latencyMs, message, detail: { stage, server, database, user, schema } }` |
@@ -109,7 +109,7 @@ and is read only by the Host, never sent to the page.
 512 KiB:
 
 ```json
-{"at":"2026-11-08T06:20:28.000Z","tool":"mcp__db__run_query","datasource":"pg-demo","ok":true,"ms":41,"rows":3,"sql":"select id, name from customers order by id"}
+{"at":"2026-11-08T06:20:28.000Z","tool":"mcp__db__execute_sql","datasource":"pg-demo","ok":true,"ms":41,"rows":3,"sql":"select id, name from customers order by id"}
 ```
 
 ### Data source fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-db-mcp",
-  "version": "0.6.10",
+  "version": "0.7.1",
   "description": "DSH plugin: import the connections DBeaver already knows, then let the agent query SQLite, PostgreSQL, MySQL and Oracle through eight MCP tools. No DSH files to edit, no data source to retype.",
   "keywords": [
     "dsh",

package/server/engines.py

@@ -549,7 +549,7 @@ def table_ddl(profile: dict, connection, table: str, schema: str | None = None)
 # queries
 
 
-def run_query(profile: dict, connection, sql: str, max_rows: int) -> dict:
+def execute_sql(profile: dict, connection, sql: str, max_rows: int) -> dict:
     ensure_readable(sql, profile)
     kind = profile.get("kind")
     started = time.perf_counter()
@@ -613,7 +613,7 @@ def connection_autocommit(kind: str) -> bool:
 
 def sample_rows(profile: dict, connection, table: str, limit: int, schema: str | None) -> dict:
     sql = f"SELECT * FROM {qualified(profile, table)}{_limit_clause(profile.get('kind'), limit)}"
-    result = run_query(profile, connection, sql, limit)
+    result = execute_sql(profile, connection, sql, limit)
     result["table"] = table
     result["schema"] = schema or (profile.get("config") or {}).get("schema") or None
     return result

package/server/main.py

@@ -27,9 +27,11 @@ HARD_MAX_ROWS = int(os.environ.get("DB_MCP_MAX_ROWS_HARD") or 2000)
 mcp = FastMCP(
     "db-mcp",
     instructions=(
-        "Query the databases the user registered in the DSH Database panel. "
+        "Work with the databases the user registered in the DSH Database panel. "
         "Start with list_datasources, then list_tables, describe_table and finally "
-        "run_query. Prefer these tools over guessing table names."
+        "execute_sql. execute_sql runs any single statement: SELECT and EXPLAIN when "
+        "the source is read-only, INSERT/UPDATE/DELETE/DDL only when writes are "
+        "enabled. Prefer these tools over guessing table names."
     ),
 )
 
@@ -201,19 +203,20 @@ def sample_rows(
 
 
 @mcp.tool()
-def run_query(sql: str, datasource: Optional[str] = None, max_rows: Optional[int] = None) -> dict:
-    """Run one SQL statement and return columns plus rows.
-
-    Read-only datasources accept SELECT/WITH/SHOW/EXPLAIN statements only.
-    Results are capped by `max_rows` (default 200); `truncated` says whether more
-    rows existed. Writes (INSERT/UPDATE/DELETE/DDL) are committed and report
-    `affectedRows` instead of a result set.
+def execute_sql(sql: str, datasource: Optional[str] = None, max_rows: Optional[int] = None) -> dict:
+    """Execute one SQL statement — a query or, when writes are enabled, a change.
+
+    Read-only datasources accept SELECT/WITH/SHOW/EXPLAIN statements only; every
+    other statement is refused before it reaches the database. Results are capped by
+    `max_rows` (default 200) and `truncated` says whether more rows existed. Writes
+    (INSERT/UPDATE/DELETE/DDL) are committed and report `affectedRows` instead of a
+    result set. One statement per call: no scripts, no `;`-separated batches.
     """
     try:
         limit = _clamp_rows(max_rows)
         profile, (connection, close) = _open(datasource)
         try:
-            result = engines.run_query(profile, connection, sql, limit)
+            result = engines.execute_sql(profile, connection, sql, limit)
         finally:
             close()
         return {"ok": True, "datasource": _source(profile), **result}

package/src/host.js

@@ -33,7 +33,7 @@ const { createBridge } = await import(new URL(`./tools.js?v=${GENERATION}`, impo
 
 const API_PREFIX = '/plugins/db-mcp/api'
 const PLUGIN_NAME = 'dsh-db-mcp'
-const PLUGIN_VERSION = '0.6.10'
+const PLUGIN_VERSION = '0.7.1'
 const SCHEMA_VERSION = 1
 const REGISTRY_FILE = 'datasources.json'
 const SECRETS_FILE = 'secrets.json'