@berthojoris/mcp-mysql-server 1.0.0

package/bin/mcp-mysql.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * MCP MySQL Server CLI
+ * This script allows the MySQL MCP server to be run via NPX
+ * It implements the Model Context Protocol using stdio transport
+ */
+
+const path = require('path');
+const { spawn } = require('child_process');
+require('dotenv').config();
+
+// Get MySQL connection string and optional permissions from command line arguments
+const mysqlUrl = process.argv[2];
+const permissions = process.argv[3]; // Optional: comma-separated list of permissions
+
+if (!mysqlUrl) {
+  console.error('Error: MySQL connection URL is required');
+  console.error('Usage: mcp-mysql mysql://user:password@host:port/dbname [permissions]');
+  console.error('');
+  console.error('Examples:');
+  console.error('  mcp-mysql mysql://root:pass@localhost:3306/mydb');
+  console.error('  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,utility"');
+  console.error('  mcp-mysql mysql://root:pass@localhost:3306/mydb "list,read,create,update,delete,utility"');
+  console.error('');
+  console.error('Available permissions: list, read, create, update, delete, execute, utility');
+  console.error('If not specified, all permissions are enabled.');
+  process.exit(1);
+}
+
+// Parse the MySQL URL to extract connection details
+let connectionConfig;
+let database;
+try {
+  const url = new URL(mysqlUrl);
+  
+  // Remove leading slash from pathname and make database optional
+  database = url.pathname.replace(/^\//, '') || null;
+  
+  // Extract username and password from auth
+  const auth = url.username && url.password 
+    ? { user: url.username, password: url.password }
+    : { user: url.username || 'root', password: url.password || '' };
+  
+  connectionConfig = {
+    host: url.hostname,
+    port: url.port || 3306,
+    ...auth,
+    ...(database ? { database } : {})
+  };
+  
+  // Set environment variables for the server
+  process.env.DB_HOST = connectionConfig.host;
+  process.env.DB_PORT = connectionConfig.port;
+  process.env.DB_USER = connectionConfig.user;
+  process.env.DB_PASSWORD = connectionConfig.password;
+  if (database) {
+    process.env.DB_NAME = database;
+  }
+  
+} catch (error) {
+  console.error('Error parsing MySQL URL:', error.message);
+  console.error('Usage: npx @modelcontextprotocol/server-mysql mysql://user:password@host:port/dbname');
+  process.exit(1);
+}
+
+const dbMessage = database 
+  ? `${connectionConfig.host}:${connectionConfig.port}/${database}`
+  : `${connectionConfig.host}:${connectionConfig.port} (no specific database selected)`;
+
+// Set permissions as environment variable if provided
+if (permissions) {
+  process.env.MCP_PERMISSIONS = permissions;
+  console.error(`Permissions: ${permissions}`);
+} else {
+  console.error('Permissions: all (default)');
+}
+
+// Log to stderr (not stdout, which is used for MCP protocol)
+console.error(`Starting MySQL MCP server with connection to ${dbMessage}`);
+
+// Run the MCP server
+try {
+  // Determine the path to the compiled MCP server file
+  const serverPath = path.resolve(__dirname, '../dist/mcp-server.js');
+  
+  // Spawn the MCP server process with stdio transport
+  // stdin/stdout are used for MCP protocol communication
+  // stderr is used for logging
+  const server = spawn('node', [serverPath], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+    env: process.env
+  });
+  
+  // Handle server process events
+  server.on('error', (err) => {
+    console.error('Failed to start MCP server:', err);
+    process.exit(1);
+  });
+  
+  server.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      console.error(`MCP server exited with code ${code}`);
+      process.exit(code);
+    }
+  });
+  
+  // Handle termination signals
+  process.on('SIGINT', () => {
+    console.error('Shutting down MySQL MCP server...');
+    server.kill('SIGINT');
+  });
+  
+  process.on('SIGTERM', () => {
+    console.error('Shutting down MySQL MCP server...');
+    server.kill('SIGTERM');
+  });
+  
+} catch (error) {
+  console.error('Error starting MCP server:', error.message);
+  process.exit(1);
+}

