@shibbirweb/mcp-db-read-only 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -6,9 +6,29 @@ Each release is published to npm and Docker Hub from the same tag. Where a versi
 
 ## [Unreleased]
 
+## [1.0.0]
+
+First stable release. Not yet published to npm, Docker Hub or the MCP Registry.
+
+### Added
+
+- `mcp-db-read-only viewer --dir <folder> --port <port>`: the live log viewer as its own process, reading a `DB_LOG_DIR` folder, with no MCP server or database. Run it in a terminal so the servers an MCP client starts only write logs and never hold a port. It exits with a clear error when the port is taken.
+
+## [0.2.0]
+
+Not yet published to npm, Docker Hub or the MCP Registry.
+
+### Added
+
+- Optional call logging (`DB_LOG`, `DB_LOG_FILE`, `DB_LOG_FORMAT`): every tool call with its input, each statement sent to the database, and the full output, in a readable boxed format or as JSON lines. Credentials are always redacted, and a logging failure never fails a call.
+- A permanent log folder (`DB_LOG_DIR`): every entry saved as its own pretty JSON file, in a folder per day, never deleted, shared safely by every copy of the server.
+- A live log viewer in the browser (`DB_LOG_PORT`, `DB_LOG_HISTORY`): paginated, 20 per page by default with 10, 20, 30 or 50 to choose from; filters across everything logged; a copy icon on every block; and live updates as each call finishes. With a log folder it shows every copy's calls, across restarts. Off unless a port is set; it has no access control and listens on all interfaces.
+- The viewer binds its port on the first tool call, so the copy of the server actually in use gets it. A busy port is explained once in the chat, naming the process holding it, and retried on every call.
+- `current_connection` reports the viewer's state.
+
 ## [0.1.0]
 
-First release. Not yet published to npm, Docker Hub or the MCP Registry.
+First version. Never published to npm, Docker Hub or the MCP Registry.
 
 ### Added
 

package/README.dockerhub.md

@@ -2,12 +2,8 @@
   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.
+  Docker Hub does not resolve relative links, so every link here is absolute.
+  Keep it in sync with README.md: the same content, plus the tags list below.
 -->
 
 # mcp-db-read-only
@@ -15,339 +11,342 @@
 [![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)
 
+Let your AI assistant **look at your databases without being able to change them.**
+
+Point it at MySQL, PostgreSQL, SQLite, SQL Server, ClickHouse, MongoDB, Redis or Elasticsearch, then just ask questions in plain words: *"how many users signed up this week?"*, *"what's in the orders table?"*, *"which Redis keys hold sessions?"*. It can read anything you give it access to, and it cannot write, update or delete anything.
+
+- **Every popular database, one server.** Switch between them in the middle of a conversation.
+- **Read-only, twice over.** Every query is checked before it is sent, and the database itself is also told to refuse writes.
+- **No restart to switch.** Change database, server or engine by asking.
+- **Optional logging**, with a live page in your browser that shows every query as it happens.
+
+Works with Claude Desktop, Claude Code, and any other [MCP](https://modelcontextprotocol.io) client.
+
 **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**.
+## Supported tags
 
-| 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` |
+`1.0.0`, `1.0`, `1`, `latest`, built for `linux/amd64` and `linux/arm64`.
 
-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.
+## Quick start
 
-```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` )
+**1. Have Node.js 22.13 or newer** (`node --version`), or Docker.
+
+**2. Add the server to your client.** For Claude Desktop, edit `claude_desktop_config.json` (Settings, Developer, Edit Config). For Claude Code, create `.mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "databases": {
+      "command": "npx",
+      "args": ["-y", "@shibbirweb/mcp-db-read-only"],
+      "env": {
+        "DB_URL": "postgres://readonly:secret@localhost:5432/myapp"
+      }
+    }
+  }
+}
 ```
 
-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.
+Replace the `DB_URL` with your own database. The examples below show one for every kind.
 
----
+**3. Restart the client once, and ask away:**
 
-## Supported tags
+> "What tables are in my database?"
+> "Show me the 5 newest orders."
+> "How many customers are in each country?"
 
-`0.1.0`, `0.1`, `0`, `latest`, built for `linux/amd64` and `linux/arm64`.
+That's it. You never need to restart again to change database; just ask the assistant to switch.
 
 ---
 
-## Quick start
+## Examples for each database
 
-### npm
+Each database has a URL **format**, then a real **example** to copy and change. Put the finished URL in `DB_URL`.
 
-```bash
-DB_URL='postgres://readonly:secret@127.0.0.1:5432/my_database' npx -y @shibbirweb/mcp-db-read-only
-```
+Replace each `[PLACEHOLDER]` with your own value:
+
+| Placeholder | What to put there |
+| --- | --- |
+| `[USER]` | The database user name |
+| `[PASSWORD]` | That user's password |
+| `[HOST]` | The server's address, e.g. `localhost` or `db.example.com` |
+| `[PORT]` | The server's port. Optional: leave out `:[PORT]` to use the usual one shown for each database |
+| `[DATABASE]` | The database name. Optional for most: leave it out and ask the assistant to list them |
 
-Requires Node 22.13 or newer. There is no container in the way, so `127.0.0.1` means what you expect.
+No password? Leave out `:[PASSWORD]`. No user either? Leave out `[USER]:[PASSWORD]@` entirely.
 
-### Docker
+### MySQL and MariaDB
 
-```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
+Format (usual port 3306):
+
+```text
+mysql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
+mariadb://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
 ```
 
