@ecubelabs/mysql-mcp 0.0.0-stage → 0.0.1

package/dist/src/db/index.js

@@ -0,0 +1,461 @@
+import { performance } from 'perf_hooks';
+import * as mysql2 from 'mysql2/promise';
+import { mcpConfig as config, describeConfiguredTarget, SSH_ENABLED, MYSQL_PROFILE, PROFILE_LABEL, CODE_BRANCH, IS_WRITE_FORBIDDEN_PROFILE, MYSQL_DISABLE_READ_ONLY_TRANSACTIONS, MYSQL_DEFAULT_TIMEOUT_SECONDS, MYSQL_MAX_TIMEOUT_SECONDS, MYSQL_CATALOG_TIMEOUT_SECONDS, MAX_RESPONSE_ROWS, } from './../config/index.js';
+import { isDDLAllowedForSchema, isInsertAllowedForSchema, isUpdateAllowedForSchema, isDeleteAllowedForSchema, } from './permissions.js';
+import { extractReferencedSchemas, findFileExport, findUnsupportedStatementType, getQueryTypes, isUnparseableIntrospection, extractQualifiers, } from './utils.js';
+import { isQueryTimeoutError, parseExplainPayload, renderTimeoutDiagnostic } from './diagnose.js';
+import { log } from './../utils/index.js';
+import { ensureTunnel, getTunnelEndpoint, getTunnelFatalError, describeTunnel } from './../ssh/tunnel.js';
+let poolPromise;
+const READ_LIMITS = {
+    maxExecutionTimeMs: MYSQL_DEFAULT_TIMEOUT_SECONDS * 1_000,
+    selectLimit: MAX_RESPONSE_ROWS + 1,
+};
+const CATALOG_LIMITS = {
+    maxExecutionTimeMs: MYSQL_CATALOG_TIMEOUT_SECONDS * 1_000,
+    selectLimit: null,
+};
+const SESSION_LIMITS = Symbol.for('mysql-mcp.sessionLimits');
+function limitCarrier(connection) {
+    const inner = connection?.connection;
+    return (inner ?? connection);
+}
+function limitsStatement(limits) {
+    const selectLimit = limits.selectLimit === null ? 'DEFAULT' : String(limits.selectLimit);
+    return (`SET SESSION max_execution_time = ${limits.maxExecutionTimeMs}, ` + `SESSION sql_select_limit = ${selectLimit}`);
+}
+function sameLimits(a, b) {
+    return a !== undefined && a.maxExecutionTimeMs === b.maxExecutionTimeMs && a.selectLimit === b.selectLimit;
+}
+async function applySessionLimits(connection, desired) {
+    const carrier = limitCarrier(connection);
+    if (sameLimits(carrier[SESSION_LIMITS], desired)) {
+        return 0;
+    }
+    try {
+        await connection.query(limitsStatement(desired));
+        carrier[SESSION_LIMITS] = desired;
+    }
+    catch (error) {
+        delete carrier[SESSION_LIMITS];
+        log('error', 'Failed to apply session limits; continuing without them:', error);
+    }
+    return 1;
+}
+const getPool = () => {
+    if (!poolPromise) {
+        poolPromise = (async () => {
+            const endpoint = await ensureTunnel();
+            const mysqlConfig = endpoint
+                ? (() => {
+                    const { socketPath: _ignored, ...rest } = config.mysql;
+                    return { ...rest, host: endpoint.host, port: endpoint.port };
+                })()
+                : config.mysql;
+            const pool = mysql2.createPool(mysqlConfig);
+            pool.on('connection', (connection) => {
+                const carrier = limitCarrier(connection);
+                const raw = connection;
+                carrier[SESSION_LIMITS] = READ_LIMITS;
+                raw.query(limitsStatement(READ_LIMITS), (error) => {
+                    if (!error) {
+                        return;
+                    }
+                    log('error', 'Failed to prime session limits on a new connection:', error);
+                    delete carrier[SESSION_LIMITS];
+                });
+            });
+            log('info', `MySQL pool created successfully (profile: ${PROFILE_LABEL}` +
+                (endpoint
+                    ? `, via ${endpoint.reused ? 'reused' : 'new'} tunnel ${endpoint.host}:${endpoint.port}`
+                    : '') +
+                ')');
+            return pool;
+        })();
+        poolPromise.catch((error) => {
+            log('error', 'Error creating MySQL pool:', error);
+            poolPromise = undefined;
+        });
+    }
+    return poolPromise;
+};
+function describeQueryError(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const { code, errno, sqlState, sql } = error;
+    if (sql !== undefined || sqlState !== undefined) {
+        return { code, errno, sqlState };
+    }
+    return error.message;
+}
+function assertTunnelHealthy() {
+    const fatal = getTunnelFatalError();
+    if (fatal) {
+        throw fatal;
+    }
+}
+function describeConnection() {
+    const endpoint = getTunnelEndpoint();
+    if (endpoint) {
+        return `${endpoint.host}:${endpoint.port} ` + `(${endpoint.reused ? 'reused' : 'new'} ssh tunnel)`;
+    }
+    const target = describeConfiguredTarget();
+    return SSH_ENABLED ? `${target} (via ssh tunnel, not yet established)` : target;
+}
+function profileBanner() {
+    const parts = [`profile: ${PROFILE_LABEL}`];
+    parts.push(IS_WRITE_FORBIDDEN_PROFILE ? 'READ-ONLY (enforced)' : 'read-only');
+    const db = config.mysql.database || 'multi-db';
+    parts.push(`database: ${db}`);
+    if (CODE_BRANCH) {
+        parts.push(`code: ${CODE_BRANCH} branch`);
+    }
+    const tunnel = describeTunnel();
+    if (tunnel) {
+        parts.push(tunnel);
+    }
+    return `[${parts.join(' | ')}]`;
+}
+async function executeQuery(sql, params = []) {
+    let connection;
+    try {
+        assertTunnelHealthy();
+        const pool = await getPool();
+        connection = await pool.getConnection();
+        await applySessionLimits(connection, CATALOG_LIMITS);
+        const result = await connection.query(sql, params);
+        return (Array.isArray(result) ? result[0] : result);
+    }
+    catch (error) {
+        log('error', 'Error executing query:', error);
+        throw error;
+    }
+    finally {
+        if (connection) {
+            try {
+                await applySessionLimits(connection, READ_LIMITS);
+            }
+            catch (restoreError) {
+                log('error', 'Error restoring session limits:', restoreError);
+            }
+            connection.release();
+            log('error', 'Connection released');
+        }
+    }
+}
+async function executeWriteQuery(sql) {
+    let connection;
+    if (IS_WRITE_FORBIDDEN_PROFILE) {
+        log('error', `Refusing write operation: profile "${MYSQL_PROFILE}" is read-only by policy.`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${profileBanner()} Error: write operations are disabled by policy for profile "${MYSQL_PROFILE}". ` +
+                        `This cannot be enabled through configuration.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        assertTunnelHealthy();
+        const pool = await getPool();
+        connection = await pool.getConnection();
+        log('error', 'Write connection acquired');
+        const schema = (extractReferencedSchemas(sql) ?? [null]).map((name) => name ?? 'default').join(', ');
+        await connection.beginTransaction();
+        try {
+            const startTime = performance.now();
+            const result = await connection.query(sql);
+            const endTime = performance.now();
+            const duration = endTime - startTime;
+            const response = Array.isArray(result) ? result[0] : result;
+            await connection.commit();
+            let responseText;
+            const queryTypes = await getQueryTypes(sql);
+            const isUpdateOperation = queryTypes.some((type) => ['update'].includes(type));
+            const isInsertOperation = queryTypes.some((type) => ['insert'].includes(type));
+            const isDeleteOperation = queryTypes.some((type) => ['delete'].includes(type));
+            const isDDLOperation = queryTypes.some((type) => ['create', 'alter', 'drop', 'truncate'].includes(type));
+            if (isInsertOperation) {
+                const resultHeader = response;
+                responseText = `Insert successful on schema '${schema}'. Affected rows: ${resultHeader.affectedRows}, Last insert ID: ${resultHeader.insertId}`;
+            }
+            else if (isUpdateOperation) {
+                const resultHeader = response;
+                responseText = `Update successful on schema '${schema}'. Affected rows: ${resultHeader.affectedRows}, Changed rows: ${resultHeader.changedRows || 0}`;
+            }
+            else if (isDeleteOperation) {
+                const resultHeader = response;
+                responseText = `Delete successful on schema '${schema}'. Affected rows: ${resultHeader.affectedRows}`;
+            }
+            else if (isDDLOperation) {
+                responseText = `DDL operation successful on schema '${schema}'.`;
+            }
+            else {
+                responseText = JSON.stringify(response, null, 2);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: responseText,
+                    },
+                    {
+                        type: 'text',
+                        text: `Query execution time: ${duration.toFixed(2)} ms`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            log('error', 'Error executing write query:', describeQueryError(error));
+            await connection.rollback();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error executing write operation: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    catch (error) {
+        log('error', 'Error in write operation transaction:', describeQueryError(error));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Database connection error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    finally {
+        if (connection) {
+            connection.release();
+            log('error', 'Write connection released');
+        }
+    }
+}
+let diagnosticsSource = null;
+function setQueryDiagnosticsSource(source) {
+    diagnosticsSource = source;
+}
+function clampTimeoutSeconds(requested) {
+    let value;
+    if (typeof requested === 'number') {
+        value = requested;
+    }
+    else if (typeof requested === 'string') {
+        const trimmed = requested.trim();
+        if (trimmed === '') {
+            return MYSQL_DEFAULT_TIMEOUT_SECONDS;
+        }
+        value = Number(trimmed);
+    }
+    else {
+        return MYSQL_DEFAULT_TIMEOUT_SECONDS;
+    }
+    if (!Number.isFinite(value)) {
+        return MYSQL_DEFAULT_TIMEOUT_SECONDS;
+    }
+    return Math.min(Math.max(Math.floor(value), 1), MYSQL_MAX_TIMEOUT_SECONDS);
+}
+async function diagnoseTimeout(connection, sql, timeoutSeconds) {
+    let plan = null;
+    try {
+        const explained = await connection.query(`EXPLAIN FORMAT=JSON ${sql}`);
+        plan = parseExplainPayload(Array.isArray(explained) ? explained[0] : explained);
+    }
+    catch (error) {
+        log('error', 'Could not EXPLAIN the timed-out query:', describeQueryError(error));
+    }
+    const qualifiers = extractQualifiers(sql);
+    const source = diagnosticsSource;
+    return renderTimeoutDiagnostic({
+        timeoutSeconds,
+        maxTimeoutSeconds: MYSQL_MAX_TIMEOUT_SECONDS,
+        plan,
+        qualifiers,
+        lookupIndexes: (name) => {
+            if (!source) {
+                return null;
+            }
+            const resolved = qualifiers.get(name.toLowerCase());
+            return source.indexFacts(resolved ?? { schema: null, table: name });
+        },
+    });
+}
+async function executeReadOnlyQuery(sql, options = {}) {
+    let connection;
+    try {
+        assertTunnelHealthy();
+        const bypassesQueryTypeChecks = isUnparseableIntrospection(sql);
+        let queryTypes = [];
+        let isUpdateOperation = false;
+        let isInsertOperation = false;
+        let isDeleteOperation = false;
+        let isDDLOperation = false;
+        if (!bypassesQueryTypeChecks) {
+            queryTypes = await getQueryTypes(sql);
+            const unsupported = findUnsupportedStatementType(queryTypes);
+            if (unsupported) {
+                const statement = unsupported.toUpperCase();
+                log('error', `Refusing ${statement} statement: not a supported statement type.`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${statement} statements are not allowed. This server runs SELECT, SHOW, ` +
+                                `DESCRIBE and EXPLAIN, plus INSERT, UPDATE, DELETE and DDL where the profile's write ` +
+                                `permissions allow them. Qualify table names with their schema instead of USE.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const fileExport = findFileExport(sql);
+            if (fileExport) {
+                log('error', `Refusing SELECT ... ${fileExport}: it writes a file on the database server.`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: SELECT ... ${fileExport} is not allowed because it writes a file on the ` +
+                                `database server. Run the SELECT without it; rows come back in this response.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            isUpdateOperation = queryTypes.some((type) => ['update'].includes(type));
+            isInsertOperation = queryTypes.some((type) => ['insert'].includes(type));
+            isDeleteOperation = queryTypes.some((type) => ['delete'].includes(type));
+            isDDLOperation = queryTypes.some((type) => ['create', 'alter', 'drop', 'truncate'].includes(type));
+        }
+        const writeChecks = [
+            { enabled: isInsertOperation, label: 'INSERT', allowed: isInsertAllowedForSchema },
+            { enabled: isUpdateOperation, label: 'UPDATE', allowed: isUpdateAllowedForSchema },
+            { enabled: isDeleteOperation, label: 'DELETE', allowed: isDeleteAllowedForSchema },
+            { enabled: isDDLOperation, label: 'DDL', allowed: isDDLAllowedForSchema },
+        ].filter((check) => check.enabled);
+        if (writeChecks.length > 0) {
+            const schemas = extractReferencedSchemas(sql);
+            for (const check of writeChecks) {
+                const deniedIndex = schemas ? schemas.findIndex((name) => !check.allowed(name)) : 0;
+                if (deniedIndex === -1) {
+                    continue;
+                }
+                const target = schemas ? (schemas[deniedIndex] ?? 'default') : 'unknown';
+                const setting = `SCHEMA_${check.label}_PERMISSIONS`;
+                log('error', `${check.label} operations are not allowed for schema '${target}'. Configure ${setting}.`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${check.label} operations are not allowed for schema '${target}'. Ask the administrator to update ${setting}.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return executeWriteQuery(sql);
+        }
+        const pool = await getPool();
+        connection = await pool.getConnection();
+        log('error', 'Read-only connection acquired');
+        const timeoutSeconds = clampTimeoutSeconds(options.timeoutSeconds);
+        let roundTrips = await applySessionLimits(connection, {
+            maxExecutionTimeMs: timeoutSeconds * 1_000,
+            selectLimit: MAX_RESPONSE_ROWS + 1,
+        });
+        if (!MYSQL_DISABLE_READ_ONLY_TRANSACTIONS) {
+            await connection.query('START TRANSACTION READ ONLY');
+        }
+        else {
+            log('info', 'Read-only transactions disabled via MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true');
+            await connection.beginTransaction();
+        }
+        roundTrips += 1;
+        try {
+            const startTime = performance.now();
+            const result = await connection.query(sql);
+            const endTime = performance.now();
+            const duration = endTime - startTime;
+            roundTrips += 1;
+            let rows = Array.isArray(result) ? result[0] : result;
+            await connection.rollback();
+            roundTrips += 1;
+            log('info', `Read query completed in ${roundTrips} DB round trips`);
+            let truncated = false;
+            if (Array.isArray(rows) && rows.length > MAX_RESPONSE_ROWS) {
+                truncated = true;
+                rows = rows.slice(0, MAX_RESPONSE_ROWS);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(rows, null, 2),
+                    },
+                    ...(truncated
+                        ? [
+                            {
+                                type: 'text',
+                                text: `[TRUNCATED] Only the first ${MAX_RESPONSE_ROWS.toLocaleString('en-US')} rows are shown; ` +
+                                    `the query matched more. This is NOT the complete result - do not count, sum, or ` +
+                                    `conclude anything about totals from it. Add a narrower WHERE, an aggregate ` +
+                                    `(COUNT/SUM/GROUP BY), or paginate with ORDER BY + LIMIT/OFFSET. Raising the cap ` +
+                                    `is an operator change (MYSQL_MAX_RESPONSE_ROWS), not something to retry around.`,
+                            },
+                        ]
+                        : []),
+                    {
+                        type: 'text',
+                        text: `Query execution time: ${duration.toFixed(2)} ms`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            log('error', 'Error executing read-only query:', describeQueryError(error));
+            await connection.rollback();
+            if (isQueryTimeoutError(error)) {
+                const diagnostic = await diagnoseTimeout(connection, sql, timeoutSeconds);
+                log('info', `Read query cancelled at ${timeoutSeconds}s after ${roundTrips + 3} DB round trips (including one EXPLAIN)`);
+                return {
+                    content: [{ type: 'text', text: diagnostic }],
+                    isError: true,
+                };
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        log('error', 'Error in read-only query transaction:', describeQueryError(error));
+        try {
+            if (connection) {
+                await connection.rollback();
+            }
+        }
+        catch (cleanupError) {
+            log('error', 'Error during cleanup:', cleanupError);
+        }
+        throw error;
+    }
+    finally {
+        if (connection) {
+            connection.release();
+            log('error', 'Read-only connection released');
+        }
+    }
+}
+export { profileBanner, describeConnection, executeQuery, getPool, executeWriteQuery, executeReadOnlyQuery, setQueryDiagnosticsSource, clampTimeoutSeconds, describeQueryError, poolPromise, };

package/dist/src/db/permissions.js

@@ -0,0 +1,26 @@
+import { ALLOW_DELETE_OPERATION, ALLOW_DDL_OPERATION, ALLOW_INSERT_OPERATION, ALLOW_UPDATE_OPERATION, SCHEMA_DELETE_PERMISSIONS, SCHEMA_DDL_PERMISSIONS, SCHEMA_INSERT_PERMISSIONS, SCHEMA_UPDATE_PERMISSIONS, } from '../config/index.js';
+function isInsertAllowedForSchema(schema) {
+    if (!schema) {
+        return ALLOW_INSERT_OPERATION;
+    }
+    return schema in SCHEMA_INSERT_PERMISSIONS ? SCHEMA_INSERT_PERMISSIONS[schema] : ALLOW_INSERT_OPERATION;
+}
+function isUpdateAllowedForSchema(schema) {
+    if (!schema) {
+        return ALLOW_UPDATE_OPERATION;
+    }
+    return schema in SCHEMA_UPDATE_PERMISSIONS ? SCHEMA_UPDATE_PERMISSIONS[schema] : ALLOW_UPDATE_OPERATION;
+}
+function isDeleteAllowedForSchema(schema) {
+    if (!schema) {
+        return ALLOW_DELETE_OPERATION;
+    }
+    return schema in SCHEMA_DELETE_PERMISSIONS ? SCHEMA_DELETE_PERMISSIONS[schema] : ALLOW_DELETE_OPERATION;
+}
+function isDDLAllowedForSchema(schema) {
+    if (!schema) {
+        return ALLOW_DDL_OPERATION;
+    }
+    return schema in SCHEMA_DDL_PERMISSIONS ? SCHEMA_DDL_PERMISSIONS[schema] : ALLOW_DDL_OPERATION;
+}
+export { isInsertAllowedForSchema, isUpdateAllowedForSchema, isDeleteAllowedForSchema, isDDLAllowedForSchema };