@cmd233/mcp-database-server 1.1.1 → 1.1.3

package/README.md.en.bak

@@ -0,0 +1,328 @@
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/executeautomation-mcp-database-server-badge.png)](https://mseep.ai/app/executeautomation-mcp-database-server)
+
+# MCP Database Server
+
+This MCP (Model Context Protocol) server provides database access capabilities to Claude, supporting SQLite, SQL Server, PostgreSQL, and MySQL databases.
+
+## Installation
+
+1. Clone the repository:
+```
+git clone https://github.com/executeautomation/mcp-database-server.git
+cd mcp-database-server
+```
+
+2. Install dependencies:
+```
+npm install
+```
+
+3. Build the project:
+```
+npm run build
+```
+
+## Usage Options
+
+There are two ways to use this MCP server with Claude:
+
+1. **Direct usage**: Install the package globally and use it directly
+2. **Local development**: Run from your local development environment
+
+### Direct Usage with NPM Package
+
+The easiest way to use this MCP server is by installing it globally:
+
+```bash
+npm install -g @executeautomation/database-server
+```
+
+This allows you to use the server directly without building it locally.
+
+### Local Development Setup
+
+If you want to modify the code or run from your local environment:
+
+1. Clone and build the repository as shown in the Installation section
+2. Run the server using the commands in the Usage section below
+
+## Usage
+
+### SQLite Database
+
+To use with an SQLite database:
+
+```
+node dist/src/index.js /path/to/your/database.db
+```
+
+### SQL Server Database
+
+To use with a SQL Server database:
+
+```
+node dist/src/index.js --sqlserver --server <server-name> --database <database-name> [--user <username> --password <password>]
+```
+
+Required parameters:
+- `--server`: SQL Server host name or IP address
+- `--database`: Name of the database
+
+Optional parameters:
+- `--user`: Username for SQL Server authentication (if not provided, Windows Authentication will be used)
+- `--password`: Password for SQL Server authentication
+- `--port`: Port number (default: 1433)
+
+### PostgreSQL Database
+
+To use with a PostgreSQL database:
+
+```
+node dist/src/index.js --postgresql --host <host-name> --database <database-name> [--user <username> --password <password>]
+```
+
+Required parameters:
+- `--host`: PostgreSQL host name or IP address
+- `--database`: Name of the database
+
+Optional parameters:
+- `--user`: Username for PostgreSQL authentication
+- `--password`: Password for PostgreSQL authentication
+- `--port`: Port number (default: 5432)
+- `--ssl`: Enable SSL connection (true/false)
+- `--connection-timeout`: Connection timeout in milliseconds (default: 30000)
+
+### MySQL Database
+
+#### Standard Authentication
+
+To use with a MySQL database:
+
+```
+node dist/src/index.js --mysql --host <host-name> --database <database-name> --port <port> [--user <username> --password <password>]
+```
+
+Required parameters:
+- `--host`: MySQL host name or IP address
+- `--database`: Name of the database
+- `--port`: Port number (default: 3306)
+
+Optional parameters:
+- `--user`: Username for MySQL authentication
+- `--password`: Password for MySQL authentication
+- `--ssl`: Enable SSL connection (true/false or object)
+- `--connection-timeout`: Connection timeout in milliseconds (default: 30000)
+
+#### AWS IAM Authentication
+
+For Amazon RDS MySQL instances with IAM database authentication:
+
+**Prerequisites:**
+- AWS credentials must be configured (the RDS Signer uses the default credential provider chain)
+- Configure using one of these methods:
+  - `aws configure` (uses default profile)
+  - `AWS_PROFILE=myprofile` environment variable
+  - `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables
+  - IAM roles (if running on EC2)
+
+```
+node dist/src/index.js --mysql --aws-iam-auth --host <rds-endpoint> --database <database-name> --user <aws-username> --aws-region <region>
+```
+
+Required parameters:
+- `--host`: RDS endpoint hostname
+- `--database`: Name of the database
+- `--aws-iam-auth`: Enable AWS IAM authentication
+- `--user`: AWS IAM username (also the database user)
+- `--aws-region`: AWS region where RDS instance is located
+
+Note: SSL is automatically enabled for AWS IAM authentication
+
+## Configuring Claude Desktop
+
+### Direct Usage Configuration
+
+If you installed the package globally, configure Claude Desktop with:
+
+```json
+{
+  "mcpServers": {
+    "sqlite": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@executeautomation/database-server",
+        "/path/to/your/database.db"
+      ]
+    },
+    "sqlserver": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@executeautomation/database-server",
+        "--sqlserver",
+        "--server", "your-server-name",
+        "--database", "your-database-name",
+        "--user", "your-username",
+        "--password", "your-password"
+      ]
+    },
+    "postgresql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@executeautomation/database-server",
+        "--postgresql",
+        "--host", "your-host-name",
+        "--database", "your-database-name",
+        "--user", "your-username",
+        "--password", "your-password"
+      ]
+    },
+    "mysql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@executeautomation/database-server",
+        "--mysql",
+        "--host", "your-host-name",
+        "--database", "your-database-name",
+        "--port", "3306",
+        "--user", "your-username",
+        "--password", "your-password"
+      ]
+    },
+    "mysql-aws": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@executeautomation/database-server",
+        "--mysql",
+        "--aws-iam-auth",
+        "--host", "your-rds-endpoint.region.rds.amazonaws.com",
+        "--database", "your-database-name",
+        "--user", "your-aws-username",
+        "--aws-region", "us-east-1"
+      ]
+    }
+  }
+}
+```
+
+### Local Development Configuration
+
+For local development, configure Claude Desktop to use your locally built version:
+
+```json
+{
+  "mcpServers": {
+    "sqlite": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/mcp-database-server/dist/src/index.js", 
+        "/path/to/your/database.db"
+      ]
+    },
+    "sqlserver": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/mcp-database-server/dist/src/index.js",
+        "--sqlserver",
+        "--server", "your-server-name",
+        "--database", "your-database-name",
+        "--user", "your-username",
+        "--password", "your-password"
+      ]
+    },
+    "postgresql": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/mcp-database-server/dist/src/index.js",
+        "--postgresql",
+        "--host", "your-host-name",
+        "--database", "your-database-name",
+        "--user", "your-username",
+        "--password", "your-password"
+      ]
+    },
+    "mysql": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/mcp-database-server/dist/src/index.js",
+        "--mysql",
+        "--host", "your-host-name",
+        "--database", "your-database-name",
+        "--port", "3306",
+        "--user", "your-username",
+        "--password", "your-password"
+      ]
+    },
+    "mysql-aws": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/mcp-database-server/dist/src/index.js",
+        "--mysql",
+        "--aws-iam-auth",
+        "--host", "your-rds-endpoint.region.rds.amazonaws.com",
+        "--database", "your-database-name",
+        "--user", "your-aws-username",
+        "--aws-region", "us-east-1"
+      ]
+    }
+  }
+}
+```
+
+The Claude Desktop configuration file is typically located at:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+## Available Database Tools
+
+The MCP Database Server provides the following tools that Claude can use:
+
+| Tool | Description | Required Parameters |
+|------|-------------|---------------------|
+| `read_query` | Execute SELECT queries to read data | `query`: SQL SELECT statement |
+| `write_query` | Execute INSERT, UPDATE, or DELETE queries | `query`: SQL modification statement |
+| `create_table` | Create new tables in the database | `query`: CREATE TABLE statement |
+| `alter_table` | Modify existing table schema | `query`: ALTER TABLE statement |
+| `drop_table` | Remove a table from the database | `table_name`: Name of table<br>`confirm`: Safety flag (must be true) |
+| `list_tables` | Get a list of all tables | None |
+| `describe_table` | View schema information for a table | `table_name`: Name of table |
+| `export_query` | Export query results as CSV/JSON | `query`: SQL SELECT statement<br>`format`: "csv" or "json" |
+| `append_insight` | Add a business insight to memo | `insight`: Text of insight |
+| `list_insights` | List all business insights | None |
+
+For practical examples of how to use these tools with Claude, see [Usage Examples](docs/usage-examples.md).
+
+## Additional Documentation
+
+- [SQL Server Setup Guide](docs/sql-server-setup.md): Details on connecting to SQL Server databases
+- [PostgreSQL Setup Guide](docs/postgresql-setup.md): Details on connecting to PostgreSQL databases
+- [Usage Examples](docs/usage-examples.md): Example queries and commands to use with Claude
+
+## Development
+
+To run the server in development mode:
+
+```
+npm run dev
+```
+
+To watch for changes during development:
+
+```
+npm run watch
+```
+
+## Requirements
+
+- Node.js 18+
+- For SQL Server connectivity: SQL Server 2012 or later
+- For PostgreSQL connectivity: PostgreSQL 9.5 or later
+
+## License
+
+MIT

package/dist/src/db/adapter.js

@@ -1,15 +1,15 @@
-// Import adapters using dynamic imports
+// 使用动态导入适配器
 import { SqliteAdapter } from './sqlite-adapter.js';
 import { SqlServerAdapter } from './sqlserver-adapter.js';
 import { PostgresqlAdapter } from './postgresql-adapter.js';
 import { MysqlAdapter } from './mysql-adapter.js';
 /**
- * Factory function to create the appropriate database adapter
+ * 工厂函数,创建相应的数据库适配器
  */
 export function createDbAdapter(type, connectionInfo) {
     switch (type.toLowerCase()) {
         case 'sqlite':
-            // For SQLite, if connectionInfo is a string, use it directly as path
+            // 对于 SQLite,如果 connectionInfo 是字符串,则直接将其用作路径
             if (typeof connectionInfo === 'string') {
                 return new SqliteAdapter(connectionInfo);
             }

package/dist/src/db/index.js

@@ -1,20 +1,20 @@
 import { createDbAdapter } from './adapter.js';
-// Store the active database adapter
+// 存储活动的数据库适配器
 let dbAdapter = null;
 /**
- * Initialize the database connection
- * @param connectionInfo Connection information object or SQLite path string
- * @param dbType Database type ('sqlite' or 'sqlserver')
+ * 初始化数据库连接
+ * @param connectionInfo 连接信息对象或 SQLite 路径字符串
+ * @param dbType 数据库类型 ('sqlite' 或 'sqlserver')
  */
 export async function initDatabase(connectionInfo, dbType = 'sqlite') {
     try {
-        // If connectionInfo is a string, assume it's a SQLite path
+        // 如果 connectionInfo 是字符串,则假定它是 SQLite 路径
         if (typeof connectionInfo === 'string') {
             connectionInfo = { path: connectionInfo };
         }
-        // Create appropriate adapter based on database type
+        // 根据数据库类型创建相应的适配器
         dbAdapter = createDbAdapter(dbType, connectionInfo);
-        // Initialize the connection
+        // 初始化连接
         await dbAdapter.init();
     }
     catch (error) {
@@ -22,10 +22,10 @@ export async function initDatabase(connectionInfo, dbType = 'sqlite') {
     }
 }
 /**
- * Execute a SQL query and get all results
- * @param query SQL query to execute
- * @param params Query parameters
- * @returns Promise with query results
+ * 执行 SQL 查询并获取所有结果
+ * @param query 要执行的 SQL 查询
+ * @param params 查询参数
+ * @returns 包含查询结果的 Promise
  */
 export function dbAll(query, params = []) {
     if (!dbAdapter) {
@@ -34,10 +34,10 @@ export function dbAll(query, params = []) {
     return dbAdapter.all(query, params);
 }
 /**
- * Execute a SQL query that modifies data
- * @param query SQL query to execute
- * @param params Query parameters
- * @returns Promise with result info
+ * 执行修改数据的 SQL 查询
+ * @param query 要执行的 SQL 查询
+ * @param params 查询参数
+ * @returns 包含结果信息的 Promise
  */
 export function dbRun(query, params = []) {
     if (!dbAdapter) {
@@ -46,9 +46,9 @@ export function dbRun(query, params = []) {
     return dbAdapter.run(query, params);
 }
 /**
- * Execute multiple SQL statements
- * @param query SQL statements to execute
- * @returns Promise that resolves when execution completes
+ * 执行多条 SQL 语句
+ * @param query 要执行的 SQL 语句
+ * @returns 执行完成后解析的 Promise
  */
 export function dbExec(query) {
     if (!dbAdapter) {
@@ -57,7 +57,7 @@ export function dbExec(query) {
     return dbAdapter.exec(query);
 }
 /**
- * Close the database connection
+ * 关闭数据库连接
  */
 export function closeDatabase() {
     if (!dbAdapter) {
@@ -66,7 +66,7 @@ export function closeDatabase() {
     return dbAdapter.close();
 }
 /**
- * Get database metadata
+ * 获取数据库元数据
  */
 export function getDatabaseMetadata() {
     if (!dbAdapter) {
@@ -75,7 +75,7 @@ export function getDatabaseMetadata() {
     return dbAdapter.getMetadata();
 }
 /**
- * Get database-specific query for listing tables
+ * 获取列出表的数据库特定查询
  */
 export function getListTablesQuery() {
     if (!dbAdapter) {
@@ -84,8 +84,8 @@ export function getListTablesQuery() {
     return dbAdapter.getListTablesQuery();
 }
 /**
- * Get database-specific query for describing a table
- * @param tableName Table name
+ * 获取描述表的数据库特定查询
+ * @param tableName 表名
  */
 export function getDescribeTableQuery(tableName) {
     if (!dbAdapter) {

package/dist/src/db/mysql-adapter.js

@@ -1,7 +1,7 @@
 import mysql from "mysql2/promise";
 import { Signer } from "@aws-sdk/rds-signer";
 /**
- * MySQL database adapter implementation
+ * MySQL 数据库适配器实现
  */
 export class MysqlAdapter {
     constructor(connectionInfo) {
@@ -23,17 +23,17 @@ export class MysqlAdapter {
             this.config.ssl = connectionInfo.ssl;
         }
         else if (connectionInfo.ssl === true) {
-            // For AWS IAM authentication, configure SSL appropriately for RDS
+            // 对于 AWS IAM 认证,为 RDS 适当配置 SSL
             if (this.awsIamAuth) {
                 this.config.ssl = {
-                    rejectUnauthorized: false // AWS RDS handles certificate validation
+                    rejectUnauthorized: false // AWS RDS 处理证书验证
                 };
             }
             else {
                 this.config.ssl = {};
             }
         }
-        // Validate port
+        // 验证端口号
         if (connectionInfo.port && typeof connectionInfo.port !== 'number') {
             const parsedPort = parseInt(connectionInfo.port, 10);
             if (isNaN(parsedPort)) {
@@ -41,11 +41,11 @@ export class MysqlAdapter {
             }
             this.config.port = parsedPort;
         }
-        // Log the port for debugging
+        // 记录端口用于调试
         console.error(`[DEBUG] MySQL connection will use port: ${this.config.port}`);
     }
     /**
-     * Generate AWS RDS authentication token
+     * 生成 AWS RDS 认证令牌
      */
     async generateAwsAuthToken() {
         if (!this.awsRegion) {
@@ -72,17 +72,17 @@ export class MysqlAdapter {
         }
     }
     /**
-     * Initialize MySQL connection
+     * 初始化 MySQL 连接
      */
     async init() {
         try {
             console.info(`[INFO] Connecting to MySQL: ${this.host}, Database: ${this.database}`);
-            // Handle AWS IAM authentication
+            // 处理 AWS IAM 认证
             if (this.awsIamAuth) {
                 console.info(`[INFO] Using AWS IAM authentication for user: ${this.config.user}`);
                 try {
                     const authToken = await this.generateAwsAuthToken();
-                    // Create a new config with the generated token as password
+                    // 使用生成的令牌作为密码创建新配置
                     const awsConfig = {
                         ...this.config,
                         password: authToken
@@ -110,7 +110,7 @@ export class MysqlAdapter {
         }
     }
     /**
-     * Execute a SQL query and get all results
+     * 执行 SQL 查询并获取所有结果
      */
     async all(query, params = []) {
         if (!this.connection) {
@@ -125,7 +125,7 @@ export class MysqlAdapter {
         }
     }
     /**
-     * Execute a SQL query that modifies data
+     * 执行修改数据的 SQL 查询
      */
     async run(query, params = []) {
         if (!this.connection) {
@@ -142,7 +142,7 @@ export class MysqlAdapter {
         }
     }
     /**
-     * Execute multiple SQL statements
+     * 执行多条 SQL 语句
      */
     async exec(query) {
         if (!this.connection) {
@@ -156,7 +156,7 @@ export class MysqlAdapter {
         }
     }
     /**
-     * Close the database connection
+     * 关闭数据库连接
      */
     async close() {
         if (this.connection) {
@@ -165,7 +165,7 @@ export class MysqlAdapter {
         }
     }
     /**
-     * Get database metadata
+     * 获取数据库元数据
      */
     getMetadata() {
         return {
@@ -176,16 +176,16 @@ export class MysqlAdapter {
         };
     }
     /**
-     * Get database-specific query for listing tables
+     * 获取列出表的数据库特定查询
      */
     getListTablesQuery() {
         return `SELECT table_name AS name FROM information_schema.tables WHERE table_schema = '${this.database}'`;
     }
     /**
-     * Get database-specific query for describing a table
+     * 获取描述表的数据库特定查询
      */
     getDescribeTableQuery(tableName) {
-        // MySQL DESCRIBE returns columns with different names, so we use a query that matches the expected format
+        // MySQL DESCRIBE 返回具有不同名称的列,因此我们使用与预期格式匹配的查询
         return `
       SELECT
         COLUMN_NAME as name,