@shibbirweb/mcp-db-read-only 0.1.0

package/dist/tools/search/SearchTool.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { DatabaseScopedTool } from "../DatabaseScopedTool.js";
+import { ToolResponse } from "../../formatting/ToolResponse.js";
+/**
+ * An Elasticsearch or OpenSearch `_search`, with the body in Query DSL.
+ *
+ * One tool rather than separate search and count tools: `size: 0` with
+ * `track_total_hits: true` is a count, and aggregations ride in the same
+ * body, so a second tool would only duplicate this one's argument.
+ */
+export class SearchTool extends DatabaseScopedTool {
+    bodies;
+    name = "search";
+    description = "Search an Elasticsearch or OpenSearch index with a Query DSL body. Use size 0 with track_total_hits true to count, and aggs for aggregations";
+    family = "search";
+    static MAX_SIZE = 100;
+    static DEFAULT_SIZE = 10;
+    annotations = {
+        title: "Search Index",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    };
+    inputSchema = {
+        index: z.string().describe("Index name, pattern such as logs-*, or comma-separated list"),
+        body: z
+            .record(z.unknown())
+            .default({})
+            .describe('Search body, e.g. {"query": {"match": {"title": "error"}}, "size": 10, "sort": [{"@timestamp": "desc"}]}'),
+    };
+    constructor(drivers, names, bodies) {
+        super(drivers, names);
+        this.bodies = bodies;
+    }
+    async read(args, target) {
+        const rejection = this.validateObjectName(target, args.index, "index name") ?? this.reject(this.bodies.validate(args.body));
+        if (rejection) {
+            return rejection;
+        }
+        const driver = await this.drivers.acquireSearch(target, this.name);
+        return ToolResponse.json(await driver.search(args.index, { ...args.body, size: this.size(args.body.size) }));
+    }
+    /**
+     * Capped rather than rejected when too large: the caller wanted results,
+     * and a hundred of them answers the question better than an error does.
+     */
+    size(requested) {
+        if (typeof requested !== "number" || !Number.isFinite(requested)) {
+            return SearchTool.DEFAULT_SIZE;
+        }
+        return Math.min(Math.max(Math.trunc(requested), 0), SearchTool.MAX_SIZE);
+    }
+}

package/dist/tools/sql/RunQueryTool.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { DatabaseScopedTool } from "../DatabaseScopedTool.js";
+import { ToolResponse } from "../../formatting/ToolResponse.js";
+/**
+ * The general escape hatch for reads on the SQL engines.
+ *
+ * No parameter binding is exposed. Adding a `params` argument would let an
+ * assistant separate values from SQL properly, but models inline their values
+ * in practice, and the validator plus each driver's server-side read-only
+ * mode already bound what a query can do.
+ */
+export class RunQueryTool extends DatabaseScopedTool {
+    validators;
+    rows;
+    name = "run_query";
+    description = "Execute a read-only SQL query (SELECT, WITH, and the engine's SHOW, DESCRIBE or EXPLAIN) on a MySQL, MariaDB, PostgreSQL, SQLite, SQL Server or ClickHouse connection";
+    family = "sql";
+    annotations = {
+        title: "Run Read-Only SQL Query",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    };
+    inputSchema = {
+        query: z.string().describe("SQL query to execute, in the active engine's dialect"),
+        database: DatabaseScopedTool.databaseParam,
+    };
+    constructor(drivers, names, validators, rows) {
+        super(drivers, names);
+        this.validators = validators;
+        this.rows = rows;
+    }
+    async read(args, target) {
+        const driver = await this.drivers.acquireSql(target, this.name);
+        // Validation happens before anything touches the network, so a rejected
+        // query costs no connection. The dialect comes from the driver, so a
+        // PostgreSQL query is lexed as PostgreSQL, dollar quotes and all.
+        const check = this.validators.for(driver.dialect).validate(args.query);
+        if (!check.valid) {
+            return ToolResponse.failure(check.error ?? "Query rejected.");
+        }
+        const result = await driver.query(args.query);
+        return ToolResponse.text(this.rows.format(result, "Add a LIMIT clause (TOP on SQL Server)"));
+    }
+}

