@shibbirweb/mcp-db-read-only 0.1.0

package/dist/drivers/DriverProvider.js

@@ -0,0 +1,71 @@
+import { ConnectionManager } from "../connections/ConnectionManager.js";
+import { EngineCatalog } from "../domain/Engine.js";
+import { EngineMismatchError } from "../errors/EngineMismatchError.js";
+/**
+ * Resolves which connection a tool call belongs to, and hands back its driver.
+ *
+ * A Facade over the registry and the driver cache, so tools never learn how a
+ * target becomes a driver. It is also the single place a call decides which
+ * connection it belongs to, which is why the per-call `database` override
+ * costs one argument in each tool rather than a branch.
+ */
+export class DriverProvider {
+    registry;
+    cache;
+    queryTools;
+    constructor(registry, cache, queryTools) {
+        this.registry = registry;
+        this.cache = cache;
+        this.queryTools = queryTools;
+    }
+    /** @throws NoActiveConnectionError when nothing is configured yet. */
+    requireActiveTarget() {
+        return this.registry.requireActiveTarget();
+    }
+    /**
+     * No argument means the active connection; a database name means the active
+     * connection pointed at that database for this call only.
+     *
+     * @throws UnsupportedOperationError on an engine with nothing to switch to.
+     */
+    resolveTarget(database) {
+        const active = this.registry.requireActiveTarget();
+        if (!database) {
+            return active;
+        }
+        ConnectionManager.assertSwitchable(active);
+        return active.withDatabase(database);
+    }
+    acquire(target) {
+        return this.cache.acquire(target);
+    }
+    /**
+     * Checked against the engine catalog before the driver is acquired, so the
+     * mismatch is reported without constructing anything.
+     *
+     * @throws EngineMismatchError naming the tools that do fit the active engine.
+     */
+    requireFamily(target, family, toolName) {
+        const engine = EngineCatalog.describe(target.engine);
+        if (engine.family === family) {
+            return;
+        }
+        throw new EngineMismatchError(toolName, EngineCatalog.labelsFor(family), engine.label, this.queryTools[engine.family]);
+    }
+    async acquireSql(target, toolName) {
+        this.requireFamily(target, "sql", toolName);
+        return (await this.acquire(target));
+    }
+    async acquireDocument(target, toolName) {
+        this.requireFamily(target, "document", toolName);
+        return (await this.acquire(target));
+    }
+    async acquireKeyValue(target, toolName) {
+        this.requireFamily(target, "keyvalue", toolName);
+        return (await this.acquire(target));
+    }
+    async acquireSearch(target, toolName) {
+        this.requireFamily(target, "search", toolName);
+        return (await this.acquire(target));
+    }
+}

package/dist/drivers/DriverRegistry.js

@@ -0,0 +1,24 @@
+/**
+ * Which driver serves which engine: an Abstract Factory keyed by engine.
+ *
+ * The composition root registers one factory per engine. Nothing else in the
+ * server names a concrete driver class, which is what lets the connection and
+ * tool layers stay engine-agnostic, and lets tests register a fake.
+ */
+export class DriverRegistry {
+    factories = new Map();
+    register(engine, factory) {
+        this.factories.set(engine, factory);
+        return this;
+    }
+    create(target) {
+        const factory = this.factories.get(target.engine);
+        if (!factory) {
+            throw new Error(`No driver is registered for ${target.engine}.`);
+        }
+        return factory(target);
+    }
+    engines() {
+        return Array.from(this.factories.keys());
+    }
+}

package/dist/drivers/GlobPattern.js

@@ -0,0 +1,41 @@
+/**
+ * The `pattern` argument of list_tables: `*` for any run of characters, `?`
+ * for one.
+ *
+ * Glob rather than SQL LIKE or regular expressions because it is the one
+ * syntax that means the same thing on every engine here. Redis SCAN MATCH and
+ * Elasticsearch index patterns take it natively; the SQL and MongoDB drivers
+ * apply it with this class after listing.
+ */
+export class GlobPattern {
+    expression;
+    constructor(pattern) {
+        this.expression = pattern ? GlobPattern.compile(pattern) : null;
+    }
+    matches(name) {
+        return this.expression ? this.expression.test(name) : true;
+    }
+    /** Filter, then cap, reporting whether the cap cut anything off. */
+    apply(names, limit) {
+        const matching = names.filter((name) => this.matches(name));
+        return {
+            names: matching.slice(0, limit),
+            truncated: matching.length > limit,
+        };
+    }
+    /** Case-insensitive, since table name case is rarely what someone means to filter on. */
+    static compile(pattern) {
+        const source = Array.from(pattern)
+            .map((char) => {
+            if (char === "*") {
+                return ".*";
+            }
+            if (char === "?") {
+                return ".";
+            }
+            return char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        })
+            .join("");
+        return new RegExp(`^${source}$`, "i");
+    }
+}

