@neverinfamous/mysql-mcp 2.1.0

package/src/types/modules/errors.ts

@@ -0,0 +1,89 @@
+/**
+ * Error Types
+ * 
+ * Custom error classes for mysql-mcp server.
+ */
+
+/**
+ * Base error class for mysql-mcp
+ */
+export class MySQLMcpError extends Error {
+    constructor(
+        message: string,
+        public readonly code: string,
+        public readonly details?: Record<string, unknown>
+    ) {
+        super(message);
+        this.name = 'MySQLMcpError';
+    }
+}
+
+/**
+ * Database connection error
+ */
+export class ConnectionError extends MySQLMcpError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, 'CONNECTION_ERROR', details);
+        this.name = 'ConnectionError';
+    }
+}
+
+/**
+ * Connection pool error
+ */
+export class PoolError extends MySQLMcpError {
+    constructor(message: string, details?: Record<string, unknown>, code?: string) {
+        super(message, code ?? 'POOL_ERROR', details);
+        this.name = 'PoolError';
+    }
+}
+
+/**
+ * Query execution error
+ */
+export class QueryError extends MySQLMcpError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, 'QUERY_ERROR', details);
+        this.name = 'QueryError';
+    }
+}
+
+/**
+ * Authentication error
+ */
+export class AuthenticationError extends MySQLMcpError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, 'AUTHENTICATION_ERROR', details);
+        this.name = 'AuthenticationError';
+    }
+}
+
+/**
+ * Authorization error (insufficient permissions)
+ */
+export class AuthorizationError extends MySQLMcpError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, 'AUTHORIZATION_ERROR', details);
+        this.name = 'AuthorizationError';
+    }
+}
+
+/**
+ * Validation error for input parameters
+ */
+export class ValidationError extends MySQLMcpError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, 'VALIDATION_ERROR', details);
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Transaction error
+ */
+export class TransactionError extends MySQLMcpError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, 'TRANSACTION_ERROR', details);
+        this.name = 'TransactionError';
+    }
+}

package/src/types/modules/oauth.ts

@@ -0,0 +1,91 @@
+/**
+ * OAuth and Authentication Types
+ * 
+ * Type definitions for OAuth 2.0 configuration, token validation,
+ * scopes, and request context.
+ */
+
+/**
+ * OAuth 2.0 configuration
+ */
+export interface OAuthConfig {
+    /** Enable OAuth authentication */
+    enabled: boolean;
+
+    /** Authorization server URL */
+    authorizationServerUrl?: string;
+
+    /** Token validation endpoint */
+    tokenEndpoint?: string;
+
+    /** JWKS URI for token verification */
+    jwksUri?: string;
+
+    /** Expected audience in tokens */
+    audience?: string;
+
+    /** Expected issuer in tokens */
+    issuer?: string;
+
+    /** Clock tolerance for token validation (seconds) */
+    clockTolerance?: number;
+
+    /** JWKS cache TTL (seconds) */
+    jwksCacheTtl?: number;
+
+    /** Paths that bypass authentication */
+    publicPaths?: string[];
+}
+
+/**
+ * OAuth scopes for access control
+ */
+export type OAuthScope =
+    | 'read'           // Read-only access to all databases
+    | 'write'          // Read and write access
+    | 'admin'          // Full administrative access
+    | `db:${string}`   // Access to specific database
+    | `table:${string}:${string}`; // Access to specific table
+
+/**
+ * Validated OAuth token claims
+ */
+export interface TokenClaims {
+    /** Subject (user ID) */
+    sub: string;
+
+    /** Granted scopes */
+    scopes: OAuthScope[];
+
+    /** Token expiration time */
+    exp: number;
+
+    /** Token issued at time */
+    iat: number;
+
+    /** Token issuer */
+    iss?: string;
+
+    /** Token audience */
+    aud?: string | string[];
+
+    /** Additional claims */
+    [key: string]: unknown;
+}
+
+/**
+ * Request context with authentication info
+ */
+export interface RequestContext {
+    /** Validated token claims (if authenticated) */
+    auth?: TokenClaims;
+
+    /** Raw access token */
+    accessToken?: string;
+
+    /** Request timestamp */
+    timestamp: Date;
+
+    /** Request ID for tracing */
+    requestId: string;
+}

package/src/types/modules/query.ts