package/dist/types/config.types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/connection.types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/driver.types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/types/tool.types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/validation.types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation/document/MongoOperatorGuard.js

@@ -0,0 +1,72 @@
+/**
+ * Rejects MongoDB filters and pipelines that contain a forbidden operator
+ * anywhere, at any depth.
+ *
+ * Layer one for MongoDB, run by the tools before a driver is touched. It is a
+ * denylist, walked recursively, because the dangerous operators can hide
+ * inside `$facet`, `$lookup.pipeline`, `$unionWith`, `$expr` and each other:
+ *
+ * - `$out` and `$merge` write the pipeline's result into a collection.
+ * - `$function`, `$accumulator` and `$where` run JavaScript on the server,
+ *   which cannot write through a read but can run for as long as it likes.
+ * - `$changeStream` opens a cursor that never finishes by design.
+ *
+ * Layer two is a different mechanism on purpose: MongoStageAllowlist, inside
+ * the driver, permits only known read stages. One is a denylist of operators,
+ * the other an allowlist of stages, so a mistake in one is not repeated in the
+ * other.
+ */
+export class MongoOperatorGuard {
+    static FORBIDDEN = new Map([
+        ["$out", "$out writes the result into a collection"],
+        ["$merge", "$merge writes the result into a collection"],
+        ["$function", "$function runs JavaScript on the server"],
+        ["$accumulator", "$accumulator runs JavaScript on the server"],
+        ["$where", "$where runs JavaScript on the server"],
+        ["$changeStream", "$changeStream opens a cursor that never completes"],
+    ]);
+    /**
+     * Deep enough for any real pipeline, and a bound on a hostile one: a value
+     * nested ten thousand levels deep would otherwise exhaust the stack.
+     */
+    static MAX_DEPTH = 64;
+    validate(value, label) {
+        const found = this.findForbidden(value, 0);
+        if (found === "too-deep") {
+            return { valid: false, error: `The ${label} is nested too deeply.` };
+        }
+        if (found) {
+            return {
+                valid: false,
+                error: `The ${label} uses ${found}, which is not allowed: ${MongoOperatorGuard.FORBIDDEN.get(found)}.`,
+            };
+        }
+        return { valid: true };
+    }
+    findForbidden(value, depth) {
+        if (depth > MongoOperatorGuard.MAX_DEPTH) {
+            return "too-deep";
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const found = this.findForbidden(item, depth + 1);
+                if (found) {
+                    return found;
+                }
+            }
+            return null;
+        }
+        if (value && typeof value === "object") {
+            for (const [key, child] of Object.entries(value)) {
+                if (MongoOperatorGuard.FORBIDDEN.has(key)) {
+                    return key;
+                }
+                const found = this.findForbidden(child, depth + 1);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        return null;
+    }
+}

package/dist/validation/keyvalue/RedisCommandValidator.js

@@ -0,0 +1,176 @@
+/**
+ * Decides whether a Redis command may run: an allowlist of read commands.
+ *
+ * Layer one for Redis, run before any connection is used. An allowlist rather
+ * than a denylist because Redis has hundreds of commands, modules add more,
+ * and an unrecognised one must be refused rather than assumed harmless.
+ *
+ * Layer two, in the driver, asks the server itself: COMMAND INFO reports
+ * whether a command is flagged `write`, and the driver refuses any that is or
+ * that is not flagged `readonly`. The two are independent, since one is a list
+ * written here and the other is the server's own knowledge of its commands.
+ *
+ * Some read commands are left out on purpose:
+ *
+ * - KEYS blocks the server while it walks every key. SCAN is the answer.
+ * - CONFIG GET returns `requirepass` and other secrets.
+ * - PFCOUNT is flagged as a write, since it may update a cached cardinality.
+ * - SORT can STORE its result; SORT_RO is the read form.
+ * - Blocking reads (BLPOP, XREAD BLOCK, SUBSCRIBE) hold the connection.
+ */
+export class RedisCommandValidator {
+    static ALLOWED = new Set([
+        // Strings and generic key inspection
+        "GET",
+        "MGET",
+        "STRLEN",
+        "GETRANGE",
+        "EXISTS",
+        "TYPE",
+        "TTL",
+        "PTTL",
+        "EXPIRETIME",
+        "PEXPIRETIME",
+        "SCAN",
+        "RANDOMKEY",
+        "DBSIZE",
+        "SORT_RO",
+        "LCS",
+        // Hashes
+        "HGET",
+        "HMGET",
+        "HGETALL",
+        "HKEYS",
+        "HVALS",
+        "HLEN",
+        "HEXISTS",
+        "HSTRLEN",
+        "HSCAN",
+        "HRANDFIELD",
+        "HTTL",
+        "HPTTL",
+        // Lists
+        "LRANGE",
+        "LLEN",
+        "LINDEX",
+        "LPOS",
+        // Sets
+        "SMEMBERS",
+        "SCARD",
+        "SISMEMBER",
+        "SMISMEMBER",
+        "SRANDMEMBER",
+        "SSCAN",
+        "SINTER",
+        "SUNION",
+        "SDIFF",
+        "SINTERCARD",
+        // Sorted sets
+        "ZRANGE",
+        "ZRANGEBYSCORE",
+        "ZRANGEBYLEX",
+        "ZREVRANGE",
+        "ZREVRANGEBYSCORE",
+        "ZREVRANGEBYLEX",
+        "ZCARD",
+        "ZSCORE",
+        "ZMSCORE",
+        "ZRANK",
+        "ZREVRANK",
+        "ZCOUNT",
+        "ZLEXCOUNT",
+        "ZSCAN",
+        "ZRANDMEMBER",
+        "ZINTER",
+        "ZUNION",
+        "ZDIFF",
+        "ZINTERCARD",
+        // Streams
+        "XRANGE",
+        "XREVRANGE",
+        "XLEN",
+        "XPENDING",
+        // Bitmaps and geo
+        "GETBIT",
+        "BITCOUNT",
+        "BITPOS",
+        "BITFIELD_RO",
+        "GEOPOS",
+        "GEODIST",
+        "GEOHASH",
+        "GEOSEARCH",
+        "GEORADIUS_RO",
+        "GEORADIUSBYMEMBER_RO",
+        // Server
+        "INFO",
+        "TIME",
+        "PING",
+        "ECHO",
+        // RedisJSON, RediSearch and RedisTimeSeries read commands
+        "JSON.GET",
+        "JSON.MGET",
+        "JSON.TYPE",
+        "JSON.STRLEN",
+        "JSON.OBJKEYS",
+        "JSON.OBJLEN",
+        "JSON.ARRLEN",
+        "JSON.ARRINDEX",
+        "FT.SEARCH",
+        "FT.AGGREGATE",
+        "FT.INFO",
+        "FT._LIST",
+        "TS.GET",
+        "TS.MGET",
+        "TS.RANGE",
+        "TS.REVRANGE",
+        "TS.MRANGE",
+        "TS.MREVRANGE",
+        "TS.INFO",
+    ]);
+    /**
+     * Container commands whose subcommands differ in kind: `OBJECT ENCODING`
+     * reads, while other subcommands of the same container may not. Only the
+     * listed pairs are allowed.
+     */
+    static ALLOWED_SUBCOMMANDS = new Map([
+        ["OBJECT", new Set(["ENCODING", "FREQ", "IDLETIME", "REFCOUNT"])],
+        ["MEMORY", new Set(["USAGE"])],
+        ["XINFO", new Set(["STREAM", "GROUPS", "CONSUMERS"])],
+    ]);
+    /** @returns the canonical upper-case name, or the reason it was refused. */
+    validate(command, args) {
+        const name = command.trim().toUpperCase();
+        if (!name) {
+            return { valid: false, error: "Empty command." };
+        }
+        if (/\s/.test(name)) {
+            return {
+                valid: false,
+                error: "Pass the command name alone and its arguments in args, e.g. command=HGET args=[\"user:1\", \"email\"].",
+            };
+        }
+        const subcommands = RedisCommandValidator.ALLOWED_SUBCOMMANDS.get(name);
+        if (subcommands) {
+            const sub = (args[0] ?? "").toUpperCase();
+            if (subcommands.has(sub)) {
+                return { valid: true, name };
+            }
+            return {
+                valid: false,
+                error: `${name} ${sub || "(no subcommand)"} is not allowed. Allowed: ${Array.from(subcommands)
+                    .map((entry) => `${name} ${entry}`)
+                    .join(", ")}.`,
+            };
+        }
+        if (name === "KEYS") {
+            return {
+                valid: false,
+                error: "KEYS blocks the server while it scans every key. Use SCAN, or list_tables with a pattern.",
+            };
+        }
+        if (!RedisCommandValidator.ALLOWED.has(name)) {
+            return { valid: false, error: `${name} is not an allowed read-only command.` };
+        }
+        return { valid: true, name };
+    }
+}

package/dist/validation/names/NamePolicy.js

@@ -0,0 +1,122 @@
+function invalid(error) {
+    return { valid: false, error };
+}
+const VALID = { valid: true };
+/**
+ * Where the pattern is only ever matched in process or sent as a command
+ * argument, any glob is safe; the length cap just keeps a runaway argument
+ * from becoming a runaway regular expression.
+ */
+function validateLocalPattern(value) {
+    if (value.length > 256) {
+        return invalid("The pattern is too long.");
+    }
+    return VALID;
+}
+/**
+ * SQL engines: an allowlist, optionally schema-qualified.
+ *
+ * Several SQL engines cannot parameterise an identifier, so a table name can
+ * end up interpolated into the statement. The allowlist is what makes that
+ * safe: nothing matching it can close a quote. Drivers additionally escape
+ * every identifier they quote, so the two protections are independent.
+ *
+ * Hyphens are allowed where the MySQL-only predecessor refused them, because
+ * every identifier is now quoted and escaped, and database names such as
+ * `my-app` are common on PostgreSQL and SQL Server. For anything needing
+ * spaces or other characters, run_query with a hand-quoted statement remains
+ * the escape hatch, and it goes through the full SQL validator instead.
+ */
+export class SqlNamePolicy {
+    static PART = "[A-Za-z0-9_$-]+";
+    static DATABASE = new RegExp(`^${SqlNamePolicy.PART}$`);
+    static OBJECT = new RegExp(`^${SqlNamePolicy.PART}(\\.${SqlNamePolicy.PART})?$`);
+    validateDatabase(value) {
+        if (!value || !SqlNamePolicy.DATABASE.test(value)) {
+            return invalid(`Invalid database name: "${value}". Only letters, digits, underscore, hyphen and $ are allowed.`);
+        }
+        return VALID;
+    }
+    validateObject(value, label) {
+        if (!value || !SqlNamePolicy.OBJECT.test(value)) {
+            return invalid(`Invalid ${label}: "${value}". Use letters, digits, underscore, hyphen and $, optionally qualified as schema.table.`);
+        }
+        return VALID;
+    }
+    validatePattern(value) {
+        return validateLocalPattern(value);
+    }
+}
+/**
+ * MongoDB: the server's own naming rules, since names never reach a query
+ * string. Collection names may contain dots (`system.profile`) and hyphens.
+ */
+export class MongoNamePolicy {
+    static DATABASE = /^[^/\\. "$*<>:|?\0]{1,63}$/;
+    validateDatabase(value) {
+        if (!MongoNamePolicy.DATABASE.test(value)) {
+            return invalid(`Invalid database name: "${value}". MongoDB database names cannot contain / \\ . space " $ * < > : | ?`);
+        }
+        return VALID;
+    }
+    validateObject(value, label) {
+        if (!value || value.length > 255 || value.includes("$") || value.includes("\0")) {
+            return invalid(`Invalid ${label}: "${value}". Collection names cannot be empty or contain $.`);
+        }
+        return VALID;
+    }
+    validatePattern(value) {
+        return validateLocalPattern(value);
+    }
+}
+/**
+ * Redis: databases are numbered, and a key is any byte string. Keys are sent
+ * as command arguments, never interpolated, so there is nothing to escape.
+ */
+export class RedisNamePolicy {
+    validateDatabase(value) {
+        if (!/^\d{1,5}$/.test(value)) {
+            return invalid(`Invalid database: "${value}". Redis databases are numbered, e.g. 0 or 3.`);
+        }
+        return VALID;
+    }
+    validateObject(value, label) {
+        if (!value) {
+            return invalid(`Invalid ${label}: a key cannot be empty.`);
+        }
+        return VALID;
+    }
+    validatePattern(value) {
+        return validateLocalPattern(value);
+    }
+}
+/**
+ * Elasticsearch and OpenSearch: an index name, pattern or comma list, which
+ * becomes a URL path segment.
+ *
+ * Percent-encoding the segment is not enough on its own. A name of `.` or one
+ * containing `..` is normalised away by the URL parser, repointing the request
+ * at a different endpoint, and a leading `_` names an API rather than an
+ * index. Those are refused before a path is ever built.
+ */
+export class ElasticNamePolicy {
+    static OBJECT = /^[A-Za-z0-9_.*,+:\-]+$/;
+    validateDatabase() {
+        return invalid("Elasticsearch has no databases. Name an index or pattern with the table argument.");
+    }
+    validateObject(value, label) {
+        const parts = value.split(",");
+        const bad = !value ||
+            !ElasticNamePolicy.OBJECT.test(value) ||
+            value.includes("..") ||
+            parts.some((part) => part === "" || part === "." || part.startsWith("_"));
+        if (bad) {
+            return invalid(`Invalid ${label}: "${value}". Use an index name, a pattern such as logs-*, or a comma-separated list; names cannot start with _ or contain "..".`);
+        }
+        return VALID;
+    }
+    /** The pattern becomes a path segment here, so it meets the same rules as a name. */
+    validatePattern(value) {
+        return this.validateObject(value, "pattern");
+    }
+}

package/dist/validation/names/NamePolicyRegistry.js

@@ -0,0 +1,33 @@
+import { EngineCatalog } from "../../domain/Engine.js";
+import { ElasticNamePolicy, MongoNamePolicy, RedisNamePolicy, SqlNamePolicy, } from "./NamePolicy.js";
+/**
+ * Picks the naming rules for an engine.
+ *
+ * Tools validate names against the active engine before any driver is
+ * touched, so a malformed name costs no connection, and they do it through
+ * this one lookup so no tool can quietly apply SQL rules to a Redis key.
+ */
+export class NamePolicyRegistry {
+    sql;
+    mongo;
+    redis;
+    elastic;
+    constructor(sql = new SqlNamePolicy(), mongo = new MongoNamePolicy(), redis = new RedisNamePolicy(), elastic = new ElasticNamePolicy()) {
+        this.sql = sql;
+        this.mongo = mongo;
+        this.redis = redis;
+        this.elastic = elastic;
+    }
+    for(engine) {
+        switch (EngineCatalog.describe(engine).family) {
+            case "sql":
+                return this.sql;
+            case "document":
+                return this.mongo;
+            case "keyvalue":
+                return this.redis;
+            case "search":
+                return this.elastic;
+        }
+    }
+}

package/dist/validation/search/SearchBodyValidator.js

@@ -0,0 +1,56 @@
+/**
+ * Checks an Elasticsearch or OpenSearch `_search` body before it is sent.
+ *
+ * Layer one for search engines: an allowlist of top-level keys. The search
+ * API cannot write whatever the body says, so this is not what keeps the data
+ * safe. What it does is keep the request inside the plain search surface:
+ * `scroll` and `pit` open server-side contexts that outlive the call, and an
+ * unknown key is far more likely a mistake than a feature worth passing
+ * through blind.
+ *
+ * Layer two is structural, in the driver: it can only send GET requests to a
+ * fixed set of read endpoints and POST requests to `_search`, with paths it
+ * builds itself from a validated index name. There is no generic request
+ * method to misuse.
+ */
+export class SearchBodyValidator {
+    static ALLOWED_KEYS = new Set([
+        "query",
+        "size",
+        "from",
+        "sort",
+        "_source",
+        "fields",
+        "docvalue_fields",
+        "stored_fields",
+        "script_fields",
+        "runtime_mappings",
+        "aggs",
+        "aggregations",
+        "post_filter",
+        "highlight",
+        "collapse",
+        "search_after",
+        "track_total_hits",
+        "min_score",
+        "knn",
+        "rescore",
+        "suggest",
+        "explain",
+        "version",
+        "seq_no_primary_term",
+        "indices_boost",
+        "timeout",
+        "terminate_after",
+    ]);
+    validate(body) {
+        const unknown = Object.keys(body).filter((key) => !SearchBodyValidator.ALLOWED_KEYS.has(key));
+        if (unknown.length > 0) {
+            return {
+                valid: false,
+                error: `Unsupported search body key${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.`,
+            };
+        }
+        return { valid: true };
+    }
+}

package/dist/validation/sql/ReadOnlyQueryValidator.js

@@ -0,0 +1,82 @@
+import { SqlDialects } from "./SqlDialect.js";
+import { SqlSkeletonizer } from "./SqlSkeletonizer.js";
+import { AmbiguousSyntaxRule, EmptyQueryRule, ForbiddenPatternRule, LeadingKeywordRule, SingleStatementRule, SmuggledWriteRule, } from "./rules/index.js";
+/**
+ * Decides whether a SQL statement may run, by walking a chain of rules.
+ *
+ * Chain of Responsibility: each rule inspects the statement and either objects
+ * or passes. The validator knows nothing about what any rule checks, and a
+ * rule knows nothing about the others, so adding or reordering a check is a
+ * local change.
+ *
+ * One validator per dialect. The rules are shared; the dialect decides how the
+ * statement is lexed and which word lists the rules consult.
+ *
+ * This is layer one of two. Every SQL driver also enforces read-only on the
+ * server side, independently, so a bug here alone cannot become a write.
+ */
+export class ReadOnlyQueryValidator {
+    dialect;
+    rules;
+    skeletonizer;
+    /**
+     * Order matters. Empty first so later rules can assume content; ambiguity
+     * before anything that trusts the skeleton; leading keyword before the
+     * smuggled-write scan, which is conditional on it.
+     */
+    static defaultRules() {
+        return [
+            new EmptyQueryRule(),
+            new AmbiguousSyntaxRule(),
+            new SingleStatementRule(),
+            new LeadingKeywordRule(),
+            new SmuggledWriteRule(),
+            new ForbiddenPatternRule(),
+        ];
+    }
+    static forDialect(name) {
+        return new ReadOnlyQueryValidator(SqlDialects.get(name));
+    }
+    constructor(dialect, rules = ReadOnlyQueryValidator.defaultRules(), skeletonizer = new SqlSkeletonizer()) {
+        this.dialect = dialect;
+        this.rules = rules;
+        this.skeletonizer = skeletonizer;
+    }
+    validate(sql) {
+        const inspection = this.inspect(sql);
+        for (const rule of this.rules) {
+            const objection = rule.evaluate(inspection);
+            if (objection) {
+                return objection;
+            }
+        }
+        return { valid: true };
+    }
+    /**
+     * Builds the view of the statement every rule shares.
+     *
+     * The original SQL is what eventually reaches the server; the skeleton is
+     * only ever used to decide whether it may.
+     */
+    inspect(sql) {
+        const skeleton = this.skeletonizer.skeletonize(sql, this.dialect.lexical);
+        const text = skeleton.text
+            .trim()
+            // A single trailing semicolon is idiomatic when pasting a query and is
+            // not statement stacking.
+            .replace(/;+\s*$/, "")
+            .trim();
+        return {
+            raw: sql,
+            skeleton: text,
+            leadingKeyword: this.leadingKeyword(text),
+            ambiguities: skeleton.ambiguities,
+            dialect: this.dialect,
+        };
+    }
+    /** Leading parentheses are stripped so `(SELECT 1) UNION (SELECT 2)` works. */
+    leadingKeyword(skeleton) {
+        const firstWord = skeleton.replace(/^[\s(]+/, "").split(/[\s(]+/)[0] ?? "";
+        return firstWord.toUpperCase();
+    }
+}