@shibbirweb/mcp-db-read-only 0.1.0

package/dist/config/EnvironmentConfigLoader.js

@@ -0,0 +1,179 @@
+import { ConnectionProfile } from "../domain/ConnectionProfile.js";
+import { ConnectionTargetFactory } from "../connections/ConnectionTargetFactory.js";
+/**
+ * Reads configuration from environment variables.
+ *
+ * Implements ConfigurationLoader so tests, and any future file or remote
+ * source, can be substituted without touching anything downstream.
+ *
+ * Two families of variables are read, in this order of precedence:
+ *
+ * 1. `DB_PROFILES` and `DB_URL`, the native form: connection URLs for any
+ *    engine.
+ * 2. `MYSQL_PROFILES` and `MYSQL_HOST`/`USER`/`DATABASE`, the configuration
+ *    of the MySQL-only server this one generalises. Read so that an existing
+ *    setup keeps working unchanged when the image is swapped. A profile name
+ *    already defined by the native form wins.
+ *
+ * Two properties are deliberate:
+ *
+ * - **Nothing is logged here.** Problems are returned as `warnings` and the
+ *   composition root decides where they go. That keeps the loader pure, and
+ *   lets tests assert on warnings instead of intercepting console output.
+ * - **Nothing is fatal.** Malformed JSON, a broken profile, or no
+ *   configuration at all all produce a usable result. A server that starts and
+ *   explains the problem can be fixed with the connect tool; one that exits
+ *   during handshake is reported by the client as a broken install.
+ */
+export class EnvironmentConfigLoader {
+    env;
+    targetFactory;
+    static DEFAULT_QUERY_TIMEOUT_MS = 30000;
+    static DEFAULT_CONNECT_TIMEOUT_MS = 10000;
+    constructor(env = process.env, targetFactory = new ConnectionTargetFactory()) {
+        this.env = env;
+        this.targetFactory = targetFactory;
+    }
+    load() {
+        const warnings = [];
+        const profiles = new Map();
+        this.loadUrlProfiles(profiles, warnings);
+        this.loadSingleUrl(profiles, warnings);
+        this.loadLegacyMySqlProfiles(profiles, warnings);
+        this.loadLegacyMySqlConnection(profiles);
+        return {
+            profiles: Array.from(profiles.values()),
+            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),
+            warnings,
+        };
+    }
+    /**
+     * DB_PROFILES: `{"name": "url"}` or `{"name": {"url": "...", "password": "..."}}`.
+     *
+     * The object form exists for passwords. A password inside a URL must be
+     * percent-encoded, and one containing `@`, `/` or `#` silently splits the URL
+     * in the wrong place when it is not. Giving it its own field removes that
+     * whole class of mistake.
+     */
+    loadUrlProfiles(target, warnings) {
+        const parsed = this.readJsonObject("DB_PROFILES", warnings);
+        if (!parsed) {
+            return;
+        }
+        for (const [name, definition] of Object.entries(parsed)) {
+            const entry = this.readUrlDefinition(definition);
+            if (!entry) {
+                warnings.push(`Skipping profile "${name}": expected a URL string or an object with "url".`);
+                continue;
+            }
+            try {
+                const connection = this.targetFactory.fromUrl(entry.url, entry.password);
+                target.set(name, ConnectionProfile.fromEnvironment(name, connection));
+            }
+            catch (error) {
+                warnings.push(`Skipping profile "${name}": ${this.reason(error)}`);
+            }
+        }
+    }
+    /** DB_URL, with DB_PASSWORD as its optional separate password, as `default`. */
+    loadSingleUrl(target, warnings) {
+        const url = this.env.DB_URL;
+        if (!url || target.has("default")) {
+            return;
+        }
+        try {
+            const connection = this.targetFactory.fromUrl(url, this.env.DB_PASSWORD);
+            target.set("default", ConnectionProfile.fromEnvironment("default", connection));
+        }
+        catch (error) {
+            warnings.push(`Ignoring DB_URL: ${this.reason(error)}`);
+        }
+    }
+    /** The legacy MYSQL_PROFILES object form, exactly as the MySQL-only server read it. */
+    loadLegacyMySqlProfiles(target, warnings) {
+        const parsed = this.readJsonObject("MYSQL_PROFILES", warnings);
+        if (!parsed) {
+            return;
+        }
+        for (const [name, definition] of Object.entries(parsed)) {
+            if (target.has(name)) {
+                warnings.push(`Skipping MYSQL_PROFILES "${name}": DB_PROFILES already defines it.`);
+                continue;
+            }
+            if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+                warnings.push(`Skipping profile "${name}": not an object.`);
+                continue;
+            }
+            try {
+                const connection = this.targetFactory.fromMySqlDefinition(definition, name);
+                target.set(name, ConnectionProfile.fromEnvironment(name, connection));
+            }
+            catch (error) {
+                warnings.push(`Skipping profile "${name}": ${this.reason(error)}`);
+            }
+        }
+    }
+    /**
+     * The MYSQL_HOST/USER/DATABASE form, registered as a profile named `default`
+     * unless something above already claimed that name.
+     */
+    loadLegacyMySqlConnection(target) {
+        const user = this.env.MYSQL_USER;
+        const database = this.env.MYSQL_DATABASE;
+        if (!user || !database || target.has("default")) {
+            return;
+        }
+        const connection = this.targetFactory.fromMySqlValues({
+            host: this.env.MYSQL_HOST,
+            port: this.env.MYSQL_PORT ? Number.parseInt(this.env.MYSQL_PORT, 10) : undefined,
+            user,
+            password: this.env.MYSQL_PASSWORD ?? "",
+            database,
+        });
+        target.set("default", ConnectionProfile.fromEnvironment("default", connection));
+    }
+    readJsonObject(variable, warnings) {
+        const raw = this.env[variable];
+        if (!raw) {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            warnings.push(`${variable} is not valid JSON, ignoring it: ${this.reason(error)}`);
+            return null;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            warnings.push(`${variable} must be a JSON object of named profiles, ignoring it.`);
+            return null;
+        }
+        return parsed;
+    }
+    readUrlDefinition(definition) {
+        if (typeof definition === "string" && definition) {
+            return { url: definition };
+        }
+        if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+            return null;
+        }
+        const raw = definition;
+        if (typeof raw.url !== "string" || !raw.url) {
+            return null;
+        }
+        return {
+            url: raw.url,
+            password: typeof raw.password === "string" ? raw.password : undefined,
+        };
+    }
+    readTimeout(value, fallback) {
+        const parsed = Number.parseInt(value ?? "", 10);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+    }
+    reason(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}

