@gizmodata/gizmosql-mcp 0.1.0

package/dist/sql-guard.js

@@ -0,0 +1,429 @@
+// Read-only classification and result-limit wrapping for SQL text.
+//
+// This is defense in depth, not the security boundary: the GizmoSQL
+// user's database-level role/privileges are the real boundary (see the
+// README). The classifier is deliberately conservative — anything it
+// cannot confidently classify as a read is rejected when writes are
+// disabled.
+/** Leading keywords that are always reads and can be wrapped in a subquery. */
+const WRAPPABLE_READ_KEYWORDS = new Set([
+    "SELECT",
+    "FROM", // DuckDB FROM-first syntax
+    "VALUES",
+    "SHOW",
+    "DESCRIBE",
+    "DESC",
+    "SUMMARIZE",
+    "TABLE", // `TABLE t` is shorthand for SELECT * FROM t
+]);
+/** Leading keywords that are reads but cannot be used as a subquery. */
+const UNWRAPPABLE_READ_KEYWORDS = new Set(["EXPLAIN", "PRAGMA"]);
+/** Everything here is a write / side-effecting statement. */
+const WRITE_KEYWORDS = new Set([
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "MERGE",
+    "UPSERT",
+    "REPLACE",
+    "TRUNCATE",
+    "CREATE",
+    "DROP",
+    "ALTER",
+    "RENAME",
+    "COPY",
+    "EXPORT",
+    "IMPORT",
+    "ATTACH",
+    "DETACH",
+    "INSTALL",
+    "FORCE", // FORCE INSTALL / FORCE CHECKPOINT
+    "LOAD",
+    "SET",
+    "RESET",
+    "USE",
+    "CALL",
+    "BEGIN",
+    "START",
+    "COMMIT",
+    "ROLLBACK",
+    "ABORT",
+    "END",
+    "CHECKPOINT",
+    "VACUUM",
+    "ANALYZE",
+    "GRANT",
+    "REVOKE",
+    "KILL",
+    "COMMENT",
+    "PIVOT",
+    "UNPIVOT",
+]);
+// PIVOT/UNPIVOT are reads in DuckDB, but they are rewritten by the
+// binder into multiple internal statements and cannot be prepared with
+// parameters or reliably wrapped; treat them as unclassifiable rather
+// than as writes.
+WRITE_KEYWORDS.delete("PIVOT");
+WRITE_KEYWORDS.delete("UNPIVOT");
+/**
+ * Removes SQL comments (`-- ...`, `/* ... *\/` with nesting) while
+ * preserving string literals, quoted identifiers and dollar-quoted
+ * strings. Comments are replaced by a single space so offsets stay
+ * meaningful for error messages.
+ */
+export function stripComments(sql) {
+    let out = "";
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (ch === "'") {
+            // single-quoted string with '' escapes
+            let j = i + 1;
+            while (j < n) {
+                if (sql[j] === "'") {
+                    if (sql[j + 1] === "'") {
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                j++;
+            }
+            out += sql.slice(i, j + 1);
+            i = j + 1;
+            continue;
+        }
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < n) {
+                if (sql[j] === '"') {
+                    if (sql[j + 1] === '"') {
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                j++;
+            }
+            out += sql.slice(i, j + 1);
+            i = j + 1;
+            continue;
+        }
+        if (ch === "$") {
+            // dollar-quoted string: $tag$ ... $tag$
+            const m = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i));
+            if (m) {
+                const delim = m[0];
+                const end = sql.indexOf(delim, i + delim.length);
+                const stop = end === -1 ? n : end + delim.length;
+                out += sql.slice(i, stop);
+                i = stop;
+                continue;
+            }
+        }
+        if (ch === "-" && next === "-") {
+            let j = i + 2;
+            while (j < n && sql[j] !== "\n")
+                j++;
+            out += " ";
+            i = j;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            let depth = 1;
+            let j = i + 2;
+            while (j < n && depth > 0) {
+                if (sql[j] === "/" && sql[j + 1] === "*") {
+                    depth++;
+                    j += 2;
+                }
+                else if (sql[j] === "*" && sql[j + 1] === "/") {
+                    depth--;
+                    j += 2;
+                }
+                else {
+                    j++;
+                }
+            }
+            out += " ";
+            i = j;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+/** Tokenizes comment-stripped SQL into words, punctuation and literals. */
+function tokenize(sql) {
+    const tokens = [];
+    let i = 0;
+    const n = sql.length;
+    while (i < n) {
+        const ch = sql[i];
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        if (ch === "'") {
+            let j = i + 1;
+            while (j < n) {
+                if (sql[j] === "'") {
+                    if (sql[j + 1] === "'") {
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                j++;
+            }
+            tokens.push({ text: sql.slice(i, j + 1), kind: "string", start: i });
+            i = j + 1;
+            continue;
+        }
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < n) {
+                if (sql[j] === '"') {
+                    if (sql[j + 1] === '"') {
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                j++;
+            }
+            tokens.push({ text: sql.slice(i, j + 1), kind: "quoted", start: i });
+            i = j + 1;
+            continue;
+        }
+        if (ch === "$") {
+            const m = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i));
+            if (m) {
+                const delim = m[0];
+                const end = sql.indexOf(delim, i + delim.length);
+                const stop = end === -1 ? n : end + delim.length;
+                tokens.push({ text: sql.slice(i, stop), kind: "string", start: i });
+                i = stop;
+                continue;
+            }
+        }
+        const word = /^[A-Za-z_][A-Za-z0-9_$]*/.exec(sql.slice(i));
+        if (word) {
+            tokens.push({ text: word[0].toUpperCase(), kind: "word", start: i });
+            i += word[0].length;
+            continue;
+        }
+        tokens.push({ text: ch, kind: "punct", start: i });
+        i++;
+    }
+    return tokens;
+}
+/**
+ * Splits SQL into top-level statements on semicolons that are outside
+ * strings, quoted identifiers and comments. Empty statements (e.g. from a
+ * trailing semicolon) are dropped.
+ */
+export function splitStatements(sql) {
+    const stripped = stripComments(sql);
+    const tokens = tokenize(stripped);
+    const statements = [];
+    let start = 0;
+    for (const t of tokens) {
+        if (t.kind === "punct" && t.text === ";") {
+            const piece = stripped.slice(start, t.start).trim();
+            if (piece)
+                statements.push(piece);
+            start = t.start + 1;
+        }
+    }
+    const tail = stripped.slice(start).trim();
+    if (tail)
+        statements.push(tail);
+    return statements;
+}
+/**
+ * Returns the statement with comments removed and any trailing
+ * semicolons stripped, ready to be wrapped in a subquery.
+ */
+export function normalizeStatement(sql) {
+    return stripComments(sql).trim().replace(/;+\s*$/u, "").trim();
+}
+/** Index of the token that closes the parenthesis opened at `open`. */
+function matchParen(tokens, open) {
+    let depth = 0;
+    for (let i = open; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.kind !== "punct")
+            continue;
+        if (t.text === "(")
+            depth++;
+        else if (t.text === ")") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Given tokens starting at a `WITH`, returns the index of the first token
+ * of the main statement that follows the CTE list, or -1 if the CTE list
+ * cannot be parsed.
+ */
+function skipCteList(tokens, withIndex) {
+    let i = withIndex + 1;
+    if (tokens[i]?.text === "RECURSIVE")
+        i++;
+    for (;;) {
+        // cte name
+        const name = tokens[i];
+        if (!name || (name.kind !== "word" && name.kind !== "quoted"))
+            return -1;
+        i++;
+        // optional column list
+        if (tokens[i]?.kind === "punct" && tokens[i].text === "(") {
+            const close = matchParen(tokens, i);
+            if (close === -1)
+                return -1;
+            i = close + 1;
+        }
+        if (tokens[i]?.text !== "AS")
+            return -1;
+        i++;
+        if (tokens[i]?.text === "NOT")
+            i++;
+        if (tokens[i]?.text === "MATERIALIZED")
+            i++;
+        if (!(tokens[i]?.kind === "punct" && tokens[i].text === "("))
+            return -1;
+        const close = matchParen(tokens, i);
+        if (close === -1)
+            return -1;
+        i = close + 1;
+        if (tokens[i]?.kind === "punct" && tokens[i].text === ",") {
+            i++;
+            continue;
+        }
+        return i < tokens.length ? i : -1;
+    }
+}
+/**
+ * Classifies a single SQL statement by its leading keyword, looking
+ * through leading parentheses and CTE lists to find the statement that
+ * actually executes.
+ */
+export function classifyStatement(sql) {
+    const tokens = tokenize(stripComments(sql));
+    let i = 0;
+    let sawWith = false;
+    for (let guard = 0; guard < 64 && i < tokens.length; guard++) {
+        const t = tokens[i];
+        if (t.kind === "punct" && t.text === "(") {
+            // `(SELECT ...) UNION (SELECT ...)` — classify the inner statement.
+            i++;
+            continue;
+        }
+        if (t.kind !== "word") {
+            return { kind: "unknown", keyword: t.text, wrappable: false };
+        }
+        if (t.text === "WITH") {
+            sawWith = true;
+            const main = skipCteList(tokens, i);
+            if (main === -1) {
+                return { kind: "unknown", keyword: "WITH", wrappable: false };
+            }
+            i = main;
+            continue;
+        }
+        if (WRAPPABLE_READ_KEYWORDS.has(t.text)) {
+            return { kind: "read", keyword: sawWith ? "WITH" : t.text, wrappable: true };
+        }
+        if (UNWRAPPABLE_READ_KEYWORDS.has(t.text)) {
+            if (t.text === "PRAGMA") {
+                // `PRAGMA name` / `PRAGMA fn(args)` are reads; `PRAGMA x = y` mutates settings.
+                const hasAssignment = tokens
+                    .slice(i + 1)
+                    .some((tok) => tok.kind === "punct" && tok.text === "=");
+                if (hasAssignment) {
+                    return { kind: "write", keyword: "PRAGMA", wrappable: false };
+                }
+            }
+            if (t.text === "EXPLAIN") {
+                // EXPLAIN of a write is a read (it never executes), but keep it
+                // conservative: classify the explained statement instead.
+                let j = i + 1;
+                if (tokens[j]?.text === "ANALYZE")
+                    j++;
+                if (tokens[j]?.kind === "punct" && tokens[j].text === "(") {
+                    // EXPLAIN (FORMAT ...) options
+                    const close = matchParen(tokens, j);
+                    if (close !== -1)
+                        j = close + 1;
+                }
+                const inner = classifyStatement(stripComments(sql).slice(tokens[j]?.start ?? sql.length));
+                return { kind: inner.kind, keyword: "EXPLAIN", wrappable: false };
+            }
+            return { kind: "read", keyword: t.text, wrappable: false };
+        }
+        if (WRITE_KEYWORDS.has(t.text)) {
+            return { kind: "write", keyword: t.text, wrappable: false };
+        }
+        return { kind: "unknown", keyword: t.text, wrappable: false };
+    }
+    return { kind: "unknown", keyword: "", wrappable: false };
+}
+export class SqlGuardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SqlGuardError";
+    }
+}
+/**
+ * Validates that `sql` is exactly one statement and, when writes are
+ * disabled, that it is a read. Throws {@link SqlGuardError} otherwise.
+ */
+export function guardStatement(sql, allowWrites) {
+    if (typeof sql !== "string" || !sql.trim()) {
+        throw new SqlGuardError("SQL statement is empty.");
+    }
+    const statements = splitStatements(sql);
+    if (statements.length === 0) {
+        throw new SqlGuardError("SQL statement is empty (only comments/semicolons).");
+    }
+    if (statements.length > 1) {
+        throw new SqlGuardError(`Only one SQL statement per call is allowed (found ${statements.length}). ` +
+            "Split the statements into separate calls.");
+    }
+    const single = normalizeStatement(statements[0]);
+    const classification = classifyStatement(single);
+    if (!allowWrites) {
+        if (classification.kind === "write") {
+            throw new SqlGuardError(`Statement type ${classification.keyword} is not allowed: this server is read-only ` +
+                "(GIZMOSQL_ALLOW_WRITES is not enabled). Only SELECT/WITH/FROM/VALUES/SHOW/" +
+                "DESCRIBE/SUMMARIZE/EXPLAIN/PRAGMA (read) statements are permitted.");
+        }
+        if (classification.kind === "unknown") {
+            throw new SqlGuardError(`Unable to classify statement starting with "${classification.keyword || single.slice(0, 20)}" ` +
+                "as read-only; this server is read-only (GIZMOSQL_ALLOW_WRITES is not enabled). " +
+                "Rewrite it as a SELECT/WITH query.");
+        }
+    }
+    return { sql: single, classification };
+}
+/** Alias used by the query wrapper so it never collides with user aliases. */
+export const WRAPPER_ALIAS = "gizmosql_mcp_q";
+/**
+ * Wraps a read statement so the server enforces the row cap:
+ * `SELECT * FROM (<sql>) AS gizmosql_mcp_q LIMIT <limit>`.
+ * The caller must pass a normalized (comment-free, no trailing `;`) statement.
+ */
+export function wrapWithLimit(sql, limit) {
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new SqlGuardError(`Row limit must be a positive integer (got ${limit}).`);
+    }
+    return `SELECT * FROM (\n${sql}\n) AS ${WRAPPER_ALIAS} LIMIT ${limit}`;
+}
+//# sourceMappingURL=sql-guard.js.map