-Use `host.docker.internal` to reach a database on the same machine as Docker. Inside the container, `localhost` means the container itself.
+Example:
 
-For SQLite in Docker, mount the file's directory read-only and point at the path inside the container:
+```text
+mysql://readonly:secret@localhost:3306/shop
+```
 
-```bash
-docker run -i --rm -v "$PWD/data:/data:ro" -e DB_URL='sqlite:///data/app.db' shibbirweb/mcp-db-read-only
+> "List the tables in shop." · "Describe the orders table." · "What were last month's top 10 products by revenue?"
+
+### PostgreSQL
+
+Format (usual port 5432). Add `?sslmode=require` to use TLS:
+
+```text
+postgres://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
 ```
 
-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.
+Example:
 
-### Claude Desktop
+```text
+postgres://readonly:secret@localhost:5432/myapp
+```
 
-Add to `claude_desktop_config.json`:
+> "Which tables are in the reporting schema?" · "Show the foreign keys on invoices." · "Count signups per day this week."
 
-```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"
-      }
-    }
-  }
-}
+### SQLite
+
+Format (three slashes, then the full path to the file):
+
+```text
+sqlite:///[PATH_TO_FILE]
 ```
 
-Or the same server in Docker:
+Example:
 
-```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"
-      ]
-    }
-  }
-}
+```text
+sqlite:///Users/me/data/app.db
 ```
 
-### Claude Code
+The file is opened read-only.
 
-The same shape, in `.mcp.json` at your project root. Either form above works.
+> "What tables does this file have?" · "Show 10 rows from notes."
 
-Restart the client once. After that you never need to restart it to change database.
+### SQL Server (and Azure SQL)
 
-> 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).
+Format (usual port 1433). Add `?trustServerCertificate=true` for a local server with a self-signed certificate:
 
-### Coming from mcp-mysql-read-only
+```text
+mssql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
+```
 
-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.
+Example:
 
----
+```text
+mssql://readonly:secret@localhost:1433/Sales?trustServerCertificate=true
+```
 
-## Switching connections
+> "List the tables in Sales." · "Show the top 5 customers by order total." (SQL Server uses `TOP 5`, not `LIMIT`; the assistant knows.)
 
-Just ask. These map onto the connection tools:
+### ClickHouse
 
-> "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"
+Format (usual port 8123, or 8443 with `clickhouse+https`):
 
-| 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
+clickhouse://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
+clickhouse+https://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
+```
+
+Example:
 
 ```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 ------------|
+clickhouse://reader:secret@localhost:8123/analytics
 ```
 
-A switch that fails verification is never committed, so the previous connection stays active and the session keeps working.
+> "How many events per hour did we have yesterday?" · "What is the sorting key of the events table?"
 
-### Named profiles
+### MongoDB
 
-Define several connections up front with `DB_PROFILES`, a JSON object whose values are URLs, or objects with a separate password:
+Format (usual port 27017). Use `mongodb+srv` for MongoDB Atlas, with no port:
 
