@hyqf98/easy_db_mcp_server 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# EasyDB MCP Server
+
+一个通过 npx 部署的 MCP 服务器，为 AI 助手提供统一的数据库访问接口。
+
+## 支持的数据库
+
+- MySQL (5.7+)
+- PostgreSQL (12+)
+- SQLite (3+)
+
+## 快速开始
+
+```bash
+npx hyqf98@easy_db_mcp_server
+```
+
+## 配置
+
+### 环境变量
+
+| 变量 | 必填 | 说明 |
+|-----|-----|------|
+| `EASYDB_TYPE` | 是 | 数据库类型：`mysql`、`postgresql` 或 `sqlite` |
+| `EASYDB_HOST` | 是* | 数据库主机（SQLite 不需要） |
+| `EASYDB_PORT` | 否 | 数据库端口（默认值：MySQL=3306、PostgreSQL=5432） |
+| `EASYDB_USER` | 是* | 数据库用户（SQLite 不需要） |
+| `EASYDB_PASSWORD` | 是* | 数据库密码（SQLite 不需要） |
+| `EASYDB_DATABASE` | 否 | 默认数据库名或 SQLite 文件路径 |
+| `EASYDB_ALLOW_WRITE` | 否 | 允许写入操作（默认：false） |
+| `EASYDB_ALLOW_DDL` | 否 | 允许 DDL 操作（默认：false） |
+
+### 配置示例
+
+**MySQL：**
+```bash
+export EASYDB_TYPE=mysql
+export EASYDB_HOST=localhost
+export EASYDB_USER=root
+export EASYDB_PASSWORD=secret
+export EASYDB_DATABASE=mydb
+```
+
+**PostgreSQL：**
+```bash
+export EASYDB_TYPE=postgresql
+export EASYDB_HOST=localhost
+export EASYDB_USER=postgres
+export EASYDB_PASSWORD=secret
+export EASYDB_DATABASE=mydb
+```
+
+**SQLite：**
+```bash
+export EASYDB_TYPE=sqlite
+export EASYDB_DATABASE=/path/to/database.db
+```
+
+## Claude Desktop 配置
+
+将以下配置添加到 Claude Desktop 配置文件中：
+
+**macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows：** `%APPDATA%/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "npx",
+      "args": ["hyqf98@easy_db_mcp_server"],
+      "env": {
+        "EASYDB_TYPE": "mysql",
+        "EASYDB_HOST": "localhost",
+        "EASYDB_USER": "root",
+        "EASYDB_PASSWORD": "your_password",
+        "EASYDB_DATABASE": "mydb"
+      }
+    }
+  }
+}
+```
+
+## 可用工具
+
+### list_tables
+
+列出数据库中的所有表。
+
+**参数：**
+- `database`（可选）：数据库名
+
+**示例：**
+```
+请显示数据库中的所有表
+```
+
+### describe_table
+
+获取表的结构，包括列、类型和约束。
+
+**参数：**
+- `table`（必填）：表名
+- `database`（可选）：数据库名
+
+**示例：**
+```
+显示 users 表的结构
+```
+
+### execute_query
+
+执行 SELECT 查询（只读）。
+
+**参数：**
+- `sql`（必填）：SQL SELECT 查询语句
+- `database`（可选）：数据库名
+
+**示例：**
+```
+查找过去 7 天内创建的所有用户
+```
+
+### execute_sql
+
+执行任意 SQL 语句（需要 `EASYDB_ALLOW_WRITE=true`）。
+
+**参数：**
+- `sql`（必填）：SQL 语句
+- `database`（可选）：数据库名
+
+**注意：** DDL 语句（CREATE、DROP、ALTER）还需要 `EASYDB_ALLOW_DDL=true`。
+
+## 安全性
+
+默认情况下，服务器只允许读取操作。要启用写入权限：
+
+```bash
+export EASYDB_ALLOW_WRITE=true
+```
+
+要启用 DDL 操作（CREATE、DROP、ALTER）：
+
+```bash
+export EASYDB_ALLOW_WRITE=true
+export EASYDB_ALLOW_DDL=true
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+
+# 开发模式运行
+npm run dev
+
+# 运行生产构建
+npm start
+```
+
+## 许可证
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export interface DatabaseConfig {
+    type: 'mysql' | 'postgresql' | 'sqlite';
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    allowWrite: boolean;
+    allowDDL: boolean;
+}
+export declare function loadConfig(): DatabaseConfig;
+export declare function getDefaultPort(type: DatabaseConfig['type']): number;

package/dist/config.js

@@ -0,0 +1,58 @@
+export function loadConfig() {
+    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;
+    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 = {
+        type: normalizedType,
+        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) {
+    switch (type) {
+        case 'mysql':
+            return 3306;
+        case 'postgresql':
+            return 5432;
+        case 'sqlite':
+            return 0;
+    }
+}

package/dist/database/base.d.ts

@@ -0,0 +1,44 @@
+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/dist/database/base.js

@@ -0,0 +1 @@
+export {};

package/dist/database/factory.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseAdapter } from './base.js';
+import type { DatabaseConfig } from '../config.js';
+export declare function createAdapter(config: DatabaseConfig): DatabaseAdapter;

package/dist/database/factory.js