package/dist/auth/authService.d.ts

@@ -0,0 +1,29 @@
+import { Request, Response, NextFunction } from 'express';
+export interface User {
+    id: string;
+    username: string;
+    role: string;
+}
+export declare class AuthService {
+    /**
+     * Generate a JWT token for a user
+     */
+    generateToken(user: User): string;
+    /**
+     * Verify a JWT token
+     */
+    verifyToken(token: string): User;
+    /**
+     * Middleware to authenticate using JWT
+     */
+    authenticateJWT(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Middleware to authenticate using API key
+     */
+    authenticateApiKey(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Login endpoint handler
+     */
+    login(req: Request, res: Response): void;
+}
+export declare const authService: AuthService;

package/dist/auth/authService.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authService = exports.AuthService = void 0;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+// Environment variables
+const JWT_SECRET = process.env.JWT_SECRET || 'default_secret_change_in_production';
+const JWT_EXPIRES_IN = process.env.JWT_EXPIRES_IN || '24h';
+const API_KEY = process.env.API_KEY;
+class AuthService {
+    /**
+     * Generate a JWT token for a user
+     */
+    generateToken(user) {
+        // Cast to any to bypass TypeScript's strict type checking for JWT
+        return jsonwebtoken_1.default.sign(user, JWT_SECRET, { expiresIn: JWT_EXPIRES_IN });
+    }
+    /**
+     * Verify a JWT token
+     */
+    verifyToken(token) {
+        // Cast to any to bypass TypeScript's strict type checking for JWT
+        return jsonwebtoken_1.default.verify(token, JWT_SECRET);
+    }
+    /**
+     * Middleware to authenticate using JWT
+     */
+    authenticateJWT(req, res, next) {
+        const authHeader = req.headers['authorization'];
+        const token = authHeader && authHeader.split(' ')[1];
+        if (!token) {
+            res.status(401).json({
+                error: {
+                    code: 'AUTH_TOKEN_MISSING',
+                    message: 'Authentication token is required',
+                    details: 'Please provide a valid JWT token in the Authorization header'
+                }
+            });
+            return;
+        }
+        try {
+            const user = this.verifyToken(token);
+            req.user = user;
+            next();
+        }
+        catch (error) {
+            res.status(403).json({
+                error: {
+                    code: 'AUTH_TOKEN_INVALID',
+                    message: 'Invalid or expired token',
+                    details: 'Please provide a valid JWT token'
+                }
+            });
+        }
+    }
+    /**
+     * Middleware to authenticate using API key
+     */
+    authenticateApiKey(req, res, next) {
+        const providedApiKey = req.headers['x-api-key'];
+        if (!API_KEY) {
+            console.warn('API_KEY environment variable is not set');
+            res.status(500).json({
+                error: {
+                    code: 'SERVER_CONFIG_ERROR',
+                    message: 'Server configuration error',
+                    details: 'API key authentication is not properly configured'
+                }
+            });
+            return;
+        }
+        if (!providedApiKey || providedApiKey !== API_KEY) {
+            res.status(401).json({
+                error: {
+                    code: 'INVALID_API_KEY',
+                    message: 'Invalid API key',
+                    details: 'Please provide a valid API key in the X-API-Key header'
+                }
+            });
+            return;
+        }
+        next();
+    }
+    /**
+     * Login endpoint handler
+     */
+    login(req, res) {
+        const { username, password } = req.body;
+        // In a real application, you would validate credentials against a database
+        // This is a simplified example for demonstration purposes
+        if (username === 'admin' && password === 'password') {
+            const user = {
+                id: '1',
+                username: 'admin',
+                role: 'admin'
+            };
+            const token = this.generateToken(user);
+            res.json({ token });
+        }
+        else {
+            res.status(401).json({
+                error: {
+                    code: 'INVALID_CREDENTIALS',
+                    message: 'Invalid username or password',
+                    details: 'Please check your credentials and try again'
+                }
+            });
+        }
+    }
+}
+exports.AuthService = AuthService;
+exports.authService = new AuthService();

package/dist/config/config.d.ts

@@ -0,0 +1,12 @@
+export interface DatabaseConfig {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+}
+export declare const dbConfig: DatabaseConfig;
+declare const _default: {
+    database: DatabaseConfig;
+};
+export default _default;

package/dist/config/config.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbConfig = void 0;
+const dotenv_1 = __importDefault(require("dotenv"));
+// Load environment variables from .env file
+dotenv_1.default.config();
+exports.dbConfig = {
+    host: process.env.DB_HOST || 'localhost',
+    port: parseInt(process.env.DB_PORT || '3306', 10),
+    user: process.env.DB_USER || 'root',
+    password: process.env.DB_PASSWORD || '',
+    database: process.env.DB_NAME || 'mysql',
+};
+exports.default = {
+    database: exports.dbConfig,
+};

package/dist/config/featureConfig.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Available MCP tool categories
+ */
+export declare enum ToolCategory {
+    LIST = "list",// List databases, tables, etc.
+    READ = "read",// Read/select data from tables
+    CREATE = "create",// Insert new records
+    UPDATE = "update",// Update existing records
+    DELETE = "delete",// Delete records
+    EXECUTE = "execute",// Execute custom SQL
+    DDL = "ddl",// Data Definition Language (CREATE/ALTER/DROP tables)
+    UTILITY = "utility",// Utility functions like connection testing
+    TRANSACTION = "transaction",// Transaction management (BEGIN, COMMIT, ROLLBACK)
+    PROCEDURE = "procedure"
+}
+/**
+ * Map of tool names to their categories
+ */
+export declare const toolCategoryMap: Record<string, ToolCategory>;
+/**
+ * Class to manage feature configuration based on runtime or environment variables
+ */
+export declare class FeatureConfig {
+    private enabledCategories;
+    constructor(configStr?: string);
+    /**
+     * Parse MCP_CONFIG from provided string or environment variables
+     */
+    private parseConfig;
+    /**
+     * Update configuration at runtime
+     */
+    setConfig(configStr: string): void;
+    /**
+     * Check if a specific tool is enabled
+     */
+    isToolEnabled(toolName: string): boolean;
+    /**
+     * Check if a category is enabled
+     */
+    isCategoryEnabled(category: ToolCategory): boolean;
+    /**
+     * Get all enabled categories
+     */
+    getEnabledCategories(): ToolCategory[];
+    /**
+     * Get all available categories with their status
+     */
+    getCategoryStatus(): Record<ToolCategory, boolean>;
+}
+export declare const featureConfig: FeatureConfig;

package/dist/config/featureConfig.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.featureConfig = exports.FeatureConfig = exports.toolCategoryMap = exports.ToolCategory = void 0;
+const dotenv_1 = __importDefault(require("dotenv"));
+// Load environment variables
+dotenv_1.default.config();
+/**
+ * Available MCP tool categories
+ */
+var ToolCategory;
+(function (ToolCategory) {
+    ToolCategory["LIST"] = "list";
+    ToolCategory["READ"] = "read";
+    ToolCategory["CREATE"] = "create";
+    ToolCategory["UPDATE"] = "update";
+    ToolCategory["DELETE"] = "delete";
+    ToolCategory["EXECUTE"] = "execute";
+    ToolCategory["DDL"] = "ddl";
+    ToolCategory["UTILITY"] = "utility";
+    ToolCategory["TRANSACTION"] = "transaction";
+    ToolCategory["PROCEDURE"] = "procedure"; // Stored procedure operations (CREATE, EXECUTE, DROP procedures)
+})(ToolCategory || (exports.ToolCategory = ToolCategory = {}));
+/**
+ * Map of tool names to their categories
+ */
+exports.toolCategoryMap = {
+    // Database tools
+    'listDatabases': ToolCategory.LIST,
+    'listTables': ToolCategory.LIST,
+    'readTableSchema': ToolCategory.LIST,
+    // CRUD tools
+    'createRecord': ToolCategory.CREATE,
+    'readRecords': ToolCategory.READ,
+    'updateRecord': ToolCategory.UPDATE,
+    'deleteRecord': ToolCategory.DELETE,
+    // Query tools
+    'runQuery': ToolCategory.READ,
+    'executeSql': ToolCategory.EXECUTE,
+    // DDL tools
+    'createTable': ToolCategory.DDL,
+    'alterTable': ToolCategory.DDL,
+    'dropTable': ToolCategory.DDL,
+    'executeDdl': ToolCategory.DDL,
+    // Utility tools
+    'describeConnection': ToolCategory.UTILITY,
+    'testConnection': ToolCategory.UTILITY,
+    'getTableRelationships': ToolCategory.UTILITY,
+    // Transaction tools
+    'beginTransaction': ToolCategory.TRANSACTION,
+    'commitTransaction': ToolCategory.TRANSACTION,
+    'rollbackTransaction': ToolCategory.TRANSACTION,
+    'getTransactionStatus': ToolCategory.TRANSACTION,
+    'executeInTransaction': ToolCategory.TRANSACTION,
+    // Stored procedure tools
+    'listStoredProcedures': ToolCategory.LIST,
+    'getStoredProcedureInfo': ToolCategory.LIST,
+    'executeStoredProcedure': ToolCategory.PROCEDURE,
+    'createStoredProcedure': ToolCategory.PROCEDURE,
+    'dropStoredProcedure': ToolCategory.PROCEDURE,
+    'showCreateProcedure': ToolCategory.LIST
+};
+/**
+ * Class to manage feature configuration based on runtime or environment variables
+ */
+class FeatureConfig {
+    constructor(configStr) {
+        this.enabledCategories = this.parseConfig(configStr);
+    }
+    /**
+     * Parse MCP_CONFIG from provided string or environment variables
+     */
+    parseConfig(configStr) {
+        // Priority: 1. Provided config, 2. Environment variable, 3. Enable all
+        const config = configStr || process.env.MCP_CONFIG || '';
+        // If config is empty, enable all features
+        if (!config.trim()) {
+            return new Set(Object.values(ToolCategory));
+        }
+        // Parse comma-separated list
+        const categories = config.split(',').map(c => c.trim().toLowerCase());
+        const validCategories = categories.filter(c => Object.values(ToolCategory).includes(c));
+        return new Set(validCategories);
+    }
+    /**
+     * Update configuration at runtime
+     */
+    setConfig(configStr) {
+        this.enabledCategories = this.parseConfig(configStr);
+    }
+    /**
+     * Check if a specific tool is enabled
+     */
+    isToolEnabled(toolName) {
+        const category = exports.toolCategoryMap[toolName];
+        // If tool is not in the map, default to disabled
+        if (!category) {
+            console.warn(`Unknown tool: ${toolName}`);
+            return false;
+        }
+        return this.enabledCategories.has(category);
+    }
+    /**
+     * Check if a category is enabled
+     */
+    isCategoryEnabled(category) {
+        return this.enabledCategories.has(category);
+    }
+    /**
+     * Get all enabled categories
+     */
+    getEnabledCategories() {
+        return Array.from(this.enabledCategories);
+    }
+    /**
+     * Get all available categories with their status
+     */
+    getCategoryStatus() {
+        const result = {};
+        for (const category of Object.values(ToolCategory)) {
+            result[category] = this.enabledCategories.has(category);
+        }
+        return result;
+    }
+}
+exports.FeatureConfig = FeatureConfig;
+// Export singleton instance
+exports.featureConfig = new FeatureConfig();

package/dist/db/connection.d.ts

@@ -0,0 +1,22 @@
+import mysql from 'mysql2/promise';
+declare class DatabaseConnection {
+    private static instance;
+    private pool;
+    private activeTransactions;
+    private constructor();
+    static getInstance(): DatabaseConnection;
+    getConnection(): Promise<mysql.PoolConnection>;
+    query<T>(sql: string, params?: any[]): Promise<T>;
+    testConnection(): Promise<{
+        connected: boolean;
+        latency: number;
+    }>;
+    closePool(): Promise<void>;
+    beginTransaction(transactionId: string): Promise<void>;
+    commitTransaction(transactionId: string): Promise<void>;
+    rollbackTransaction(transactionId: string): Promise<void>;
+    getActiveTransactionIds(): string[];
+    hasActiveTransaction(transactionId: string): boolean;
+    executeInTransaction<T>(transactionId: string, sql: string, params?: any[]): Promise<T>;
+}
+export default DatabaseConnection;

package/dist/db/connection.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promise_1 = __importDefault(require("mysql2/promise"));
+const config_1 = require("../config/config");
+class DatabaseConnection {
+    constructor() {
+        this.pool = promise_1.default.createPool({
+            host: config_1.dbConfig.host,
+            port: config_1.dbConfig.port,
+            user: config_1.dbConfig.user,
+            password: config_1.dbConfig.password,
+            database: config_1.dbConfig.database,
+            waitForConnections: true,
+            connectionLimit: 10,
+            queueLimit: 0
+        });
+        this.activeTransactions = new Map();
+    }
+    static getInstance() {
+        if (!DatabaseConnection.instance) {
+            DatabaseConnection.instance = new DatabaseConnection();
+        }
+        return DatabaseConnection.instance;
+    }
+    async getConnection() {
+        try {
+            return await this.pool.getConnection();
+        }
+        catch (error) {
+            throw new Error(`Failed to get database connection: ${error}`);
+        }
+    }
+    async query(sql, params) {
+        try {
+            const [results] = await this.pool.query(sql, params);
+            return results;
+        }
+        catch (error) {
+            throw new Error(`Query execution failed: ${error}`);
+        }
+    }
+    async testConnection() {
+        const startTime = Date.now();
+        try {
+            const connection = await this.getConnection();
+            connection.release();
+            const endTime = Date.now();
+            return { connected: true, latency: endTime - startTime };
+        }
+        catch (error) {
+            return { connected: false, latency: -1 };
+        }
+    }
+    async closePool() {
+        try {
+            await this.pool.end();
+        }
+        catch (error) {
+            throw new Error(`Failed to close connection pool: ${error}`);
+        }
+    }
+    // Transaction Management Methods
+    async beginTransaction(transactionId) {
+        try {
+            const connection = await this.getConnection();
+            await connection.beginTransaction();
+            this.activeTransactions.set(transactionId, connection);
+        }
+        catch (error) {
+            throw new Error(`Failed to begin transaction: ${error}`);
+        }
+    }
+    async commitTransaction(transactionId) {
+        const connection = this.activeTransactions.get(transactionId);
+        if (!connection) {
+            throw new Error(`No active transaction found with ID: ${transactionId}`);
+        }
+        try {
+            await connection.commit();
+            connection.release();
+            this.activeTransactions.delete(transactionId);
+        }
+        catch (error) {
+            // If commit fails, rollback and release connection
+            try {
+                await connection.rollback();
+                connection.release();
+            }
+            catch (rollbackError) {
+                console.error('Failed to rollback after commit error:', rollbackError);
+            }
+            this.activeTransactions.delete(transactionId);
+            throw new Error(`Failed to commit transaction: ${error}`);
+        }
+    }
+    async rollbackTransaction(transactionId) {
+        const connection = this.activeTransactions.get(transactionId);
+        if (!connection) {
+            throw new Error(`No active transaction found with ID: ${transactionId}`);
+        }
+        try {
+            await connection.rollback();
+            connection.release();
+            this.activeTransactions.delete(transactionId);
+        }
+        catch (error) {
+            connection.release();
+            this.activeTransactions.delete(transactionId);
+            throw new Error(`Failed to rollback transaction: ${error}`);
+        }
+    }
+    getActiveTransactionIds() {
+        return Array.from(this.activeTransactions.keys());
+    }
+    hasActiveTransaction(transactionId) {
+        return this.activeTransactions.has(transactionId);
+    }
+    async executeInTransaction(transactionId, sql, params) {
+        const connection = this.activeTransactions.get(transactionId);
+        if (!connection) {
+            throw new Error(`No active transaction found with ID: ${transactionId}`);
+        }
+        try {
+            const [results] = await connection.query(sql, params);
+            return results;
+        }
+        catch (error) {
+            throw new Error(`Query execution in transaction failed: ${error}`);
+        }
+    }
+}
+exports.default = DatabaseConnection;