package/dist/sql-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guard.js","sourceRoot":"","sources":["../src/sql-guard.ts"],"names":[],"mappings":"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"}

package/dist/sso.d.ts

@@ -0,0 +1,22 @@
+import type { GizmoConnection } from "./connection.js";
+export interface SsoOptions {
+    waitSeconds: number;
+    pollIntervalMs?: number;
+    /** Test hook: replaces the browser opener. */
+    openUrl?: (url: string) => Promise<void>;
+    /** Test hook: replaces HTTP GET JSON. */
+    getJson?: (url: string, tlsSkipVerify: boolean) => Promise<Record<string, unknown>>;
+    /** Test hook: replaces OAuth URL discovery. */
+    discover?: () => Promise<string | null>;
+}
+export interface SsoOutcome {
+    status: "complete" | "pending" | "unavailable" | "error";
+    message: string;
+    authUrl?: string;
+}
+/** GET a JSON document (small helper so the flow works without extra dependencies). */
+export declare function httpGetJson(url: string, tlsSkipVerify: boolean): Promise<Record<string, unknown>>;
+/** Opens a URL in the user's default browser without any extra dependency. */
+export declare function openInBrowser(url: string): Promise<void>;
+/** Runs (or resumes) the SSO login flow for the shared connection. */
+export declare function runSsoLogin(connection: GizmoConnection, options: SsoOptions): Promise<SsoOutcome>;