@@ -0,0 +1,15 @@
+import { MySQLAdapter } from './mysql.js';
+import { PostgreSQLAdapter } from './postgresql.js';
+import { SQLiteAdapter } from './sqlite.js';
+export function createAdapter(config) {
+    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/dist/database/mysql.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseAdapter, TableInfo, TableColumn, QueryResult } from './base.js';
+import type { DatabaseConfig } from '../config.js';
+export declare class MySQLAdapter implements DatabaseAdapter {
+    private pool?;
+    private config;
+    constructor(config: DatabaseConfig);
+    connect(): Promise<void>;
+    listTables(database?: string): Promise<TableInfo[]>;
+    describeTable(table: string, database?: string): Promise<TableColumn[]>;
+    executeQuery(sql: string, database?: string): Promise<QueryResult>;
+    executeSQL(sql: string, database?: string): Promise<QueryResult | {
+        affectedRows: number;
+    }>;
+    close(): Promise<void>;
+}

package/dist/database/mysql.js

@@ -0,0 +1,96 @@
+import mysql from 'mysql2/promise';
+export class MySQLAdapter {
+    pool;
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        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) {
+        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('SELECT TABLE_NAME as name, TABLE_ROWS as rowCount FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = ?', [dbName]);
+        return rows.map((row) => ({
+            name: row.name,
+            rowCount: row.rowCount,
+        }));
+    }
+    async describeTable(table, database) {
+        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(`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) => ({
+            name: row.name,
+            type: row.type,
+            nullable: row.nullable === 'YES',
+            defaultValue: row.defaultValue,
+            primaryKey: row.primaryKey === 'PRI',
+            extra: row.extra,
+        }));
+    }
+    async executeQuery(sql, database) {
+        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,
+            rowCount: Array.isArray(rows) ? rows.length : 0,
+        };
+    }
+    async executeSQL(sql, database) {
+        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,
+            rowCount: Array.isArray(result) ? result.length : 0,
+        };
+    }
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = undefined;
+        }
+    }
+}

package/dist/database/postgresql.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseAdapter, TableInfo, TableColumn, QueryResult } from './base.js';
+import type { DatabaseConfig } from '../config.js';
+export declare class PostgreSQLAdapter implements DatabaseAdapter {
+    private pool?;
+    private config;
+    constructor(config: DatabaseConfig);
+    connect(): Promise<void>;
+    listTables(database?: string): Promise<TableInfo[]>;
+    describeTable(table: string, database?: string): Promise<TableColumn[]>;
+    executeQuery(sql: string, database?: string): Promise<QueryResult>;
+    executeSQL(sql: string, database?: string): Promise<QueryResult | {
+        affectedRows: number;
+    }>;
+    close(): Promise<void>;
+}

package/dist/database/postgresql.js

@@ -0,0 +1,97 @@
+import pg from 'pg';
+const { Pool } = pg;
+export class PostgreSQLAdapter {
+    pool;
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        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) {
+        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) => ({
+            name: row.name,
+            rowCount: row.rowCount,
+        }));
+    }
+    async describeTable(table, database) {
+        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) => ({
+            name: row.name,
+            type: row.type,
+            nullable: row.nullable === 'YES',
+            defaultValue: row.defaultValue,
+            primaryKey: row.primaryKey,
+        }));
+    }
+    async executeQuery(sql, database) {
+        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, database) {
+        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() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = undefined;
+        }
+    }
+}

package/dist/database/sqlite.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseAdapter, TableInfo, TableColumn, QueryResult } from './base.js';
+import type { DatabaseConfig } from '../config.js';
+export declare class SQLiteAdapter implements DatabaseAdapter {
+    private db?;
+    private config;
+    constructor(config: DatabaseConfig);
+    connect(): Promise<void>;
+    listTables(): Promise<TableInfo[]>;
+    describeTable(table: string): Promise<TableColumn[]>;
+    executeQuery(sql: string): Promise<QueryResult>;
+    executeSQL(sql: string): Promise<QueryResult | {
+        affectedRows: number;
+    }>;
+    close(): Promise<void>;
+}

package/dist/database/sqlite.js

@@ -0,0 +1,69 @@
+import Database from 'better-sqlite3';
+export class SQLiteAdapter {
+    db;
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        if (!this.config.database) {
+            throw new Error('Database file path required for SQLite');
+        }
+        this.db = new Database(this.config.database);
+    }
+    async listTables() {
+        if (!this.db)
+            throw new Error('Not connected');
+        const rows = this.db
+            .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name`)
+            .all();
+        return rows.map((row) => ({
+            name: row.name,
+        }));
+    }
+    async describeTable(table) {
+        if (!this.db)
+            throw new Error('Not connected');
+        const rows = this.db.prepare(`PRAGMA table_info(${table})`).all();
+        return rows.map((row) => ({
+            name: row.name,
+            type: row.type,
+            nullable: row.notnull === 0,
+            defaultValue: row.dflt_value,
+            primaryKey: row.pk > 0,
+        }));
+    }
+    async executeQuery(sql) {
+        if (!this.db)
+            throw new Error('Not connected');
+        const trimmed = sql.trim().toUpperCase();
+        if (!trimmed.startsWith('SELECT')) {
+            throw new Error('Only SELECT queries allowed in executeQuery');
+        }
+        const rows = this.db.prepare(sql).all();
+        return {
+            rows,
+            rowCount: rows.length,
+        };
+    }
+    async executeSQL(sql) {
+        if (!this.db)
+            throw new Error('Not connected');
+        const trimmed = sql.trim().toUpperCase();
+        if (trimmed.startsWith('SELECT')) {
+            const rows = this.db.prepare(sql).all();
+            return {
+                rows,
+                rowCount: rows.length,
+            };
+        }
+        const result = this.db.prepare(sql).run();
+        return { affectedRows: result.changes };
+    }
+    async close() {
+        if (this.db) {
+            this.db.close();
+            this.db = undefined;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};