@hyqf98/easy_db_mcp_server 1.0.0

package/dist/index.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig } from './config.js';
+import { createAdapter } from './database/factory.js';
+// Create server instance
+const server = new Server({
+    name: 'hyqf98@easy_db_mcp_server',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Load configuration and create adapter
+let adapter;
+try {
+    const config = loadConfig();
+    adapter = createAdapter(config);
+    await adapter.connect();
+    console.error(`Connected to ${config.type} database`);
+}
+catch (error) {
+    console.error('Failed to connect to database:', error);
+    process.exit(1);
+}
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'list_tables',
+                description: 'List all tables in the database. If EASYDB_DATABASE is not set, the database parameter must be provided.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        database: {
+                            type: 'string',
+                            description: 'Database name (optional if EASYDB_DATABASE is set, otherwise required)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'describe_table',
+                description: 'Get the structure of a table including columns, types, and constraints. If EASYDB_DATABASE is not set, the database parameter must be provided.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        table: {
+                            type: 'string',
+                            description: 'Table name',
+                        },
+                        database: {
+                            type: 'string',
+                            description: 'Database name (optional if EASYDB_DATABASE is set, otherwise required)',
+                        },
+                    },
+                    required: ['table'],
+                },
+            },
+            {
+                name: 'execute_query',
+                description: 'Execute a SELECT query (read-only). If EASYDB_DATABASE is not set, the database parameter must be provided.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        sql: {
+                            type: 'string',
+                            description: 'SQL SELECT query to execute',
+                        },
+                        database: {
+                            type: 'string',
+                            description: 'Database name (optional if EASYDB_DATABASE is set, otherwise required)',
+                        },
+                    },
+                    required: ['sql'],
+                },
+            },
+            {
+                name: 'execute_sql',
+                description: 'Execute any SQL statement (requires EASYDB_ALLOW_WRITE=true). If EASYDB_DATABASE is not set, the database parameter must be provided.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        sql: {
+                            type: 'string',
+                            description: 'SQL statement to execute (INSERT, UPDATE, DELETE, DDL, etc.)',
+                        },
+                        database: {
+                            type: 'string',
+                            description: 'Database name (optional if EASYDB_DATABASE is set, otherwise required)',
+                        },
+                    },
+                    required: ['sql'],
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const config = loadConfig();
+    // Helper function to validate database parameter
+    const getDatabase = (paramDb) => {
+        if (paramDb) {
+            return paramDb;
+        }
+        if (config.database) {
+            return config.database;
+        }
+        throw new Error('Database name is required. Either set EASYDB_DATABASE environment variable or pass the database parameter in the tool call.');
+    };
+    try {
+        switch (name) {
+            case 'list_tables': {
+                const database = getDatabase(args?.database);
+                const tables = await adapter.listTables(database);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(tables, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'describe_table': {
+                const database = getDatabase(args?.database);
+                const columns = await adapter.describeTable(args?.table, database);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(columns, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'execute_query': {
+                const database = getDatabase(args?.database);
+                const result = await adapter.executeQuery(args?.sql, database);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'execute_sql': {
+                if (!config.allowWrite) {
+                    throw new Error('SQL execution requires EASYDB_ALLOW_WRITE=true for safety. Please enable this environment variable if you want to allow write operations.');
+                }
+                const sql = args?.sql;
+                const trimmed = sql.trim().toUpperCase();
+                // Check for DDL statements
+                const isDDL = trimmed.startsWith('CREATE ') ||
+                    trimmed.startsWith('DROP ') ||
+                    trimmed.startsWith('ALTER ') ||
+                    trimmed.startsWith('TRUNCATE ');
+                if (isDDL && !config.allowDDL) {
+                    throw new Error('DDL statements require EASYDB_ALLOW_DDL=true for safety. Please enable this environment variable if you want to allow DDL operations.');
+                }
+                const database = getDatabase(args?.database);
+                const result = await adapter.executeSQL(sql, database);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('EasyDB MCP Server running');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});
+// Cleanup on exit
+process.on('SIGINT', async () => {
+    console.error('\\nShutting down...');
+    await adapter.close();
+    process.exit(0);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hyqf98/easy_db_mcp_server",
+  "version": "1.0.0",
+  "description": "MCP server for database access (MySQL, PostgreSQL, SQLite)",
+  "type": "module",
+  "bin": {
+    "hyqf98@easy_db_mcp_server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "echo \"Tests not yet implemented\""
+  },
+  "keywords": [
+    "mcp",
+    "database",
+    "mysql",
+    "postgresql",
+    "sqlite"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "mysql2": "^3.11.0",
+    "pg": "^8.13.1",
+    "better-sqlite3": "^11.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/pg": "^8.11.10",
+    "@types/better-sqlite3": "^7.6.12",
+    "typescript": "^5.7.2",
+    "tsx": "^4.19.2"
+  }
+}

package/src/config.ts

@@ -0,0 +1,75 @@
+export interface DatabaseConfig {
+  type: 'mysql' | 'postgresql' | 'sqlite';
+  host?: string;
+  port?: number;
+  user?: string;
+  password?: string;
+  database?: string;
+  allowWrite: boolean;
+  allowDDL: boolean;
+}
+
+export function loadConfig(): DatabaseConfig {
+  const type = process.env.EASYDB_TYPE?.trim();
+
+  if (!type) {
+    throw new Error('EASYDB_TYPE is required. Must be one of: mysql, postgresql, sqlite');
+  }
+
+  const normalizedType = type.toLowerCase();
+  if (!['mysql', 'postgresql', 'sqlite'].includes(normalizedType)) {
+    throw new Error(`EASYDB_TYPE must be one of: mysql, postgresql, sqlite. Got: ${type}`);
+  }
+
+  // Parse and validate port
+  let port: number | undefined;
+  const portEnv = process.env.EASYDB_PORT?.trim();
+  if (portEnv) {
+    port = parseInt(portEnv, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      throw new Error(`EASYDB_PORT must be a valid port number (1-65535). Got: ${portEnv}`);
+    }
+  }
+
+  const config: DatabaseConfig = {
+    type: normalizedType as DatabaseConfig['type'],
+    host: process.env.EASYDB_HOST?.trim(),
+    port,
+    user: process.env.EASYDB_USER?.trim(),
+    password: process.env.EASYDB_PASSWORD,
+    database: process.env.EASYDB_DATABASE?.trim(),
+    allowWrite: process.env.EASYDB_ALLOW_WRITE === 'true',
+    allowDDL: process.env.EASYDB_ALLOW_DDL === 'true',
+  };
+
+  // Validate required fields based on type
+  if (normalizedType !== 'sqlite') {
+    if (!config.host || config.host.length === 0) {
+      throw new Error('EASYDB_HOST is required for mysql/postgresql');
+    }
+    if (!config.user || config.user.length === 0) {
+      throw new Error('EASYDB_USER is required for mysql/postgresql');
+    }
+    if (!config.password) {
+      throw new Error('EASYDB_PASSWORD is required for mysql/postgresql');
+    }
+    // database is optional - can be specified in tool calls
+  } else {
+    if (!config.database || config.database.length === 0) {
+      throw new Error('EASYDB_DATABASE (file path) is required for sqlite');
+    }
+  }
+
+  return config;
+}
+
+export function getDefaultPort(type: DatabaseConfig['type']): number {
+  switch (type) {
+    case 'mysql':
+      return 3306;
+    case 'postgresql':
+      return 5432;
+    case 'sqlite':
+      return 0;
+  }
+}

package/src/database/base.ts

@@ -0,0 +1,50 @@
+export interface TableColumn {
+  name: string;
+  type: string;
+  nullable: boolean;
+  defaultValue: string | null;
+  primaryKey: boolean;
+  extra?: string;
+}
+
+export interface TableInfo {
+  name: string;
+  rowCount?: number;
+}
+
+export interface QueryResult {
+  rows: Record<string, unknown>[];
+  rowCount: number;
+}
+
+export interface DatabaseAdapter {
+  /**
+   * Establish connection to the database
+   */
+  connect(): Promise<void>;
+
+  /**
+   * List all tables in the database
+   */
+  listTables(database?: string): Promise<TableInfo[]>;
+
+  /**
+   * Get table structure/column information
+   */
+  describeTable(table: string, database?: string): Promise<TableColumn[]>;
+
+  /**
+   * Execute a SELECT query
+   */
+  executeQuery(sql: string, database?: string): Promise<QueryResult>;
+
+  /**
+   * Execute any SQL statement (INSERT, UPDATE, DELETE, DDL)
+   */
+  executeSQL(sql: string, database?: string): Promise<QueryResult | { affectedRows: number }>;
+
+  /**
+   * Close the database connection
+   */
+  close(): Promise<void>;
+}

package/src/database/factory.ts

@@ -0,0 +1,18 @@
+import { MySQLAdapter } from './mysql.js';
+import { PostgreSQLAdapter } from './postgresql.js';
+import { SQLiteAdapter } from './sqlite.js';
+import type { DatabaseAdapter } from './base.js';
+import type { DatabaseConfig } from '../config.js';
+
+export function createAdapter(config: DatabaseConfig): DatabaseAdapter {
+  switch (config.type) {
+    case 'mysql':
+      return new MySQLAdapter(config);
+    case 'postgresql':
+      return new PostgreSQLAdapter(config);
+    case 'sqlite':
+      return new SQLiteAdapter(config);
+    default:
+      throw new Error(`Unsupported database type: ${config.type}`);
+  }
+}

package/src/database/mysql.ts

@@ -0,0 +1,124 @@
+import mysql from 'mysql2/promise';
+import type {
+  DatabaseAdapter,
+  TableInfo,
+  TableColumn,
+  QueryResult,
+} from './base.js';
+import type { DatabaseConfig } from '../config.js';
+
+export class MySQLAdapter implements DatabaseAdapter {
+  private pool?: mysql.Pool;
+  private config: DatabaseConfig;
+
+  constructor(config: DatabaseConfig) {
+    this.config = config;
+  }
+
+  async connect(): Promise<void> {
+    this.pool = mysql.createPool({
+      host: this.config.host,
+      port: this.config.port || 3306,
+      user: this.config.user,
+      password: this.config.password,
+      database: this.config.database,
+      waitForConnections: true,
+      connectionLimit: 10,
+    });
+
+    // Test connection
+    const connection = await this.pool.getConnection();
+    connection.release();
+  }
+
+  async listTables(database?: string): Promise<TableInfo[]> {
+    if (!this.pool) throw new Error('Not connected');
+
+    const dbName = database || this.config.database;
+    if (!dbName) throw new Error('Database name required');
+
+    const [rows] = await this.pool.query<mysql.RowDataPacket[]>(
+      'SELECT TABLE_NAME as name, TABLE_ROWS as rowCount FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = ?',
+      [dbName]
+    );
+
+    return rows.map((row: any) => ({
+      name: row.name,
+      rowCount: row.rowCount,
+    }));
+  }
+
+  async describeTable(table: string, database?: string): Promise<TableColumn[]> {
+    if (!this.pool) throw new Error('Not connected');
+
+    const dbName = database || this.config.database;
+    if (!dbName) throw new Error('Database name required');
+
+    const [rows] = await this.pool.query<mysql.RowDataPacket[]>(
+      `SELECT
+        COLUMN_NAME as name,
+        DATA_TYPE as type,
+        IS_NULLABLE as nullable,
+        COLUMN_DEFAULT as defaultValue,
+        COLUMN_KEY as primaryKey,
+        EXTRA as extra
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
+      ORDER BY ORDINAL_POSITION`,
+      [dbName, table]
+    );
+
+    return rows.map((row: any) => ({
+      name: row.name,
+      type: row.type,
+      nullable: row.nullable === 'YES',
+      defaultValue: row.defaultValue,
+      primaryKey: row.primaryKey === 'PRI',
+      extra: row.extra,
+    }));
+  }
+
+  async executeQuery(sql: string, database?: string): Promise<QueryResult> {
+    if (!this.pool) throw new Error('Not connected');
+
+    // If database is specified and different from config, we need to handle it
+    // For now, we'll allow queries to use fully qualified table names
+    // Verify it's a SELECT query
+    const trimmed = sql.trim().toUpperCase();
+    if (!trimmed.startsWith('SELECT')) {
+      throw new Error('Only SELECT queries allowed in executeQuery');
+    }
+
+    const [rows] = await this.pool.query(sql);
+
+    return {
+      rows: rows as Record<string, unknown>[],
+      rowCount: Array.isArray(rows) ? rows.length : 0,
+    };
+  }
+
+  async executeSQL(sql: string, database?: string): Promise<QueryResult | { affectedRows: number }> {
+    if (!this.pool) throw new Error('Not connected');
+
+    // Allow SQL execution with database-specific queries
+    const [result] = await this.pool.query(sql);
+
+    // @ts-ignore - MySQL result structure
+    if (result.affectedRows !== undefined) {
+      // @ts-ignore
+      return { affectedRows: result.affectedRows };
+    }
+
+    return {
+      rows: result as Record<string, unknown>[],
+      rowCount: Array.isArray(result) ? result.length : 0,
+    };
+  }
+
+  async close(): Promise<void> {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = undefined;
+    }
+  }
+}

package/src/database/postgresql.ts

@@ -0,0 +1,126 @@
+import pg from 'pg';
+import type {
+  DatabaseAdapter,
+  TableInfo,
+  TableColumn,
+  QueryResult,
+} from './base.js';
+import type { DatabaseConfig } from '../config.js';
+
+const { Pool } = pg;
+
+export class PostgreSQLAdapter implements DatabaseAdapter {
+  private pool?: pg.Pool;
+  private config: DatabaseConfig;
+
+  constructor(config: DatabaseConfig) {
+    this.config = config;
+  }
+
+  async connect(): Promise<void> {
+    this.pool = new Pool({
+      host: this.config.host,
+      port: this.config.port || 5432,
+      user: this.config.user,
+      password: this.config.password,
+      database: this.config.database,
+      max: 10,
+    });
+
+    // Test connection
+    const client = await this.pool.connect();
+    client.release();
+  }
+
+  async listTables(database?: string): Promise<TableInfo[]> {
+    if (!this.pool) throw new Error('Not connected');
+
+    const dbName = database || this.config.database;
+    if (!dbName) throw new Error('Database name required');
+
+    const result = await this.pool.query(
+      `SELECT tablename as name, n_live_tup as "rowCount"
+       FROM pg_stat_user_tables
+       WHERE schemaname = 'public'`
+    );
+
+    return result.rows.map((row: any) => ({
+      name: row.name,
+      rowCount: row.rowCount,
+    }));
+  }
+
+  async describeTable(table: string, database?: string): Promise<TableColumn[]> {
+    if (!this.pool) throw new Error('Not connected');
+
+    const dbName = database || this.config.database;
+
+    const result = await this.pool.query(
+      `SELECT
+        column_name as name,
+        data_type as type,
+        is_nullable as nullable,
+        column_default as "defaultValue",
+        COALESCE(pk.primary, false) as "primaryKey"
+      FROM information_schema.columns
+      LEFT JOIN (
+        SELECT a.attname as primary, c.relname
+        FROM pg_index i
+        JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+        JOIN pg_class c ON c.oid = i.indrelid
+        WHERE i.indisprimary
+      ) pk ON pk.primary = column_name AND pk.relname = $1
+      WHERE table_schema = 'public' AND table_name = $1
+      ORDER BY ordinal_position`,
+      [table]
+    );
+
+    return result.rows.map((row: any) => ({
+      name: row.name,
+      type: row.type,
+      nullable: row.nullable === 'YES',
+      defaultValue: row.defaultValue,
+      primaryKey: row.primaryKey,
+    }));
+  }
+
+  async executeQuery(sql: string, database?: string): Promise<QueryResult> {
+    if (!this.pool) throw new Error('Not connected');
+
+    // Allow queries with fully qualified table names (schema.table)
+    const trimmed = sql.trim().toUpperCase();
+    if (!trimmed.startsWith('SELECT')) {
+      throw new Error('Only SELECT queries allowed in executeQuery');
+    }
+
+    const result = await this.pool.query(sql);
+
+    return {
+      rows: result.rows,
+      rowCount: result.rowCount || 0,
+    };
+  }
+
+  async executeSQL(sql: string, database?: string): Promise<QueryResult | { affectedRows: number }> {
+    if (!this.pool) throw new Error('Not connected');
+
+    // Allow SQL execution with database-specific queries
+    const result = await this.pool.query(sql);
+
+    if (result.rowCount !== null && result.command !== 'SELECT') {
+      return { affectedRows: result.rowCount };
+    }
+
+    return {
+      rows: result.rows,
+      rowCount: result.rowCount || 0,
+    };
+  }
+
+  async close(): Promise<void> {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = undefined;
+    }
+  }
+}