@jessejoris/mcp-mysql-via-api 1.0.0

package/dist/tools/toolHandlers.d.ts

@@ -0,0 +1,16 @@
+import { PermissionManager } from "../permissions/permissionManager.js";
+import { MysqlApiClient } from "../api-client/mysqlApiClient.js";
+import { ServerConfig } from "../types/index.js";
+export declare class ToolHandlerRegistry {
+    private permissionManager;
+    private apiClient;
+    private config;
+    constructor(config: ServerConfig, permissionManager: PermissionManager, apiClient: MysqlApiClient);
+    handleToolCall(toolName: string, args?: Record<string, any>): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+}

package/dist/tools/toolHandlers.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolHandlerRegistry = void 0;
+const toolDefinitions_js_1 = require("./toolDefinitions.js");
+const permissionManager_js_1 = require("../permissions/permissionManager.js");
+const jsonResponse_js_1 = require("../formatters/jsonResponse.js");
+class ToolHandlerRegistry {
+    permissionManager;
+    apiClient;
+    config;
+    constructor(config, permissionManager, apiClient) {
+        this.config = config;
+        this.permissionManager = permissionManager;
+        this.apiClient = apiClient;
+    }
+    async handleToolCall(toolName, args = {}) {
+        const startTime = Date.now();
+        // 1. Permission check
+        const queryContext = args?.query || undefined;
+        const permCheck = this.permissionManager.isToolAllowed(toolName, queryContext);
+        if (!permCheck.allowed) {
+            return jsonResponse_js_1.JsonResponseFormatter.mcpError("PERMISSION_DENIED", permCheck.reason || `Tool '${toolName}' is not permitted under current policy.`, {
+                tool: toolName,
+                requiredPermission: permCheck.requiredPermission,
+                activePermissions: this.permissionManager.getActivePermissions(),
+                policy: this.permissionManager.getProfileSummary().preset,
+            });
+        }
+        // 2. Dispatch to specific tool handler
+        try {
+            let result;
+            switch (toolName) {
+                // --- Discovery Tools ---
+                case "list_databases":
+                    result = await this.apiClient.listDatabases();
+                    break;
+                case "list_tables":
+                    result = await this.apiClient.listTables(args.database);
+                    break;
+                case "read_table_schema":
+                    result = await this.apiClient.readTableSchema(args.table_name, args.database);
+                    break;
+                case "get_database_summary":
+                    result = await this.apiClient.getDatabaseSummary({
+                        database: args.database,
+                        maxTables: args.max_tables,
+                        includeRelationships: args.include_relationships,
+                    });
+                    break;
+                case "get_schema_rag_context":
+                    result = await this.apiClient.getSchemaRagContext({
+                        database: args.database,
+                        max_tables: args.max_tables,
+                        max_columns: args.max_columns,
+                        keyword_filter: args.keyword_filter,
+                    });
+                    break;
+                case "get_schema_erd":
+                    result = await this.apiClient.getSchemaErd(args.database);
+                    break;
+                case "get_all_tables_relationships":
+                    result = await this.apiClient.getAllTablesRelationships(args.database);
+                    break;
+                case "search_schema":
+                    result = await this.apiClient.searchSchema(args.query, args.database);
+                    break;
+                case "find_tables_by_keyword":
+                    result = await this.apiClient.findTablesByKeyword(args.keyword, args.database, args.limit);
+                    break;
+                case "search_data_across_tables":
+                    result = await this.apiClient.searchDataAcrossTables({
+                        keyword: args.keyword,
+                        tables: args.tables,
+                        database: args.database,
+                        max_tables: args.max_tables,
+                        limit_per_table: args.limit_per_table,
+                    });
+                    break;
+                // --- CRUD Tools with Default Pagination and Bypass ---
+                case "read_records":
+                    result = await this.apiClient.readRecords({
+                        table_name: args.table_name,
+                        columns: args.columns,
+                        filters: args.filters || args.conditions,
+                        conditions: args.conditions,
+                        sorting: args.sorting,
+                        pagination: args.pagination,
+                        bypass_pagination: args.bypass_pagination ?? args.all,
+                        all: args.all,
+                        database: args.database,
+                    });
+                    break;
+                case "read_record":
+                    result = await this.apiClient.readRecord({
+                        table_name: args.table_name,
+                        id: args.id,
+                        key_column: args.key_column,
+                        key_value: args.key_value,
+                        database: args.database,
+                    });
+                    break;
+                case "count_records":
+                    result = await this.apiClient.countRecords({
+                        table_name: args.table_name,
+                        filters: args.filters || args.conditions,
+                        conditions: args.conditions,
+                        database: args.database,
+                    });
+                    break;
+                case "create_record":
+                    result = await this.apiClient.createRecord({
+                        table_name: args.table_name,
+                        data: args.data,
+                        database: args.database,
+                    });
+                    break;
+                case "bulk_insert":
+                    result = await this.apiClient.bulkInsert({
+                        table_name: args.table_name,
+                        records: args.records,
+                        database: args.database,
+                    });
+                    break;
+                case "update_record":
+                    result = await this.apiClient.updateRecord({
+                        table_name: args.table_name,
+                        data: args.data,
+                        filters: args.filters || args.conditions,
+                        conditions: args.conditions,
+                        database: args.database,
+                    });
+                    break;
+                case "bulk_update":
+                    result = await this.apiClient.bulkUpdate({
+                        table_name: args.table_name,
+                        records: args.records,
+                        key_column: args.key_column,
+                        database: args.database,
+                    });
+                    break;
+                case "delete_record":
+                    result = await this.apiClient.deleteRecord({
+                        table_name: args.table_name,
+                        filters: args.filters || args.conditions,
+                        conditions: args.conditions,
+                        database: args.database,
+                    });
+                    break;
+                case "bulk_delete":
+                    result = await this.apiClient.bulkDelete({
+                        table_name: args.table_name,
+                        key_column: args.key_column,
+                        keys: args.keys,
+                        database: args.database,
+                    });
+                    break;
+                // --- Data Analysis Tools ---
+                case "get_column_statistics":
+                    result = await this.apiClient.getColumnStatistics({
+                        table_name: args.table_name,
+                        column_name: args.column_name,
+                        database: args.database,
+                    });
+                    break;
+                // --- Query Management ---
+                case "run_select_query":
+                    result = await this.apiClient.runSelectQuery({
+                        query: args.query,
+                        params: args.params,
+                        page: args.page,
+                        limit: args.limit,
+                        bypass_pagination: args.bypass_pagination ?? args.all,
+                        all: args.all,
+                        database: args.database,
+                    });
+                    break;
+                case "execute_write_query":
+                    result = await this.apiClient.executeWriteQuery({
+                        query: args.query,
+                        params: args.params,
+                        database: args.database,
+                    });
+                    break;
+                // --- Schema DDL ---
+                case "create_table":
+                    result = await this.apiClient.createTable({
+                        table_name: args.table_name,
+                        columns: args.columns,
+                        primary_key: args.primary_key,
+                        database: args.database,
+                    });
+                    break;
+                case "alter_table":
+                    result = await this.apiClient.alterTable(args.table_name, args.action, args.column_definition, args.database);
+                    break;
+                case "drop_table":
+                    result = await this.apiClient.dropTable({
+                        table_name: args.table_name,
+                        if_exists: args.if_exists,
+                        database: args.database,
+                    });
+                    break;
+                case "execute_ddl":
+                    result = await this.apiClient.executeDdl({
+                        query: args.query,
+                        database: args.database,
+                    });
+                    break;
+                // --- Utilities ---
+                case "test_connection":
+                    result = await this.apiClient.testConnection();
+                    break;
+                case "describe_connection":
+                    result = {
+                        data: {
+                            apiEndpoint: this.config.apiEndpoint,
+                            hasApiKey: Boolean(this.config.apiKey),
+                            permissionsProfile: this.permissionManager.getProfileSummary(),
+                            paginationDefaults: {
+                                defaultPageSize: this.config.defaultPageSize,
+                                maxPageSize: this.config.maxPageSize,
+                                maxBypassLimit: this.config.maxBypassLimit,
+                            },
+                            timeoutMs: this.config.apiTimeoutMs,
+                            status: "connected",
+                        },
+                        meta: {
+                            executionTimeMs: Date.now() - startTime,
+                        },
+                    };
+                    break;
+                case "list_all_tools": {
+                    const catalog = toolDefinitions_js_1.TOOL_DEFINITIONS.map((def) => {
+                        const reqPerm = permissionManager_js_1.TOOL_PERMISSION_MAP[def.name];
+                        const isEnabled = this.permissionManager.isPermissionAllowed(reqPerm);
+                        return {
+                            name: def.name,
+                            requiredPermission: reqPerm,
+                            enabled: isEnabled,
+                            description: def.description,
+                        };
+                    });
+                    result = {
+                        data: {
+                            totalTools: catalog.length,
+                            enabledTools: catalog.filter((t) => t.enabled).length,
+                            blockedTools: catalog.filter((t) => !t.enabled).length,
+                            profile: this.permissionManager.getProfileSummary(),
+                            tools: catalog,
+                        },
+                        meta: {
+                            executionTimeMs: Date.now() - startTime,
+                        },
+                    };
+                    break;
+                }
+                case "export_table_to_csv":
+                    result = await this.apiClient.exportTableToCsv(args.table_name, args.limit, args.database);
+                    break;
+                case "export_query_to_csv":
+                    result = await this.apiClient.exportQueryToCsv(args.query, args.limit, args.database);
+                    break;
+                default:
+                    return jsonResponse_js_1.JsonResponseFormatter.mcpError("UNKNOWN_TOOL", `No handler found for tool '${toolName}'.`);
+            }
+            // Check if result has standard data/meta or raw payload
+            const responseData = result?.data !== undefined ? result.data : result;
+            const responseMeta = {
+                executionTimeMs: Date.now() - startTime,
+                ...result?.meta,
+            };
+            return jsonResponse_js_1.JsonResponseFormatter.mcpSuccess(responseData, responseMeta);
+        }
+        catch (error) {
+            return jsonResponse_js_1.JsonResponseFormatter.mcpError(error.code || (error.status ? `HTTP_${error.status}` : "API_REQUEST_FAILED"), error.message || "An unexpected error occurred while executing tool via API.", {
+                tool: toolName,
+                executionTimeMs: Date.now() - startTime,
+                endpoint: this.config.apiEndpoint,
+                status: error.status,
+                details: error.details,
+            });
+        }
+    }
+}
+exports.ToolHandlerRegistry = ToolHandlerRegistry;

