dsh-db-mcp 0.6.10 → 0.7.0

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 |

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

@@ -6,24 +6,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 +231,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/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.0",
   "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.0'
 const SCHEMA_VERSION = 1
 const REGISTRY_FILE = 'datasources.json'
 const SECRETS_FILE = 'secrets.json'