@neverinfamous/mysql-mcp 2.1.0

package/src/transports/http.ts

@@ -0,0 +1,248 @@
+/**
+ * mysql-mcp - HTTP Transport
+ * 
+ * HTTP/SSE transport with OAuth 2.0 support.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { OAuthResourceServer } from '../auth/OAuthResourceServer.js';
+import type { TokenValidator } from '../auth/TokenValidator.js';
+import { validateAuth, formatOAuthError } from '../auth/middleware.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * HTTP transport configuration
+ */
+export interface HttpTransportConfig {
+    /** Port to listen on */
+    port: number;
+
+    /** Host to bind to (default: localhost) */
+    host?: string;
+
+    /** OAuth resource server (optional) */
+    resourceServer?: OAuthResourceServer;
+
+    /** Token validator (optional, required if resourceServer is provided) */
+    tokenValidator?: TokenValidator;
+
+    /** CORS allowed origins (default: none) */
+    corsOrigins?: string[];
+}
+
+/**
+ * HTTP Transport for MCP
+ */
+export class HttpTransport {
+    private server: ReturnType<typeof createServer> | null = null;
+    private readonly config: HttpTransportConfig;
+    private transport: StreamableHTTPServerTransport | null = null;
+    private readonly onConnect?: (transport: StreamableHTTPServerTransport) => void;
+
+    constructor(config: HttpTransportConfig, onConnect?: (transport: StreamableHTTPServerTransport) => void) {
+        this.config = {
+            ...config,
+            host: config.host ?? 'localhost'
+        };
+        this.onConnect = onConnect;
+    }
+
+    /**
+     * Start the HTTP server
+     */
+    async start(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => {
+                this.handleRequest(req, res).catch((error: unknown) => {
+                    logger.error('HTTP request handler error', { error: String(error) });
+                    if (!res.headersSent) {
+                        res.writeHead(500);
+                        res.end(JSON.stringify({ error: 'Internal server error' }));
+                    }
+                });
+            });
+
+            this.server.on('error', reject);
+
+            this.server.listen(this.config.port, this.config.host, () => {
+                logger.info(`HTTP transport listening on ${this.config.host}:${this.config.port}`);
+                resolve();
+            });
+        });
+    }
+
+    /**
+     * Stop the HTTP server
+     */
+    async stop(): Promise<void> {
+        return new Promise((resolve) => {
+            if (this.server) {
+                this.server.close(() => {
+                    logger.info('HTTP transport stopped');
+                    resolve();
+                });
+            } else {
+                resolve();
+            }
+        });
+    }
+
+    /**
+     * Handle incoming HTTP request
+     */
+    private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+        // Set security headers for all responses
+        this.setSecurityHeaders(res);
+
+        // Set CORS headers
+        this.setCorsHeaders(req, res);
+
+        // Handle preflight
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+
+        const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+
+        // Handle well-known endpoints
+        if (url.pathname === '/.well-known/oauth-protected-resource') {
+            this.handleProtectedResourceMetadata(res);
+            return;
+        }
+
+        // Health check
+        if (url.pathname === '/health') {
+            this.handleHealthCheck(res);
+            return;
+        }
+
+        // Authenticate if OAuth is configured
+        // Note: For SSE connection (/sse), we authenticate via query param or header
+        if (this.config.resourceServer && this.config.tokenValidator) {
+            try {
+                // For regular requests
+                await validateAuth(req.headers.authorization, {
+                    tokenValidator: this.config.tokenValidator,
+                    required: true
+                });
+            } catch (error) {
+                const { status, body } = formatOAuthError(error);
+                res.writeHead(status, {
+                    'Content-Type': 'application/json',
+                    'WWW-Authenticate': 'Bearer'
+                });
+                res.end(JSON.stringify(body));
+                return;
+            }
+        }
+
+        // Handle MCP requests
+        if (url.pathname === '/sse') {
+            await this.handleSSERequest(req, res);
+            return;
+        }
+
+        if (url.pathname === '/messages') {
+            await this.handleMessageRequest(req, res);
+            return;
+        }
+
+        res.writeHead(404);
+        res.end(JSON.stringify({ error: 'Not found' }));
+    }
+
+    /**
+     * Handle SSE connection request
+     */
+    private async handleSSERequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+        // StreamableHTTPServerTransport usage guided by type feedback and introspection
+        const transport = new StreamableHTTPServerTransport();
+        this.transport = transport;
+
+        await transport.start();
+
+        if (this.onConnect) {
+            this.onConnect(transport);
+        }
+
+        // Handle the request (keeps connection open for SSE)
+        await transport.handleRequest(req, res);
+    }
+
+    /**
+     * Handle MCP message request
+     */
+    private async handleMessageRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+        if (!this.transport) {
+            res.writeHead(400);
+            res.end(JSON.stringify({ error: 'No active connection' }));
+            return;
+        }
+
+        await this.transport.handleRequest(req, res);
+    }
+
+    /**
+     * Handle protected resource metadata endpoint
+     */
+    private handleProtectedResourceMetadata(res: ServerResponse): void {
+        if (!this.config.resourceServer) {
+            res.writeHead(404);
+            res.end(JSON.stringify({ error: 'OAuth not configured' }));
+            return;
+        }
+
+        const metadata = this.config.resourceServer.getMetadata();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(metadata));
+    }
+
+    /**
+     * Handle health check endpoint
+     */
+    private handleHealthCheck(res: ServerResponse): void {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'healthy', timestamp: new Date().toISOString() }));
+    }
+
+    /**
+     * Set security headers for all responses
+     */
+    private setSecurityHeaders(res: ServerResponse): void {
+        // Prevent MIME type sniffing
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        // Prevent clickjacking
+        res.setHeader('X-Frame-Options', 'DENY');
+        // Enable XSS filtering
+        res.setHeader('X-XSS-Protection', '1; mode=block');
+        // Prevent caching of API responses
+        res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+        // Content Security Policy - API server has no content to load
+        res.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'");
+    }
+
+    /**
+     * Set CORS headers
+     */
+    private setCorsHeaders(req: IncomingMessage, res: ServerResponse): void {
+        const origin = req.headers.origin;
+
+        // Only allow configured origins
+        if (origin && this.config.corsOrigins?.includes(origin)) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+            res.setHeader('Access-Control-Max-Age', '86400');
+        }
+    }
+}
+
+/**
+ * Create an HTTP transport instance
+ */
+export function createHttpTransport(config: HttpTransportConfig, onConnect?: (transport: StreamableHTTPServerTransport) => void): HttpTransport {
+    return new HttpTransport(config, onConnect);
+}

