npm - dsh-db-mcp - Versions diffs - 0.6.9 → 0.6.10 - Mend

dsh-db-mcp 0.6.9 → 0.6.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +64 -347
package/README.zh.md +38 -223
package/docs/{requirements.md → design-notes.md} +5 -0
package/docs/development.md +99 -0
package/docs/guide.md +223 -0
package/docs/reference.md +146 -0
package/package.json +2 -2
package/src/host.js +1 -1

package/README.md CHANGED Viewed

@@ -1,370 +1,87 @@
 # dsh-db-mcp
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/dsh-db-mcp.svg)](https://www.npmjs.com/package/dsh-db-mcp)
 English | [中文](README.zh.md)
-DSH plugin that adds a **Database** entry to the sidebar with a data-source
-management panel, backed by a Python MCP server that lets the agent query those
-databases through tools (not through the page).
+A [DSH](https://github.com/deepseek-ai/deepseek-harness) plugin that hands your
+databases to the agent. It adds a **Database** panel to the sidebar and publishes
+every registered source as `mcp__db__*` tools.
-- One panel for every engine: SQLite, PostgreSQL, MySQL, Oracle.
-- One connection string fills the whole form; passwords never leave the machine
-  and never come back to the page.
-- Import the connections DBeaver already has, including its encrypted passwords.
-- Read-only by default, with two independent write gates and an audit log.
-- The agent gets eight MCP tools, not a SQL editor in the UI.
+**Zero configuration.** There is nothing to edit in DSH and no connection to type
+twice: import the connections DBeaver already knows, then just ask.
-Requirements and staged plan: [`docs/requirements.md`](docs/requirements.md).
+## Zero configuration, in three senses
-## What exists today (P7)
+- **No DSH files.** The bundle patch inserts one Loader row. The plugin starts its
+  own Python MCP server over stdio and registers the tools on the host `tools`
+  service — no `dsh-mcp-client` row, no JSON to hand-edit, no env var to export.
+- **No data source to fill in.** The importer reads `data-sources.json` from the
+  DBeaver workspace and decrypts `credentials-config.json` with DBeaver's own key,
+  so host, port, database, user and saved password arrive together. Ticking a box
+  is the whole setup step.
+- **No Python to prepare.** The panel finds an interpreter, creates the venv and
+  installs the four driver packages from **Runtime → Install / repair
+  dependencies**.
-- **Host half** (`index.js` → `src/host.js`): a Cordis plugin serving
-  `/plugins/db-mcp/api` from the DSH web server.
+## Run
-  | 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=…]` | read-only structure: tables, or the columns of one table |
-  | `GET /groups` | declared groups plus every group label in use |
-  | `GET /dbeaver/scan` | connections already configured in DBeaver |
-  | `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` | the tail of the tool-call audit log |
-  | `GET /python/env` | interpreter, venv path, installed driver versions |
-  | `POST /python/setup` | create the venv and `pip install -r server/requirements.txt` |
-  | `POST /datasources/save` | create or update a source (`id` is immutable) |
-  | `POST /datasources/delete` | remove a source and its stored secret |
-  | `POST /datasources/test` | real login probe: SQLite over `node:sqlite`, the rest through the Python drivers |
-  | `POST /datasources/bulk` | test / read-only / group / delete a set of sources |
-  | `POST /groups/save` · `POST /groups/delete` | create, rename 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 |
-- **Client half** (`client.js`): sidebar entry (`db-mcp`, order 25) plus the main
-  panel with the source list, the minimal create/edit form (one connection string),
-  test/delete/default actions, a read-only *structure* browser, the DBeaver import
-  flow, a *Restart MCP* button, the runtime diagnostics card (tool count, global
-  write switch, venv and package versions with a one-click install) and an
-  *audit log* card. Copy is localized (zh/en) through the client `locale` service.
-- **Python server** (`server/`): `main.py` (FastMCP, eight tools), `engines.py`
-  (per-engine connect/introspect/query), `store.py` (reads the registry).
-  The plugin spawns it over stdio and publishes its tools as `mcp__db__*` on the
-  host `tools` service — it does not go through a `dsh-mcp-client` Loader row.
-### Tools the agent gets
-| Tool | Purpose |
-| ---- | ------- |
-| `mcp__db__list_datasources` | the registered sources (id, kind, target, read-only) |
-| `mcp__db__list_tables` | tables/views of one source |
-| `mcp__db__describe_table` | columns, types, nullability, primary key |
-| `mcp__db__sample_rows` | a few rows of one table |
-| `mcp__db__run_query` | one statement; read-only sources refuse writes |
-| `mcp__db__explain_query` | query plan |
-| `mcp__db__get_ddl` | `CREATE TABLE` statement (SQLite: as created; others: rebuilt from the catalog) |
-| `mcp__db__test_connection` | log in for real, run `select 1`, report server/user/schema |
-`datasource` is optional everywhere: omitted, the default source is used.
-### Python environment
-Interpreter discovery order: plugin config `pythonPath` → `<DSH_HOME>/db-mcp/.venv/Scripts/python.exe` → that venv on POSIX → `python` → `python3`. Dependencies live in the runtime venv, not in the package:
-    python -m venv C:\Users\<you>\.dsh\db-mcp\.venv
-    C:\Users\<you>\.dsh\db-mcp\.venv\Scripts\python.exe -m pip install -r server\requirements.txt
-`mcp` must stay on 1.x (2.x renamed `FastMCP` to `MCPServer`).
-## Does the Test button really log in?
-Yes. For PostgreSQL, MySQL and Oracle the panel's **Test** action calls
-`mcp__db__test_connection` over the Python MCP server, so the probe is a real
-authenticated login plus `select 1` (Oracle uses `select 1 from dual`). The
-panel row then shows the server banner, the connected user and database, and how
-long the login took, for example:
-```
-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
-```
-A wrong password or an unreachable listener now surfaces the driver's own
-message (`ORA-01017`, `DPY-6005`, `password authentication failed` — instead of
-"port reachable"). Testing an unsaved form works too: `test_connection` accepts
-`kind` + `config` + `password` without writing the registry first. When the
-Python server cannot start, the probe degrades to a TCP check and says so.
-## Filling the form from one string
-The create/edit form is deliberately as small as DBeaver's connection dialog:
-**connection string**, **user**, **password** (with a *save password* box), and
-that is it. Pasting a JDBC URL, a DSN, an Oracle TNS descriptor or a `.db` path
-fills type, host, port, database/service, name and identifier; the derived values
-only show up under **More settings**, together with schema, SID, SSL mode,
-charset and the read-only switch.
-Accepted shapes (see `dev/parse.test.mjs` for the full matrix):
-```
-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 to `POST /datasources/save` and
-then only stored in `secrets.json`; it is never echoed back.
-Writes are `POST` only (the same-origin check compares `Origin` with `Host`).
-Passwords never enter `datasources.json`; they live in `secrets.json` and are
-never returned to the page (`hasSecret` is the only signal).
-## DBeaver import
-`GET /dbeaver/scan` 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`). A workspace that never saved passwords simply
-imports the connection with an empty password, which the UI shows as
-`no password`.
-Connections created through the DBeaver driver dialog carry only a JDBC URL
-(`configurationType: URL`) — no `database` field at all and no `user`. The
-importer therefore parses `jdbc:mysql://host:port/db`,
-`jdbc:postgresql://…` and `jdbc:oracle:thin:@…` for whatever the form fields
-omit, and takes the user from the decrypted credentials when it is stored
-there. The imported source is named after the DBeaver connection name (slugged
-into an id), keeps `readOnly: true`, and gets the saved password copied into
-`secrets.json`. Anything still missing is reported in `warnings`.
-A connection that is already configured is not offered twice: every source
-is identified by kind + host + port + database/service/SID + user (SQLite by
-file path), and a DBeaver entry that matches one of them comes back with
-`alreadyImported: true`, `duplicateId` and `duplicateName`. The panel disables
-its checkbox and says *already added as …*; `POST /dbeaver/import` reports such
-ids under `skipped` instead of creating a second copy.
-The panel navigates with a tab bar (*Data source list / New data source /
-Import from DBeaver / Runtime / Audit log*): the active step is plain text, every
-earlier step is a link back, and no page needs a separate "back to list" button.
-## Test databases in Docker
-Nothing has to be installed on the host; every engine below is a throwaway
-container with a demo account (`demo` / `dbmcp-demo`).
-```
-# PostgreSQL — smallest and fastest to start, 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 instead, e.g. `-p 11521:1521`; the
-datasource then points at port 11521.
-Then create a source in the panel with the matching connection string, e.g.
-`postgresql://demo:dbmcp-demo@127.0.0.1:5432/demo`,
-`mysql://demo:dbmcp-demo@127.0.0.1:3306/demo` or
-`oracle://system:dbmcp-demo@127.0.0.1:1521/FREEPDB1`.
-## Install into a profile
-```
-plugin_manager install_bundle  target=<absolute path to this directory>
-```
-or, from npm:
-```
+```sh
 dsh plugin add dsh-db-mcp@latest
 ```
-The bundle patch (`cordis.patch.yml`) inserts one Loader row with id `db-mcp`.
-A profile that links this directory keeps file edits live; the Host module is
-imported once per process, hence `POST /plugins/db-mcp/api/reload` (or an app
-restart) after changing `src/host.js`.
-## Panel layout
-The page follows the same chrome as the other first-party panels:
-- a masthead with **‹ Back to chat** (closes the panel through
-  `ctx.layout.selectPanel(null)`), the **Database** title, and the
-  connection/version pills;
-- a tab row — **Data source list / New data source / Import from DBeaver /
-  Runtime / Audit log** — with the active tab underlined.
-Picking **New data source** or **Import from DBeaver** swaps only the card below
-the tabs — the masthead and the tabs stay put. Editing reuses the **New data
-source** tab; the structure browser is a sub-view of **Data source list** with
-its own `← Sources` link. There is no second action bar: **Refresh** and
-**Restart MCP** sit in the source-list card header, and the list itself owns the
-group tools.
-## Schema overview
-The **Structure** button on a source row opens a read-only browser: the tables
-(or views) of that source on the left, and the columns of the selected table on
-the right — name, type, nullability, default value and primary-key marker. It is
-served by `GET /schema`, which only forwards `list_tables` / `describe_table` to
-the MCP server, so the page itself can never run SQL. Nothing is cached: each
-open reads the live catalog.
-## Groups and bulk actions
-Every source carries an optional **group** label (`group` in the registry,
-editable under *More settings*). Groups are user-owned: type a name in the
-**New group** box to create one, **double-click a group name to rename it** (or
-the delete button to drop the group), and drag a source row onto a group to move
-it there (drag it onto **Ungrouped** to clear the label). Double-clicking a
-source name renames just that source — its id never changes. The list renders one
-section per group, sorted by name with the ungrouped sources last; while no group
-exists the list keeps its flat look.
-Each group header carries a select-all box, so sources inside a group take part
-in bulk work exactly like loose ones. Tick any row to open the bulk bar: test all
-selected sources, flip them to read-only or writable, move them into a group, or
-delete them (two-step confirmation). Bulk moves go through
-`POST /datasources/bulk` with
-`{ action: 'test' | 'readOnly' | 'group' | 'delete', ids: [...], … }`, while group
-CRUD uses `GET /groups`, `POST /groups/save` and `POST /groups/delete`.
-## Releasing
-The package is published from GitHub Actions with [npm trusted publishing](https://docs.npmjs.com/trusted-publishers):
-`.github/workflows/publish.yml` trades the workflow's OIDC token for a short-lived
-publish credential, so no `NPM_TOKEN` secret exists anywhere.
-```bash
-node dev/bump.mjs 0.6.5      # package.json + src/host.js
-git commit -am "chore: release 0.6.5"
-git tag v0.6.5 && git push origin main --tags
-```
-The workflow refuses to publish when the tag and `package.json` disagree, runs the
-portable suites (`npm run test:ci`), publishes with `--provenance`, then waits for the
-version to appear in the registry. Local `npm publish` still works for the very first
-release, before a trusted publisher exists for the package.
-## Development
-```
-node dev/engines.test.mjs # 11 checks: engines.py commit/rollback + affectedRows, stub connection
-node dev/selftest.mjs     # mounts src/host.js on a throwaway port, 46 checks
-node dev/shims.test.mjs   # mounts index.js, checks routes, /reload, tool publication
-node dev/parse.test.mjs   # 24 checks: connection-string parser (DSN/JDBC/TNS/paths)
-node dev/render.test.mjs  # 40 checks: components and the result renderer, stub React
-node dev/i18n.test.mjs    # 12 checks: en/zh parity, no dead keys, no stray copy
-node dev/p5.test.mjs      # 15 checks: settings, audit log, python environment
-node dev/mcp.test.mjs     # 19 checks: real Python server over stdio, real SQLite + Oracle logins
-```
-`npm test` runs everything except `mcp.test.mjs`, which needs the venv and the
-Oracle container. `dev/engines.test.mjs` needs a Python interpreter (the plugin
-venv, else `python` on PATH) but no database: it drives `server/engines.py`
-against a stub DB-API connection, covering the commit/rollback and
-`affectedRows` contract of `run_query`. `node dev/bump.mjs 0.6.6` updates both
-version strings.
-## Safety switches
-Two independent gates decide whether a statement may write:
-1. **Global switch** — `allowWrite` in `<runtime>/settings.json`, toggled from the
-   diagnostics card. Off by default; while off every write statement is refused
-   with `user_error` and a hint pointing at the switch.
-2. **Per-source flag** — `readOnly` on the data source, on by default. A source
-   stays read-only even when the global switch is on until you clear its flag.
-   Click the *read-only* / *writable* pill on a source row to flip it in one
-   click; the pill turns amber while that source accepts writes, and the notice
-   reminds you when the global switch is still off.
-The Python server reads the global flag from `DB_MCP_ALLOW_WRITE` at start-up; the
-host restarts it whenever the switch flips. Read-only is also enforced by the
-driver itself where the engine allows it (`mode=ro` for SQLite,
-`default_transaction_read_only` for PostgreSQL, `SET SESSION TRANSACTION READ ONLY`
-for MySQL).
+Then:
-### What the plugin runs, and with what
+1. Sidebar → **Database**.
+2. **Import from DBeaver** → tick the connections → **Import selected**.
+3. Ask the agent something like *"which tables does my Chinook database have?"*
-- The Python server is started with a fixed interpreter path, a fixed script and a
-  fixed argument list — never through a shell, so no string is ever re-parsed by
-  `cmd.exe` or `/bin/sh`.
-- The child does **not** inherit the host environment. It gets a short allowlist
-  (`PATH`, `TEMP`, `HOME`, `PYTHON*`, and similar) plus the three `DB_MCP_*` flags
-  the plugin sets. Tokens or cloud credentials in the DSH process are not passed
-  down.
-- Connections to PostgreSQL, MySQL and Oracle are opened by that child; only SQLite
-  is read in-process. The raw TCP probe is a fallback used when the child cannot
-  start, and it never sends credentials.
-- Passwords live in `secrets.json` (mode `0600`) and are never returned by any HTTP
-  route; the panel only learns `hasSecret`.
+A connection whose password was never saved shows **no password**; open the source
+once and type it — it goes to `secrets.json` and never comes back to the page.
-## Audit log
+Prefer to start from scratch? **New data source** takes one connection string
+(`postgresql://user:pw@host:5432/db`, a JDBC URL, an Oracle TNS descriptor or a
+`.db` path) and fills the form from it.
-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 turned off with `auditLog: false` in
-`settings.json`. The panel shows the last dozen entries on **your own clock** —
-the file keeps UTC so it stays comparable across machines, the card converts each
-stamp to the viewer's time zone and prints the offset it used.
+## What the agent gets
-`dev/shims.test.mjs` also asserts that `package.json` has no UTF-8 BOM: the host
-parses it with `JSON.parse`, which rejects a BOM, and the plugin then shows up as
-`availability: missing` instead of loading. Editors that "add BOM" will break the
-bundle silently — if the sidebar entry disappears after a restart, check this
-first.
-## Stage map
-| Stage | Content |
-| ----- | ------- |
-| P1 | installable skeleton: sidebar entry, empty panel, Host health API (done) |
-| P2 | data-source CRUD, connection test, DBeaver import (done) |
-| P3 | Python MCP server, tools published as `mcp__db__*` (done) |
-| P4 | PostgreSQL / MySQL / Oracle dialects (done) |
-| P5 | diagnostics, one-click venv, reload, audit log, global write switch (done) |
-| P6 | i18n polish and docs (done) |
-| P7 | read-only schema overview, groups, bulk actions (done) |
+| Tool | Purpose |
+| ---- | ------- |
+| `mcp__db__list_datasources` | registered sources: id, kind, target, read-only |
+| `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__explain_query` | query plan |
+| `mcp__db__get_ddl` | `CREATE TABLE` statement |
+| `mcp__db__test_connection` | real login, `select 1`, server/user/schema |
+`datasource` is optional on all of them: omitted, the default source is used.
+Queries run **in the conversation**; the panel is for managing connections, not a
+SQL console.
+## Safety
+- **Read-only by default**, with two independent gates: a global write switch and a
+  per-source flag. Both must be open before a statement may write.
+- **Passwords stay local.** They live in `secrets.json` (mode `0600`); no HTTP route
+  ever returns one, and the Python child receives a short environment allowlist
+  rather than the whole DSH environment.
+- **Every tool call is audited** to `logs/audit.jsonl` — tool, source, duration, row
+  count, SQL. Result rows are never logged.
+- **Nothing runs from the panel except catalog reads.** The structure browser only
+  forwards `list_tables` and `describe_table`.
+## Documentation
+| Document | Contents |
+| -------- | -------- |
+| [docs/guide.md](docs/guide.md) | Panel walkthrough, connection strings, groups, Docker test databases, troubleshooting |
+| [docs/reference.md](docs/reference.md) | HTTP routes, tool contracts, registry and settings files, plugin config |
+| [docs/development.md](docs/development.md) | Repository layout, hot reload, test suites, release flow |
+| [docs/design-notes.md](docs/design-notes.md) | Historical design log (P1 → P7) and the decisions behind them |
 ## License
 Apache License 2.0 — see [LICENSE](LICENSE).