@@ -0,0 +1,140 @@
+/**
+ * Query and Schema Types
+ * 
+ * Type definitions for query results, columns, tables, indexes,
+ * and other database schema elements.
+ */
+
+/**
+ * Query execution result
+ */
+export interface QueryResult {
+    /** Rows returned (for SELECT queries) */
+    rows?: Record<string, unknown>[];
+
+    /** Number of rows affected (for INSERT/UPDATE/DELETE) */
+    rowsAffected?: number;
+
+    /** Last inserted ID (for INSERT with auto-increment) */
+    lastInsertId?: number | bigint;
+
+    /** Warning count */
+    warningCount?: number;
+
+    /** Query execution time in milliseconds */
+    executionTimeMs?: number;
+
+    /** Column metadata */
+    columns?: ColumnInfo[];
+
+    /** Field info from MySQL */
+    fields?: FieldInfo[];
+}
+
+/**
+ * Column metadata information
+ */
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    primaryKey?: boolean;
+    defaultValue?: unknown;
+    autoIncrement?: boolean;
+    unsigned?: boolean;
+    zerofill?: boolean;
+    characterSet?: string;
+    collation?: string;
+    comment?: string;
+}
+
+/**
+ * MySQL field information from result set
+ */
+export interface FieldInfo {
+    name: string;
+    table: string;
+    database: string;
+    type: number;
+    length: number;
+    flags: number;
+}
+
+/**
+ * Table information
+ */
+export interface TableInfo {
+    name: string;
+    schema?: string;
+    type: 'table' | 'view' | 'materialized_view';
+    engine?: string;
+    rowCount?: number;
+    dataLength?: number;
+    indexLength?: number;
+    createTime?: Date;
+    updateTime?: Date;
+    collation?: string;
+    comment?: string;
+    columns?: ColumnInfo[];
+}
+
+/**
+ * Schema information for a database
+ */
+export interface SchemaInfo {
+    tables: TableInfo[];
+    views?: TableInfo[];
+    indexes?: IndexInfo[];
+    constraints?: ConstraintInfo[];
+    routines?: RoutineInfo[];
+    triggers?: TriggerInfo[];
+}
+
+/**
+ * Index information
+ */
+export interface IndexInfo {
+    name: string;
+    tableName: string;
+    columns: string[];
+    unique: boolean;
+    type: 'BTREE' | 'HASH' | 'FULLTEXT' | 'SPATIAL';
+    cardinality?: number;
+}
+
+/**
+ * Constraint information
+ */
+export interface ConstraintInfo {
+    name: string;
+    tableName: string;
+    type: 'primary_key' | 'foreign_key' | 'unique' | 'check';
+    columns: string[];
+    referencedTable?: string;
+    referencedColumns?: string[];
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+}
+
+/**
+ * Stored procedure/function information
+ */
+export interface RoutineInfo {
+    name: string;
+    type: 'PROCEDURE' | 'FUNCTION';
+    database: string;
+    definer: string;
+    created: Date;
+    modified: Date;
+}
+
+/**
+ * Trigger information
+ */
+export interface TriggerInfo {
+    name: string;
+    table: string;
+    event: 'INSERT' | 'UPDATE' | 'DELETE';
+    timing: 'BEFORE' | 'AFTER';
+    statement: string;
+}

package/src/types/modules/server.ts

@@ -0,0 +1,39 @@
+/**
+ * Server Configuration Types
+ * 
+ * Type definitions for MCP server transport and configuration.
+ */
+
+import type { DatabaseConfig } from './database.js';
+import type { OAuthConfig } from './oauth.js';
+
+/**
+ * Transport type for MCP communication
+ */
+export type TransportType = 'stdio' | 'http' | 'sse';
+
+/**
+ * MCP Server configuration
+ */
+export interface McpServerConfig {
+    /** Server name */
+    name: string;
+
+    /** Server version */
+    version: string;
+
+    /** Transport configuration */
+    transport: TransportType;
+
+    /** HTTP port (for http/sse transports) */
+    port?: number;
+
+    /** Database configurations */
+    databases: DatabaseConfig[];
+
+    /** OAuth configuration */
+    oauth?: OAuthConfig;
+
+    /** Tool filtering configuration */
+    toolFilter?: string;
+}

package/src/types/modules/tools.ts