package/src/transports/index.ts

@@ -0,0 +1,7 @@
+/**
+ * mysql-mcp - Transports Module
+ * 
+ * Transport implementations for MCP server.
+ */
+
+export { HttpTransport, createHttpTransport, type HttpTransportConfig } from './http.js';

package/src/types/__tests__/types.test.ts

@@ -0,0 +1,201 @@
+/**
+ * mysql-mcp - Types Unit Tests
+ * 
+ * Tests for error classes defined in types/index.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+    MySQLMcpError,
+    ConnectionError,
+    PoolError,
+    QueryError,
+    AuthenticationError,
+    AuthorizationError,
+    ValidationError,
+    TransactionError
+} from '../index.js';
+
+describe('Error Classes', () => {
+    describe('MySQLMcpError', () => {
+        it('should create error with message and code', () => {
+            const error = new MySQLMcpError('Test error', 'TEST_CODE');
+            expect(error.message).toBe('Test error');
+            expect(error.code).toBe('TEST_CODE');
+            expect(error.name).toBe('MySQLMcpError');
+        });
+
+        it('should create error with details', () => {
+            const details = { table: 'users', operation: 'insert' };
+            const error = new MySQLMcpError('Test error', 'TEST_CODE', details);
+            expect(error.details).toEqual(details);
+        });
+
+        it('should be instance of Error', () => {
+            const error = new MySQLMcpError('Test', 'CODE');
+            expect(error).toBeInstanceOf(Error);
+        });
+
+        it('should have stack trace', () => {
+            const error = new MySQLMcpError('Test', 'CODE');
+            expect(error.stack).toBeDefined();
+        });
+    });
+
+    describe('ConnectionError', () => {
+        it('should create with correct code', () => {
+            const error = new ConnectionError('Connection failed');
+            expect(error.code).toBe('CONNECTION_ERROR');
+            expect(error.name).toBe('ConnectionError');
+        });
+
+        it('should be instance of MySQLMcpError', () => {
+            const error = new ConnectionError('Failed');
+            expect(error).toBeInstanceOf(MySQLMcpError);
+        });
+
+        it('should accept details', () => {
+            const error = new ConnectionError('Failed', { host: 'localhost' });
+            expect(error.details?.['host']).toBe('localhost');
+        });
+    });
+
+    describe('PoolError', () => {
+        it('should create with correct code', () => {
+            const error = new PoolError('Pool exhausted');
+            expect(error.code).toBe('POOL_ERROR');
+            expect(error.name).toBe('PoolError');
+        });
+
+        it('should be instance of MySQLMcpError', () => {
+            const error = new PoolError('Exhausted');
+            expect(error).toBeInstanceOf(MySQLMcpError);
+        });
+
+        it('should accept details', () => {
+            const error = new PoolError('Exhausted', { active: 10, limit: 10 });
+            expect(error.details).toEqual({ active: 10, limit: 10 });
+        });
+    });
+
+    describe('QueryError', () => {
+        it('should create with correct code', () => {
+            const error = new QueryError('Query failed');
+            expect(error.code).toBe('QUERY_ERROR');
+            expect(error.name).toBe('QueryError');
+        });
+
+        it('should be instance of MySQLMcpError', () => {
+            const error = new QueryError('Failed');
+            expect(error).toBeInstanceOf(MySQLMcpError);
+        });
+
+        it('should accept SQL in details', () => {
+            const error = new QueryError('Syntax error', { sql: 'SELECT * FORM users' });
+            expect(error.details?.['sql']).toContain('FORM');
+        });
+    });
+
+    describe('AuthenticationError', () => {
+        it('should create with correct code', () => {
+            const error = new AuthenticationError('Invalid credentials');
+            expect(error.code).toBe('AUTHENTICATION_ERROR');
+            expect(error.name).toBe('AuthenticationError');
+        });
+
+        it('should be instance of MySQLMcpError', () => {
+            const error = new AuthenticationError('Invalid');
+            expect(error).toBeInstanceOf(MySQLMcpError);
+        });
+
+        it('should accept details', () => {
+            const error = new AuthenticationError('Failed', { reason: 'expired_token' });
+            expect(error.details?.['reason']).toBe('expired_token');
+        });
+    });
+
+    describe('AuthorizationError', () => {
+        it('should create with correct code', () => {
+            const error = new AuthorizationError('Insufficient permissions');
+            expect(error.code).toBe('AUTHORIZATION_ERROR');
+            expect(error.name).toBe('AuthorizationError');
+        });
+
+        it('should be instance of MySQLMcpError', () => {
+            const error = new AuthorizationError('Forbidden');
+            expect(error).toBeInstanceOf(MySQLMcpError);
+        });
+
+        it('should accept details', () => {
+            const error = new AuthorizationError('Denied', {
+                requiredScope: 'write',
+                userScopes: ['read']
+            });
+            expect(error.details?.['requiredScope']).toBe('write');
+        });
+    });
+
+    describe('ValidationError', () => {
+        it('should create with correct code', () => {
+            const error = new ValidationError('Invalid input');
+            expect(error.code).toBe('VALIDATION_ERROR');
+            expect(error.name).toBe('ValidationError');
+        });
+
+        it('should be instance of MySQLMcpError', () => {
+            const error = new ValidationError('Invalid');
+            expect(error).toBeInstanceOf(MySQLMcpError);
+        });
+
+        it('should accept details with field info', () => {
+            const error = new ValidationError('Invalid field', {
+                field: 'email',
+                value: 'not-an-email',
+                expected: 'valid email format'
+            });
+            expect(error.details?.['field']).toBe('email');
+        });
+    });
+
+    describe('TransactionError', () => {
+        it('should create with correct code', () => {
+            const error = new TransactionError('Transaction failed');
+            expect(error.code).toBe('TRANSACTION_ERROR');
+            expect(error.name).toBe('TransactionError');
+        });
+
+        it('should be instance of MySQLMcpError', () => {
+            const error = new TransactionError('Failed');
+            expect(error).toBeInstanceOf(MySQLMcpError);
+        });
+
+        it('should accept details with transaction ID', () => {
+            const error = new TransactionError('Rollback failed', {
+                transactionId: 'txn-12345',
+                reason: 'deadlock'
+            });
+            expect(error.details?.['transactionId']).toBe('txn-12345');
+        });
+    });
+
+    describe('Error inheritance chain', () => {
+        it('should maintain proper prototype chain for all errors', () => {
+            const errors = [
+                new ConnectionError('test'),
+                new PoolError('test'),
+                new QueryError('test'),
+                new AuthenticationError('test'),
+                new AuthorizationError('test'),
+                new ValidationError('test'),
+                new TransactionError('test')
+            ];
+
+            for (const error of errors) {
+                expect(error).toBeInstanceOf(Error);
+                expect(error).toBeInstanceOf(MySQLMcpError);
+                expect(typeof error.message).toBe('string');
+                expect(typeof error.code).toBe('string');
+            }
+        });
+    });
+});

package/src/types/index.ts

@@ -0,0 +1,58 @@
+/**
+ * mysql-mcp - MySQL MCP Server
+ * 
+ * Core type definitions for the MCP server, database adapters,
+ * OAuth 2.0 authentication, and tool filtering.
+ * 
+ * This is a barrel export that re-exports all types from the modules directory.
+ */
+
+// Database and connection types
+export type { DatabaseType, DatabaseConfig, MySQLOptions, PoolConfig, PoolStats, HealthStatus } from './modules/database.js';
+
+// Query and schema types
+export type {
+    QueryResult,
+    ColumnInfo,
+    FieldInfo,
+    TableInfo,
+    SchemaInfo,
+    IndexInfo,
+    ConstraintInfo,
+    RoutineInfo,
+    TriggerInfo
+} from './modules/query.js';
+
+// Server configuration types
+export type { TransportType, McpServerConfig } from './modules/server.js';
+
+// OAuth and authentication types
+export type { OAuthConfig, OAuthScope, TokenClaims, RequestContext } from './modules/oauth.js';
+
+// Tool, resource, and filtering types
+export type {
+    ToolGroup,
+    MetaGroup,
+    RouterConfig,
+    MySQLShellConfig,
+    ToolFilterRule,
+    ToolFilterConfig,
+    AdapterCapabilities,
+    ToolAnnotations,
+    ToolDefinition,
+    ResourceAnnotations,
+    ResourceDefinition,
+    PromptDefinition
+} from './modules/tools.js';
+
+// Error classes
+export {
+    MySQLMcpError,
+    ConnectionError,
+    PoolError,
+    QueryError,
+    AuthenticationError,
+    AuthorizationError,
+    ValidationError,
+    TransactionError
+} from './modules/errors.js';