package/dist/drivers/LazyResource.js

@@ -0,0 +1,56 @@
+/**
+ * Something expensive to open, opened once, on first use.
+ *
+ * Every driver holds its client in one of these. Two properties matter:
+ *
+ * - **A failed open is forgotten.** Without that, a server that was down when
+ *   first asked would stay "down" in this process forever, because every later
+ *   call would await the same rejected promise.
+ * - **Concurrent first calls share one open.** Two tool calls arriving
+ *   together must not each open a pool and leak one of them.
+ */
+export class LazyResource {
+    open;
+    dispose;
+    pending = null;
+    constructor(open, dispose) {
+        this.open = open;
+        this.dispose = dispose;
+    }
+    get() {
+        if (!this.pending) {
+            const opening = this.open();
+            this.pending = opening;
+            opening.catch(() => {
+                // Compared rather than cleared unconditionally, so a failure of an
+                // old open cannot wipe out a newer one started after a reset.
+                if (this.pending === opening) {
+                    this.pending = null;
+                }
+            });
+        }
+        return this.pending;
+    }
+    /**
+     * Drop the resource so the next `get` opens a fresh one, for when a client
+     * has died in a way it cannot recover from.
+     */
+    reset() {
+        return this.close();
+    }
+    /** Never throws: shutdown must not stall on one broken connection. */
+    async close() {
+        const pending = this.pending;
+        this.pending = null;
+        if (!pending) {
+            return;
+        }
+        try {
+            await this.dispose(await pending);
+        }
+        catch {
+            // Already failed to open, or failed to close: either way nothing is
+            // left to release.
+        }
+    }
+}

package/dist/drivers/document/MongoDriver.js

