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

package/CHANGELOG.md

@@ -6,9 +6,21 @@ Each release is published to npm and Docker Hub from the same tag. Where a versi
 
 ## [Unreleased]
 
+## [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

@@ -65,7 +65,7 @@ The server lives for the whole session, so the active connection is just state i
 
 ## Supported tags
 
-`0.1.0`, `0.1`, `0`, `latest`, built for `linux/amd64` and `linux/arm64`.
+`0.2.0`, `0.2`, `0`, `latest`, built for `linux/amd64` and `linux/arm64`.
 
 ---
 
@@ -271,6 +271,12 @@ Every reading tool also accepts an optional `database`, applied to that call onl
 | `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 |
+| `DB_LOG` | off | `true` logs every tool call to stderr. See [Call logging](https://github.com/shibbirweb/mcp-db-read-only#call-logging) |
+| `DB_LOG_FILE` | none | Log every tool call to this file instead |
+| `DB_LOG_DIR` | none | Save every tool call as its own JSON file in this folder, permanently |
+| `DB_LOG_FORMAT` | `pretty` | `pretty` or `json` |
+| `DB_LOG_PORT` | none | Serve a live log viewer in the browser on this port |
+| `DB_LOG_HISTORY` | `500` | Entries the viewer keeps in memory when there is no `DB_LOG_DIR` |
 | `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`.
@@ -279,6 +285,77 @@ Starting profile: `DB_DEFAULT_PROFILE` (or `MYSQL_DEFAULT_PROFILE`) if it names
 
 ---
 
+## Call logging
+
+Off by default. Turn it on to see every tool call the assistant makes: its input, each statement the drivers sent to the database, and the full output.
+
+| Variable | Effect |
+| --- | --- |
+| `DB_LOG=true` | Log to stderr, which your MCP client keeps (Claude Code shows it in its MCP logs) |
+| `DB_LOG_FILE=/path/calls.log` | Log to that file instead, appended to, created readable by you only. Implies `DB_LOG` |
+| `DB_LOG_DIR=/path/folder` | Save every entry as its own JSON file in that folder, permanently. Implies logging on its own, without also writing text |
+| `DB_LOG_FORMAT=json` | One JSON object per line, for `jq` or a log shipper. The default is `pretty` |
+
+A pretty entry:
+
+```text
+┌─ #3 run_query · ok · 38 ms · 2026-09-25T10:14:03.221Z
+│ connection  dev (MySQL) mysql://reader@127.0.0.1:3306/app
+│ input
+│   {
+│     "query": "SELECT COUNT(*) AS n FROM members"
+│   }
+│ statements (1)
+│   1. MySQL · 12 ms · 1 row
+│      SELECT COUNT(*) AS n FROM members
+│ output
+│   [
+│     {
+│       "n": 17440
+│     }
+│   ]
+└─
+```
+
+- **Everything is logged, including the full output of every call.** Treat a log file like the data it contains.
+- **Credentials never are.** A `password` argument, the password inside a connection URL, and secret-looking URL options such as `api_key` are always written as `***`, with no way to turn that off.
+- **Statements** include the ones the server sends on its own behalf: PostgreSQL's `BEGIN READ ONLY` and `ROLLBACK`, Redis's `COMMAND INFO` checks, the catalog queries behind `describe_table`. Each shows its duration and outcome (a row count, or the error); the data itself is in the call's output. A statement sent outside any call, such as MySQL's per-connection setup, gets an entry of its own.
+- An entry is written when its call finishes, and numbered when it starts, so calls handled concurrently can appear out of numeric order.
+- With `DB_LOG_DIR`, each entry is its own file in a folder per UTC day, e.g. `2026-09-25/103014-221Z_p72440_c000012_run_query_ok.json`, holding the full record as pretty JSON: time, pid, sequence, tool and outcome are in the name, so `ls` and `grep` work without opening anything. Files and folders are readable by you only. Nothing is ever deleted or rotated; archive or remove old day folders yourself. Every copy of the server can share one folder, since names never collide.
+- Logging can never break a call. If the log cannot be written (say, the disk is full), the call still succeeds, one warning is printed, and logging stops.
+
+In Docker, a log file or folder must be on a mounted volume to outlive the container: `-v "$PWD/logs:/logs" -e DB_LOG_DIR=/logs`. `DB_LOG=true` needs no mount.
+
+### Live viewer in the browser
+
+Add `DB_LOG_PORT` to watch calls arrive in a browser page, updating the moment each one finishes:
+
+```bash
+DB_LOG=true DB_LOG_PORT=4800 npx -y @shibbirweb/mcp-db-read-only
+# then open http://127.0.0.1:4800/
+```
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `DB_LOG_PORT` | none | Serve the live viewer on this port. Needs `DB_LOG_DIR`, `DB_LOG` or `DB_LOG_FILE` as well; alone it only prints a warning |
+| `DB_LOG_HISTORY` | `500` | Without `DB_LOG_DIR`, how many recent entries the viewer keeps in memory. `0` keeps none |
+
+The page lists calls newest first, **20 per page by default**, with page controls and a choice of 10, 20, 30 or 50 per page (remembered in your browser). Each call is a card (tool, status, duration, connection, and which client and process made it) that expands to its input, statements and output, every block with its own copy icon. Filters (text, tool, failures only) apply across everything logged, not just the page shown. Page 1 updates itself as calls arrive; on any other page a "new entries" button appears instead, so the page you are reading does not shift. It follows your system's light or dark theme and loads nothing from the internet.
+
+With `DB_LOG_DIR` the viewer reads the folder, so it shows everything ever saved there, across restarts, **including calls made by other copies of the server** sharing the folder (Claude Desktop runs several). Without it, it shows this copy's last `DB_LOG_HISTORY` calls from memory.
+
+> **The viewer has no access control and listens on every network interface (`0.0.0.0`).** Anyone who can reach the port, including other devices on the same network, can read every query and every result in the log. Use it on a network you trust, or block the port at your firewall. The server prints a reminder of this when the viewer starts.
+
+With no `DB_LOG_PORT`, nothing listens on any port.
+
+The viewer takes its port on the **first tool call**, not at startup. MCP clients such as Claude Desktop start one copy of the server per chat surface, and most copies are never used; binding lazily means the copy your chat is using gets the port, and idle copies hold none (they open no database connections either until used).
+
+If the port is taken when a call arrives (another chat is already using the viewer, say), the call still works, and its result carries one extra line saying which process holds the port: free it, or set `DB_LOG_PORT` to another one. Every later call retries, so once the port is free the viewer comes up on the next call and says so. `current_connection` always shows the viewer's state.
+
+In Docker, publish the port as well: `-p 4800:4800 -e DB_LOG=true -e DB_LOG_PORT=4800`. Publishing it as `-p 127.0.0.1:4800:4800` keeps it reachable from this machine only.
+
+---
+
 ## 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.
@@ -333,7 +410,7 @@ Other limits worth knowing:
 
 **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.
+**Shutdown.** The server exits on `SIGINT`/`SIGTERM`, not when stdin closes. The live viewer, if running, closes its port with it. Open sockets keep the event loop alive, and stdin reaching EOF only means no further requests were buffered.
 
 ---
 

package/README.md

@@ -256,6 +256,12 @@ Every reading tool also accepts an optional `database`, applied to that call onl
 | `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 |