@@ -0,0 +1,296 @@
+/**
+ * Tool, Resource, and Prompt Types
+ * 
+ * Type definitions for MCP tools, resources, prompts, filtering,
+ * and adapter capabilities.
+ */
+
+import type { OAuthScope } from './oauth.js';
+import type { RequestContext } from './oauth.js';
+
+/**
+ * Tool group identifiers for MySQL
+ */
+export type ToolGroup =
+    | 'core'           // Basic CRUD, schema operations
+    | 'json'           // JSON operations (MySQL 5.7+)
+    | 'text'           // Text processing (LIKE, REGEXP)
+    | 'fulltext'       // FULLTEXT search
+    | 'performance'    // EXPLAIN, query analysis
+    | 'optimization'   // Index hints, recommendations
+    | 'admin'          // OPTIMIZE, ANALYZE, FLUSH
+    | 'monitoring'     // PROCESSLIST, status variables
+    | 'backup'         // Export, import, mysqldump
+    | 'replication'    // Master/slave, binlog
+    | 'partitioning'   // Partition management
+    | 'transactions'   // Transaction control
+    | 'router'         // MySQL Router management
+    | 'proxysql'       // ProxySQL management
+    | 'shell'          // MySQL Shell utilities
+    // New tool groups (v2.0.0)
+    | 'schema'         // Schema object management
+    | 'events'         // Event Scheduler
+    | 'sysschema'      // sys schema diagnostics
+    | 'stats'          // Statistical analysis
+    | 'spatial'        // GIS/Spatial functions
+    | 'security'       // Security and auditing
+    | 'cluster'        // Group Replication & InnoDB Cluster
+    | 'roles'          // Role management
+    | 'docstore';      // Document Store / X DevAPI
+
+/**
+ * Meta-group identifiers for common multi-group selections
+ * These are shortcuts that expand to multiple ToolGroups
+ */
+export type MetaGroup =
+    | 'starter'        // Recommended default (Core, JSON, Trans, Text) ~38 tools
+    | 'essential'      // Minimal footprint (Core, Trans) ~15 tools
+    | 'dev-power'      // Power Developer (Core, Schema, Perf, Stats, Fulltext) ~45 tools
+    | 'ai-data'        // AI Data Analyst (Core, JSON, DocStore, Text, Fulltext) ~44 tools
+    | 'ai-spatial'     // AI Spatial Analyst (Core, Spatial, Stats, Perf) ~43 tools
+    | 'dba-monitor'    // DBA Monitoring (Core, Monitor, Perf, SysSchema, Opt) ~35 tools
+    | 'dba-manage'     // DBA Management (Core, Admin, Backup, Repl, Parts, Events) ~33 tools
+    | 'dba-secure'     // DBA Security (Core, Security, Roles, Cluster) ~42 tools
+    | 'base-core'      // Base: Core Operations ~48 tools
+    | 'base-advanced'  // Base: Advanced Features ~39 tools
+    | 'ecosystem';     // External Tools ~31 tools
+
+/**
+ * MySQL Router REST API configuration
+ */
+export interface RouterConfig {
+    /** Router REST API base URL (e.g., https://localhost:8443) */
+    url?: string;
+
+    /** Router API username */
+    username?: string;
+
+    /** Router API password */
+    password?: string;
+
+    /** Skip TLS certificate verification (for self-signed certs) */
+    insecure?: boolean;
+
+    /** API version path (default: /api/20190715) */
+    apiVersion?: string;
+}
+
+/**
+ * MySQL Shell configuration
+ */
+export interface MySQLShellConfig {
+    /** Path to mysqlsh binary (defaults to 'mysqlsh' from PATH) */
+    binPath?: string;
+
+    /** Timeout for shell commands in milliseconds (default: 300000 = 5 min) */
+    timeout?: number;
+
+    /** Working directory for dump/load operations */
+    workDir?: string;
+}
+
+/**
+ * Tool filter rule
+ */
+export interface ToolFilterRule {
+    /** Rule type: include or exclude */
+    type: 'include' | 'exclude';
+
+    /** Target: group name or tool name */
+    target: string;
+
+    /** Whether target is a group (true) or individual tool (false) */
+    isGroup: boolean;
+}
+
+/**
+ * Parsed tool filter configuration
+ */
+export interface ToolFilterConfig {
+    /** Original filter string */
+    raw: string;
+
+    /** Parsed rules in order */
+    rules: ToolFilterRule[];
+
+    /** Set of enabled tool names after applying rules */
+    enabledTools: Set<string>;
+}
+
+/**
+ * Capabilities supported by a database adapter
+ */
+export interface AdapterCapabilities {
+    /** Supports JSON operations */
+    json: boolean;
+
+    /** Supports full-text search */
+    fullTextSearch: boolean;
+
+    /** Supports vector/embedding operations */
+    vector: boolean;
+
+    /** Supports geospatial operations */
+    geospatial: boolean;
+
+    /** Supports transactions */
+    transactions: boolean;
+
+    /** Supports prepared statements */
+    preparedStatements: boolean;
+
+    /** Supports connection pooling */
+    connectionPooling: boolean;
+
+    /** Supports partitioning */
+    partitioning: boolean;
+
+    /** Supports replication */
+    replication: boolean;
+
+    /** Additional capability flags */
+    [key: string]: boolean;
+}
+
+/**
+ * MCP Tool Annotations (MCP Spec 2025-11-25)
+ * 
+ * Behavioral hints for AI clients to understand tool characteristics.
+ * These are hints only - clients may ignore them.
+ */
+export interface ToolAnnotations {
+    /** 
+     * Tool does not modify state (idempotent reads).
+     * AI clients may auto-execute read-only tools without confirmation.
+     */
+    readOnlyHint?: boolean;
+
+    /** 
+     * Tool may permanently delete/destroy data.
+     * AI clients should require explicit confirmation.
+     */
+    destructiveHint?: boolean;
+
+    /** 
+     * Repeated calls with same args produce same result.
+     * Useful for caching or retry logic.
+     */
+    idempotentHint?: boolean;
+
+    /** 
+     * Tool interacts with external services (network, APIs).
+     * May have side effects outside the server.
+     */
+    openWorldHint?: boolean;
+}
+
+/**
+ * Tool definition for registration
+ */
+export interface ToolDefinition {
+    /** Unique tool name */
+    name: string;
+
+    /** Human-readable description */
+    description: string;
+
+    /** Tool group for filtering */
+    group: ToolGroup;
+
+    /** Zod schema for input validation */
+    inputSchema: unknown;
+
+    /** Required OAuth scopes */
+    requiredScopes?: OAuthScope[];
+
+    /** Tool handler function */
+    handler: (params: unknown, context: RequestContext) => Promise<unknown>;
+
+    // MCP 2025-11-25 Tool Enhancements
+
+    /** Human-readable display title (defaults to name if not provided) */
+    title?: string;
+
+    /** JSON Schema for structured tool output (enables schema validation) */
+    outputSchema?: unknown;
+
+    /** Behavioral hints for AI clients */
+    annotations?: ToolAnnotations;
+}
+
+/**
+ * MCP Resource Annotations (MCP Spec 2025-11-25)
+ * 
+ * Metadata hints for AI clients to understand resource characteristics.
+ */
+export interface ResourceAnnotations {
+    /** 
+     * Intended audience for this resource.
+     * 'user' = display to human, 'assistant' = use in AI context.
+     */
+    audience?: ('user' | 'assistant')[];
+
+    /** 
+     * Importance level from 0.0 (optional) to 1.0 (required).
+     * AI clients may use this for context prioritization.
+     */
+    priority?: number;
+
+    /** 
+     * ISO 8601 timestamp of when resource was last modified.
+     * Useful for cache invalidation and freshness checks.
+     */
+    lastModified?: string;
+}
+
+/**
+ * Resource definition for MCP
+ */
+export interface ResourceDefinition {
+    /** Resource URI template */
+    uri: string;
+
+    /** Human-readable name */
+    name: string;
+
+    /** Description */
+    description: string;
+
+    /** MIME type */
+    mimeType?: string;
+
+    /** Resource handler */
+    handler: (uri: string, context: RequestContext) => Promise<unknown>;
+
+    // MCP 2025-11-25 Resource Enhancements
+
+    /** Human-readable display title */
+    title?: string;
+
+    /** Size in bytes (if known) */
+    size?: number;
+
+    /** Resource metadata annotations */
+    annotations?: ResourceAnnotations;
+}
+
+/**
+ * Prompt definition for MCP
+ */
+export interface PromptDefinition {
+    /** Prompt name */
+    name: string;
+
+    /** Description */
+    description: string;
+
+    /** Argument definitions */
+    arguments?: {
+        name: string;
+        description: string;
+        required?: boolean;
+    }[];
+
+    /** Prompt handler */
+    handler: (args: Record<string, string>, context: RequestContext) => Promise<unknown>;
+}