package/dist/sso.js

@@ -0,0 +1,143 @@
+// Optional OAuth/SSO browser login (enabled with GIZMOSQL_ENABLE_SSO=true).
+//
+// Flow (see the gizmosql-client README and the Go driver's oauth.go):
+//   GET {oauthUrl}/oauth/initiate            -> { session_uuid, auth_url }
+//   open auth_url in the user's browser
+//   poll GET {oauthUrl}/oauth/token/{uuid}   -> { status: pending|complete|error|not_found, token? }
+//   reconnect with username "token" / password <identity token>
+// The token lives in process memory only.
+import { spawn } from "node:child_process";
+import * as http from "node:http";
+import * as https from "node:https";
+const pendingSessions = new WeakMap();
+/** GET a JSON document (small helper so the flow works without extra dependencies). */
+export function httpGetJson(url, tlsSkipVerify) {
+    return new Promise((resolve, reject) => {
+        const lib = url.startsWith("https") ? https : http;
+        const req = lib.get(url, url.startsWith("https") ? { rejectUnauthorized: !tlsSkipVerify, timeout: 10000 } : { timeout: 10000 }, (res) => {
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => (body += chunk));
+            res.on("end", () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    reject(new Error(`Unexpected non-JSON response (HTTP ${res.statusCode}) from ${url}`));
+                }
+            });
+        });
+        req.on("timeout", () => {
+            req.destroy(new Error(`Timed out contacting ${url}`));
+        });
+        req.on("error", reject);
+    });
+}
+/** Opens a URL in the user's default browser without any extra dependency. */
+export function openInBrowser(url) {
+    return new Promise((resolve, reject) => {
+        let cmd;
+        let args;
+        if (process.platform === "darwin") {
+            cmd = "open";
+            args = [url];
+        }
+        else if (process.platform === "win32") {
+            cmd = "rundll32";
+            args = ["url.dll,FileProtocolHandler", url];
+        }
+        else {
+            cmd = "xdg-open";
+            args = [url];
+        }
+        try {
+            const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+            child.on("error", reject);
+            child.on("spawn", () => {
+                child.unref();
+                resolve();
+            });
+        }
+        catch (err) {
+            reject(err);
+        }
+    });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Runs (or resumes) the SSO login flow for the shared connection. */
+export async function runSsoLogin(connection, options) {
+    const tlsSkipVerify = connection.config.tlsSkipVerify;
+    const getJson = options.getJson ?? httpGetJson;
+    const openUrl = options.openUrl ?? openInBrowser;
+    const pollIntervalMs = options.pollIntervalMs ?? 1000;
+    let session = pendingSessions.get(connection);
+    if (!session || Date.now() - session.startedAt > 10 * 60 * 1000) {
+        const discover = options.discover ?? (() => connection.run((c) => c.discoverOAuthUrl(), { timeoutSeconds: 30 }));
+        const baseUrl = await discover();
+        if (!baseUrl) {
+            return {
+                status: "unavailable",
+                message: "The GizmoSQL server does not expose OAuth/SSO (no /oauth/initiate endpoint on port " +
+                    `${connection.config.oauthPort}). Configure username/password or a token instead.`,
+            };
+        }
+        const init = await getJson(`${baseUrl}/oauth/initiate`, tlsSkipVerify);
+        const sessionUuid = typeof init.session_uuid === "string" ? init.session_uuid : "";
+        const authUrl = typeof init.auth_url === "string" ? init.auth_url : "";
+        if (!sessionUuid || !authUrl) {
+            return { status: "error", message: `Unexpected response from /oauth/initiate: ${JSON.stringify(init)}` };
+        }
+        session = { baseUrl, sessionUuid, authUrl, startedAt: Date.now() };
+        pendingSessions.set(connection, session);
+        try {
+            await openUrl(authUrl);
+        }
+        catch {
+            // The URL is returned in the message so the user can open it manually.
+        }
+    }
+    const deadline = Date.now() + options.waitSeconds * 1000;
+    const pollUrl = `${session.baseUrl}/oauth/token/${session.sessionUuid}`;
+    while (Date.now() < deadline) {
+        const data = await getJson(pollUrl, tlsSkipVerify);
+        const status = typeof data.status === "string" ? data.status : "";
+        if (status === "complete") {
+            const token = typeof data.token === "string" ? data.token : "";
+            pendingSessions.delete(connection);
+            if (!token) {
+                return { status: "error", message: "Token poll returned 'complete' but no token." };
+            }
+            await connection.useCredentials({ username: "token", password: token });
+            try {
+                await connection.query("SELECT 1");
+            }
+            catch (err) {
+                return {
+                    status: "error",
+                    message: `Signed in, but reconnecting with the identity token failed: ${connection.redact(err instanceof Error ? err.message : String(err))}`,
+                };
+            }
+            return { status: "complete", message: "Signed in with SSO. Subsequent queries use your identity token." };
+        }
+        if (status === "error") {
+            pendingSessions.delete(connection);
+            return { status: "error", message: `OAuth flow failed: ${String(data.error ?? "unknown error")}` };
+        }
+        if (status === "not_found") {
+            pendingSessions.delete(connection);
+            return { status: "error", message: "OAuth session not found (it may have expired). Call login_sso again." };
+        }
+        if (status !== "pending") {
+            pendingSessions.delete(connection);
+            return { status: "error", message: `Unexpected token poll status: ${JSON.stringify(status)}` };
+        }
+        await sleep(pollIntervalMs);
+    }
+    return {
+        status: "pending",
+        authUrl: session.authUrl,
+        message: "Waiting for you to finish signing in. A browser window should have opened; if not, open this URL: " +
+            `${session.authUrl}\nThen call login_sso again to complete the sign-in.`,
+    };
+}
+//# sourceMappingURL=sso.js.map

package/dist/sso.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso.js","sourceRoot":"","sources":["../src/sso.ts"],"names":[],"mappings":"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"}

package/dist/transports.d.ts

@@ -0,0 +1,18 @@
+import * as http from "node:http";
+import { type McpConfig } from "./connection.js";
+/** Runs the server on stdio (Claude Desktop / `claude mcp add`). */
+export declare function startStdio(config: McpConfig): Promise<void>;
+export interface HttpOptions {
+    host: string;
+    port: number;
+}
+/**
+ * Runs the server as stateless Streamable HTTP on `/mcp`. Every request
+ * gets its own McpServer + transport (the SDK's stateless pattern) while
+ * sharing the single GizmoSQL connection.
+ *
+ * Authentication: when GIZMOSQL_MCP_BEARER_TOKEN is set every request must
+ * carry `Authorization: Bearer <token>`. OAuth is a future extension point:
+ * replace `authorize()` with an OAuth token verifier.
+ */
+export declare function startHttp(config: McpConfig, options: HttpOptions): Promise<http.Server>;