@neverinfamous/mysql-mcp 2.1.0

package/server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
+  "name": "io.github.neverinfamous/mysql-mcp",
+  "description": "Enterprise-grade MySQL MCP Server with OAuth 2.0, 191 tools, and Docker deployment",
+  "version": "2.0.0",
+  "packages": [
+    {
+      "registryType": "oci",
+      "identifier": "docker.io/writenotenow/mysql-mcp:v2.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ],
+  "keywords": [
+    "mcp",
+    "mysql",
+    "database",
+    "model-context-protocol",
+    "oauth",
+    "docker"
+  ],
+  "author": {
+    "name": "Adamic.tech"
+  },
+  "homepage": "https://github.com/neverinfamous/mysql-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverinfamous/mysql-mcp.git",
+    "source": "github"
+  },
+  "license": "MIT"
+}

package/src/__tests__/cli.test.ts

@@ -0,0 +1,304 @@
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { main } from '../cli.js';
+
+// Hoist mocks to be accessible in vi.mock factory
+const mocks = vi.hoisted(() => ({
+    createServer: vi.fn(),
+    MySQLAdapter: vi.fn(),
+    serverInstance: {
+        start: vi.fn(),
+        stop: vi.fn(),
+        registerAdapter: vi.fn()
+    },
+    adapterInstance: {
+        connect: vi.fn()
+    }
+}));
+
+// Mock McpServer partially
+vi.mock('../server/McpServer.js', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('../server/McpServer.js')>();
+    return {
+        ...actual,
+        createServer: mocks.createServer
+    };
+});
+
+// Mock MySQLAdapter
+vi.mock('../adapters/mysql/MySQLAdapter.js', () => ({
+    MySQLAdapter: mocks.MySQLAdapter
+}));
+
+// Mock process.exit
+const mockExit = vi.spyOn(process, 'exit').mockImplementation((code?: number | string | null | undefined) => {
+    throw new Error(`process.exit(${code})`);
+});
+
+// Mock console.error
+const mockConsoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+
+// Fix: Use a regular function for implementation so it can be called with 'new'
+const mockMySQLAdapterImplementation = function () {
+    return mocks.adapterInstance;
+};
+
+describe('CLI', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+
+        // Setup default mock behaviors
+        mocks.createServer.mockReturnValue(mocks.serverInstance);
+        // Set implementation for MySQLAdapter (class constructor mock)
+        mocks.MySQLAdapter.mockImplementation(mockMySQLAdapterImplementation);
+
+        mocks.serverInstance.start.mockResolvedValue(undefined);
+        mocks.serverInstance.stop.mockResolvedValue(undefined);
+        mocks.adapterInstance.connect.mockResolvedValue(undefined);
+
+        delete process.env['MYSQL_HOST'];
+        delete process.env['MYSQL_USER'];
+        delete process.env['MYSQL_PASSWORD'];
+        delete process.env['MYSQL_DATABASE'];
+        delete process.env['MYSQL_MCP_TOOL_FILTER'];
+        delete process.env['OAUTH_ENABLED'];
+    });
+
+    describe('canSkipMySQLConnection logic', () => {
+        it('should skip MySQL connection for router-only filter', async () => {
+            await main({
+                config: { toolFilter: 'router' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            // Should NOT call connect because router tools don't need MySQL
+            expect(mocks.adapterInstance.connect).not.toHaveBeenCalled();
+            expect(mocks.serverInstance.registerAdapter).toHaveBeenCalled();
+        });
+
+        it('should skip MySQL connection for proxysql-only filter', async () => {
+            await main({
+                config: { toolFilter: 'proxysql' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).not.toHaveBeenCalled();
+        });
+
+        it('should skip MySQL connection for shell-only filter', async () => {
+            await main({
+                config: { toolFilter: 'shell' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).not.toHaveBeenCalled();
+        });
+
+        it('should skip MySQL connection for ecosystem shortcut', async () => {
+            await main({
+                config: { toolFilter: 'ecosystem' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).not.toHaveBeenCalled();
+        });
+
+        it('should skip MySQL connection for combined MySQL-optional groups', async () => {
+            await main({
+                config: { toolFilter: 'router,proxysql,shell' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).not.toHaveBeenCalled();
+        });
+
+        it('should require MySQL connection for starter shortcut', async () => {
+            await main({
+                config: { toolFilter: 'starter' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+        });
+
+        it('should require MySQL connection for dev-power shortcut', async () => {
+            await main({
+                config: { toolFilter: 'dev-power' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+        });
+
+        it('should require MySQL connection for mixed MySQL and non-MySQL groups', async () => {
+            await main({
+                config: { toolFilter: 'router,core' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+        });
+
+        it('should require MySQL connection for exclusion-only filters', async () => {
+            await main({
+                config: { toolFilter: '-router' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            // Exclusion only means no explicit enabled groups, so can't skip
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+        });
+
+        it('should create placeholder adapter when no databases but using external-only tools', async () => {
+            await main({
+                config: { toolFilter: 'router' },
+                databases: [],
+                oauth: undefined
+            });
+
+            // Should register a placeholder adapter
+            expect(mocks.serverInstance.registerAdapter).toHaveBeenCalledWith(
+                expect.anything(),
+                'mysql:external'
+            );
+        });
+
+        it('should require MySQL connection for base-core shortcut', async () => {
+            await main({
+                config: { toolFilter: 'base-core' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+        });
+
+        it('should require MySQL connection for ai-data shortcut', async () => {
+            await main({
+                config: { toolFilter: 'ai-data' },
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+        });
+
+        it('should require MySQL connection with no toolFilter', async () => {
+            await main({
+                config: {},
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+        });
+    });
+
+    describe('main', () => {
+        it('should fail if no database config provided', async () => {
+            await expect(main({
+                config: {},
+                databases: [],
+                oauth: undefined
+            })).rejects.toThrow('process.exit(1)');
+
+            expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('No database connection specified'));
+        });
+
+        it('should start server with valid config', async () => {
+            await main({
+                config: {},
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(mocks.createServer).toHaveBeenCalled();
+            expect(mocks.MySQLAdapter).toHaveBeenCalled(); // verify class instantiation
+            expect(mocks.adapterInstance.connect).toHaveBeenCalled();
+            expect(mocks.serverInstance.registerAdapter).toHaveBeenCalled();
+            expect(mocks.serverInstance.start).toHaveBeenCalled();
+        });
+
+        it('should handle startup error', async () => {
+            mocks.serverInstance.start.mockRejectedValue(new Error('Startup failed'));
+
+            await expect(main({
+                config: {},
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            })).rejects.toThrow('process.exit(1)');
+
+            expect(mockConsoleError).toHaveBeenCalledWith('Fatal error:', expect.any(Error));
+        });
+
+        it('should log oauth configuration if enabled', async () => {
+            await main({
+                config: {},
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: {
+                    enabled: true,
+                    issuer: 'https://issuer.com',
+                    audience: 'aud'
+                }
+            });
+
+            expect(mockConsoleError).toHaveBeenCalledWith('OAuth authentication enabled');
+        });
+
+
+        it('should exit immediately if shouldExit is true', async () => {
+            await expect(main({
+                config: {},
+                databases: [],
+                oauth: undefined,
+                shouldExit: true
+            })).rejects.toThrow('process.exit(0)');
+        });
+
+        it('should handle graceful shutdown on signal', async () => {
+            // Override mockExit to NOT throw for this test to avoid unhandled rejections from async void handler
+            mockExit.mockImplementation(() => { return undefined as never });
+
+            const handlers: Record<string, () => void> = {};
+            const originalOn = process.on.bind(process);
+
+            const onSpy = vi.spyOn(process, 'on').mockImplementation((event, listener) => {
+                if (event === 'SIGINT' || event === 'SIGTERM') {
+                    handlers[event as string] = listener as () => void;
+                    return process;
+                }
+                return originalOn(event, listener);
+            });
+
+            await main({
+                config: {},
+                databases: [{ type: 'mysql', host: 'localhost', database: 'test' } as any],
+                oauth: undefined
+            });
+
+            expect(handlers['SIGINT']).toBeDefined();
+            expect(handlers['SIGTERM']).toBeDefined();
+
+            // Trigger shutdown (SIGINT)
+            handlers['SIGINT']();
+
+            // Wait for async execution
+            await new Promise(resolve => setTimeout(resolve, 10));
+
+            expect(mocks.serverInstance.stop).toHaveBeenCalled();
+            expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Shutting down'));
+            expect(mockExit).toHaveBeenCalledWith(0);
+
+            onSpy.mockRestore();
+        });
+    });
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import * as Index from '../index.js';
+
+describe('Index Exports', () => {
+    it('should export core modules', () => {
+        expect(Index.McpServer).toBeDefined();
+        expect(Index.DatabaseAdapter).toBeDefined();
+        expect(Index.MySQLAdapter).toBeDefined();
+        expect(Index.ConnectionPool).toBeDefined();
+    });
+
+    it('should export error classes', () => {
+        expect(Index.MySQLMcpError).toBeDefined();
+        expect(Index.ConnectionError).toBeDefined();
+        expect(Index.AuthenticationError).toBeDefined();
+    });
+
+    it('should export types', () => {
+        // Types are erased at runtime, but we can check if the module object has keys
+        // or just rely on the test compiling as verification that types are exported
+        // if we import them as types.
+        // For runtime check, we just verify the module object is substantial
+        expect(Object.keys(Index).length).toBeGreaterThan(0);
+    });
+});

package/src/__tests__/mocks/adapter.ts

@@ -0,0 +1,265 @@
+/**
+ * mysql-mcp - MySQL Adapter Mock
+ * 
+ * Provides mock implementation of MySQLAdapter for testing
+ * tools, resources, and prompts without database dependency.
+ */
+
+import { vi } from 'vitest';
+import type { MySQLAdapter } from '../../adapters/mysql/MySQLAdapter.js';
+import type { QueryResult, TableInfo, IndexInfo, SchemaInfo, HealthStatus, ColumnInfo } from '../../types/index.js';
+
+/**
+ * Create a mock query result
+ */
+export function createMockQueryResult(
+    rows: Record<string, unknown>[] = [],
+    affectedRows = 0
+): QueryResult {
+    return {
+        rows,
+        rowsAffected: affectedRows,
+        executionTimeMs: 5
+    };
+}
+
+/**
+ * Create a mock column info
+ */
+export function createMockColumnInfo(name: string, type: string, nullable = true, primaryKey = false): ColumnInfo {
+    return {
+        name,
+        type,
+        nullable,
+        primaryKey
+    };
+}
+
+/**
+ * Create a mock table info
+ */
+export function createMockTableInfo(name: string, rowCount = 100): TableInfo {
+    return {
+        name,
+        type: 'table',
+        columns: [
+            createMockColumnInfo('id', 'int', false, true),
+            createMockColumnInfo('name', 'varchar(255)', true, false),
+            createMockColumnInfo('created_at', 'datetime', false, false)
+        ],
+        rowCount,
+        engine: 'InnoDB',
+        collation: 'utf8mb4_unicode_ci'
+    };
+}
+
+/**
+ * Create mock index info
+ */
+export function createMockIndexInfo(tableName: string, indexName: string): IndexInfo {
+    return {
+        name: indexName,
+        tableName,
+        columns: ['id'],
+        unique: indexName === 'PRIMARY',
+        type: 'BTREE'
+    };
+}
+
+/**
+ * Create mock schema info
+ */
+export function createMockSchemaInfo(): SchemaInfo {
+    return {
+        tables: [createMockTableInfo('users'), createMockTableInfo('products')],
+        views: [],
+        indexes: [createMockIndexInfo('users', 'PRIMARY')]
+    };
+}
+
+/**
+ * Create mock health status
+ */
+export function createMockHealthStatus(connected = true): HealthStatus {
+    return {
+        connected,
+        latencyMs: 5,
+        version: '8.0.35',
+        poolStats: {
+            total: 10,
+            active: 2,
+            idle: 8,
+            waiting: 0,
+            totalQueries: 100
+        }
+    };
+}
+
+/**
+ * Create a mock MySQLAdapter
+ */
+export function createMockMySQLAdapter(): Partial<MySQLAdapter> & {
+    executeQuery: ReturnType<typeof vi.fn>;
+    executeReadQuery: ReturnType<typeof vi.fn>;
+    executeWriteQuery: ReturnType<typeof vi.fn>;
+    rawQuery: ReturnType<typeof vi.fn>;
+    getTableIndexes: ReturnType<typeof vi.fn>;
+    describeTable: ReturnType<typeof vi.fn>;
+    listTables: ReturnType<typeof vi.fn>;
+    getSchema: ReturnType<typeof vi.fn>;
+} {
+    const mockQueryResult = createMockQueryResult([{ id: 1, name: 'test' }]);
+
+    return {
+        type: 'mysql' as const,
+        name: 'MySQL Adapter',
+        version: '0.1.0',
+
+        // Connection methods
+        connect: vi.fn().mockResolvedValue(undefined),
+        disconnect: vi.fn().mockResolvedValue(undefined),
+        getHealth: vi.fn().mockResolvedValue(createMockHealthStatus()),
+        isConnected: vi.fn().mockReturnValue(true),
+
+        // Query execution
+        executeQuery: vi.fn().mockResolvedValue(mockQueryResult),
+        executeReadQuery: vi.fn().mockResolvedValue(mockQueryResult),
+        executeWriteQuery: vi.fn().mockResolvedValue(mockQueryResult),
+        rawQuery: vi.fn().mockResolvedValue(mockQueryResult),
+
+        // Transaction methods
+        beginTransaction: vi.fn().mockResolvedValue('txn-123'),
+        commitTransaction: vi.fn().mockResolvedValue(undefined),
+        rollbackTransaction: vi.fn().mockResolvedValue(undefined),
+        getTransactionConnection: vi.fn().mockReturnValue(undefined),
+
+        // Schema methods
+        getSchema: vi.fn().mockResolvedValue(createMockSchemaInfo()),
+        listTables: vi.fn().mockResolvedValue([createMockTableInfo('users')]),
+        describeTable: vi.fn().mockResolvedValue(createMockTableInfo('users')),
+        listSchemas: vi.fn().mockResolvedValue(['testdb', 'information_schema']),
+        getTableIndexes: vi.fn().mockResolvedValue([createMockIndexInfo('users', 'PRIMARY')]),
+
+        // Capabilities
+        getCapabilities: vi.fn().mockReturnValue({
+            json: true,
+            fullTextSearch: true,
+            vector: false,
+            geospatial: true,
+            transactions: true,
+            preparedStatements: true,
+            connectionPooling: true,
+            partitioning: true,
+            replication: true
+        }),
+        getSupportedToolGroups: vi.fn().mockReturnValue([
+            'core', 'transactions', 'json', 'text', 'fulltext',
+            'performance', 'optimization', 'admin', 'monitoring', 'backup'
+        ]),
+
+        // Definition getters
+        getToolDefinitions: vi.fn().mockReturnValue([]),
+        getResourceDefinitions: vi.fn().mockReturnValue([]),
+        getPromptDefinitions: vi.fn().mockReturnValue([]),
+
+        // Registration methods (used by McpServer)
+        registerTools: vi.fn(),
+        registerResources: vi.fn(),
+        registerPrompts: vi.fn(),
+
+        // Pool access
+        getPool: vi.fn().mockReturnValue(null)
+    };
+}
+
+/**
+ * Create a mock RequestContext for handler testing
+ */
+export function createMockRequestContext(): {
+    timestamp: Date;
+    requestId: string;
+} {
+    return {
+        timestamp: new Date(),
+        requestId: 'test-request-' + Math.random().toString(36).slice(2, 9)
+    };
+}
+
+/**
+ * Helper to configure mock adapter response for specific queries
+ */
+export function configureMockAdapterQuery(
+    adapter: ReturnType<typeof createMockMySQLAdapter>,
+    pattern: string,
+    result: QueryResult
+): void {
+    const originalImpl = adapter.executeQuery.getMockImplementation() as ((sql: string) => Promise<QueryResult>) | undefined;
+
+    adapter.executeQuery.mockImplementation((sql: string) => {
+        if (sql.includes(pattern)) {
+            return Promise.resolve(result);
+        }
+        return originalImpl?.(sql) ?? Promise.resolve(createMockQueryResult());
+    });
+}
+
+/**
+ * Create a mock MySQLAdapter that returns empty results
+ */
+export function createMockMySQLAdapterEmpty(): ReturnType<typeof createMockMySQLAdapter> {
+    const adapter = createMockMySQLAdapter();
+    const emptyResult = createMockQueryResult([]);
+
+    adapter.executeQuery.mockResolvedValue(emptyResult);
+    adapter.executeReadQuery.mockResolvedValue(emptyResult);
+    adapter.executeWriteQuery.mockResolvedValue({ rows: [], rowsAffected: 0, executionTimeMs: 1 });
+    adapter.rawQuery.mockResolvedValue(emptyResult);
+
+    return adapter;
+}
+
+/**
+ * Create a mock MySQLAdapter that throws on query execution
+ */
+export function createMockMySQLAdapterWithError(
+    errorMessage = 'Database connection failed'
+): ReturnType<typeof createMockMySQLAdapter> {
+    const adapter = createMockMySQLAdapter();
+    const dbError = new Error(errorMessage);
+
+    adapter.executeQuery.mockRejectedValue(dbError);
+    adapter.executeReadQuery.mockRejectedValue(dbError);
+    adapter.executeWriteQuery.mockRejectedValue(dbError);
+    adapter.rawQuery.mockRejectedValue(dbError);
+    (adapter.getHealth as ReturnType<typeof vi.fn>).mockResolvedValue(createMockHealthStatus(false));
+
+    return adapter;
+}
+
+/**
+ * Create a mock adapter for transaction testing with a mock connection
+ */
+export function createMockMySQLAdapterWithTransaction(): ReturnType<typeof createMockMySQLAdapter> & {
+    mockConnection: {
+        query: ReturnType<typeof vi.fn>;
+        execute: ReturnType<typeof vi.fn>;
+        release: ReturnType<typeof vi.fn>;
+    };
+} {
+    const adapter = createMockMySQLAdapter();
+
+    const mockConnection = {
+        query: vi.fn().mockResolvedValue([[], []]),
+        execute: vi.fn().mockResolvedValue([[], []]),
+        release: vi.fn()
+    };
+
+    (adapter.getTransactionConnection as ReturnType<typeof vi.fn>).mockReturnValue(mockConnection);
+
+    return { ...adapter, mockConnection };
+}
+
+/**
+ * Type alias for the mock adapter return type
+ */
+export type MockMySQLAdapter = ReturnType<typeof createMockMySQLAdapter>;

package/src/__tests__/mocks/index.ts

@@ -0,0 +1,36 @@
+/**
+ * mysql-mcp - Test Mocks
+ * 
+ * Centralized mock factories for testing. All tests should import
+ * mocks from this module for consistency.
+ */
+
+// MySQL Adapter mocks
+export {
+    createMockQueryResult,
+    createMockColumnInfo,
+    createMockTableInfo,
+    createMockIndexInfo,
+    createMockSchemaInfo,
+    createMockHealthStatus,
+    createMockMySQLAdapter,
+    createMockMySQLAdapterEmpty,
+    createMockMySQLAdapterWithError,
+    createMockMySQLAdapterWithTransaction,
+    createMockRequestContext,
+    configureMockAdapterQuery
+} from './adapter.js';
+export type { MockMySQLAdapter } from './adapter.js';
+
+// MySQL connection and pool mocks
+export {
+    createMockFieldPacket,
+    createMockResultSetHeader,
+    createMockPoolConnection,
+    createMockPool,
+    mockMysql2Module,
+    setupMockQueryResponse
+} from './mysql.js';
+
+// Re-export types for convenience
+export type { QueryResult, TableInfo, IndexInfo, SchemaInfo, HealthStatus, ColumnInfo } from '../../types/index.js';