package/dist/config/PackageVersionLoader.js

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+/**
+ * Reads the version clients see in the MCP handshake from `package.json`.
+ *
+ * A literal in the server class would mean a release has to remember to
+ * change the same number in two files. Nothing enforces that, and the tag
+ * check in the publish workflows never looks at a literal, so a missed bump
+ * would ship a server that misreports itself to every client. The MySQL-only
+ * predecessor of this server shipped exactly that bug before this class
+ * existed.
+ *
+ * `package.json` is present in all three ways this server is distributed: the
+ * npm tarball always includes it, the runtime image copies it in before the
+ * build output, and a local checkout has it by definition.
+ */
+export class PackageVersionLoader {
+    packageJsonUrl;
+    /**
+     * Used when `package.json` cannot be read. A server that starts and reports
+     * an obviously wrong version is easier to diagnose than one that refuses to
+     * start over metadata it does not need in order to answer queries.
+     */
+    static UNKNOWN_VERSION = "0.0.0";
+    /**
+     * Resolved from this module rather than from `process.cwd()`, so the answer
+     * does not depend on the directory the client happened to launch us from.
+     */
+    constructor(packageJsonUrl = new URL("../../package.json", import.meta.url)) {
+        this.packageJsonUrl = packageJsonUrl;
+    }
+    load() {
+        try {
+            const contents = readFileSync(this.packageJsonUrl, "utf8");
+            const version = JSON.parse(contents).version;
+            return typeof version === "string" && version.length > 0
+                ? version
+                : PackageVersionLoader.UNKNOWN_VERSION;
+        }
+        catch {
+            return PackageVersionLoader.UNKNOWN_VERSION;
+        }
+    }
+}