-## Runtime layout
-```
-$DSH_HOME/db-mcp/
-  datasources.json   # profiles, 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
-```

package/README.zh.md CHANGED Viewed

@@ -1,252 +1,67 @@
 # dsh-db-mcp
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/dsh-db-mcp.svg)](https://www.npmjs.com/package/dsh-db-mcp)
 [English](README.md) | 中文
-一个 DSH 插件：在侧边栏加一个 **数据库** 入口，配一个数据源管理面板，背后是 Python 写的 MCP 服务——让智能体通过工具查询这些数据库，而不是在页面里执行 SQL。
-- 一个面板管四种引擎：SQLite、PostgreSQL、MySQL、Oracle。
-- 一条连接串填满整张表单；口令只存在本机，永不回传给页面。
-- 可以把 DBeaver 里已有的连接（连同它加密保存的口令）直接导入。
-- 默认只读，两道互相独立的写闸门，加一份审计日志。
-- 给智能体的是 8 个 MCP 工具，界面里没有 SQL 编辑器。
-需求与阶段计划见 [`docs/requirements.md`](docs/requirements.md)。
-## 现在有什么（P7）
-- **Host 半边**（`index.js` → `src/host.js`）：一个 Cordis 插件，通过 DSH 的 web server 提供 `/plugins/db-mcp/api`。
-  | 路由 | 用途 |
-  | ---- | ---- |
-  | `GET /health` | 插件版本、Host 信息、Python 探测、运行时路径、注册表状态、MCP 状态、设置 |
-  | `GET /datasources` | 注册表，口令字段已剔除 |
-  | `GET /schema?datasource=…&table=…[&schema=…]` | 只读结构：表清单，或某张表的列 |
-  | `GET /groups` | 已声明的分组，加上所有正在使用的分组名 |
-  | `GET /dbeaver/scan` | DBeaver 里已配置的连接 |
-  | `GET /mcp/status` | Python 服务所处阶段、工具清单、最后的错误、stderr 尾部 |
-  | `GET /settings` · `POST /settings` | 全局写开关与审计开关 |
-  | `GET /audit?limit=N` | 工具调用审计日志的末尾若干条 |
-  | `GET /python/env` | 解释器、venv 路径、已安装的驱动版本 |
-  | `POST /python/setup` | 建 venv 并 `pip install -r server/requirements.txt` |
-  | `POST /datasources/save` | 新建或更新数据源（`id` 不可改） |
-  | `POST /datasources/delete` | 删除数据源及其口令 |
-  | `POST /datasources/test` | 真实登录探测：SQLite 走 `node:sqlite`，其余走 Python 驱动 |
-  | `POST /datasources/bulk` | 对一批数据源做 测试 / 只读 / 分组 / 删除 |
-  | `POST /groups/save` · `POST /groups/delete` | 新建、重命名、删除分组 |
-  | `POST /dbeaver/import` | 把选中的 DBeaver 连接复制进注册表 |
-  | `POST /mcp/start` · `POST /mcp/restart` | 启动或重启 Python MCP 服务 |
-  | `POST /mcp/call` | 开发辅助：经面板调用某个 MCP 工具 |
-  | `POST /reload` | 开发辅助：不重启 DSH 重新导入 `src/host.js` |
-- **Client 半边**（`client.js`）：侧边栏入口（`db-mcp`，order 25）加主面板——数据源列表、极简的新建/编辑表单（一条连接串）、测试/删除/设为默认、只读的「结构」浏览、DBeaver 导入流程、「重启 MCP」按钮、运行时诊断卡（工具数、全局写开关、venv 与依赖版本及一键安装）、以及「审计日志」卡。文案经客户端 `locale` 服务做中英本地化。
-- **Python 服务**（`server/`）：`main.py`（FastMCP，8 个工具）、`engines.py`（按引擎连接/内省/查询）、`store.py`（读注册表）。插件用 stdio 拉起它，把它的工具以 `mcp__db__*` 发布到 Host 的 `tools` 服务上——**不**经过 `dsh-mcp-client` 的 Loader 行。
-### 智能体拿到的工具
-| 工具 | 用途 |
-| ---- | ---- |
-| `mcp__db__list_datasources` | 已登记的数据源（id、类型、目标、是否只读） |
-| `mcp__db__list_tables` | 某个数据源的表/视图 |
-| `mcp__db__describe_table` | 列、类型、是否可空、主键 |
-| `mcp__db__sample_rows` | 某张表的少量样本 |
-| `mcp__db__run_query` | 执行一条语句；只读源拒绝写 |
-| `mcp__db__explain_query` | 查询计划 |
-| `mcp__db__get_ddl` | `CREATE TABLE` 语句（SQLite 取原文，其余按目录重建） |
-| `mcp__db__test_connection` | 真实登录、执行 `select 1`、回报服务器/用户/模式 |
-`datasource` 处处可选：不填就用默认数据源。
-### Python 环境
-解释器探测顺序：插件配置 `pythonPath` → `<DSH_HOME>/db-mcp/.venv/Scripts/python.exe` → POSIX 上的同一个 venv → `python` → `python3`。依赖装在运行时 venv 里，不随包分发：
-    python -m venv C:\Users\<you>\.dsh\db-mcp\.venv
-    C:\Users\<you>\.dsh\db-mcp\.venv\Scripts\python.exe -m pip install -r server\requirements.txt
-`mcp` 必须固定在 1.x（2.x 把 `FastMCP` 改名成了 `MCPServer`）。
-## 「测试」按钮是真的登录吗？
-是。PostgreSQL、MySQL、Oracle 的 **测试** 走 `mcp__db__test_connection`，经 Python MCP 服务执行一次真实认证登录加 `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`），而不是笼统的「端口可达」。未保存的表单也能测：`test_connection` 接受 `kind` + `config` + `password`，不需要先写注册表。Python 服务起不来时，探测退回 TCP 检查，并明确说明这一点。
-## 一条连接串填完整张表单
-新建/编辑表单刻意做得和 DBeaver 的连接对话框一样小：**连接串**、**用户**、**口令**（带「保存密码」勾选），就这些。粘贴 JDBC URL、DSN、Oracle TNS 描述符或 `.db` 路径，类型、主机、端口、库名/服务名、名称与标识符都会自动带出；推导出来的值默认收在「更多设置」里，与模式、SID、SSL 模式、字符集、只读开关放在一起。
-支持的写法（完整矩阵见 `dev/parse.test.mjs`）：
-```
-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
-```
-连接串里的口令只发送一次给 `POST /datasources/save`，之后只存在 `secrets.json` 里，永不回显。
-写操作一律用 `POST`（同源校验比较 `Origin` 与 `Host`）。口令不会进 `datasources.json`，只存在 `secrets.json`，页面拿到的唯一信号是 `hasSecret`。
-## 从 DBeaver 导入
-`GET /dbeaver/scan` 会在 `%APPDATA%\DBeaverData\workspace*\General\.dbeaver\` 下找 `data-sources.json`（同时兼容 `General` 布局与 Linux/macOS 位置）。同级存在 `credentials-config.json` 时，用 DBeaver 内置的密钥解密（AES-128-CBC、零 IV、前 16 字节前缀，参考 `Tatsh/dbeaver-creds`）。从未保存过口令的工作区，导入出来的连接口令为空，界面显示「无密码」。
-通过 DBeaver 驱动对话框建的连接，往往只有一条 JDBC URL（`configurationType: URL`），既没有 `database` 字段也没有 `user` 字段。导入器因此会自己解析 `jdbc:mysql://host:port/db`、`jdbc:postgresql://…`、`jdbc:oracle:thin:@…`，补上表单字段缺的部分，并在解密凭据里存了用户名时从那里取。导入的数据源按 DBeaver 连接名命名（再 slug 成 id），保持 `readOnly: true`，已存的口令会复制进 `secrets.json`；仍然缺的东西写进 `warnings`。
-已经配置过的连接不会被导入两次：每个数据源用 类型 + 主机 + 端口 + 库名/服务名/SID + 用户 做身份（SQLite 用文件路径），命中的 DBeaver 条目会带上 `alreadyImported: true`、`duplicateId`、`duplicateName` 返回。面板把它的复选框禁用并标注「已作为 … 添加」，`POST /dbeaver/import` 则把这类 id 放进 `skipped`，不会建出第二份。
-面板用标签栏导航（*数据源列表 / 新建数据源 / 从 DBeaver 导入 / 运行时诊断 / 审计日志*）：当前步骤是纯文本、可回退的步骤是链接，任何页面都不需要额外的「返回列表」按钮。
-## 用 Docker 起测试库
-宿主机什么都不用装，下面每个引擎都是用完即弃的容器，演示账号 `demo` / `dbmcp-demo`。
-```
-# 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
-```
+一个 [DSH](https://github.com/deepseek-ai/deepseek-harness) 插件，把数据库交给智能体：侧栏多出一个**数据库**面板，登记过的每个数据源都会变成 `mcp__db__*` 工具。
-Windows 上 1521 常常落在 Hyper-V 的保留端口段里，`docker run` 会报「尝试访问套接字的方式被其访问权限禁止」。用 `netsh interface ipv4 show excludedportrange protocol=tcp` 查一下，换一个宿主端口发布即可，例如 `-p 11521:1521`，数据源里填 11521。
+**零配置。** 不需要改 DSH 里的任何文件，也不用手工抄一遍连接信息——直接把 DBeaver 里已有的连接导进来，然后开口问就行。
-然后在面板里用对应的连接串建数据源，例如
-`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`。
+## 三个方面都不用配
-## 装进一个 profile
+- **不用改 DSH 文件。** bundle 的 patch 只插入一行 Loader 记录；插件自己用 stdio 拉起 Python MCP 服务，并把工具注册到 Host 的 `tools` 服务上——不需要 `dsh-mcp-client` 那一行，也不用编辑 JSON、导环境变量。
+- **不用填数据源。** 导入器读取 DBeaver 工作区的 `data-sources.json`，再用 DBeaver 自带的密钥解密 `credentials-config.json`，主机、端口、库名、用户、已存口令一次到位。勾一个框就是全部配置工作。
+- **不用准备 Python。** 面板会自己找解释器、建 venv、装四个驱动包，入口在 **运行时诊断 → 安装 / 修复依赖**。
-```
-plugin_manager install_bundle  target=<本目录的绝对路径>
-```
+## 运行
-或者从 npm 装：
-```
+```sh
 dsh plugin add dsh-db-mcp@latest
 ```
-bundle patch（`cordis.patch.yml`）只插入一行 Loader 配置，id 为 `db-mcp`。以链接方式装入的 profile 改文件即生效；Host 模块每个进程只导入一次，所以改完 `src/host.js` 要 `POST /plugins/db-mcp/api/reload`（或重启应用）。
-## 面板布局
-页面与其它官方面板保持一致的外壳：
-- 页头：**‹ 返回会话**（经 `ctx.layout.selectPanel(null)` 关闭面板）、**数据库** 标题，以及连接状态与版本药丸；
-- 标签栏 —— **数据源列表 / 新建数据源 / 从 DBeaver 导入 / 运行时诊断 / 审计日志**，当前标签带下划线。
-点「新建数据源」或「从 DBeaver 导入」只切换标签下方那张卡片，页头与标签栏不动。编辑复用「新建数据源」标签；结构浏览是「数据源列表」下的子视图，带自己的 `← 数据源` 链接。没有第二排操作栏：**刷新** 与 **重启 MCP** 在数据源列表卡片的头部，分组相关的操作归列表自己管。
-## 结构概览
-数据源行上的「结构」按钮打开只读浏览器：左边是该源的表（或视图），右边是选中表的列——名称、类型、可空、默认值、主键标记。数据由 `GET /schema` 提供，它只把 `list_tables` / `describe_table` 转发给 MCP 服务，页面本身永远执行不了 SQL。不缓存：每次打开都读实时目录。
-## 分组与批量操作
-每个数据源带一个可选的**分组**标签（注册表里的 `group`，可在「更多设置」里改）。分组归用户所有：在「新建分组」框里输入名字即可创建，**双击组名改名**（或按删除按钮删组），把数据源行拖到某个组上即可移过去（拖到「未分组」上则清除标签）。双击数据源名只改这一条的名字，id 永不改变。列表按组渲染成若干区块，组名排序、未分组的排最后；没有分组时列表保持原来的平铺样式。
-每个组头都有全选复选框，所以组内的数据源和散在外面的完全一样，都能参与批量操作。勾选任意行即出现批量操作条：批量测试、设为只读或允许写、移动到某个分组、或删除（两步确认）。批量移动走 `POST /datasources/bulk`，body 形如 `{ action: 'test' | 'readOnly' | 'group' | 'delete', ids: [...], … }`；分组的增删改走 `GET /groups`、`POST /groups/save`、`POST /groups/delete`。
-## 发布
-包由 GitHub Actions 通过 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) 发布：`.github/workflows/publish.yml` 用 workflow 的 OIDC token 换短期发布凭据，因此仓库里没有任何 `NPM_TOKEN` 密钥。
-```bash
-node dev/bump.mjs 0.6.5      # 同时改 package.json 与 src/host.js
-git commit -am "chore: release 0.6.5"
-git tag v0.6.5 && git push origin main --tags
-```
-workflow 会拒绝 tag 与 `package.json` 版本不一致的情况，先跑可移植测试（`npm run test:ci`），再带 `--provenance` 发布，最后轮询 registry 确认版本已出现。首次发布（包还没有 trusted publisher 时）仍可本地 `npm publish`。
-## 开发
-```
-node dev/engines.test.mjs # 11 项：engines.py 的 commit/rollback 与 affectedRows，用假连接
-node dev/selftest.mjs     # 在临时端口挂载 src/host.js，46 项断言
-node dev/shims.test.mjs   # 挂载 index.js，检查路由、/reload、工具发布
-node dev/parse.test.mjs   # 24 项：连接串解析（DSN/JDBC/TNS/路径）
-node dev/render.test.mjs  # 40 项：用 stub React 渲染组件与结果渲染器
-node dev/i18n.test.mjs    # 12 项：中英键集合一致、无死键、无漏译
-node dev/p5.test.mjs      # 15 项：设置、审计日志、Python 环境
-node dev/mcp.test.mjs     # 19 项：真实 Python 服务走 stdio，真实 SQLite 与 Oracle 登录
-```
-`npm test` 跑除 `mcp.test.mjs` 之外的全部（后者需要 venv 与 Oracle 容器）。`dev/engines.test.mjs` 只需要一个 Python 解释器（插件 venv，否则 PATH 里的 `python`），不连数据库：它用假 DB-API 连接驱动 `server/engines.py`，守住 `run_query` 的 commit/rollback 与 `affectedRows` 契约。`node dev/bump.mjs 0.6.6` 会同步两处版本号。
+然后：
-## 安全闸门
+1. 侧栏 → **数据库**。
+2. **从 DBeaver 导入** → 勾选连接 → **导入所选**。
+3. 问智能体一句：*「我的 Chinook 库里有哪些表？」*
-是否允许写入由两道互相独立的闸门决定：
+如果某条连接在 DBeaver 里没保存口令，卡片会显示**无密码**；打开该数据源补一次即可——口令只写进 `secrets.json`，不会再回到页面上。
-1. **全局开关** —— `<运行时目录>/settings.json` 的 `allowWrite`，在诊断卡上切换。默认关闭；关闭期间所有写语句都以 `user_error` 拒绝，并给出指向该开关的提示。
-2. **单源标记** —— 数据源的 `readOnly`，默认开启。即使全局开关打开，只要不清掉这条标记，该源仍然只读。点数据源行上的「只读 / 可写」药丸即可一键切换：该源可写时药丸变成琥珀色，若全局开关仍关着，提示条会提醒你去打开它。
+想从零开始也行：**新建数据源**里粘一条连接串（`postgresql://user:pw@host:5432/db`、JDBC URL、Oracle TNS 描述符或 `.db` 路径），表单会自动填好。
-Python 服务启动时从环境变量 `DB_MCP_ALLOW_WRITE` 读取全局标记；开关一变，Host 就会重启它。只要引擎支持，只读还会在驱动层再兜一次（SQLite 的 `mode=ro`、PostgreSQL 的 `default_transaction_read_only`、MySQL 的 `SET SESSION TRANSACTION READ ONLY`）。
-### 插件会启动什么，以及带着什么
-- Python 服务用固定的解释器路径、固定脚本、固定参数启动，**从不经过 shell**，所以任何字符串都不会被 `cmd.exe` 或 `/bin/sh` 再解析一次。
-- 子进程**不继承** Host 的环境变量。它只拿到一张很短的允许清单（`PATH`、`TEMP`、`HOME`、`PYTHON*` 之类）再加上插件自己设置的 `DB_MCP_*`。DSH 进程里的 token、云凭据不会被带下去。
-- PostgreSQL / MySQL / Oracle 都由这个子进程连接，只有 SQLite 是在进程内读的。裸 TCP 探测只是子进程起不来时的兜底，且不发任何凭据。
-- 口令存在 `secrets.json`（`0600`），任何 HTTP 接口都不会返回它；面板只知道 `hasSecret`。
+## 智能体拿到的工具
+| 工具 | 作用 |
+| ---- | ---- |
+| `mcp__db__list_datasources` | 已登记的数据源：id、类型、目标、是否只读 |
+| `mcp__db__list_tables` | 某个源里的表与视图 |
+| `mcp__db__describe_table` | 列、类型、可空、主键 |
+| `mcp__db__sample_rows` | 取几行样本 |
+| `mcp__db__run_query` | 执行一条语句 |
+| `mcp__db__explain_query` | 执行计划 |
+| `mcp__db__get_ddl` | `CREATE TABLE` 语句 |
+| `mcp__db__test_connection` | 真实登录 + `select 1`，回报服务器/用户/schema |
-## 审计日志
+`datasource` 在所有工具里都是可选的，省略就用默认数据源。查询发生在**对话里**，面板只负责管理连接，不是 SQL 控制台。
-每次 MCP 工具调用都会向 `<运行时目录>/logs/audit.jsonl`（0600）追加一行 JSON：时间、工具、数据源、耗时、行数、截断到 2000 字符的 SQL，以及失败时的错误。结果行永不记录。文件超过 512 KiB 轮转为 `audit.1.jsonl`，也可以在 `settings.json` 里用 `auditLog: false` 关掉。面板显示最近十几条，时间按**本机时区**换算——文件里存的是 UTC，这样换机器也仍然可比；卡片会把每条时间戳转成浏览者的时区，并标出所用偏移。
+## 安全
-`dev/shims.test.mjs` 还断言 `package.json` 不带 UTF-8 BOM：Host 用 `JSON.parse` 读它，而 `JSON.parse` 会拒绝 BOM，插件随之显示为 `availability: missing`，并不加载。会「添加 BOM」的编辑器会静默弄坏 bundle——如果重启后侧边栏入口消失，先查这一项。
+- **默认只读**，两道互相独立的闸门：全局写开关 + 单源标记，两者都打开才允许写入。
+- **口令不出本机。** 存在 `secrets.json`（`0600`）；任何 HTTP 接口都不返回它，Python 子进程拿到的也只是很短的环境变量白名单，而不是整个 DSH 环境。
+- **每次工具调用都有审计**，写入 `logs/audit.jsonl`——工具、数据源、耗时、行数、SQL；结果行永不记录。
+- **面板不会执行 SQL。** 结构浏览只转发 `list_tables` 与 `describe_table`。
-## 阶段表
+## 文档
-| 阶段 | 内容 |
+| 文档 | 内容 |
 | ---- | ---- |
-| P1 | 可安装的骨架：侧边栏入口、空面板、Host 健康接口（已完成） |
-| P2 | 数据源 CRUD、连接测试、DBeaver 导入（已完成） |
-| P3 | Python MCP 服务，工具以 `mcp__db__*` 发布（已完成） |
-| P4 | PostgreSQL / MySQL / Oracle 方言（已完成） |
-| P5 | 诊断、一键 venv、热重载、审计日志、全局写开关（已完成） |
-| P6 | 多语言打磨与文档（已完成） |
-| P7 | 只读结构概览、分组、批量操作（已完成） |
+| [docs/guide.md](docs/guide.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）与决策记录（英文） |
 ## 许可
 Apache License 2.0 —— 见 [LICENSE](LICENSE)。
-## 运行时目录
-```
-$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
-```

package/docs/{requirements.md → design-notes.md} RENAMED Viewed

@@ -1,3 +1,8 @@
+> **Design log.** The working record of the design and the P1 → P7 build, written in
+> Chinese as the project ran. It is kept for the decisions and the edge cases behind
+> them, not as user documentation: start at [../README.md](../README.md), or
+> [guide.md](guide.md) for usage and [reference.md](reference.md) for the wire format.
 # DSH 数据库插件（暂名 `dsh-db-mcp`）需求细化 v0.2
 > 状态：需求已按你的选择定稿，代码尚未开始

package/docs/development.md ADDED Viewed

@@ -0,0 +1,99 @@
+# Development
+How the repository is put together, how to iterate on it without restarting DSH
+every time, and how a release happens.
+## Layout
+```
+index.js            Cordis entry: routes only, plus the cache-busting import of src/host.js
+src/host.js         Host half: registry, DBeaver import, probes, settings, audit, MCP bridge wiring
+src/mcp.js          minimal MCP client over stdio (newline-delimited JSON-RPC)
+src/tools.js        spawns the Python server, publishes its tools on the host tools service
+client.js           browser half: sidebar entry + panel (React, theme tokens only)
+locale/{en,zh}.json package metadata (title/description) shown by the plugin card
+server/main.py      FastMCP server: eight tools
+server/engines.py   per-engine connect / introspect / query / DDL
+server/store.py     reads the registry written by the Host
+cordis.patch.yml    one Loader row with id "db-mcp"
+dev/                test suites and the version bump script
+docs/               this documentation
+```
+The package ships `index.js`, `src/*.js`, `client.js`, `locale/*.json`, `icon.svg`,
+`cordis.patch.yml`, `server/*.py`, `server/requirements.txt`, `docs/*.md`, both
+READMEs and the license.
+## Hot reload
+The Cordis Loader imports a plugin entry **once per process**, so editing
+`index.js` needs a DSH restart. Everything else is deliberately reloadable:
+- `index.js` only registers two routes and imports `./src/host.js?v=<n>`, so
+  `POST /plugins/db-mcp/api/reload` re-imports the whole Host half.
+- `src/host.js` and `src/tools.js` propagate the same generation string to their own
+  imports (`new URL(import.meta.url).searchParams.get('v')`), otherwise Node's module
+  cache would keep returning the old copies of the inner files.
+- The Python server is a child process: `POST /mcp/restart` (or the **Restart MCP**
+  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.
+## Tests
+```sh
+npm test              # everything below except mcp.test.mjs
+npm run test:ci       # the portable subset the publish workflow runs
+npm run test:mcp      # real Python server, real SQLite; Oracle when its container is up
+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/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) |
+| `dev/render.test.mjs` | components rendered with a stub React: tab bar, form fields, list, bulk bar, breadcrumbs |
+| `dev/i18n.test.mjs` | en/zh key parity, no dead keys, no stray copy outside the dictionaries |
+| `dev/p5.test.mjs` | settings, audit rotation, Python environment discovery |
+| `dev/mcp.test.mjs` | real stdio handshake, all eight tools, read-only refusal, login failures |
+Suites that need external services skip rather than fail: `mcp.test.mjs` probes the
+Oracle port and prints `skip … is not listening` when the container is down.
+## Releasing
+The package publishes from GitHub Actions with
+[npm trusted publishing](https://docs.npmjs.com/trusted-publishers):
+`.github/workflows/publish.yml` trades the workflow's OIDC token for a short-lived
+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"
+git push origin main
+git tag v0.6.10 && git push origin v0.6.10
+```
+The workflow refuses to publish when the tag and `package.json` disagree, runs
+`npm run test:ci`, publishes with `--provenance`, then polls the registry until the
+version appears. Local `npm publish` still works for the very first release, before
+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.
+## Adding an engine
+1. `server/engines.py`: extend `connect()` and the dialect tables (`_quote`,
+   `_limit_clause`, `list_tables`, `describe_table`, `table_ddl`).
+2. `src/host.js`: add the kind to `KINDS`, give it a default port, a validation
+   branch in `normalizeInput`, and a `describeTarget` label.
+3. `client.js`: add the string to `KINDS` and, if the form needs extra fields, to
+   `SourceForm`; extend `parseConnectionText` with the scheme and JDBC prefix.
+4. `server/requirements.txt`: the driver, and `docs/reference.md`: the field table.
+5. Tests: `dev/parse.test.mjs` for the string, `dev/selftest.mjs` for validation and
+   the probe, and a demo container in `docs/guide.md`.

package/docs/guide.md ADDED Viewed

@@ -0,0 +1,223 @@
+# 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
+```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)
+```
+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
+```
+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.
+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; re-apply with `plugin_manager set_bundle` |
+| 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 ADDED Viewed

@@ -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 }` |
+| `run_query` | `sql`, `datasource?`, `max_rows?` | `{ columns, rows, rowCount, truncated, elapsedMs }` |
+| `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__run_query","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 CHANGED Viewed

@@ -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.6.10",
+  "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/src/host.js CHANGED Viewed

@@ -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.6.10'
 const SCHEMA_VERSION = 1
 const REGISTRY_FILE = 'datasources.json'
 const SECRETS_FILE = 'secrets.json'