@@ -0,0 +1,187 @@
+import { ObjectNotFoundError } from "../../errors/ObjectNotFoundError.js";
+import { BaseDriver } from "../BaseDriver.js";
+import { GlobPattern } from "../GlobPattern.js";
+import { LazyResource } from "../LazyResource.js";
+import { MongoSchemaSampler } from "./MongoSchemaSampler.js";
+import { MongoStageAllowlist } from "./MongoStageAllowlist.js";
+/**
+ * MongoDB, through the official driver.
+ *
+ * Read-only layer two is structural. This class calls only read operations
+ * (`find`, `aggregate`, `countDocuments`, `distinct`, the list commands and
+ * `ping`) and never a generic command, so there is no method here through
+ * which a write could be expressed. The one read operation that can write,
+ * `aggregate` with `$out` or `$merge`, passes MongoStageAllowlist first.
+ *
+ * Filters and pipelines arrive as Extended JSON, so `{"$oid": "..."}` and
+ * `{"$date": "..."}` work, and results go back the same way, so an ObjectId
+ * survives the round trip into a follow-up filter.
+ */
+export class MongoDriver extends BaseDriver {
+    tuning;
+    stages;
+    sampler;
+    family = "document";
+    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);
+        this.tuning = tuning;
+        this.stages = stages;
+        this.sampler = sampler;
+        this.client = new LazyResource(() => this.open(), (opened) => opened.client.close());
+    }
+    async verify() {
+        const { client } = await this.client.get();
+        await client.db(this.target.database || "admin").command({ ping: 1 });
+    }
+    close() {
+        return this.client.close();
+    }
+    /**
+     * `authorizedDatabases` so a user with access to a few databases sees those,
+     * rather than an authorisation error for not being allowed to see them all.
+     */
+    async listDatabases() {
+        const { client } = await this.client.get();
+        const result = await client.db("admin").admin().listDatabases({ nameOnly: true, authorizedDatabases: true });
+        return result.databases.map((entry) => ({
+            name: entry.name,
+            system: MongoDriver.SYSTEM_DATABASES.has(entry.name),
+        }));
+    }
+    async listObjects(pattern, limit) {
+        const database = await this.database();
+        const collections = await 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();
+        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();
+        return {
+            collection: name,
+            sampled_documents: documents.length,
+            fields: this.sampler.infer(documents),
+            validator: info.options?.validator ?? null,
+        };
+    }
+    async listIndexes(name) {
+        await this.assertCollection(name);
+        const database = await this.database();
+        return database.collection(name).indexes();
+    }
+    async sample(name, limit) {
+        await this.assertCollection(name);
+        return this.find(name, { filter: {}, limit, skip: 0 });
+    }
+    async find(collection, request) {
+        const { bson } = await this.client.get();
+        const database = await this.database();
+        const cursor = database.collection(collection).find(this.fromJson(bson, request.filter), {
+            projection: request.projection ? this.fromJson(bson, request.projection) : undefined,
+            sort: request.sort ? this.fromJson(bson, request.sort) : undefined,
+            limit: request.limit,
+            skip: request.skip,
+            maxTimeMS: this.tuning.queryTimeoutMs,
+        });
+        return this.toJson(bson, await cursor.toArray());
+    }
+    /**
+     * Reads at most `limit + 1` documents and closes the cursor, so a pipeline
+     * matching millions of documents costs one batch, and the extra document
+     * says whether there were more.
+     */
+    async aggregate(collection, pipeline, limit) {
+        this.stages.assertAllowed(pipeline);
+        const { bson } = await this.client.get();
+        const database = await this.database();
+        const cursor = database.collection(collection).aggregate(pipeline.map((stage) => this.fromJson(bson, stage)), {
+            maxTimeMS: this.tuning.queryTimeoutMs,
+            allowDiskUse: false,
+            batchSize: limit + 1,
+        });
+        const rows = [];
+        try {
+            for await (const document of cursor) {
+                rows.push(document);
+                if (rows.length > limit) {
+                    break;
+                }
+            }
+        }
+        finally {
+            await cursor.close();
+        }
+        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 });
+    }
+    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 });
+        return this.toJson(bson, values);
+    }
+    async database() {
+        const { client } = await this.client.get();
+        return client.db(this.requireDatabase());
+    }
+    async assertCollection(name) {
+        const database = await this.database();
+        const found = await database.listCollections({ name }, { nameOnly: true }).toArray();
+        if (found.length === 0) {
+            throw new ObjectNotFoundError(this.objectNoun, name);
+        }
+    }
+    /** Extended JSON in: `{"$oid": ...}` becomes an ObjectId the server can match. */
+    fromJson(bson, value) {
+        return bson.EJSON.deserialize(value, { relaxed: true });
+    }
+    /** Relaxed Extended JSON out: numbers stay numbers, and ObjectIds stay recognisable. */
+    toJson(bson, values) {
+        return values.map((value) => bson.EJSON.serialize(value, { relaxed: true }));
+    }
+    /**
+     * The URL is rebuilt without credentials, which go through `auth` instead,
+     * so a password containing URL syntax never has to survive a round trip
+     * through encoding. Imported on first use; see MySqlDriver.createPool.
+     */
+    async open() {
+        const mongodb = (await import("mongodb"));
+        const hosts = this.target.hosts
+            .map((entry) => (entry.port > 0 ? `${entry.host}:${entry.port}` : entry.host))
+            .join(",");
+        const query = new URLSearchParams({ ...this.target.options, ...this.target.secretOptions }).toString();
+        const url = `${this.target.scheme}://${hosts}/${query ? `?${query}` : ""}`;
+        const client = new mongodb.MongoClient(url, {
+            auth: this.target.user ? { username: this.target.user, password: this.target.password } : undefined,
+            // The database named in the URL is also where credentials are checked,
+            // unless authSource says otherwise, which is what a MongoDB URL means.
+            authSource: this.target.option("authSource") ?? (this.target.database || undefined),
+            appName: "mcp-db-read-only",
+            maxPoolSize: this.tuning.connectionLimit,
+            connectTimeoutMS: this.tuning.connectTimeoutMs,
+            serverSelectionTimeoutMS: this.tuning.connectTimeoutMs,
+        });
+        await client.connect();
+        return { client, bson: mongodb.BSON };
+    }
+}

