@shibbirweb/mcp-db-read-only 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+Each release is published to npm and Docker Hub from the same tag. Where a version reaches one channel but not the other, the entry says so.
+
+## [Unreleased]
+
+## [0.1.0]
+
+First release. Not yet published to npm, Docker Hub or the MCP Registry.
+
+### Added
+
+- Read-only access to MySQL, MariaDB, PostgreSQL, SQLite, SQL Server, ClickHouse, MongoDB, Redis, Elasticsearch and OpenSearch from one server, with the connection, database and engine switchable mid-conversation.
+- Connections configured as URLs, through `DB_URL`, `DB_PROFILES` or the `connect` tool, with the password optionally given separately.
+- The configuration of `mcp-mysql-read-only` (`MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PROFILES` and the rest) is read unchanged, so the image or package can be swapped in place.
+- Browse tools that work on every engine: `list_tables` (with a glob `pattern`), `describe_table`, `get_table_indexes`, `get_foreign_keys`, `get_table_sample`.
+- Query tools per engine family: `run_query` for SQL, `find_documents`, `aggregate`, `count_documents` and `distinct_values` for MongoDB, `search` for Elasticsearch and OpenSearch, `redis_command` for Redis.
+- Two independent read-only layers on every engine, each proved by integration tests that send writes straight to the driver.
+- A dialect-aware SQL validator that lexes PostgreSQL dollar quotes and `E''` strings, SQL Server brackets and ClickHouse heredocs, scans every T-SQL statement for writes, and refuses constructs it cannot read with certainty, such as nested comments and MySQL executable comments.
+- SQLite runs in a separate process, so a query past the timeout is killed rather than freezing the server.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Md. Shibbir Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.dockerhub.md