package/dist/types/index.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Type definitions for MySQL MCP via API
+ */
+export type ToolPermission = "list" | "read" | "create" | "update" | "delete" | "execute" | "ddl" | "utility" | "transaction";
+export type PermissionPreset = "only-read" | "readonly" | "read-only" | "read-write" | "admin" | "all" | "custom";
+export interface PaginationParams {
+    page?: number;
+    limit?: number;
+    bypass_pagination?: boolean;
+}
+export interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+    bypassed?: boolean;
+}
+export interface ApiResponseMeta {
+    pagination?: PaginationMeta;
+    timestamp: string;
+    executionTimeMs?: number;
+    endpoint?: string;
+    recordCount?: number;
+    warning?: string;
+}
+export interface ApiSuccessEnvelope<T = any> {
+    success: true;
+    data: T;
+    meta: ApiResponseMeta;
+}
+export interface ApiErrorDetail {
+    code: string;
+    message: string;
+    details?: Record<string, any>;
+    timestamp: string;
+}
+export interface ApiErrorEnvelope {
+    success: false;
+    error: ApiErrorDetail;
+}
+export type StrictJsonResponse<T = any> = ApiSuccessEnvelope<T> | ApiErrorEnvelope;
+export type FilterOperator = "=" | "==" | "eq" | "!=" | "<>" | "neq" | ">" | "gt" | ">=" | "gte" | "<" | "lt" | "<=" | "lte" | "LIKE" | "like" | "NOT LIKE" | "not like" | "IN" | "in" | "NOT IN" | "not in" | "IS NULL" | "is null" | "IS NOT NULL" | "is not null" | "BETWEEN" | "between";
+export interface FilterClause {
+    field: string;
+    operator: FilterOperator | string;
+    value?: any;
+    secondValue?: any;
+}
+export interface SortingClause {
+    field: string;
+    direction: "asc" | "desc" | "ASC" | "DESC";
+}
+export interface ReadRecordsParams extends PaginationParams {
+    table_name: string;
+    columns?: string[];
+    filters?: FilterClause[];
+    conditions?: FilterClause[];
+    sorting?: SortingClause;
+    database?: string;
+    all?: boolean;
+    pagination?: {
+        page?: number;
+        limit?: number;
+    };
+}
+export interface ReadRecordParams {
+    table_name: string;
+    id?: string | number;
+    key_column?: string;
+    key_value?: string | number;
+    database?: string;
+}
+export interface CreateRecordParams {
+    table_name: string;
+    data: Record<string, any>;
+    database?: string;
+}
+export interface BulkInsertParams {
+    table_name: string;
+    records: Array<Record<string, any>>;
+    database?: string;
+}
+export interface UpdateRecordParams {
+    table_name: string;
+    data: Record<string, any>;
+    filters?: FilterClause[];
+    conditions?: FilterClause[];
+    database?: string;
+}
+export interface BulkUpdateParams {
+    table_name: string;
+    records: Array<Record<string, any>>;
+    key_column: string;
+    database?: string;
+}
+export interface DeleteRecordParams {
+    table_name: string;
+    filters?: FilterClause[];
+    conditions?: FilterClause[];
+    database?: string;
+}
+export interface BulkDeleteParams {
+    table_name: string;
+    key_column: string;
+    keys: Array<string | number>;
+    database?: string;
+}
+export interface CountRecordsParams {
+    table_name: string;
+    filters?: FilterClause[];
+    conditions?: FilterClause[];
+    database?: string;
+}
+export interface RagContextParams {
+    database?: string;
+    max_tables?: number;
+    max_columns?: number;
+    include_relationships?: boolean;
+    include_comments?: boolean;
+    keyword_filter?: string;
+}
+export interface SearchDataParams {
+    keyword: string;
+    database?: string;
+    tables?: string[];
+    columns?: string[];
+    max_tables?: number;
+    limit_per_table?: number;
+}
+export interface ColumnStatsParams {
+    table_name: string;
+    column_name: string;
+    database?: string;
+}
+export interface SelectQueryParams extends PaginationParams {
+    query: string;
+    params?: any[];
+    database?: string;
+    all?: boolean;
+}
+export interface WriteQueryParams {
+    query: string;
+    params?: any[];
+    database?: string;
+}
+export interface DdlQueryParams {
+    query: string;
+    database?: string;
+}
+export interface CreateTableParams {
+    table_name: string;
+    columns: Array<{
+        name: string;
+        type: string;
+        nullable?: boolean;
+        defaultValue?: any;
+        autoIncrement?: boolean;
+        primaryKey?: boolean;
+    }>;
+    primary_key?: string | string[];
+    database?: string;
+}
+export interface DropTableParams {
+    table_name: string;
+    if_exists?: boolean;
+    database?: string;
+}
+export interface ExportCsvParams {
+    table_name?: string;
+    query?: string;
+    limit?: number;
+    database?: string;
+}
+export interface ServerConfig {
+    apiEndpoint: string;
+    apiKey: string;
+    permissions: string;
+    defaultPageSize: number;
+    maxPageSize: number;
+    maxBypassLimit: number;
+    apiTimeoutMs: number;
+    serverPort?: number;
+}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for MySQL MCP via API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@jessejoris/mcp-mysql-via-api",
+  "version": "1.0.0",
+  "description": "Model Context Protocol server for MySQL access via HTTP/REST API with strict JSON output, default pagination with bypass, and configurable granular permissions",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "PRD.md"
+  ],
+  "bin": {
+    "mcp-mysql-via-api": "bin/mcp-mysql-via-api.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/mcp-server.js",
+    "start:server": "node dist/server/standalone.js",
+    "dev": "ts-node src/mcp-server.ts",
+    "dev:server": "ts-node src/server/standalone.ts",
+    "test": "jest --runInBand --detectOpenHandles",
+    "test:coverage": "jest --coverage --runInBand --detectOpenHandles"
+  },
+  "keywords": [
+    "mcp",
+    "mysql",
+    "api",
+    "rest",
+    "model-context-protocol",
+    "ai",
+    "hermes",
+    "openclaw",
+    "claude",
+    "cursor",
+    "windsurf",
+    "cline"
+  ],
+  "author": "Bertho Joris",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.0",
+    "mysql2": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.0",
+    "@types/supertest": "^6.0.2",
+    "jest": "^29.7.0",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}