dbmastermind-mcp 0.0.0-stage → 1.5.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Václav Mudra and DB Mastermind contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,129 @@
1
- # Temporary Holding Version
1
+ # dbmastermind-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An MCP server that lets AI agents (Claude Code, Codex, Cursor, Claude Desktop, VS Code and others) explore and
4
+ query your databases, read-only unless you allow writes. The package also installs `dbm`, a command line for
5
+ scripts and CI.
6
+
7
+ **PostgreSQL · SQL Server · Oracle · MySQL · MariaDB · SQLite · DuckDB · ClickHouse · BigQuery · Trino ·
8
+ CockroachDB.** Hosted services that run one of these engines work the same way (Supabase, Neon, Amazon RDS,
9
+ Azure SQL, Google Cloud SQL and others).
10
+
11
+ Needs Node.js 22.16 or newer. Free and open source (MIT).
12
+
13
+ ## Quick start
14
+
15
+ Claude Code:
16
+
17
+ ```bash
18
+ claude mcp add shop -- npx -y dbmastermind-mcp --url 'postgres://me:${PGPASSWORD}@localhost:5432/shop'
19
+ ```
20
+
21
+ Codex (`~/.codex/config.toml`):
22
+
23
+ ```toml
24
+ [mcp_servers.shop]
25
+ command = "npx"
26
+ args = ["-y", "dbmastermind-mcp", "--url", "jdbc:sqlserver://sql01:1433;databaseName=Sales;user=report;password=${SQL_PASSWORD};trustServerCertificate=true"]
27
+ ```
28
+
29
+ Claude Desktop, Cursor, Windsurf, Gemini CLI and other clients with a JSON config:
30
+
31
+ ```json
32
+ {
33
+ "mcpServers": {
34
+ "shop": {
35
+ "command": "npx",
36
+ "args": ["-y", "dbmastermind-mcp", "--url", "sqlite:///Users/me/data/shop.db"]
37
+ }
38
+ }
39
+ }
40
+ ```
41
+
42
+ VS Code uses the key `servers` instead of `mcpServers`.
43
+
44
+ `${NAME}` in a URL or a `--config` file is replaced with the environment variable `NAME` when the server starts, so
45
+ passwords don't have to be written into the agent's configuration. In a shell, keep such a URL in single quotes (or
46
+ the shell replaces it first), and make sure the agent passes the variable to the servers it starts; most clients take
47
+ an `env` entry next to `command` and `args`.
48
+
49
+ ## Connection URLs
50
+
51
+ | Database | `--url` |
52
+ |---|---|
53
+ | PostgreSQL, CockroachDB | `postgres://user:password@host:5432/db?sslmode=require` |
54
+ | SQL Server | `sqlserver://user:password@host:1433/db`, JDBC (`jdbc:sqlserver://host:1433;databaseName=db;user=…;password=…`) or ADO.NET (`Server=host,1433;Database=db;User Id=…;Password=…`) |
55
+ | Oracle | `oracle://user:password@host:1521/service` or `jdbc:oracle:thin:user/password@host:1521/service` |
56
+ | MySQL, MariaDB | `mysql://user:password@host:3306/db`, `mariadb://…` |
57
+ | SQLite | `sqlite:///path/to/file.db` |
58
+ | DuckDB | `duckdb:///path/to/file.duckdb`, or `duckdb://` for an in-memory database |
59
+ | ClickHouse | `clickhouse://user:password@host:8123/db` |
60
+ | Trino | `trino://user@host:8080/catalog/schema` |
61
+ | BigQuery | with `--config`: `{ "name": "bq", "driver": "bigquery", "database": "<project id>", "filePath": "<service account key.json>" }` (without `filePath`, Google's application default credentials) |
62
+
63
+ JDBC URLs (`jdbc:postgresql://…?user=…&password=…`) work as well.
64
+
65
+ ## What agents get
66
+
67
+ - **Schema**: `list_connections`, `list_tables`, `describe_table` (columns, keys, indexes, comments, incoming
68
+ references), `search_schema`, `get_relationships`, `find_join_path` (the shortest join chain, with ready SQL),
69
+ `get_definition` (the SQL of a view, function or procedure; a table's CREATE)
70
+ - **Data**: `sample_rows`, `run_query` (results as compact CSV), `explain_query` (the plan as a tree)
71
+ - **Knowledge base**: point `--knowledge` at a folder of Markdown notes about the database. Agents search and
72
+ read them (`search_knowledge`, `read_knowledge`), and relationships declared there
73
+ (`relations: ["orders.customer_code -> customers.code"]`) count as foreign keys. With
74
+ `--allow-knowledge-writes` they can also add notes (`write_knowledge`).
75
+ - **Prompts**: `explore_database`, `document_database`
76
+
77
+ **Read-only by default.** Without `--allow-writes`, statements run in a read-only transaction that is always rolled
78
+ back, so a function that writes or a statement that only looks like a SELECT can't change anything. With
79
+ `--read-only` the database session itself is read-only where the engine supports it. `--schema-only` never
80
+ returns table contents.
81
+
82
+ ## Options
83
+
84
+ | Flag | |
85
+ |---|---|
86
+ | `--url <url>` | A connection (see above). Repeat it for several databases. |
87
+ | `--name <name>` | Name for the preceding `--url` (default: host/database) |
88
+ | `--knowledge <dir>` | Knowledge base folder for the preceding `--url` |
89
+ | `--config <file>` | JSON array of connections: `name`, `url` or `driver`/`host`/`port`/`database`/`user`/`password`, `knowledgeBase`, `readOnly`, `files` |
90
+ | `--allow-files <path>` | DuckDB: a file or folder agents may read, for the preceding `--url` (repeatable; `"files": [...]` in `--config`). Without it only the database file is readable. |
91
+ | `--allow-writes` | Allow INSERT, UPDATE, DELETE and DDL |
92
+ | `--allow-knowledge-writes` | Let agents create knowledge base files |
93
+ | `--schema-only` | Never return table contents |
94
+ | `--read-only` | Mark every connection read-only (enforced by the database where supported) |
95
+
96
+ ## `dbm`: the command line
97
+
98
+ The same connections (`--url`, `--config`, `${ENV}` placeholders) for scripts and CI:
99
+
100
+ ```bash
101
+ npx -p dbmastermind-mcp dbm query --url "$DATABASE_URL" "SELECT * FROM orders WHERE created_at > now() - interval '1 day'" --format csv --out orders.csv
102
+ npx -p dbmastermind-mcp dbm dictionary --url "$DATABASE_URL" --format html --out docs/database.html
103
+ npx -p dbmastermind-mcp dbm check model.dbml # model checks; exit 1 when a table has problems
104
+ npx -p dbmastermind-mcp dbm diff model.dbml --url "$DATABASE_URL" # exit 2 and the migration when the database drifted
105
+ ```
106
+
107
+ `query` streams one SELECT of any size (csv, tsv, json, jsonl, markdown) and is read-only unless `--allow-writes`.
108
+ DuckDB reads other files only when they are allowed, and compares the path as written, so use absolute paths:
109
+
110
+ ```bash
111
+ npx -p dbmastermind-mcp dbm query --url duckdb:///data/shop.duckdb --allow-files /data/exports "SELECT count(*) FROM read_csv('/data/exports/*.csv')"
112
+ ```
113
+
114
+ `diff` never changes the database and keeps tables only the database has unless `--drop-extra`.
115
+ `npx -p dbmastermind-mcp dbm --help` lists everything.
116
+
117
+ ## The desktop app
118
+
119
+ This package is part of [DB Mastermind](https://dbmastermind.app), a free, open-source database client and data
120
+ modeler for Windows, macOS and Linux. The app can be the MCP server too, with your saved connections and the
121
+ passwords in your system keychain (Settings → MCP server), and there agents can also propose a new connection,
122
+ which you review and save in the app.
123
+
124
+ - Website: [dbmastermind.app](https://dbmastermind.app) · [Privacy](https://dbmastermind.app/privacy.html)
125
+ - Source and issues: [github.com/eLh0m3r0/db-mastermind](https://github.com/eLh0m3r0/db-mastermind)
126
+
127
+ ## License
128
+
129
+ MIT