package/src/types/modules/database.ts

@@ -0,0 +1,127 @@
+/**
+ * Database and Connection Types
+ * 
+ * Type definitions for database configuration, connection pooling,
+ * and health monitoring.
+ */
+
+/**
+ * Database type identifier (MySQL only for this server)
+ */
+export type DatabaseType = 'mysql';
+
+/**
+ * MySQL connection configuration
+ */
+export interface DatabaseConfig {
+    /** Database type identifier */
+    type: DatabaseType;
+
+    /** Connection string (mysql://user:pass@host:port/database) */
+    connectionString?: string;
+
+    /** Individual connection parameters (alternative to connectionString) */
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string;
+
+    /** Connection pool options */
+    pool?: PoolConfig;
+
+    /** Additional MySQL-specific options */
+    options?: MySQLOptions;
+}
+
+/**
+ * MySQL-specific connection options
+ */
+export interface MySQLOptions {
+    /** SSL configuration */
+    ssl?: boolean | {
+        ca?: string;
+        cert?: string;
+        key?: string;
+        rejectUnauthorized?: boolean;
+    };
+
+    /** Character set (default: utf8mb4) */
+    charset?: string;
+
+    /** Timezone (default: local) */
+    timezone?: string;
+
+    /** Enable multiple statements (default: false for security) */
+    multipleStatements?: boolean;
+
+    /** Connection timeout in ms */
+    connectTimeout?: number;
+
+    /** Support big numbers as strings */
+    supportBigNumbers?: boolean;
+
+    /** Convert big numbers to strings */
+    bigNumberStrings?: boolean;
+
+    /** Date strings instead of Date objects */
+    dateStrings?: boolean;
+}
+
+/**
+ * Connection pool configuration
+ */
+export interface PoolConfig {
+    /** Maximum number of connections in pool (default: 10) */
+    connectionLimit?: number;
+
+    /** Wait for connections if none available (default: true) */
+    waitForConnections?: boolean;
+
+    /** Maximum waiting requests (0 = unlimited, default: 0) */
+    queueLimit?: number;
+
+    /** Connection acquire timeout in ms (default: 10000) */
+    acquireTimeout?: number;
+
+    /** Enable TCP keep-alive (default: true) */
+    enableKeepAlive?: boolean;
+
+    /** Keep-alive initial delay in ms (default: 0) */
+    keepAliveInitialDelay?: number;
+
+    /** Idle timeout before closing connection in ms */
+    idleTimeout?: number;
+}
+
+/**
+ * Connection pool statistics
+ */
+export interface PoolStats {
+    /** Total connections in pool */
+    total: number;
+
+    /** Active connections (in use) */
+    active: number;
+
+    /** Idle connections (available) */
+    idle: number;
+
+    /** Waiting requests in queue */
+    waiting: number;
+
+    /** Total queries executed */
+    totalQueries: number;
+}
+
+/**
+ * Database connection health status
+ */
+export interface HealthStatus {
+    connected: boolean;
+    latencyMs?: number | undefined;
+    version?: string | undefined;
+    poolStats?: PoolStats | undefined;
+    details?: Record<string, unknown> | undefined;
+    error?: string | undefined;
+}