@@ -0,0 +1,354 @@
+<!--
+  This file is the Docker Hub description, published by
+  .github/workflows/dockerhub-description.yml via `readme-filepath`.
+
+  It exists because Docker Hub does NOT render mermaid: a ```mermaid block
+  shows up as raw source. It also does not resolve relative links, so every
+  link here must be absolute.
+
+  Keep it in sync with README.md. Same content, with ASCII diagrams instead of
+  mermaid and the contributor sections reduced to pointers.
+-->
+
+# mcp-db-read-only
+
+[![CI](https://github.com/shibbirweb/mcp-db-read-only/actions/workflows/ci.yml/badge.svg)](https://github.com/shibbirweb/mcp-db-read-only/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40shibbirweb%2Fmcp-db-read-only?label=npm&color=cb3837)](https://www.npmjs.com/package/@shibbirweb/mcp-db-read-only)
+[![Docker Hub](https://img.shields.io/docker/v/shibbirweb/mcp-db-read-only?label=docker%20hub&sort=semver)](https://hub.docker.com/r/shibbirweb/mcp-db-read-only)
+[![Image size](https://img.shields.io/docker/image-size/shibbirweb/mcp-db-read-only/latest?style=flat&label=image%20size)](https://hub.docker.com/r/shibbirweb/mcp-db-read-only/tags)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/shibbirweb/mcp-db-read-only/blob/master/LICENSE)
+
+**Source and full documentation: [github.com/shibbirweb/mcp-db-read-only](https://github.com/shibbirweb/mcp-db-read-only)**
+
+An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant **read-only** access to your databases, whichever kind they are, and lets it **switch database, server, credentials and even engine mid-conversation without restarting the client**.
+
+| Engine | URL scheme | Queried with |
+| --- | --- | --- |
+| MySQL, MariaDB | `mysql://`, `mariadb://` | `run_query` (SQL) |
+| PostgreSQL (and wire-compatible) | `postgres://`, `postgresql://` | `run_query` (SQL) |
+| SQLite | `sqlite:///path/to/file.db` | `run_query` (SQL) |
+| SQL Server, Azure SQL | `mssql://`, `sqlserver://` | `run_query` (T-SQL) |
+| ClickHouse | `clickhouse://`, `clickhouse+https://` | `run_query` (SQL) |
+| MongoDB | `mongodb://`, `mongodb+srv://` | `find_documents`, `aggregate`, `count_documents`, `distinct_values` |
+| Redis (and Valkey, KeyDB) | `redis://`, `rediss://` | `redis_command` |
+| Elasticsearch, OpenSearch | `elasticsearch://`, `opensearch://`, `+https` variants | `search` |
+
+The browse tools (`list_tables`, `describe_table`, `get_table_sample`, ...) work on every engine, in that engine's terms: tables, collections, keys or indices.
+
+Runs from npm with `npx`, or entirely in Docker with nothing installed on your machine.
+
+```text
+                 +--------------------------------------+
+                 |            AI assistant              |
+                 |     Claude Desktop / Claude Code     |
+                 +------------------+-------------------+
+                                    |
+                             MCP over stdio
+                                    |
+                 +------------------v-------------------+
+                 |          mcp-db-read-only            |
+                 |    one container, whole session      |
+                 +------------------+-------------------+
+                                    |
+                       one driver per target
+                                    |
+      +-------------+-------------+-+-----------+-----------------+
+      |             |             |             |                 |
+      v             v             v             v                 v
+ ( PostgreSQL )  ( MySQL )   ( MongoDB )    ( Redis )     ( anything reached
+    app           legacy       events         cache         with `connect` )
+```
+
+The server lives for the whole session, so the active connection is just state inside it. Switching selects a different driver rather than reconnecting, and switching back reuses a warm one.
+
+---
+
+## Supported tags
+
+`0.1.0`, `0.1`, `0`, `latest`, built for `linux/amd64` and `linux/arm64`.
+
+---
+
+## Quick start
+
+### npm
+
+```bash
+DB_URL='postgres://readonly:secret@127.0.0.1:5432/my_database' npx -y @shibbirweb/mcp-db-read-only
+```
+
+Requires Node 22.13 or newer. There is no container in the way, so `127.0.0.1` means what you expect.
+
+### Docker
+
+```bash
+docker run -i --rm \
+  --add-host host.docker.internal:host-gateway \
+  -e DB_URL='postgres://readonly:secret@host.docker.internal:5432/my_database' \
+  shibbirweb/mcp-db-read-only
+```
+
+Use `host.docker.internal` to reach a database on the same machine as Docker. Inside the container, `localhost` means the container itself.
+
+For SQLite in Docker, mount the file's directory read-only and point at the path inside the container:
+
+```bash
+docker run -i --rm -v "$PWD/data:/data:ro" -e DB_URL='sqlite:///data/app.db' shibbirweb/mcp-db-read-only
+```
+
+The container is the more isolated of the two: the server runs with only what the image and the environment give it. Over npm it runs directly on your machine with your user's access. Both enforce the same read-only guarantees.
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "databases": {
+      "command": "npx",
+      "args": ["-y", "@shibbirweb/mcp-db-read-only"],
+      "env": {
+        "DB_PROFILES": "{\"app\": \"postgres://readonly@127.0.0.1/app\", \"cache\": \"redis://127.0.0.1:6379/0\"}",
+        "DB_DEFAULT_PROFILE": "app"
+      }
+    }
+  }
+}
+```
+
+Or the same server in Docker:
+
+```json
+{
+  "mcpServers": {
+    "databases": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "--add-host", "host.docker.internal:host-gateway",
+        "-e", "DB_URL=postgres://readonly:secret@host.docker.internal:5432/app",
+        "shibbirweb/mcp-db-read-only"
+      ]
+    }
+  }
+}
+```
+
+### Claude Code
+
+The same shape, in `.mcp.json` at your project root. Either form above works.
+
+Restart the client once. After that you never need to restart it to change database.
+
+> Credentials in these files sit on disk in plain text. Prefer read-only database accounts, and keep the file out of version control. See [Security](https://github.com/shibbirweb/mcp-db-read-only#security).
+
+### Coming from mcp-mysql-read-only
+
+This server reads the old `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE`, `MYSQL_PROFILES` and `MYSQL_DEFAULT_PROFILE` unchanged, so swapping the image or package name is enough. Tool names are the same too; the one change is that `connect` now takes a URL.
+
+---
+
+## Switching connections
+
+Just ask. These map onto the connection tools:
+
+> "switch to the staging database"
+> "what collections are in the events database?"
+> "connect to the Redis on 10.0.0.5 and show me the session keys"
+
+| Want | Restart? |
+| --- | --- |
+| Another database on the same server | No |
+| Another named profile, on any engine | No |
+| A different server, credentials or engine | No |
+| A new permanent profile in `DB_PROFILES` | Yes, once |
+
+```text
+ You          Assistant                 MCP server             PostgreSQL   MongoDB
+  | "signups?"    |                          |                      |          |
+  |-------------->| run_query(SELECT ...)    |                      |          |
+  |               |------------------------->| read-only transaction|          |
+  |               |                          |--------------------->|          |
+  |               |<-------------------------|<------ 4821 ---------|          |
+  | "opened app?" |                          |                               |
+  |-------------->| use_connection(events)   |   connect + ping              |
+  |               |------------------------->|------------------------------>|
+  |               |                          |  verified, switch committed   |
+  |               | count_documents(...)     |                               |
+  |               |------------------------->|------------------------------>|
+  |<-- 3907 ------|<-------------------------|<------------ 3907 ------------|
+```
+
+A switch that fails verification is never committed, so the previous connection stays active and the session keeps working.
+
+### Named profiles
+
+Define several connections up front with `DB_PROFILES`, a JSON object whose values are URLs, or objects with a separate password:
+
+```json
+{
+  "app":     "postgres://readonly@db.internal:5432/app",
+  "legacy":  "mysql://readonly@legacy.internal/shop",
+  "events":  { "url": "mongodb://reader@mongo.internal/events", "password": "p@ss/w#rd" },
+  "cache":   "redis://cache.internal:6379/0",
+  "logs":    "elasticsearch+https://reader@logs.internal:9200",
+  "reports": "sqlite:///data/reports.db"
+}
+```
+
+The object form exists because a password inside a URL must be percent-encoded, and one containing `@`, `/` or `#` otherwise splits the URL in the wrong place. A profile that fails to parse is skipped with a warning rather than taking the server down.
+
+### Reaching somewhere not in the profiles
+
+The `connect` tool takes a URL (and optionally a separate password) at runtime and keeps it for the rest of the session under an alias. Nothing is written to disk, and no restart is involved.
+
+### URL details
+
+| Engine | Notes |
+| --- | --- |
+| MySQL | `?ssl=true` requires TLS; `?ssl-mode=VERIFY_IDENTITY` also checks the certificate |
+| PostgreSQL | `?sslmode=require`, `verify-ca` or `verify-full`, as in libpq |
+| SQLite | `sqlite:///absolute/path.db`; a relative path is resolved once, at startup |
+| SQL Server | Encrypted by default. `?trustServerCertificate=true` for self-signed development servers; `?applicationIntent=ReadOnly` routes to a readable secondary |
+| ClickHouse | The HTTP interface: port 8123, or 8443 with `clickhouse+https` |
+| MongoDB | Replica sets as `mongodb://a:27017,b:27017/db?replicaSet=rs0`; any driver option passes through the query string |
+| Redis | The path is the database number: `redis://host:6379/3` |
+| Elasticsearch | `?api_key=...` authenticates with an API key; it is treated as a secret and never displayed |
+
+---
+
+## Tools
+
+### Connection
+
+| Tool | Purpose |
+| --- | --- |
+| `current_connection` | Which engine, server and database is active |
+| `list_connections` | Available profiles and their engines, `*` marks the active one |
+| `list_databases` | Databases on the connected server |
+| `use_database` | Switch database on the current server |
+| `use_connection` | Switch to a named profile, optional `database` override |
+| `connect` | Open any server from a URL, optional `alias` |
+
+### Browsing, on every engine
+
+| Tool | SQL engines | MongoDB | Redis | Elasticsearch |
+| --- | --- | --- | --- | --- |
+| `list_tables` | tables and views | collections | keys, by SCAN | indices |
+| `describe_table` | columns | fields inferred from 100 sampled documents | type, TTL, length | mapping |
+| `get_table_indexes` | indexes | indexes | n/a | n/a |
+| `get_foreign_keys` | foreign keys (not ClickHouse) | n/a | n/a | n/a |
+| `get_table_sample` | up to 50 rows | up to 50 documents | the start of the value | up to 50 hits |
+
+`list_tables` takes an optional glob `pattern`, such as `user*`, which is how you browse a Redis instance with millions of keys.
+
+### Querying, per engine family
+
+| Tool | Engine | Accepts |
+| --- | --- | --- |
+| `run_query` | SQL engines | One read-only statement in the engine's own dialect |
+| `find_documents` | MongoDB | Filter, projection, sort, limit and skip, as Extended JSON |
+| `aggregate` | MongoDB | A pipeline, without `$out` or `$merge` |
+| `count_documents` | MongoDB | A filter |
+| `distinct_values` | MongoDB | A field and an optional filter |
+| `search` | Elasticsearch, OpenSearch | A Query DSL body; `size: 0` with `track_total_hits` counts |
+| `redis_command` | Redis | One read-only command and its arguments |
+
+Every tool is advertised all the time, since MCP fixes the tool list at startup while the active engine can change. Calling one against the wrong engine says which tools fit instead.
+
+Every reading tool also accepts an optional `database`, applied to that call only, leaving the active connection alone.
+
+---
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `DB_URL` | none | One connection, registered as the profile `default` |
+| `DB_PASSWORD` | none | Password for `DB_URL`, so it need not be encoded into the URL |
+| `DB_PROFILES` | none | JSON object of named profiles |
+| `DB_DEFAULT_PROFILE` | none | Which profile starts active |
+| `DB_QUERY_TIMEOUT_MS` | `30000` | Statement timeout, enforced by each server where it can be |
+| `DB_CONNECT_TIMEOUT_MS` | `10000` | Connection timeout |
+| `MYSQL_*` | | The legacy MySQL-only variables, read unchanged. See above |
+
+None of these are required: with no configuration at all the server still starts, and the tools tell you to call `connect`.
+
+Starting profile: `DB_DEFAULT_PROFILE` (or `MYSQL_DEFAULT_PROFILE`) if it names a real profile, else `default`, else the first one defined.
+
+---
+
+## Security
+
+Every engine is kept read-only by **two independent layers**, so a hole in one is not automatically a write. The first layer runs before any connection is used; the second is enforced by the database server itself wherever the engine offers a way, and structurally where it does not.
+
+| Engine | Layer one, in this server | Layer two |
+| --- | --- | --- |
+| MySQL, MariaDB | SQL validator | `SET SESSION TRANSACTION READ ONLY` on every connection; the driver cannot send a second statement |
+| PostgreSQL | SQL validator, dialect-aware (dollar quotes, `E''` strings) | Every statement runs in a `READ ONLY` transaction that is always rolled back; extended query protocol, one statement only |
+| SQLite | SQL validator | The file is opened read-only by SQLite; extensions disabled |
+| SQL Server | SQL validator, scanning every statement since T-SQL needs no separators | Every batch runs in a transaction that is always rolled back |
+| ClickHouse | SQL validator, refusing table functions that reach outside the server | ClickHouse's own `readonly` setting on every query |
+| MongoDB | Operator denylist: `$out`, `$merge`, `$function`, `$where` anywhere | Stage allowlist in the driver, which only ever calls read operations |
+| Redis | Command allowlist | The server's own `COMMAND INFO` flags: a command is sent only if Redis itself calls it read-only |
+| Elasticsearch | Search body allowlist; index names cannot address an API | The driver can only reach fixed read endpoints |
+
+The SQL validator lexes each dialect exactly as the server will: string literals, quoted identifiers and comments are blanked before any rule looks at the statement, so a keyword or semicolon inside a literal is never mistaken for SQL. Constructs it cannot be certain the server reads the same way, such as nested block comments or MySQL's executable `/*! */` comments, are refused rather than guessed at. Only the dialect's read statements may lead (`SELECT`, `WITH`, and `SHOW`, `DESCRIBE` or `EXPLAIN` where they exist). Functions that write files, reach other servers or run SQL hidden in a string (`INTO OUTFILE`, `lo_export`, `dblink`, `OPENROWSET`, ClickHouse's `url()` and `file()`) are blocked.
+
+Integration tests prove layer two separately: they send writes straight to each driver, bypassing every validator, and assert the server refused or undid them.
+
+### What this is not
+
+**This is a guard, not a permission system.** It stops an assistant from writing through *this* server. It does not stop anyone holding the same credentials from writing through any other client.
+
+**Point it at read-only accounts.** This is the real protection, and on MongoDB and Elasticsearch, whose servers have no read-only session mode, it is the only server-side one:
+
+```sql
+-- MySQL
+CREATE USER 'readonly'@'%' IDENTIFIED BY '...'; GRANT SELECT ON app.* TO 'readonly'@'%';
+-- PostgreSQL
+CREATE ROLE readonly LOGIN PASSWORD '...'; GRANT pg_read_all_data TO readonly;
+```
+
+```js
+// MongoDB
+db.createUser({ user: "reader", pwd: "...", roles: [{ role: "read", db: "app" }] });
+```
+
+```text
+# Redis
+ACL SETUSER reader on >... ~* +@read -@dangerous
+```
+
+Other limits worth knowing:
+
+- Results are truncated to 100 rows in the tool output. Add a `LIMIT` (or `$limit`) when reading large tables.
+- A column named exactly like a write keyword must be quoted where the validator scans for them: inside `WITH` queries, and in every SQL Server statement.
+- SQLite queries run in a separate process, so one that exceeds the timeout can be killed outright.
+
+---
+
+## Known behaviour
+
+**Parallel tool calls.** The active connection is a single piece of process state. If a client issues several tool calls in one batch they are handled concurrently, so a `use_database` batched alongside a query is not guaranteed to land first. When a read must be pinned to a particular database, pass the per-call `database` argument instead.
+
+**Shutdown.** The server exits on `SIGINT`/`SIGTERM`, not when stdin closes. Open sockets keep the event loop alive, and stdin reaching EOF only means no further requests were buffered.
+
+---
+
+## Development and contributing
+
+Building, testing against every engine in throwaway containers, the project structure and the contribution guide are in the [repository README](https://github.com/shibbirweb/mcp-db-read-only#development) and the [wiki](https://github.com/shibbirweb/mcp-db-read-only/wiki).
+
+## Changelog
+
+Release history is in [CHANGELOG.md](https://github.com/shibbirweb/mcp-db-read-only/blob/master/CHANGELOG.md).
+
+## Privacy
+
+The server sends nothing anywhere except to the databases you point it at: no telemetry, no analytics, nothing written to disk, nothing kept after it exits. What does leave your machine is whatever your assistant reads, since query results become conversation content. [PRIVACY.md](https://github.com/shibbirweb/mcp-db-read-only/blob/master/PRIVACY.md) sets out both halves.
+
+## License
+
+[MIT](https://github.com/shibbirweb/mcp-db-read-only/blob/master/LICENSE) © Md. Shibbir Ahmed