+| `DB_LOG` | off | `true` logs every tool call to stderr. See [Call logging](#call-logging) |
+| `DB_LOG_FILE` | none | Log every tool call to this file instead |
+| `DB_LOG_DIR` | none | Save every tool call as its own JSON file in this folder, permanently |
+| `DB_LOG_FORMAT` | `pretty` | `pretty` or `json` |
+| `DB_LOG_PORT` | none | Serve a live log viewer in the browser on this port |
+| `DB_LOG_HISTORY` | `500` | Entries the viewer keeps in memory when there is no `DB_LOG_DIR` |
 | `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`.
@@ -264,6 +270,77 @@ Starting profile: `DB_DEFAULT_PROFILE` (or `MYSQL_DEFAULT_PROFILE`) if it names
 
 ---
 
+## Call logging
+
+Off by default. Turn it on to see every tool call the assistant makes: its input, each statement the drivers sent to the database, and the full output.
+
+| Variable | Effect |
+| --- | --- |
+| `DB_LOG=true` | Log to stderr, which your MCP client keeps (Claude Code shows it in its MCP logs) |
+| `DB_LOG_FILE=/path/calls.log` | Log to that file instead, appended to, created readable by you only. Implies `DB_LOG` |
+| `DB_LOG_DIR=/path/folder` | Save every entry as its own JSON file in that folder, permanently. Implies logging on its own, without also writing text |
+| `DB_LOG_FORMAT=json` | One JSON object per line, for `jq` or a log shipper. The default is `pretty` |
+
+A pretty entry:
+
+```text
+┌─ #3 run_query · ok · 38 ms · 2026-09-25T10:14:03.221Z
+│ connection  dev (MySQL) mysql://reader@127.0.0.1:3306/app
+│ input
+│   {
+│     "query": "SELECT COUNT(*) AS n FROM members"
+│   }
+│ statements (1)
+│   1. MySQL · 12 ms · 1 row
+│      SELECT COUNT(*) AS n FROM members
+│ output
+│   [
+│     {
+│       "n": 17440
+│     }
+│   ]
+└─
+```
+
+- **Everything is logged, including the full output of every call.** Treat a log file like the data it contains.
+- **Credentials never are.** A `password` argument, the password inside a connection URL, and secret-looking URL options such as `api_key` are always written as `***`, with no way to turn that off.
+- **Statements** include the ones the server sends on its own behalf: PostgreSQL's `BEGIN READ ONLY` and `ROLLBACK`, Redis's `COMMAND INFO` checks, the catalog queries behind `describe_table`. Each shows its duration and outcome (a row count, or the error); the data itself is in the call's output. A statement sent outside any call, such as MySQL's per-connection setup, gets an entry of its own.
+- An entry is written when its call finishes, and numbered when it starts, so calls handled concurrently can appear out of numeric order.
+- With `DB_LOG_DIR`, each entry is its own file in a folder per UTC day, e.g. `2026-09-25/103014-221Z_p72440_c000012_run_query_ok.json`, holding the full record as pretty JSON: time, pid, sequence, tool and outcome are in the name, so `ls` and `grep` work without opening anything. Files and folders are readable by you only. Nothing is ever deleted or rotated; archive or remove old day folders yourself. Every copy of the server can share one folder, since names never collide.
+- Logging can never break a call. If the log cannot be written (say, the disk is full), the call still succeeds, one warning is printed, and logging stops.
+
+In Docker, a log file or folder must be on a mounted volume to outlive the container: `-v "$PWD/logs:/logs" -e DB_LOG_DIR=/logs`. `DB_LOG=true` needs no mount.
+
+### Live viewer in the browser
+
+Add `DB_LOG_PORT` to watch calls arrive in a browser page, updating the moment each one finishes:
+
+```bash
+DB_LOG=true DB_LOG_PORT=4800 npx -y @shibbirweb/mcp-db-read-only
+# then open http://127.0.0.1:4800/
+```
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `DB_LOG_PORT` | none | Serve the live viewer on this port. Needs `DB_LOG_DIR`, `DB_LOG` or `DB_LOG_FILE` as well; alone it only prints a warning |
+| `DB_LOG_HISTORY` | `500` | Without `DB_LOG_DIR`, how many recent entries the viewer keeps in memory. `0` keeps none |
+
+The page lists calls newest first, **20 per page by default**, with page controls and a choice of 10, 20, 30 or 50 per page (remembered in your browser). Each call is a card (tool, status, duration, connection, and which client and process made it) that expands to its input, statements and output, every block with its own copy icon. Filters (text, tool, failures only) apply across everything logged, not just the page shown. Page 1 updates itself as calls arrive; on any other page a "new entries" button appears instead, so the page you are reading does not shift. It follows your system's light or dark theme and loads nothing from the internet.
+
+With `DB_LOG_DIR` the viewer reads the folder, so it shows everything ever saved there, across restarts, **including calls made by other copies of the server** sharing the folder (Claude Desktop runs several). Without it, it shows this copy's last `DB_LOG_HISTORY` calls from memory.
+
+> **The viewer has no access control and listens on every network interface (`0.0.0.0`).** Anyone who can reach the port, including other devices on the same network, can read every query and every result in the log. Use it on a network you trust, or block the port at your firewall. The server prints a reminder of this when the viewer starts.
+
+With no `DB_LOG_PORT`, nothing listens on any port.
+
+The viewer takes its port on the **first tool call**, not at startup. MCP clients such as Claude Desktop start one copy of the server per chat surface, and most copies are never used; binding lazily means the copy your chat is using gets the port, and idle copies hold none (they open no database connections either until used).
+
+If the port is taken when a call arrives (another chat is already using the viewer, say), the call still works, and its result carries one extra line saying which process holds the port: free it, or set `DB_LOG_PORT` to another one. Every later call retries, so once the port is free the viewer comes up on the next call and says so. `current_connection` always shows the viewer's state.
+
+In Docker, publish the port as well: `-p 4800:4800 -e DB_LOG=true -e DB_LOG_PORT=4800`. Publishing it as `-p 127.0.0.1:4800:4800` keeps it reachable from this machine only.
+
+---
+
 ## 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.
@@ -318,7 +395,7 @@ Other limits worth knowing:
 
 **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.
+**Shutdown.** The server exits on `SIGINT`/`SIGTERM`, not when stdin closes. The live viewer, if running, closes its port with it. Open sockets keep the event loop alive, and stdin reaching EOF only means no further requests were buffered.
 
 ---
 

package/dist/ApplicationFactory.js

@@ -16,6 +16,17 @@ import { MySqlDriver } from "./drivers/sql/MySqlDriver.js";
 import { PostgresDriver } from "./drivers/sql/PostgresDriver.js";
 import { SqliteDriver } from "./drivers/sql/SqliteDriver.js";
 import { RowFormatter } from "./formatting/RowFormatter.js";
+import { CallLogger } from "./logging/CallLogger.js";
+import { TextLogChannel } from "./logging/LogChannel.js";
+import { LiveLogViewer } from "./logging/viewer/LiveLogViewer.js";
+import { LiveViewerObserver } from "./logging/viewer/LiveViewerObserver.js";
+import { FolderLogChannel } from "./logging/store/FolderLogChannel.js";
+import { FolderLogStore } from "./logging/store/FolderLogStore.js";
+import { MemoryLogStore } from "./logging/store/MemoryLogStore.js";
+import { JsonLogFormatter, PrettyLogFormatter } from "./logging/LogFormatter.js";
+import { FileSink, StderrSink } from "./logging/LogSink.js";
+import { SilentTracer } from "./logging/StatementTracer.js";
+import { SilentObserver } from "./logging/ToolCallObserver.js";
 import { McpDbServer } from "./server/McpDbServer.js";
 import { DescribeTableTool } from "./tools/browse/DescribeTableTool.js";
 import { GetForeignKeysTool } from "./tools/browse/GetForeignKeysTool.js";
@@ -63,6 +74,11 @@ export class ApplicationFactory {
      * total open connections at MAX_DRIVERS * CONNECTION_LIMIT.
      */
     static MAX_DRIVERS = 8;
+    /**
+     * Set once built, for the call log's client name: the logger has to exist
+     * before the server that will learn the name at handshake.
+     */
+    server = null;
     constructor(configLoader = new EnvironmentConfigLoader(), logger = (message) => console.error(`[mcp-db-ro] ${message}`), versionLoader = new PackageVersionLoader()) {
         this.configLoader = configLoader;
         this.logger = logger;
@@ -86,31 +102,112 @@ export class ApplicationFactory {
             connectTimeoutMs: config.connectTimeoutMs,
             queryTimeoutMs: config.queryTimeoutMs,
         };
-        const cache = new DriverCache(this.createDriverRegistry(tuning), ApplicationFactory.MAX_DRIVERS);
+        const callLog = this.createCallLog(config.logging, registry);
+        const cache = new DriverCache(this.createDriverRegistry(tuning, callLog.tracer), ApplicationFactory.MAX_DRIVERS);
         const connections = new ConnectionManager(registry, cache);
         const drivers = new DriverProvider(registry, cache, QUERY_TOOLS);
-        const tools = this.createTools(connections, drivers);
-        return new McpDbServer(tools, cache, this.logger, this.versionLoader.load());
+        const tools = this.createTools(connections, drivers, callLog.viewerStatus);
+        const server = new McpDbServer(tools, cache, this.logger, callLog.observer, callLog.services, this.versionLoader.load());
+        this.server = server;
+        return server;
+    }
+    /**
+     * The call log when DB_LOG or DB_LOG_FILE asks for it, silent stand-ins
+     * otherwise. One CallLogger plays both roles, observer for the tools and
+     * tracer for the drivers, which is what lets it nest each driver statement
+     * under the call that caused it.
+     */
+    createCallLog(settings, registry) {
+        if (!settings.enabled) {
+            return { observer: new SilentObserver(), tracer: new SilentTracer(), services: [], viewerStatus: () => null };
+        }
+        const channels = [];
+        const services = [];
+        let viewer = null;
+        const outputs = [];
+        const sink = settings.file ? new FileSink(settings.file) : new StderrSink();
+        if (settings.text) {
+            const formatter = settings.format === "json" ? new JsonLogFormatter() : new PrettyLogFormatter();
+            channels.push(new TextLogChannel(sink, formatter));
+            outputs.push(`${settings.format} text to ${sink.description}`);
+        }
+        // The viewer reads the folder when there is one, which also shows the
+        // calls of every other copy of the server saving there, and otherwise
+        // keeps this process's recent entries in memory.
+        let store;
+        if (settings.directory) {
+            const folderStore = new FolderLogStore(settings.directory);
+            store = folderStore;
+            channels.push(new FolderLogChannel(settings.directory, (entry) => folderStore.noteWritten(entry)));
+            outputs.push(`one JSON file per entry in ${settings.directory}`);
+        }
+        else {
+            const memoryStore = new MemoryLogStore(settings.viewerHistory);
+            store = memoryStore;
+            if (settings.viewerPort !== null) {
+                channels.push(memoryStore);
+            }
+        }
+        if (settings.viewerPort !== null) {
+            // Always all interfaces, as configured: reachable from other machines
+            // and from a Docker host without extra settings. The viewer announces
+            // that it has no access control when it starts, which is on the first
+            // tool call rather than here.
+            viewer = new LiveLogViewer("0.0.0.0", settings.viewerPort, store, this.logger);
+            services.push(viewer);
+        }
+        const logger = new CallLogger(channels, () => {
+            const target = registry.getActiveTarget();
+            return target
+                ? `${registry.getActiveName()} (${EngineCatalog.label(target.engine)}) ${target.describe()}`
+                : null;
+        }, this.logger, () => this.clientName());
+        // Said once at startup, because with logging on every query and every
+        // result is being written somewhere, and the operator should know where.
+        this.logger(`call logging on: every tool call, its statements and its full output are written as ${outputs.join(" and ")}`);
+        const fallback = outputs.length > 0 ? outputs.join(" and ") : "nowhere else";
+        const observer = viewer ? new LiveViewerObserver(logger, viewer, fallback, this.logger) : logger;
+        return {
+            observer,
+            tracer: logger,
+            services,
+            viewerStatus: () => (viewer ? this.describeViewer(viewer) : null),
+        };
+    }
+    clientName() {
+        return this.server?.clientName() ?? null;
+    }
+    /** One line for current_connection. */
+    describeViewer(viewer) {
+        const status = viewer.status;
+        switch (status.state) {
+            case "running":
+                return `running at ${status.url}`;
+            case "unavailable":
+                return `unavailable, ${status.reason} (free it or set DB_LOG_PORT to another port)`;
+            case "idle":
+                return "starts on the first tool call";
+        }
     }
     /** One factory per engine. None of them does I/O; drivers connect on first use. */
-    createDriverRegistry(tuning) {
+    createDriverRegistry(tuning, tracer) {
         return new DriverRegistry()
-            .register("mysql", (target) => new MySqlDriver(target, tuning, this.logger))
-            .register("postgres", (target) => new PostgresDriver(target, tuning))
-            .register("sqlite", (target) => new SqliteDriver(target, tuning))
-            .register("mssql", (target) => new MsSqlDriver(target, tuning))
-            .register("clickhouse", (target) => new ClickHouseDriver(target, tuning))
-            .register("mongodb", (target) => new MongoDriver(target, tuning))
-            .register("redis", (target) => new RedisDriver(target, tuning, this.logger))
-            .register("elasticsearch", (target) => new ElasticsearchDriver(target, tuning));
+            .register("mysql", (target) => new MySqlDriver(target, tuning, tracer, this.logger))
+            .register("postgres", (target) => new PostgresDriver(target, tuning, tracer))
+            .register("sqlite", (target) => new SqliteDriver(target, tuning, tracer))
+            .register("mssql", (target) => new MsSqlDriver(target, tuning, tracer))
+            .register("clickhouse", (target) => new ClickHouseDriver(target, tuning, tracer))
+            .register("mongodb", (target) => new MongoDriver(target, tuning, tracer))
+            .register("redis", (target) => new RedisDriver(target, tuning, tracer, this.logger))
+            .register("elasticsearch", (target) => new ElasticsearchDriver(target, tuning, tracer));
     }
-    createTools(connections, drivers) {
+    createTools(connections, drivers, viewerStatus) {
         const names = new NamePolicyRegistry();
         const targetFactory = new ConnectionTargetFactory();
         const rows = new RowFormatter();
         const mongoGuard = new MongoOperatorGuard();
         const tools = [
-            new CurrentConnectionTool(connections),
+            new CurrentConnectionTool(connections, viewerStatus),
             new ListConnectionsTool(connections),
             new ListDatabasesTool(drivers),
             new UseDatabaseTool(connections, names),

package/dist/config/EnvironmentConfigLoader.js

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import { ConnectionProfile } from "../domain/ConnectionProfile.js";
 import { ConnectionTargetFactory } from "../connections/ConnectionTargetFactory.js";
 /**
@@ -30,6 +31,7 @@ export class EnvironmentConfigLoader {
     targetFactory;
     static DEFAULT_QUERY_TIMEOUT_MS = 30000;
     static DEFAULT_CONNECT_TIMEOUT_MS = 10000;
+    static DEFAULT_VIEWER_HISTORY = 500;
     constructor(env = process.env, targetFactory = new ConnectionTargetFactory()) {
         this.env = env;
         this.targetFactory = targetFactory;
@@ -46,9 +48,65 @@ export class EnvironmentConfigLoader {
             defaultProfileName: this.env.DB_DEFAULT_PROFILE || this.env.MYSQL_DEFAULT_PROFILE || null,
             queryTimeoutMs: this.readTimeout(this.env.DB_QUERY_TIMEOUT_MS ?? this.env.MYSQL_QUERY_TIMEOUT_MS, EnvironmentConfigLoader.DEFAULT_QUERY_TIMEOUT_MS),
             connectTimeoutMs: this.readTimeout(this.env.DB_CONNECT_TIMEOUT_MS ?? this.env.MYSQL_CONNECT_TIMEOUT_MS, EnvironmentConfigLoader.DEFAULT_CONNECT_TIMEOUT_MS),
+            logging: this.readLogging(warnings),
             warnings,
         };
     }
+    /**
+     * DB_LOG=true logs text to stderr; DB_LOG_FILE=/path logs text to that
+     * file. DB_LOG_DIR=/folder saves every entry as its own JSON file there.
+     * Each of the three turns logging on by itself, and they combine.
+     * DB_LOG_FORMAT picks pretty (the default) or json for the text output.
+     *
+     * Relative paths are made absolute here, against the directory the server
+     * was started in, so the startup message names the real location.
+     */
+    readLogging(warnings) {
+        const file = this.env.DB_LOG_FILE ? resolve(this.env.DB_LOG_FILE) : null;
+        const directory = this.env.DB_LOG_DIR ? resolve(this.env.DB_LOG_DIR) : null;
+        const stderr = ["true", "1", "yes", "on"].includes((this.env.DB_LOG ?? "").toLowerCase());
+        const text = stderr || file !== null;
+        const enabled = text || directory !== null;
+        const requested = (this.env.DB_LOG_FORMAT ?? "").toLowerCase();
+        let format = "pretty";
+        if (requested === "json") {
+            format = "json";
+        }
+        else if (requested && requested !== "pretty") {
+            warnings.push(`DB_LOG_FORMAT="${this.env.DB_LOG_FORMAT}" is not pretty or json, using pretty.`);
+        }
+        return { enabled, text, file, directory, format, ...this.readViewer(enabled, warnings) };
+    }
+    /**
+     * DB_LOG_PORT starts the live browser viewer, but only while logging is on:
+     * the viewer shows the call log, so without one it has nothing to show, and
+     * it says so rather than silently doing nothing.
+     */
+    readViewer(loggingEnabled, warnings) {
+        const history = this.readCount(this.env.DB_LOG_HISTORY, EnvironmentConfigLoader.DEFAULT_VIEWER_HISTORY);
+        const raw = this.env.DB_LOG_PORT;
+        if (!raw) {
+            return { viewerPort: null, viewerHistory: history };
+        }
+        const port = Number(raw);
+        if (!/^\d+$/.test(raw) || port < 1 || port > 65535) {
+            warnings.push(`DB_LOG_PORT="${raw}" is not a port from 1 to 65535, so the live viewer is off.`);
+            return { viewerPort: null, viewerHistory: history };
+        }
+        if (!loggingEnabled) {
+            warnings.push("DB_LOG_PORT is set but call logging is off. Set DB_LOG_DIR, DB_LOG=true or DB_LOG_FILE to use the live viewer.");
+            return { viewerPort: null, viewerHistory: history };
+        }
+        return { viewerPort: port, viewerHistory: history };
+    }
+    /** A non-negative integer, or the fallback. 0 is allowed and means none. */
+    readCount(value, fallback) {
+        if (value === undefined || value === "") {
+            return fallback;
+        }
+        const parsed = Number(value);
+        return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+    }
     /**
      * DB_PROFILES: `{"name": "url"}` or `{"name": {"url": "...", "password": "..."}}`.
      *

package/dist/drivers/BaseDriver.js

@@ -7,11 +7,16 @@ import { UnsupportedOperationError } from "../errors/UnsupportedOperationError.j
  * The two optional capabilities, indexes and foreign keys, default to a
  * refusal here, so an engine without them needs no code to say so, and an
  * engine that has them overrides the one method.
+ *
+ * Every statement a driver sends goes through `traced`, which reports it to
+ * the call log when logging is on and is a plain call when it is off.
  */
 export class BaseDriver {
     target;
-    constructor(target) {
+    tracer;
+    constructor(target, tracer) {
         this.target = target;
+        this.tracer = tracer;
     }
     async listIndexes(_name) {
         throw new UnsupportedOperationError(this.label, "indexes to list");
@@ -19,6 +24,10 @@ export class BaseDriver {
     async listForeignKeys(_name) {
         throw new UnsupportedOperationError(this.label, "foreign keys");
     }
+    /** Run one statement through the tracer, labelled with this engine. */
+    traced(text, params, run, describe) {
+        return this.tracer.trace(this.label, { text, params }, run, describe);
+    }
     get label() {
         return EngineCatalog.label(this.target.engine);
     }

package/dist/drivers/document/MongoDriver.js

@@ -25,8 +25,8 @@ export class MongoDriver extends BaseDriver {
     static SYSTEM_DATABASES = new Set(["admin", "local", "config"]);
     static SCHEMA_SAMPLE_SIZE = 100;
     client;
-    constructor(target, tuning, stages = new MongoStageAllowlist(), sampler = new MongoSchemaSampler()) {
-        super(target);
+    constructor(target, tuning, tracer, stages = new MongoStageAllowlist(), sampler = new MongoSchemaSampler()) {
+        super(target, tracer);
         this.tuning = tuning;
         this.stages = stages;
         this.sampler = sampler;
@@ -34,7 +34,8 @@ export class MongoDriver extends BaseDriver {
     }
     async verify() {
         const { client } = await this.client.get();
-        await client.db(this.target.database || "admin").command({ ping: 1 });
+        const database = this.target.database || "admin";
+        await this.traced(`${database}.ping`, undefined, () => client.db(database).command({ ping: 1 }), () => "ok");
     }
     close() {
         return this.client.close();
@@ -45,7 +46,7 @@ export class MongoDriver extends BaseDriver {
      */
     async listDatabases() {
         const { client } = await this.client.get();
-        const result = await client.db("admin").admin().listDatabases({ nameOnly: true, authorizedDatabases: true });
+        const result = await this.traced("admin.listDatabases", { nameOnly: true, authorizedDatabases: true }, () => client.db("admin").admin().listDatabases({ nameOnly: true, authorizedDatabases: true }), (answer) => `${answer.databases.length} databases`);
         return result.databases.map((entry) => ({
             name: entry.name,
             system: MongoDriver.SYSTEM_DATABASES.has(entry.name),
@@ -53,22 +54,18 @@ export class MongoDriver extends BaseDriver {
     }
     async listObjects(pattern, limit) {
         const database = await this.database();
-        const collections = await database
-            .listCollections({}, { nameOnly: true, authorizedCollections: true })
-            .toArray();
+        const collections = await this.traced(`${database.databaseName}.listCollections`, undefined, () => database.listCollections({}, { nameOnly: true, authorizedCollections: true }).toArray());
         return new GlobPattern(pattern).apply(collections.map((entry) => entry.name).sort(), limit);
     }
     /** The inferred shape of a sample, plus any JSON Schema validator the collection declares. */
     async describeObject(name) {
         const database = await this.database();
-        const [info] = await database.listCollections({ name }).toArray();
+        const [info] = await this.traced(`${database.databaseName}.listCollections`, { name }, () => database.listCollections({ name }).toArray());
         if (!info) {
             throw new ObjectNotFoundError(this.objectNoun, name);
         }
-        const documents = await database
-            .collection(name)
-            .aggregate([{ $sample: { size: MongoDriver.SCHEMA_SAMPLE_SIZE } }], { maxTimeMS: this.tuning.queryTimeoutMs })
-            .toArray();
+        const sampling = [{ $sample: { size: MongoDriver.SCHEMA_SAMPLE_SIZE } }];
+        const documents = await this.traced(`${database.databaseName}.${name}.aggregate`, sampling, () => database.collection(name).aggregate(sampling, { maxTimeMS: this.tuning.queryTimeoutMs }).toArray());
         return {
             collection: name,
             sampled_documents: documents.length,
@@ -79,7 +76,7 @@ export class MongoDriver extends BaseDriver {
     async listIndexes(name) {
         await this.assertCollection(name);
         const database = await this.database();
-        return database.collection(name).indexes();
+        return this.traced(`${database.databaseName}.${name}.indexes`, undefined, () => database.collection(name).indexes());
     }
     async sample(name, limit) {
         await this.assertCollection(name);
@@ -95,7 +92,8 @@ export class MongoDriver extends BaseDriver {
             skip: request.skip,
             maxTimeMS: this.tuning.queryTimeoutMs,
         });
-        return this.toJson(bson, await cursor.toArray());
+        const documents = await this.traced(`${database.databaseName}.${collection}.find`, request, () => cursor.toArray());
+        return this.toJson(bson, documents);
     }
     /**
      * Reads at most `limit + 1` documents and closes the cursor, so a pipeline
@@ -112,32 +110,31 @@ export class MongoDriver extends BaseDriver {
             batchSize: limit + 1,
         });
         const rows = [];
-        try {
-            for await (const document of cursor) {
-                rows.push(document);
-                if (rows.length > limit) {
-                    break;
+        await this.traced(`${database.databaseName}.${collection}.aggregate`, pipeline, async () => {
+            try {
+                for await (const document of cursor) {
+                    rows.push(document);
+                    if (rows.length > limit) {
+                        break;
+                    }
                 }
             }
-        }
-        finally {
-            await cursor.close();
-        }
+            finally {
+                await cursor.close();
+            }
+            return rows;
+        });
         return { rows: this.toJson(bson, rows.slice(0, limit)), truncated: rows.length > limit };
     }
     async count(collection, filter) {
         const { bson } = await this.client.get();
         const database = await this.database();
-        return database
-            .collection(collection)
-            .countDocuments(this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs });
+        return this.traced(`${database.databaseName}.${collection}.countDocuments`, filter, () => database.collection(collection).countDocuments(this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs }));
     }
     async distinct(collection, field, filter) {
         const { bson } = await this.client.get();
         const database = await this.database();
-        const values = await database
-            .collection(collection)
-            .distinct(field, this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs });
+        const values = await this.traced(`${database.databaseName}.${collection}.distinct`, { field, filter }, () => database.collection(collection).distinct(field, this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs }));
         return this.toJson(bson, values);
     }
     async database() {
@@ -146,7 +143,7 @@ export class MongoDriver extends BaseDriver {
     }
     async assertCollection(name) {
         const database = await this.database();
-        const found = await database.listCollections({ name }, { nameOnly: true }).toArray();
+        const found = await this.traced(`${database.databaseName}.listCollections`, { name }, () => database.listCollections({ name }, { nameOnly: true }).toArray());
         if (found.length === 0) {
             throw new ObjectNotFoundError(this.objectNoun, name);
         }