dsh-db-mcp 0.6.9 → 0.7.0

package/docs/guide.md

@@ -0,0 +1,241 @@
+# Guide
+
+Everything the panel can do, in the order you meet it. For the wire protocol and
+file formats see [reference.md](reference.md); for build and release see
+[development.md](development.md).
+
+## 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 --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 --profile desktop add C:\path\to\dsh-db-mcp
+```
+
+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).
+
+## The panel
+
+Sidebar → **Database**. The masthead carries **‹ Back to chat**, the title, and the
+connection and version pills. Below it, five tabs:
+
+| Tab | What it does |
+| ---- | ------------ |
+| Data source list | the registry: rows grouped by label, bulk actions, refresh, restart MCP |
+| New data source | one connection string, user, password; also used for editing |
+| Import from DBeaver | scan, tick, import |
+| Runtime | Host facts, tool count, global write switch, venv and driver versions |
+| Audit log | the last dozen tool calls, converted to your time zone |
+
+**New data source** and **Import from DBeaver** swap only the card under the tabs —
+the masthead and tabs stay put, and every earlier step is still a tab away.
+
+## Adding a source
+
+The form is as small as DBeaver's connection dialog: **connection string**, **user**,
+**password** (with a *save password* box). Pasting fills type, host, port,
+database/service, name and identifier; the derived values only appear under
+**More settings**, together with schema, SID, SSL mode, charset and the read-only
+switch.
+
+Accepted shapes — a DSN, a JDBC URL, an Oracle TNS descriptor, a JDBC thin
+descriptor, or a bare database file:
+
+```
+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        # service name
+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
+```
+
+A password found inside the URL is sent once and then only stored; it is never
+echoed back. `id` is immutable once created — rename the *display name* instead
+(double-click the name on a row).
+
+## Importing from DBeaver
+
+The importer looks for `data-sources.json` under
+`%APPDATA%\DBeaverData\workspace*\General\.dbeaver\`, plus the `General` and
+Linux/macOS layouts. When the sibling `credentials-config.json` exists it is
+decrypted with DBeaver's built-in key (AES-128-CBC, zero IV, 16-byte prefix — see
+[Tatsh/dbeaver-creds](https://github.com/Tatsh/dbeaver-creds)). Ticked entries are
+copied into the registry, their passwords into `secrets.json`.
+
+Two details make real DBeaver workspaces work:
+
+- Connections created through the driver dialog often carry only a JDBC URL
+  (`configurationType: URL`) with no `database` field and no `user`. The importer
+  parses the URL for whatever the form fields omit and takes the user from the
+  decrypted credentials.
+- A connection already configured is not offered twice. Sources are identified by
+  kind + host + port + database/service/SID + user (SQLite by file path); a match
+  comes back as `alreadyImported`, the checkbox is disabled and the row says
+  *already added as …*.
+
+A workspace that never saved passwords is fine: the connection is imported with an
+empty password and the row shows **no password**. Fill it in once and it stays.
+
+## Testing a connection
+
+**Test** performs a real login: SQLite is opened read-only through `node:sqlite`,
+the other engines go through the Python drivers, which authenticate and run
+`select 1` (Oracle: `select 1 from dual`). The row then shows the banner, the user
+and database, and how long the login took:
+
+```
+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
+```
+
+Wrong passwords now surface the driver's own message (`ORA-01017`, `DPY-6005`,
+`password authentication failed`) instead of "port reachable". An unsaved form can
+be tested too. When the Python server cannot start, the probe degrades to a TCP
+check and says so.
+
+## Groups and bulk actions
+
+Every source carries an optional **group** label, editable under *More settings*.
+
+- **Create** — type a name in **New group**.
+- **Rename** — double-click the group name; **delete** drops the label from its
+  members.
+- **Move** — drag a source row onto a group, or onto **Ungrouped** to clear it.
+- **Rename a source** — double-click its name; the id never changes.
+- **Select** — each group header has a select-all box, so grouped sources join bulk
+  work exactly like loose ones.
+
+With a selection made, the bulk bar can test, flip read-only, move into a group, or
+delete (two-step confirmation).
+
+## Structure browser
+
+**Structure** on a source row opens a read-only view: tables and views on the left,
+columns of the selected table on the right (name, type, nullability, default,
+primary-key marker). It is served by `GET /schema`, which only forwards
+`list_tables` / `describe_table` to the MCP server — the page cannot run SQL, and
+nothing is cached.
+
+## Safety switches
+
+Two independent gates decide whether a statement may write:
+
+1. **Global switch** — `allowWrite` in `<runtime>/settings.json`, toggled on the
+   *Runtime* tab. Off by default; while off every write is refused with
+   `user_error` and a hint pointing at the switch.
+2. **Per-source flag** — `readOnly` on the source, on by default. Click the
+   *read-only* / *writable* pill on a row to flip it in one click; the pill turns
+   amber while that source accepts writes.
+
+The Python server reads the global flag at start-up and the host restarts it
+whenever the switch flips. Read-only is enforced again at the driver where the
+engine allows it (`mode=ro` for SQLite, `default_transaction_read_only` for
+PostgreSQL, `SET SESSION TRANSACTION READ ONLY` for MySQL).
+
+## Audit log
+
+Every MCP tool call appends one JSON line to `<runtime>/logs/audit.jsonl` (0600):
+time, tool, source, duration, row count, the SQL truncated to 2000 characters, and
+the error when it failed. Result rows are never logged. The file rotates to
+`audit.1.jsonl` at 512 KiB and logging can be switched off with `auditLog: false`.
+
+The panel shows the last dozen entries **on your own clock**; the file keeps UTC so
+it stays comparable across machines. Each stamp carries the full local timestamp in
+its tooltip.
+
+## Runtime layout
+
+```
+$DSH_HOME/db-mcp/
+  datasources.json   # sources and groups, never passwords, 0600
+  secrets.json       # per-source password, 0600, Host-only
+  settings.json      # global write switch + audit switch, 0600
+  logs/mcp.log       # masked log
+  logs/audit.jsonl   # one line per MCP tool call, rotates at 512 KiB
+  .venv/             # plugin-local venv: mcp, psycopg, PyMySQL, oracledb
+```
+
+## Test databases in Docker
+
+Nothing has to be installed on the host; each engine below is a throwaway
+container with a demo account (`demo` / `dbmcp-demo`).
+
+```sh
+# PostgreSQL — smallest and fastest, the recommended first target
+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 — several GB, a minute or two to become healthy
+docker run -d --name dbmcp-oracle -p 1521:1521 -e ORACLE_PASSWORD=dbmcp-demo \
+  gvenzl/oracle-free:23-slim
+```
+
+On Windows, 1521 often falls inside a Hyper-V reserved port block and `docker run`
+fails with *"An attempt was made to access a socket in a way forbidden by its access
+permissions"*. Check `netsh interface ipv4 show excludedportrange protocol=tcp` and
+publish another host port, e.g. `-p 11521:1521`; point the datasource at 11521.
+
+Then import or create a source with the matching string:
+
+```
+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
+```
+
+## Troubleshooting
+
+| 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 (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** |
+| `unknown tool "mcp__db__…"` right after a restart | tool registration was disposed with the old process | restart DSH once, then drive restarts from **Restart MCP** |
+| Oracle login fails with `DPY-6005` | listener unreachable, or host/port wrong | `docker ps`, then *Test* again |
+| `ORA-01950` on first write | Oracle user has no tablespace quota | `alter user <user> quota unlimited on users` |
+| Import row red: *incomplete host/database* | the DBeaver entry has neither fields nor a parsable URL | open the connection in DBeaver once, or create the source by hand |

package/docs/reference.md

@@ -0,0 +1,146 @@
+# Reference
+
+Wire-level details: HTTP routes, tool contracts, the files on disk, and the plugin
+configuration. For usage see [guide.md](guide.md).
+
+Everything below is served under `/plugins/db-mcp/api` on the DSH web origin. Reads
+are `GET`; every mutation is `POST` (the same-origin check compares `Origin` with
+`Host`). Responses are JSON with `cache-control: no-store`.
+
+## HTTP routes
+
+| Route | Purpose |
+| ----- | ------- |
+| `GET /health` | plugin version, Host facts, Python discovery, runtime paths, registry state, MCP status, settings |
+| `GET /datasources` | registry, credentials projected away |
+| `GET /schema?datasource=…&table=…[&schema=…]` | tables, or the columns of one table |
+| `GET /groups` | declared groups plus every group label in use |
+| `GET /dbeaver/scan` | DBeaver connections; never includes passwords |
+| `GET /mcp/status` | Python server phase, tool list, last error, stderr tail |
+| `GET /settings` · `POST /settings` | global write switch and audit switch |
+| `GET /audit?limit=N` | tail of the tool-call audit log (default 20, max 200) |
+| `GET /python/env` · `GET /python/status` | interpreter, venv path, installed driver versions |
+| `POST /python/setup` | create the venv and install `server/requirements.txt` |
+| `POST /datasources/save` | create or update a source (`id` immutable) |
+| `POST /datasources/delete` | remove a source and its stored secret |
+| `POST /datasources/test` | real login probe |
+| `POST /datasources/bulk` | `action: test \| readOnly \| group \| delete` over `ids` |
+| `POST /groups/save` · `POST /groups/delete` | create, rename (`from`) or delete a group |
+| `POST /dbeaver/import` | copy selected DBeaver connections into the registry |
+| `POST /mcp/start` · `POST /mcp/restart` | start or restart the Python MCP server |
+| `POST /mcp/call` | dev helper: call one MCP tool through the panel |
+| `POST /reload` | dev helper: re-import `src/host.js` without restarting DSH |
+
+### Status codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 200 | success; bodies carry `ok: true` |
+| 400 | validation error (`id must match …`, `oracle requires config.serviceName or config.sid`, `group name is required`, …) |
+| 403 | `Origin` present and different from `Host` |
+| 404 | unknown route, unknown datasource (`unknown datasources: …`), unknown group |
+| 405 | method not GET/HEAD/POST |
+| 500 | unexpected failure, including a Host module that failed to load |
+| 503 | MCP server not ready (`start the MCP server from the panel and try again`) |
+
+## Tools
+
+Names are prefixed at publication time: `mcp__db__list_datasources` and so on.
+`datasource` is optional everywhere — omitted, the default source is used.
+Row limits come from the server: `DB_MCP_MAX_ROWS` (default 200) per call, capped at
+`DB_MCP_MAX_ROWS_HARD` (default 2000).
+
+| Tool | Parameters | Returns |
+| ---- | ---------- | ------- |
+| `list_datasources` | — | `[{ id, name, kind, target, readOnly, isDefault }]` |
+| `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 }` |
+| `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 } }` |
+
+Failures come back as `{ ok: false, error: { code, message, hint? } }` with
+
+| Code | Meaning |
+| ---- | ------- |
+| `user_error` | the request is wrong: unknown datasource, refused write, bad table name |
+| `db_error` | the engine refused or failed: authentication, syntax, timeout |
+| `infra_error` | the plugin could not get that far: interpreter missing, venv broken |
+
+## Files
+
+All under `$DSH_HOME/db-mcp` (override with the `runtimeDir` option), mode `0600`,
+written atomically via a temporary file plus rename.
+
+`datasources.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "updatedAt": "2026-11-07T09:00:00.000Z",
+  "groups": ["docker"],
+  "datasources": [
+    {
+      "id": "pg-demo",
+      "name": "PostgreSQL demo",
+      "kind": "postgres",
+      "group": "docker",
+      "config": { "host": "127.0.0.1", "port": 5432, "database": "demo", "user": "demo", "schema": "public" },
+      "readOnly": true,
+      "isDefault": true,
+      "tags": [],
+      "createdAt": "…",
+      "updatedAt": "…",
+      "lastProbe": { "ok": true, "message": "PostgreSQL 15.19 · demo@demo · select version() ok", "latencyMs": 140, "at": "…" }
+    }
+  ]
+}
+```
+
+`secrets.json` holds `{ "schemaVersion": 1, "secrets": { "<id>": { "password": "…" } } }`
+and is read only by the Host, never sent to the page.
+
+`settings.json` holds `{ "allowWrite": false, "auditLog": true, "updatedAt": "…" }`.
+`allowWrite` counts only when it is exactly `true`.
+
+`logs/audit.jsonl` — one JSON object per tool call; rotates to `audit.1.jsonl` at
+512 KiB:
+
+```json
+{"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
+
+| Kind | `config` keys |
+| ---- | ------------- |
+| `sqlite` | `file` (absolute path), `readOnlyOpen?`, `busyTimeoutMs?` |
+| `postgres` | `host`, `port` (5432), `database`, `user`, `schema?`, `sslMode?` |
+| `mysql` | `host`, `port` (3306), `database`, `user`, `charset?` |
+| `oracle` | `host`, `port` (1521), `serviceName` **or** `sid`, `user`, `schema?` |
+
+`id` must match `^[a-z0-9][a-z0-9-]{0,31}$` and never changes; `name` ≤ 64
+characters; `group` ≤ 48.
+
+## Plugin configuration
+
+The bundle row in the profile accepts these options (all optional):
+
+| Key | Default | Meaning |
+| --- | ------- | ------- |
+| `pythonPath` | auto | interpreter to use ahead of the venv and `PATH` |
+| `runtimeDir` | `$DSH_HOME/db-mcp` | where the registry, secrets, settings and logs live |
+| `probeTimeoutMs` | `10000` | per-probe timeout for *Test* |
+| `mcpServerName` | `db` | prefix after `mcp__` when publishing tools |
+| `debug` | `false` | log Host activity to the DSH console |
+
+The Python side reads `DB_MCP_RUNTIME`, `DB_MCP_ALLOW_WRITE`, `DB_MCP_MAX_ROWS` and
+`DB_MCP_MAX_ROWS_HARD`; the Host sets the first two when spawning.
+
+## Runtime requirements
+
+- Node 22+ on the Host (the plugin uses `node:sqlite` for the SQLite probe).
+- A Python 3.10+ interpreter for the MCP server, with the four packages from
+  `server/requirements.txt`. `mcp` must stay on 1.x — 2.x renamed `FastMCP`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-db-mcp",
-  "version": "0.6.9",
-  "description": "DSH database plugin: a data-source management panel plus a Python MCP server that exposes those sources to the agent.",
+  "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",
     "dsh-plugin",

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.9'
+const PLUGIN_VERSION = '0.7.0'
 const SCHEMA_VERSION = 1
 const REGISTRY_FILE = 'datasources.json'
 const SECRETS_FILE = 'secrets.json'