@jessejoris/mcp-mysql-via-api 1.0.0

package/dist/api-client/mysqlApiClient.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MysqlApiClient = void 0;
+class MysqlApiClient {
+    endpoint;
+    apiKey;
+    timeoutMs;
+    defaultPageSize;
+    maxPageSize;
+    maxBypassLimit;
+    constructor(config) {
+        this.endpoint = config.apiEndpoint.replace(/\/+$/, "");
+        this.apiKey = config.apiKey;
+        this.timeoutMs = config.apiTimeoutMs;
+        this.defaultPageSize = config.defaultPageSize;
+        this.maxPageSize = config.maxPageSize;
+        this.maxBypassLimit = config.maxBypassLimit;
+    }
+    getHeaders() {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+            headers["x-api-key"] = this.apiKey;
+        }
+        return headers;
+    }
+    async request(method, path, body, queryParams) {
+        let url = `${this.endpoint}${path.startsWith("/") ? path : `/${path}`}`;
+        if (queryParams) {
+            const searchParams = new URLSearchParams();
+            for (const [key, value] of Object.entries(queryParams)) {
+                if (value !== undefined && value !== null) {
+                    if (typeof value === "object") {
+                        searchParams.append(key, JSON.stringify(value));
+                    }
+                    else {
+                        searchParams.append(key, String(value));
+                    }
+                }
+            }
+            const qs = searchParams.toString();
+            if (qs) {
+                url += (url.includes("?") ? "&" : "?") + qs;
+            }
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const startTime = Date.now();
+            const response = await fetch(url, {
+                method,
+                headers: this.getHeaders(),
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            const duration = Date.now() - startTime;
+            const text = await response.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`Remote server returned non-JSON response (HTTP ${response.status}): ${text.slice(0, 200)}`);
+            }
+            if (!response.ok) {
+                const errorMsg = parsed?.error?.message ||
+                    parsed?.message ||
+                    `Remote API error (HTTP ${response.status})`;
+                const errorObj = new Error(errorMsg);
+                errorObj.status = response.status;
+                errorObj.details = parsed;
+                throw errorObj;
+            }
+            // If remote already wrapped in envelope
+            if (parsed && typeof parsed === "object" && "success" in parsed && "data" in parsed) {
+                return {
+                    data: parsed.data,
+                    meta: {
+                        ...parsed.meta,
+                        executionTimeMs: duration,
+                        endpoint: path,
+                    },
+                };
+            }
+            return {
+                data: parsed,
+                meta: {
+                    executionTimeMs: duration,
+                    endpoint: path,
+                },
+            };
+        }
+        catch (err) {
+            if (err.name === "AbortError") {
+                throw new Error(`Request to MySQL API timed out after ${this.timeoutMs}ms (${method} ${path})`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    // Health / Ping
+    async testConnection() {
+        return await this.request("GET", "/health");
+    }
+    async getInfo() {
+        return await this.request("GET", "/api/info");
+    }
+    // Discovery
+    async listDatabases() {
+        return await this.request("GET", "/api/databases");
+    }
+    async listTables(database) {
+        return await this.request("GET", "/api/tables", undefined, { database });
+    }
+    async readTableSchema(tableName, database) {
+        return await this.request("GET", `/api/tables/${encodeURIComponent(tableName)}/schema`, undefined, {
+            database,
+        });
+    }
+    async getDatabaseSummary(options) {
+        return await this.request("GET", "/api/schema/summary", undefined, {
+            database: options?.database,
+            max_tables: options?.maxTables,
+            include_relationships: options?.includeRelationships,
+        });
+    }
+    async getSchemaRagContext(options) {
+        return await this.request("GET", "/api/schema/rag-context", undefined, {
+            database: options?.database,
+            max_tables: options?.max_tables,
+            max_columns: options?.max_columns,
+            keyword_filter: options?.keyword_filter,
+        });
+    }
+    async getSchemaErd(database) {
+        return await this.request("GET", "/api/schema/erd", undefined, { database });
+    }
+    async getAllTablesRelationships(database) {
+        return await this.request("GET", "/api/schema/relationships", undefined, { database });
+    }
+    async searchSchema(query, database) {
+        return await this.request("GET", "/api/schema/search", undefined, { query, database });
+    }
+    async findTablesByKeyword(keyword, database, limit) {
+        return await this.request("GET", "/api/tables/find", undefined, {
+            keyword,
+            database,
+            limit,
+        });
+    }
+    async searchDataAcrossTables(options) {
+        return await this.request("GET", "/api/tables/search-data", undefined, {
+            keyword: options.keyword,
+            database: options.database,
+            tables: options.tables,
+            columns: options.columns,
+            max_tables: options.max_tables,
+            limit_per_table: options.limit_per_table,
+        });
+    }
+    // CRUD with Default Pagination + Bypass
+    async readRecords(params) {
+        const isBypass = Boolean(params.bypass_pagination || params.all || params.limit === 0 || params.pagination?.limit === 0);
+        let page = params.pagination?.page || params.page || 1;
+        let limit = params.pagination?.limit || params.limit || this.defaultPageSize;
+        if (isBypass) {
+            limit = this.maxBypassLimit;
+        }
+        else {
+            if (limit > this.maxPageSize) {
+                limit = this.maxPageSize;
+            }
+        }
+        const filters = params.filters || params.conditions;
+        return await this.request("GET", `/api/tables/${encodeURIComponent(params.table_name)}/records`, undefined, {
+            database: params.database,
+            columns: params.columns?.join(","),
+            filters,
+            sort_field: params.sorting?.field,
+            sort_direction: params.sorting?.direction,
+            page,
+            limit,
+            bypass: isBypass,
+        });
+    }
+    async readRecord(params) {
+        const id = params.id !== undefined ? params.id : params.key_value;
+        return await this.request("GET", `/api/tables/${encodeURIComponent(params.table_name)}/records/${encodeURIComponent(String(id))}`, undefined, {
+            database: params.database,
+            key_column: params.key_column,
+        });
+    }
+    async countRecords(params) {
+        const filters = params.filters || params.conditions;
+        return await this.request("GET", `/api/tables/${encodeURIComponent(params.table_name)}/count`, undefined, {
+            database: params.database,
+            filters,
+        });
+    }
+    async getColumnStatistics(params) {
+        return await this.request("GET", `/api/tables/${encodeURIComponent(params.table_name)}/columns/${encodeURIComponent(params.column_name)}/stats`, undefined, {
+            database: params.database,
+        });
+    }
+    async createRecord(params) {
+        return await this.request("POST", `/api/tables/${encodeURIComponent(params.table_name)}/records`, {
+            data: params.data,
+            database: params.database,
+        });
+    }
+    async bulkInsert(params) {
+        return await this.request("POST", `/api/tables/${encodeURIComponent(params.table_name)}/records/bulk`, {
+            records: params.records,
+            database: params.database,
+        });
+    }
+    async updateRecord(params) {
+        const filters = params.filters || params.conditions;
+        return await this.request("PUT", `/api/tables/${encodeURIComponent(params.table_name)}/records`, {
+            data: params.data,
+            filters,
+            database: params.database,
+        });
+    }
+    async bulkUpdate(params) {
+        return await this.request("PUT", `/api/tables/${encodeURIComponent(params.table_name)}/records/bulk`, {
+            records: params.records,
+            key_column: params.key_column,
+            database: params.database,
+        });
+    }
+    async deleteRecord(params) {
+        const filters = params.filters || params.conditions;
+        return await this.request("DELETE", `/api/tables/${encodeURIComponent(params.table_name)}/records`, {
+            filters,
+            database: params.database,
+        });
+    }
+    async bulkDelete(params) {
+        return await this.request("POST", `/api/tables/${encodeURIComponent(params.table_name)}/records/bulk-delete`, {
+            key_column: params.key_column,
+            keys: params.keys,
+            database: params.database,
+        });
+    }
+    // Queries
+    async runSelectQuery(params) {
+        const isBypass = Boolean(params.bypass_pagination || params.all || params.limit === 0);
+        let page = params.page || 1;
+        let limit = params.limit || this.defaultPageSize;
+        if (isBypass) {
+            limit = this.maxBypassLimit;
+        }
+        else {
+            if (limit > this.maxPageSize) {
+                limit = this.maxPageSize;
+            }
+        }
+        return await this.request("POST", "/api/query/select", {
+            query: params.query,
+            params: params.params,
+            database: params.database,
+            page,
+            limit,
+            bypass: isBypass,
+        });
+    }
+    async executeWriteQuery(params) {
+        return await this.request("POST", "/api/query/write", {
+            query: params.query,
+            params: params.params,
+            database: params.database,
+        });
+    }
+    // DDL
+    async createTable(params) {
+        return await this.request("POST", "/api/tables", params);
+    }
+    async alterTable(tableName, action, columnDefinition, database) {
+        return await this.request("PUT", `/api/tables/${encodeURIComponent(tableName)}`, {
+            action,
+            column_definition: columnDefinition,
+            database,
+        });
+    }
+    async dropTable(params) {
+        return await this.request("DELETE", `/api/tables/${encodeURIComponent(params.table_name)}`, {
+            if_exists: params.if_exists,
+            database: params.database,
+        });
+    }
+    async executeDdl(params) {
+        return await this.request("POST", "/api/ddl", {
+            query: params.query,
+            database: params.database,
+        });
+    }
+    // Export
+    async exportTableToCsv(tableName, limit, database) {
+        return await this.request("GET", `/api/tables/${encodeURIComponent(tableName)}/export`, undefined, {
+            limit,
+            database,
+        });
+    }
+    async exportQueryToCsv(query, limit, database) {
+        return await this.request("POST", "/api/query/export", {
+            query,
+            limit,
+            database,
+        });
+    }
+}
+exports.MysqlApiClient = MysqlApiClient;

package/dist/config/config.d.ts

@@ -0,0 +1,10 @@
+import { ServerConfig } from "../types/index.js";
+export declare class ConfigManager {
+    private static instance;
+    private config;
+    private constructor();
+    static getInstance(overrides?: Partial<ServerConfig>): ConfigManager;
+    getConfig(): ServerConfig;
+    updateConfig(updates: Partial<ServerConfig>): void;
+}
+export declare const appConfig: ServerConfig;

package/dist/config/config.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appConfig = exports.ConfigManager = void 0;
+const dotenv_1 = __importDefault(require("dotenv"));
+dotenv_1.default.config();
+class ConfigManager {
+    static instance;
+    config;
+    constructor(overrides) {
+        this.config = {
+            apiEndpoint: process.env.MYSQL_API_ENDPOINT ||
+                process.env.API_ENDPOINT ||
+                "http://localhost:3300",
+            apiKey: process.env.MYSQL_API_KEY ||
+                process.env.API_KEY ||
+                process.env.MYSQL_API_TOKEN ||
+                "",
+            permissions: process.env.MCP_PERMISSIONS ||
+                process.env.MCP_CONFIG ||
+                "all",
+            defaultPageSize: parseInt(process.env.DEFAULT_PAGE_SIZE || "50", 10),
+            maxPageSize: parseInt(process.env.MAX_PAGE_SIZE || "500", 10),
+            maxBypassLimit: parseInt(process.env.MAX_BYPASS_LIMIT || "10000", 10),
+            apiTimeoutMs: parseInt(process.env.API_TIMEOUT_MS || "30000", 10),
+            serverPort: parseInt(process.env.PORT || process.env.SERVER_PORT || "3300", 10),
+            ...overrides,
+        };
+        // Normalize endpoint (strip trailing slash)
+        if (this.config.apiEndpoint.endsWith("/")) {
+            this.config.apiEndpoint = this.config.apiEndpoint.slice(0, -1);
+        }
+    }
+    static getInstance(overrides) {
+        if (!ConfigManager.instance || overrides) {
+            ConfigManager.instance = new ConfigManager(overrides);
+        }
+        return ConfigManager.instance;
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    updateConfig(updates) {
+        this.config = {
+            ...this.config,
+            ...updates,
+        };
+        if (this.config.apiEndpoint.endsWith("/")) {
+            this.config.apiEndpoint = this.config.apiEndpoint.slice(0, -1);
+        }
+    }
+}
+exports.ConfigManager = ConfigManager;
+exports.appConfig = ConfigManager.getInstance().getConfig();

package/dist/formatters/jsonResponse.d.ts

@@ -0,0 +1,48 @@
+import { ApiResponseMeta } from "../types/index.js";
+/**
+ * Strict JSON Response Formatter
+ * Guarantees that all outputs returned to AI Agents (Hermes, OpenClaw, Claude, etc.)
+ * are 100% valid JSON adhering to a standardized schema.
+ */
+export declare class JsonResponseFormatter {
+    /**
+     * Formats successful data into a standardized JSON string envelope.
+     */
+    static formatSuccess<T = any>(data: T, metaOptions?: Partial<ApiResponseMeta>): string;
+    /**
+     * Formats error data into a standardized JSON string envelope.
+     * Under no circumstances returns non-JSON or raw text prefixes.
+     */
+    static formatError(code: string, message: string, details?: Record<string, any>): string;
+    /**
+     * Wraps formatted JSON string in standard MCP tool response format.
+     * The text inside content is guaranteed to be parseable JSON.
+     */
+    static toMcpResult(jsonString: string, isError?: boolean): {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    };
+    /**
+     * Helper to directly produce a success MCP result
+     */
+    static mcpSuccess<T = any>(data: T, metaOptions?: Partial<ApiResponseMeta>): {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    };
+    /**
+     * Helper to directly produce an error MCP result
+     */
+    static mcpError(code: string, message: string, details?: Record<string, any>): {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    };
+}

package/dist/formatters/jsonResponse.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonResponseFormatter = void 0;
+/**
+ * Strict JSON Response Formatter
+ * Guarantees that all outputs returned to AI Agents (Hermes, OpenClaw, Claude, etc.)
+ * are 100% valid JSON adhering to a standardized schema.
+ */
+class JsonResponseFormatter {
+    /**
+     * Formats successful data into a standardized JSON string envelope.
+     */
+    static formatSuccess(data, metaOptions = {}) {
+        const envelope = {
+            success: true,
+            data,
+            meta: {
+                timestamp: new Date().toISOString(),
+                ...metaOptions,
+            },
+        };
+        return JSON.stringify(envelope, null, 2);
+    }
+    /**
+     * Formats error data into a standardized JSON string envelope.
+     * Under no circumstances returns non-JSON or raw text prefixes.
+     */
+    static formatError(code, message, details) {
+        const envelope = {
+            success: false,
+            error: {
+                code,
+                message,
+                details: details || {},
+                timestamp: new Date().toISOString(),
+            },
+        };
+        return JSON.stringify(envelope, null, 2);
+    }
+    /**
+     * Wraps formatted JSON string in standard MCP tool response format.
+     * The text inside content is guaranteed to be parseable JSON.
+     */
+    static toMcpResult(jsonString, isError = false) {
+        // Validate JSON validity just in case
+        let validatedString = jsonString;
+        try {
+            JSON.parse(jsonString);
+        }
+        catch {
+            validatedString = JSON.stringify({
+                success: false,
+                error: {
+                    code: "INTERNAL_SERIALIZATION_ERROR",
+                    message: "Output could not be serialized to valid JSON",
+                    timestamp: new Date().toISOString(),
+                },
+            });
+            isError = true;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: validatedString,
+                },
+            ],
+            isError,
+        };
+    }
+    /**
+     * Helper to directly produce a success MCP result
+     */
+    static mcpSuccess(data, metaOptions = {}) {
+        const jsonStr = this.formatSuccess(data, metaOptions);
+        return this.toMcpResult(jsonStr, false);
+    }
+    /**
+     * Helper to directly produce an error MCP result
+     */
+    static mcpError(code, message, details) {
+        const jsonStr = this.formatError(code, message, details);
+        return this.toMcpResult(jsonStr, true);
+    }
+}
+exports.JsonResponseFormatter = JsonResponseFormatter;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./types/index.js";
+export * from "./config/config.js";
+export * from "./permissions/permissionManager.js";
+export * from "./formatters/jsonResponse.js";
+export * from "./api-client/mysqlApiClient.js";
+export * from "./tools/toolDefinitions.js";
+export * from "./tools/toolHandlers.js";
+export * from "./server/apiServer.js";
+export * from "./server/dbPool.js";

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/index.js"), exports);
+__exportStar(require("./config/config.js"), exports);
+__exportStar(require("./permissions/permissionManager.js"), exports);
+__exportStar(require("./formatters/jsonResponse.js"), exports);
+__exportStar(require("./api-client/mysqlApiClient.js"), exports);
+__exportStar(require("./tools/toolDefinitions.js"), exports);
+__exportStar(require("./tools/toolHandlers.js"), exports);
+__exportStar(require("./server/apiServer.js"), exports);
+__exportStar(require("./server/dbPool.js"), exports);

package/dist/mcp-server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp-server.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const config_js_1 = require("./config/config.js");
+const permissionManager_js_1 = require("./permissions/permissionManager.js");
+const mysqlApiClient_js_1 = require("./api-client/mysqlApiClient.js");
+const toolHandlers_js_1 = require("./tools/toolHandlers.js");
+const toolDefinitions_js_1 = require("./tools/toolDefinitions.js");
+const jsonResponse_js_1 = require("./formatters/jsonResponse.js");
+const SERVER_NAME = "mysql-mcp-via-api";
+const SERVER_VERSION = "1.0.0";
+async function main() {
+    // 1. Initialize configuration & dependencies
+    const configManager = config_js_1.ConfigManager.getInstance();
+    const config = configManager.getConfig();
+    // Allow CLI arguments override:
+    // e.g. mcp-mysql-via-api <apiEndpoint> <permissions> <apiKey>
+    const args = process.argv.slice(2);
+    if (args[0] && !args[0].startsWith("-")) {
+        config.apiEndpoint = args[0];
+    }
+    if (args[1] && !args[1].startsWith("-")) {
+        config.permissions = args[1];
+    }
+    if (args[2] && !args[2].startsWith("-")) {
+        config.apiKey = args[2];
+    }
+    configManager.updateConfig(config);
+    const permissionManager = new permissionManager_js_1.PermissionManager(config.permissions);
+    const apiClient = new mysqlApiClient_js_1.MysqlApiClient(config);
+    const handlerRegistry = new toolHandlers_js_1.ToolHandlerRegistry(config, permissionManager, apiClient);
+    // 2. Instantiate MCP Server
+    const server = new index_js_1.Server({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // 3. List Tools Handler
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        return {
+            tools: toolDefinitions_js_1.TOOL_DEFINITIONS,
+        };
+    });
+    // 4. Call Tool Handler
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name, arguments: toolArgs } = request.params;
+        try {
+            return await handlerRegistry.handleToolCall(name, toolArgs || {});
+        }
+        catch (err) {
+            // Catch-all safety: ensure strictly valid JSON envelope
+            return jsonResponse_js_1.JsonResponseFormatter.mcpError("UNHANDLED_EXCEPTION", err.message || "An unhandled exception occurred during tool execution", { tool: name, stack: err.stack });
+        }
+    });
+    // 5. Connect Stdio transport
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    const profile = permissionManager.getProfileSummary();
+    console.error(`[${SERVER_NAME} v${SERVER_VERSION}] running on stdio`);
+    console.error(`[Target API]: ${config.apiEndpoint}`);
+    console.error(`[Policy Profile]: ${profile.preset || "custom"}`);
+    console.error(`[Active Permissions]: [${profile.activePermissions.join(", ")}]`);
+    console.error(`[Strict JSON Guarantee]: ACTIVE`);
+    console.error(`[Pagination Default]: limit=${config.defaultPageSize}, bypass_enabled=true`);
+}
+main().catch((fatalError) => {
+    console.error("Fatal error starting MCP server:", fatalError);
+    process.exit(1);
+});

package/dist/permissions/permissionManager.d.ts

@@ -0,0 +1,25 @@
+import { ToolPermission } from "../types/index.js";
+export declare const ALL_PERMISSIONS: ToolPermission[];
+export declare const DANGEROUS_SQL_KEYWORDS: string[];
+export declare const TOOL_PERMISSION_MAP: Record<string, ToolPermission>;
+export declare class PermissionManager {
+    private activePermissions;
+    private originalConfig;
+    private presetName?;
+    constructor(permissionsConfig?: string);
+    parseConfig(configStr: string): void;
+    isPermissionAllowed(perm: ToolPermission): boolean;
+    isToolAllowed(toolName: string, queryContext?: string): {
+        allowed: boolean;
+        requiredPermission?: ToolPermission;
+        reason?: string;
+    };
+    getActivePermissions(): ToolPermission[];
+    getBlockedPermissions(): ToolPermission[];
+    getProfileSummary(): {
+        preset: string | undefined;
+        originalConfig: string;
+        activePermissions: ToolPermission[];
+        blockedPermissions: ToolPermission[];
+    };
+}