npm package: @porcorosso0709/database-mcp
Description: MCP server for database operations using Sequelize
Author: data_wise
Latest version: 1.0.10

# Database MCP Server

一个基于 Model Context Protocol (MCP) 的数据库查询服务，支持多种关系型数据库(通过Sequelize)。

## 功能特点

- 支持多种关系型数据库（MySQL, PostgreSQL, SQLite, Microsoft SQL Server, MariaDB）
- 多数据库连接配置
- 执行SQL查询
- 数据库表结构查询

## 安装

### 全局安装

```bash
npm install -g @data_wise/database-mcp
```

### 本地安装

```bash
npm install @data_wise/database-mcp
```

## 使用方法

### 数据库连接管理

连接配置默认保存在用户目录下的 `.datawise/database.db`（即 `~/.datawise/database.db`）。在 **Docker / 远程容器** 中 `HOME` 往往与宿主机不同，配置会写到容器内对应 home，容易「找不到先前保存的连接」。

**解决办法：** 设置环境变量 `DATAWISE_HOME` 指向容器内固定目录（并可选地挂载数据卷），例如 `/data/datawise`，则 SQLite 使用 `$DATAWISE_HOME/database.db`。

```json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@data_wise/database-mcp"],
      "env": {
        "DATAWISE_HOME": "/data/datawise"
      }
    }
  }
}
```

连接一次后会持久化到上述路径，可通过 MCP 工具添加、测试和管理数据库连接。

#### 关系型数据库配置参数
- `name`: 数据库连接的唯一标识名（必填）
- `dialect`: 数据库类型（mysql, postgres, sqlite, mssql, mariadb）
- `host`: 数据库主机地址，默认为 localhost
- `port`: 数据库端口
- `username`: 数据库用户名
- `password`: 数据库密码
- `database`: 数据库名称
- `storage`: SQLite数据库文件路径（仅用于SQLite）
- `pool`: 连接池配置（可选）
  - `max`: 最大连接数，默认10
  - `min`: 最小连接数，默认0
  - `idle`: 空闲超时（毫秒），默认10000
  - `acquire`: 获取超时（毫秒），默认30000

### MCP示例配置

```json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@data_wise/database-mcp"],
      "env": {}
    }
  }
}
```

本地直连可使用空 `env`；若 MCP 跑在容器内，请在 `env` 中设置 `DATAWISE_HOME`（见上文）。

### 可用工具

#### 关系型数据库工具

##### 1. 列出可用关系型数据库 (listRelationalDatabases)

请求格式：
```json
{}
```

响应格式：
```json
{
  "success": true,
  "data": [
    {
      "name": "main",
      "dialect": "mysql",
      "host": "localhost",
      "database": "main_db",
      "pool": {
        "max": 10,
        "min": 0,
        "idle": 10000,
        "acquire": 30000
      }
    },
    {
      "name": "analytics",
      "dialect": "postgres",
      "host": "db.example.com",
      "database": "analytics_db"
    }
  ],
  "metadata": {
    "count": 2
  }
}
```

##### 2. 添加数据库连接 (addDatabaseConnection)

请求格式：
```json
{
  "name": "new_db",
  "dialect": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "testdb"
}
```

响应格式：
```json
{
  "success": true,
  "data": {
    "name": "new_db",
    "dialect": "mysql",
    "connected": true
  },
  "message": "数据库连接 'new_db' 已成功添加并连接"
}
```

##### 3. 测试数据库连接 (testDatabaseConnection)

请求格式（测试已存在的连接）：
```json
{
  "mode": "existing",
  "name": "main"
}
```

请求格式（测试新连接配置）：
```json
{
  "mode": "new",
  "name": "test_conn",
  "dialect": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "testdb"
}
```

响应格式：
```json
{
  "success": true,
  "data": {
    "name": "test_conn",
    "mode": "new",
    "connectionTestResult": true
  },
  "message": "数据库连接测试成功"
}
```

##### 4. 更新数据库连接 (updateDatabaseConnection)

请求格式：
```json
{
  "name": "main",
  "host": "new-host.example.com",
  "port": 3307,
  "password": "new-password"
}
```

响应格式：
```json
{
  "success": true,
  "data": {
    "name": "main",
    "updated": true,
    "host": "new-host.example.com",
    "port": 3307,
    "password": "new-password"
  },
  "message": "数据库连接 'main' 已成功更新并重新连接"
}
```

##### 5. 列出关系型数据库表 (listRelationalTables)

请求格式：
```json
{
  "dbName": "main"
}
```

响应格式：
```json
{
  "success": true,
  "data": [
    "users",
    "products",
    "orders",
    "categories"
  ],
  "metadata": {
    "dbName": "main",
    "count": 4
  }
}
```

##### 6. 查询关系型数据库表结构 (describeRelationalTable)

请求格式：
```json
{
  "dbName": "main",
  "tableName": "users"
}
```

响应格式：
```json
{
  "success": true,
  "data": {
    "id": {
      "type": "INTEGER",
      "allowNull": false,
      "primaryKey": true,
      "autoIncrement": true
    },
    "username": {
      "type": "VARCHAR(255)",
      "allowNull": false,
      "defaultValue": null
    },
    "email": {
      "type": "VARCHAR(255)",
      "allowNull": false,
      "unique": true
    },
    "created_at": {
      "type": "DATETIME",
      "allowNull": false
    }
  },
  "metadata": {
    "dbName": "main",
    "tableName": "users"
  }
}
```

##### 7. 执行SQL查询 (executeQuery)

请求格式：
```json
{
  "dbName": "main",
  "sql": "SELECT * FROM users WHERE id = ?",
  "params": [1]
}
```

响应格式：
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "created_at": "2023-01-01 00:00:00"
    }
  ],
  "metadata": {
    "dbName": "main",
    "rowCount": 1,
    "fields": ["id", "username", "email", "created_at"]
  }
}
```

##### 8. 删除数据库连接 (deleteDatabaseConnection)

请求格式：
```json
{
  "name": "old_db"
}
```

响应格式：
```json
{
  "success": true,
  "data": {
    "name": "old_db",
    "deleted": true
  },
  "message": "数据库连接 'old_db' 已成功删除"
}
```

##### 9. 断开数据库连接 (disconnectDatabase)

请求格式：
```json
{
  "name": "temp_db"
}
```

响应格式：
```json
{
  "success": true,
  "data": {
    "name": "temp_db",
    "disconnected": true
  },
  "message": "数据库连接 'temp_db' 已成功断开"
}
```

## 错误处理

所有工具都会返回统一格式的错误响应：

```json
{
  "success": false,
  "error": "详细的错误信息",
  "details": "友好的错误说明，包含可能的解决方案"
}
```

## 开发说明

### 环境要求

- Node.js >= 14.0.0
- NPM >= 7.0.0

### 目录结构

```
database-mcp/
├── bin/
│   └── cli.js              # CLI入口
├── src/
│   ├── index.ts            # 主入口
│   ├── database-manager.ts # 关系型数据库管理
│   └── database-mcp-server.ts # MCP服务器实现
└── package.json
```

### 开发构建

```bash
# 安装依赖
npm install

# 启动MCP服务器
npm run start-mcp-server
```