package/dist/connections/ConnectionManager.js

@@ -0,0 +1,101 @@
+import { ConnectionProfile } from "../domain/ConnectionProfile.js";
+import { EngineCatalog } from "../domain/Engine.js";
+import { UnknownProfileError } from "../errors/UnknownProfileError.js";
+import { UnsupportedOperationError } from "../errors/UnsupportedOperationError.js";
+/**
+ * Orchestrates changing the active connection.
+ *
+ * Sits between the tools and the registry so that every switch follows the
+ * same rule: **verify, then commit**. The registry cannot enforce that itself
+ * without taking a dependency on the drivers, and the tools should not each be
+ * trusted to remember it.
+ *
+ * Committing only after a successful verification is what makes a failed
+ * switch harmless: the previous connection stays active and the session
+ * remains usable.
+ */
+export class ConnectionManager {
+    registry;
+    drivers;
+    constructor(registry, drivers) {
+        this.registry = registry;
+        this.drivers = drivers;
+    }
+    getActiveTarget() {
+        return this.registry.getActiveTarget();
+    }
+    getActiveName() {
+        return this.registry.getActiveName();
+    }
+    requireActiveTarget() {
+        return this.registry.requireActiveTarget();
+    }
+    listProfiles() {
+        return this.registry.list();
+    }
+    findProfile(profileName) {
+        return this.registry.find(profileName);
+    }
+    /**
+     * Move to a different database on the current server.
+     *
+     * Keeps the current profile label: the connection is still "staging", just
+     * pointed elsewhere, and renaming it would throw away that context.
+     *
+     * @throws UnsupportedOperationError for engines with nothing to switch to,
+     *   before any network work.
+     */
+    async useDatabase(database) {
+        const active = this.registry.requireActiveTarget();
+        ConnectionManager.assertSwitchable(active);
+        const candidate = active.withDatabase(database);
+        await this.drivers.verify(candidate);
+        return this.registry.activateTarget(candidate, this.registry.getActiveName() ?? "custom");
+    }
+    /**
+     * Move to a named profile, optionally overriding its database.
+     *
+     * @throws UnknownProfileError carrying the known names, checked before any
+     *   network work so a typo fails instantly.
+     */
+    async useProfile(profileName, database) {
+        const profile = this.registry.find(profileName);
+        if (!profile) {
+            throw new UnknownProfileError(profileName, this.registry.names());
+        }
+        let candidate = profile.target;
+        if (database) {
+            ConnectionManager.assertSwitchable(profile.target);
+            candidate = profile.target.withDatabase(database);
+        }
+        await this.drivers.verify(candidate);
+        return this.registry.activateTarget(candidate, profileName);
+    }
+    /**
+     * Open an arbitrary connection and keep it under an alias for the session.
+     *
+     * This is what makes a restart unnecessary in every case: DB_PROFILES is a
+     * convenience, this is the guarantee. Credentials are held in memory only
+     * and vanish on exit, which list_connections communicates via the `session`
+     * origin.
+     */
+    async connect(target, alias) {
+        await this.drivers.verify(target);
+        this.registry.register(ConnectionProfile.fromSession(alias, target));
+        return this.registry.activateTarget(target, alias);
+    }
+    /**
+     * Shared with DriverProvider so use_database and the per-call `database`
+     * argument refuse in exactly the same words.
+     */
+    static assertSwitchable(target) {
+        const engine = EngineCatalog.describe(target.engine);
+        if (engine.switchesDatabases) {
+            return;
+        }
+        const alternative = target.engine === "sqlite"
+            ? "The file is the database; call connect with another sqlite:// URL to open a different one."
+            : "Its indices are listed by list_tables.";
+        throw new UnsupportedOperationError(engine.label, "separate databases to switch between", alternative);
+    }
+}