-```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"
-}
+```text
+mongodb://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]?authSource=admin
+mongodb+srv://[USER]:[PASSWORD]@[CLUSTER_HOST]/[DATABASE]
 ```
 
-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.
+Example:
 
-### Reaching somewhere not in the profiles
+```text
+mongodb://reader:secret@localhost:27017/myapp?authSource=admin
+```
 
-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.
+> "What collections are in myapp?" · "What fields do documents in users have?" · "Find the 5 most recent orders over 100." · "Count users by country."
 
-### URL details
+### Redis (and Valkey, KeyDB)
 
-| 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 |
+Format (usual port 6379). `[DB_NUMBER]` is the database number, 0 if left out; `rediss` means TLS:
 
----
+```text
+redis://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NUMBER]
+rediss://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NUMBER]
+```
 
-## Tools
+Example:
 
-### Connection
+```text
+redis://localhost:6379/0
+```
 
-| 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` |
+> "Which keys start with session:?" · "What's inside user:42?" · "How long until cache:home expires?"
 
-### Browsing, on every engine
+### Elasticsearch and OpenSearch
 
-| 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 |
+Format (usual port 9200, no database). Add `+https` for TLS, or `?api_key=[API_KEY]` instead of a user and password:
 
-`list_tables` takes an optional glob `pattern`, such as `user*`, which is how you browse a Redis instance with millions of keys.
+```text
+elasticsearch://[USER]:[PASSWORD]@[HOST]:[PORT]
+opensearch://[USER]:[PASSWORD]@[HOST]:[PORT]
+```
 
-### Querying, per engine family
+Example:
 
-| 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 |
+```text
+elasticsearch+https://elastic:secret@search.example.com:9200
+```
 
-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.
+> "What indices do we have?" · "Find error logs from the last hour." · "How many documents are in logs-2026.09?"
 
-Every reading tool also accepts an optional `database`, applied to that call only, leaving the active connection alone.
+Detailed notes for every database, including how to create a read-only account, are in the [Databases guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Databases).
 
 ---
 
-## Configuration
+## Using several databases
 
-| 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 |
+Give each one a name with `DB_PROFILES`, and switch by asking ("switch to legacy", "use the cache"):
+
+```json
+"env": {
+  "DB_PROFILES": "{\"app\": \"postgres://readonly@localhost/app\", \"legacy\": \"mysql://readonly@localhost/shop\", \"cache\": \"redis://localhost:6379/0\"}",
+  "DB_DEFAULT_PROFILE": "app"
+}
+```
 
-None of these are required: with no configuration at all the server still starts, and the tools tell you to call `connect`.
+You can also connect to a database you didn't list, mid-conversation: *"connect to postgres://readonly@10.0.0.5/reports"*.
 
-Starting profile: `DB_DEFAULT_PROFILE` (or `MYSQL_DEFAULT_PROFILE`) if it names a real profile, else `default`, else the first one defined.
+**Password with special characters** (`@`, `/`, `#`)? Give it separately instead of inside the URL: `DB_PASSWORD` next to `DB_URL`, or `{"url": "...", "password": "..."}` inside `DB_PROFILES`.
 
 ---
 
-## Security
+## Running with Docker
 
-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.
+Nothing to install but Docker:
 
-| 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 |
+```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/myapp",
+        "shibbirweb/mcp-db-read-only"
+      ]
+    }
+  }
+}
+```
 
-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.
+Inside Docker, use `host.docker.internal` instead of `localhost` to reach a database on your own computer. For SQLite, mount the folder: add `"-v", "/Users/me/data:/data:ro"` and use `sqlite:///data/app.db`.
 
-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
+## Watching what the assistant does
 
-**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.
+Turn on logging to keep a record of every query the assistant runs, and see them live in your browser.
 
-**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:
+**1. Save logs to a folder** by adding this to the server's `env`:
 
-```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;
+```json
+"DB_LOG_DIR": "/Users/me/Library/Logs/mcp-db-read-only"
 ```
 
-```js
-// MongoDB
-db.createUser({ user: "reader", pwd: "...", roles: [{ role: "read", db: "app" }] });
-```
+Each query is saved as its own file, one folder per day. Nothing is ever deleted automatically.
 
-```text
-# Redis
-ACL SETUSER reader on >... ~* +@read -@dangerous
+**2. Open the viewer** in a terminal, whenever you want to watch:
+
+```bash
+npx -y @shibbirweb/mcp-db-read-only viewer --dir /Users/me/Library/Logs/mcp-db-read-only --port 4800
 ```
 