package/dist/drivers/document/MongoSchemaSampler.js

@@ -0,0 +1,74 @@
+/**
+ * Infers a collection's shape from a sample of its documents.
+ *
+ * MongoDB has no schema to read, so describe_table answers the question
+ * people actually ask of a table description ("what fields are there, and of
+ * what type") by looking at documents. The presence percentage matters as much
+ * as the types: a field present in 3% of documents is a very different thing
+ * to query on than one present in all of them.
+ */
+export class MongoSchemaSampler {
+    /** Deep enough for real documents without turning one describe into a dump. */
+    static MAX_DEPTH = 4;
+    infer(documents) {
+        const types = new Map();
+        const counts = new Map();
+        for (const document of documents) {
+            const seen = new Set();
+            this.walk(document, "", 0, types, seen);
+            for (const path of seen) {
+                counts.set(path, (counts.get(path) ?? 0) + 1);
+            }
+        }
+        const total = Math.max(documents.length, 1);
+        return Array.from(types.entries())
+            .map(([path, found]) => ({
+            path,
+            types: Array.from(found).sort(),
+            presentPercent: Math.round(((counts.get(path) ?? 0) / total) * 100),
+        }))
+            .sort((a, b) => a.path.localeCompare(b.path));
+    }
+    walk(value, prefix, depth, types, seen) {
+        for (const [key, child] of Object.entries(value)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            seen.add(path);
+            const found = types.get(path) ?? new Set();
+            found.add(this.typeOf(child));
+            types.set(path, found);
+            if (this.isPlainObject(child) && depth < MongoSchemaSampler.MAX_DEPTH) {
+                this.walk(child, path, depth + 1, types, seen);
+            }
+        }
+    }
+    /**
+     * BSON types by their driver class name (ObjectId, Decimal128, Long), which
+     * is what a reader needs to write a correct filter against the field.
+     */
+    typeOf(value) {
+        if (value === null) {
+            return "null";
+        }
+        if (Array.isArray(value)) {
+            return "array";
+        }
+        if (value instanceof Date) {
+            return "date";
+        }
+        if (typeof value === "object") {
+            const bsonType = value._bsontype;
+            if (typeof bsonType === "string") {
+                return bsonType;
+            }
+            return "object";
+        }
+        return typeof value;
+    }
+    isPlainObject(value) {
+        return (value !== null &&
+            typeof value === "object" &&
+            !Array.isArray(value) &&
+            !(value instanceof Date) &&
+            typeof value._bsontype !== "string");
+    }
+}

package/dist/drivers/document/MongoStageAllowlist.js

@@ -0,0 +1,87 @@
+/**
+ * The aggregation stages the MongoDB driver will send, and no others.
+ *
+ * Layer two for MongoDB, checked inside the driver immediately before
+ * `aggregate` is called. MongoDB has no read-only session mode, so the server
+ * cannot be asked to refuse a write; this list is the structural substitute.
+ * It is an allowlist of stages, deliberately a different mechanism from the
+ * tool-level MongoOperatorGuard (a denylist of operators), so the two do not
+ * share a blind spot.
+ *
+ * Nested pipelines are walked too: `$facet` holds several, and `$lookup` and
+ * `$unionWith` each hold one, any of which could otherwise carry a `$merge`.
+ *
+ * The honest limit of this layer: it constrains what this server sends. It is
+ * not a server-side guarantee, which is why the README recommends connecting
+ * with a user granted only the `read` role.
+ */
+export class MongoStageAllowlist {
+    static STAGES = new Set([
+        "$match",
+        "$project",
+        "$addFields",
+        "$set",
+        "$unset",
+        "$group",
+        "$sort",
+        "$limit",
+        "$skip",
+        "$unwind",
+        "$lookup",
+        "$graphLookup",
+        "$unionWith",
+        "$facet",
+        "$count",
+        "$sortByCount",
+        "$bucket",
+        "$bucketAuto",
+        "$replaceRoot",
+        "$replaceWith",
+        "$sample",
+        "$redact",
+        "$geoNear",
+        "$setWindowFields",
+        "$densify",
+        "$fill",
+        "$documents",
+        "$collStats",
+        "$indexStats",
+        "$search",
+        "$searchMeta",
+        "$vectorSearch",
+    ]);
+    /** @throws Error naming the first stage that is not allowed. */
+    assertAllowed(pipeline) {
+        for (const stage of pipeline) {
+            if (!stage || typeof stage !== "object" || Array.isArray(stage)) {
+                throw new Error("Every pipeline stage must be an object such as {\"$match\": {...}}.");
+            }
+            const keys = Object.keys(stage);
+            if (keys.length !== 1) {
+                throw new Error("Every pipeline stage must have exactly one stage operator.");
+            }
+            const name = keys[0];
+            if (!MongoStageAllowlist.STAGES.has(name)) {
+                throw new Error(`The aggregation stage ${name} is not allowed on a read-only connection.`);
+            }
+            this.assertNested(name, stage[name]);
+        }
+    }
+    assertNested(name, body) {
+        if (!body || typeof body !== "object") {
+            return;
+        }
+        if (name === "$facet") {
+            for (const nested of Object.values(body)) {
+                this.assertAllowed(Array.isArray(nested) ? nested : [nested]);
+            }
+            return;
+        }
+        if (name === "$lookup" || name === "$unionWith") {
+            const nested = body.pipeline;
+            if (nested !== undefined) {
+                this.assertAllowed(Array.isArray(nested) ? nested : [nested]);
+            }
+        }
+    }
+}