package/dist/connections/ConnectionRegistry.js

@@ -0,0 +1,109 @@
+import { NoActiveConnectionError } from "../errors/NoActiveConnectionError.js";
+import { UnknownProfileError } from "../errors/UnknownProfileError.js";
+/**
+ * The Registry: every known connection, and which one is active.
+ *
+ * This is the only mutable state that makes runtime switching possible. As an
+ * injected instance rather than module-level state it is ordinary to
+ * construct, and several can exist side by side in a test file.
+ *
+ * It holds no database machinery on purpose. Verifying that a connection
+ * actually works belongs to ConnectionManager, which keeps this class free of
+ * I/O and trivially testable.
+ */
+export class ConnectionRegistry {
+    profiles = new Map();
+    activeName = null;
+    activeTarget = null;
+    constructor(profiles = []) {
+        for (const profile of profiles) {
+            this.profiles.set(profile.name, profile);
+        }
+    }
+    /**
+     * Choose the starting connection, in order of preference:
+     * the requested name, a profile called `default`, then the first defined.
+     *
+     * @returns a warning when the requested name does not exist, else null.
+     *   A typo should not stop the server; saying so and carrying on is more
+     *   useful than refusing to start.
+     */
+    selectInitial(preferredName) {
+        if (preferredName && this.profiles.has(preferredName)) {
+            this.activateProfile(preferredName);
+            return null;
+        }
+        const warning = preferredName
+            ? `The default profile "${preferredName}" does not match any profile.`
+            : null;
+        if (this.profiles.has("default")) {
+            this.activateProfile("default");
+            return warning;
+        }
+        const first = this.profiles.keys().next();
+        if (!first.done) {
+            this.activateProfile(first.value);
+        }
+        return warning;
+    }
+    /** Insertion order, which is what makes "the first profile" meaningful. */
+    list() {
+        return Array.from(this.profiles.values());
+    }
+    names() {
+        return Array.from(this.profiles.keys());
+    }
+    find(profileName) {
+        return this.profiles.get(profileName);
+    }
+    has(profileName) {
+        return this.profiles.has(profileName);
+    }
+    /**
+     * Register an alias opened at runtime. An existing name is replaced, so
+     * reconnecting with corrected credentials fixes the entry rather than
+     * failing.
+     */
+    register(profile) {
+        this.profiles.set(profile.name, profile);
+    }
+    getActiveTarget() {
+        return this.activeTarget;
+    }
+    getActiveName() {
+        return this.activeName;
+    }
+    /**
+     * @throws NoActiveConnectionError whose message names both ways out. Tool
+     *   handlers convert it to a tool result, so that message is what the user
+     *   reads.
+     */
+    requireActiveTarget() {
+        if (!this.activeTarget) {
+            throw new NoActiveConnectionError();
+        }
+        return this.activeTarget;
+    }
+    /** @throws UnknownProfileError listing the names that do exist. */
+    activateProfile(profileName) {
+        const profile = this.profiles.get(profileName);
+        if (!profile) {
+            throw new UnknownProfileError(profileName, this.names());
+        }
+        this.activeName = profile.name;
+        this.activeTarget = profile.target;
+        return this.activeTarget;
+    }
+    /**
+     * Point at an explicit target under a label.
+     *
+     * No defensive copy is needed because ConnectionTarget is immutable: nothing
+     * downstream can mutate the active target into corrupting the profile it
+     * came from.
+     */
+    activateTarget(target, label) {
+        this.activeName = label;
+        this.activeTarget = target;
+        return target;
+    }
+}

package/dist/connections/ConnectionTargetFactory.js