-Other limits worth knowing:
+Then open **http://127.0.0.1:4800/**. You'll see every call: what was asked, the exact query sent, how long it took, and the result. It updates live, shows 20 per page (10, 20, 30 or 50 to choose from), and lets you filter and copy anything. Press Ctrl+C to close it.
+
+> The viewer has no password. Anyone who can reach that port on your network can read the log while it runs.
+
+Passwords are never written to the logs. More in the [Logging guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Logging-and-Viewer).
+
+---
+
+## Is it really read-only?
+
+Yes, in two independent ways, so a mistake in one is caught by the other:
+
+1. **Before anything is sent**, every query is checked. Only reads are allowed: `SELECT` and friends for SQL, read commands for Redis, searches for Elasticsearch, and no `$out` or `$merge` for MongoDB.
+2. **The database is told to refuse writes too**, wherever it supports that: read-only sessions on MySQL, read-only transactions on PostgreSQL, a read-only file on SQLite, and so on.
 
-- 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.
+**The best protection is still a read-only database account.** Then nothing can write through it, whatever happens. The [Databases guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Databases) shows how to create one for each database.
+
+Keep in mind that the assistant **can read** whatever the account can see, and what it reads becomes part of your conversation with the AI provider. Only connect accounts that can see data you are happy to share. See [PRIVACY.md](https://github.com/shibbirweb/mcp-db-read-only/blob/master/PRIVACY.md).
 
 ---
 
-## Known behaviour
+## Settings
 
-**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.
+All optional. Set them in the server's `env`.
 
-**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.
+| Setting | What it does |
+| --- | --- |
+| `DB_URL` | The database to connect to at startup |
+| `DB_PASSWORD` | The password for `DB_URL`, if you'd rather keep it out of the URL |
+| `DB_PROFILES` | Several named databases, as JSON, to switch between |
+| `DB_DEFAULT_PROFILE` | Which of those to start with |
+| `DB_QUERY_TIMEOUT_MS` | Stop a query after this long (default 30000, that is 30 seconds) |
+| `DB_CONNECT_TIMEOUT_MS` | Give up connecting after this long (default 10000) |
+| `DB_LOG_DIR` | Save every call as a file in this folder |
+| `DB_LOG=true` | Write every call to the client's log instead |
+| `DB_LOG_FILE` | Write every call to one file instead |
+| `DB_LOG_FORMAT` | `pretty` (default) or `json`, for `DB_LOG` and `DB_LOG_FILE` |
+| `DB_LOG_PORT` | Run the viewer inside the server itself (the separate `viewer` command is usually better) |
+
+Coming from `mcp-mysql-read-only`? Its `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` and `MYSQL_PROFILES` settings still work as they are.
+
+Full details: [Configuration guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Configuration).
 
 ---
 
-## Development and contributing
+## Troubleshooting
+
+**"Can't connect" from Docker to a database on my computer.** Use `host.docker.internal` instead of `localhost`, and keep the `--add-host` line from the Docker example.
+
+**The server won't start with npx.** Check `node --version` is 22.13 or newer.
 
-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).
+**SQL Server says the certificate isn't trusted.** Add `?trustServerCertificate=true` to the URL for a local or development server.
 
-## Changelog
+**"No database selected".** Your URL has no database name. Add one (`.../myapp`), or ask the assistant to list the databases and pick one.
 
-Release history is in [CHANGELOG.md](https://github.com/shibbirweb/mcp-db-read-only/blob/master/CHANGELOG.md).
+**My password has `@` or `#` in it.** Use `DB_PASSWORD`, or the `{"url": ..., "password": ...}` form in `DB_PROFILES`.
+
+**The viewer says the port is in use.** Something else is using it. Close that, or pick another port with `--port 4801`.
+
+More answers in the [Troubleshooting guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Troubleshooting).
+
+---
 
-## Privacy
+## Learn more
 
-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.
+- [Wiki](https://github.com/shibbirweb/mcp-db-read-only/wiki): user guides for every feature, plus developer documentation
+- [CHANGELOG.md](https://github.com/shibbirweb/mcp-db-read-only/blob/master/CHANGELOG.md): what changed in each version
+- [PRIVACY.md](https://github.com/shibbirweb/mcp-db-read-only/blob/master/PRIVACY.md): what the server sends where (nothing, except to your databases)
+- Contributing: pull requests to `master` are welcome. `./scripts/test-in-docker.sh` runs the full test suite against every database in throwaway containers; see [Testing](https://github.com/shibbirweb/mcp-db-read-only/wiki/Testing). If you change this README, change [README.dockerhub.md](https://github.com/shibbirweb/mcp-db-read-only/blob/master/README.dockerhub.md) to match.
 
 ## License