package/dist/drivers/keyvalue/RedisCommandFlagsGuard.js

@@ -0,0 +1,69 @@
+/**
+ * Asks the Redis server whether a command is read-only before it is sent.
+ *
+ * Layer two for Redis. The tool-level allowlist is a list written in this
+ * repository; this is the server's own classification of its commands, as
+ * reported by COMMAND INFO. A command is sent only if the server flags it
+ * `readonly` and does not flag it `write`. The two layers are independent: a
+ * command wrongly added to the allowlist is still refused here, and a server
+ * whose flags differ from what the allowlist assumed is caught too.
+ *
+ * It fails closed. When COMMAND itself is unavailable, renamed or denied by an
+ * ACL, the command is refused with a message saying why, rather than sent on
+ * the strength of the allowlist alone.
+ */
+export class RedisCommandFlagsGuard {
+    cache = new Map();
+    /**
+     * @param name the canonical upper-case command
+     * @param subcommand for container commands such as OBJECT ENCODING
+     * @throws Error when the server does not confirm the command is read-only
+     */
+    async assertReadOnly(call, name, subcommand) {
+        const flags = await this.flagsFor(call, name, subcommand);
+        const readOnly = flags.includes("readonly") && !flags.includes("write");
+        if (!readOnly) {
+            const label = subcommand ? `${name} ${subcommand}` : name;
+            throw new Error(`The server does not flag ${label} as read-only (flags: ${flags.join(", ") || "none"}), so it was not sent.`);
+        }
+    }
+    async flagsFor(call, name, subcommand) {
+        const key = subcommand ? `${name}|${subcommand}` : name;
+        const cached = this.cache.get(key);
+        if (cached) {
+            return cached;
+        }
+        let reply;
+        try {
+            // Redis 7 answers `container|subcommand` directly; older servers only
+            // know the container, whose flags then stand for all its subcommands.
+            reply = await call("COMMAND", "INFO", subcommand ? `${name.toLowerCase()}|${subcommand.toLowerCase()}` : name);
+            if (subcommand && this.isEmpty(reply)) {
+                reply = await call("COMMAND", "INFO", name);
+            }
+        }
+        catch (error) {
+            throw new Error(`Could not confirm ${name} is read-only because COMMAND INFO failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const flags = this.parseFlags(reply);
+        if (!flags) {
+            throw new Error(`The server does not know the command ${name}.`);
+        }
+        this.cache.set(key, flags);
+        return flags;
+    }
+    /** COMMAND INFO replies `[[name, arity, [flags...], ...]]`, or `[null]` for an unknown command. */
+    parseFlags(reply) {
+        if (!Array.isArray(reply) || !Array.isArray(reply[0])) {
+            return null;
+        }
+        const flags = reply[0][2];
+        if (!Array.isArray(flags)) {
+            return null;
+        }
+        return flags.map((flag) => String(flag).toLowerCase());
+    }
+    isEmpty(reply) {
+        return !Array.isArray(reply) || reply[0] === null || reply[0] === undefined;
+    }
+}