@@ -0,0 +1,104 @@
+import { resolve } from "node:path";
+import { ConnectionTarget } from "../domain/ConnectionTarget.js";
+import { InvalidProfileDefinitionError } from "../errors/InvalidProfileDefinitionError.js";
+import { ConnectionUrlParser } from "./ConnectionUrlParser.js";
+/**
+ * Builds ConnectionTarget instances from untrusted input.
+ *
+ * A Factory rather than a constructor because the input arrives in three
+ * shapes (a URL, a legacy MYSQL_PROFILES object, and the legacy MYSQL_*
+ * variables) and every one has to be checked and defaulted the same way.
+ * Keeping all three here means they cannot drift apart in what they accept.
+ */
+export class ConnectionTargetFactory {
+    parser;
+    resolvePath;
+    /**
+     * The legacy MYSQL_* form's default host.
+     *
+     * `localhost` inside a container means the container itself, which is the
+     * single most common mistake when the database runs on the host. Kept from
+     * the MySQL-only server so an existing configuration behaves identically.
+     * URLs always name their host, so this never applies to them.
+     */
+    static DEFAULT_MYSQL_HOST = "host.docker.internal";
+    static DEFAULT_MYSQL_PORT = 3306;
+    /**
+     * @param resolvePath turns a SQLite path absolute. Injected so tests do not
+     *   depend on the directory they run from.
+     */
+    constructor(parser = new ConnectionUrlParser(), resolvePath = (path) => resolve(path)) {
+        this.parser = parser;
+        this.resolvePath = resolvePath;
+    }
+    /**
+     * @param password used instead of the URL's own password when non-empty, so
+     *   a password full of `@`, `/` and `#` never needs percent-encoding.
+     * @throws InvalidConnectionUrlError describing the problem without the URL.
+     */
+    fromUrl(url, password) {
+        const props = this.parser.parse(url);
+        // A SQLite path is made absolute once, here, so the same file reached as
+        // `./app.db` and `/work/app.db` is recognised as one connection, and so a
+        // later change of working directory cannot repoint it.
+        const database = props.engine === "sqlite" ? this.resolvePath(props.database) : props.database;
+        return new ConnectionTarget({
+            ...props,
+            password: password ? password : props.password,
+            database,
+        });
+    }
+    /**
+     * One entry of the legacy MYSQL_PROFILES object form.
+     *
+     * @throws InvalidProfileDefinitionError when user or database is missing.
+     *   The caller turns this into a warning; one broken profile must not stop
+     *   the server from starting.
+     */
+    fromMySqlDefinition(raw, profileName) {
+        const user = this.readString(raw.user);
+        const database = this.readString(raw.database);
+        if (!user) {
+            throw new InvalidProfileDefinitionError(profileName, 'is missing "user".');
+        }
+        if (!database) {
+            throw new InvalidProfileDefinitionError(profileName, 'is missing "database".');
+        }
+        return this.fromMySqlValues({
+            host: this.readString(raw.host),
+            port: this.readPort(raw.port),
+            user,
+            password: this.readString(raw.password),
+            database,
+        });
+    }
+    /** Builds a MySQL target from already-trusted values, applying the legacy defaults. */
+    fromMySqlValues(values) {
+        return new ConnectionTarget({
+            engine: "mysql",
+            scheme: "mysql",
+            hosts: [
+                {
+                    host: values.host || ConnectionTargetFactory.DEFAULT_MYSQL_HOST,
+                    port: values.port ?? ConnectionTargetFactory.DEFAULT_MYSQL_PORT,
+                },
+            ],
+            user: values.user,
+            password: values.password ?? "",
+            database: values.database,
+            options: {},
+            secretOptions: {},
+        });
+    }
+    readString(value) {
+        return typeof value === "string" ? value : "";
+    }
+    /**
+     * Only a real number is accepted. A port given as the string "3306" falls
+     * back to the default rather than becoming NaN and failing much later with
+     * an unrecognisable error.
+     */
+    readPort(value) {
+        return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+    }
+}