npm package: @porcorosso0709/database-safe
Description: Safety-oriented MCP database server: same tools as database-mcp fork, without exposing delete-connection; use DB grants for read/write policy
Author: data_wise
Latest version: 1.0.3

# Database Safe MCP Server

npm 包：**[@porcorosso0709/database-safe](https://www.npmjs.com/package/@porcorosso0709/database-safe)**。在 [data_wise / database-mcp](https://www.npmjs.com/package/@data_wise/database-mcp) 同类能力上的安全向定制：**不向 MCP 暴露「删除已保存的数据库连接」工具**，便于生产/安全生产场景；业务库上的读写删能否执行，请**自行用数据库账号权限**约束（本包不解析拦截 SQL）。

## 致谢

本项目在开发与维护过程中参考并延续了 **data_wise** 的 [database-mcp](https://www.npmjs.com/package/@data_wise/database-mcp) 思路与实现基础；仓库及协议中的著作权归属仍以原项目为准（见 `LICENSE`）。感谢 **data_wise** 开源本类工具，为 MCP 数据库能力提供的宝贵基础。

## 本包与上游的主要差异（安全向）

| 项目 | 说明 |
|------|------|
| **删除连接配置** | MCP 工具 `deleteDatabaseConnection` 在 `src/database-mcp-server.ts` 中已整体注释，**不会出现在 MCP 工具列表**。`DatabaseManager.deleteDatabaseConnection` 实现仍保留；若需恢复，去掉该段块注释即可。 |
| **业务数据 / DDL** | `query` 工具仍会将给定 SQL 提交到数据库执行。**是否允许 `DELETE`、`DROP`、`TRUNCATE` 等，由连接所用的数据库用户权限决定**（例如在 PostgreSQL 中只授予 `SELECT, INSERT, UPDATE`、不授予 `DELETE`）。 |
| **包名与命令行** | 包名为 `@porcorosso0709/database-safe`；全局可执行名为 **`database-safe`**；同时为兼容旧配置提供别名 **`database-mcp`**（与 `database-safe` 同一入口，见 `package.json` 的 `bin`）。 |

## 功能特点

- 支持多种关系型数据库（MySQL, PostgreSQL, SQLite, Microsoft SQL Server, MariaDB）
- 多数据库连接配置
- 通过 `query` 执行 SQL（请为生产环境配置合适的数据库账号权限）
- 列出表、查看表结构等

## 安装

### 全局安装

```bash
npm install -g @porcorosso0709/database-safe
```

安装后可在终端使用全局命令 **`database-safe`**。

### 本地安装

```bash
npm install @porcorosso0709/database-safe
```

可使用 `npx database-safe`、`npx @porcorosso0709/database-safe`，或克隆本仓库后用 `npm run start`（见下文开发说明）。

## 使用方法

### 数据库连接管理

数据库连接信息会自动保存到用户目录下的 `.datawise/database.db` 文件中，连接一次后就会保存，无需每次配置。可以通过提供的API工具添加、测试和管理数据库连接。

#### 关系型数据库配置参数
- `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-safe": {
      "command": "npx",
      "args": ["-y", "@porcorosso0709/database-safe"],
      "env": {}
    }
  }
}
```

说明：`npx` 增加 `-y` 可在首次拉取包时自动确认，适合在 Cursor / VS Code 等编辑器中无交互启动 MCP。

若已全局安装本包，也可将配置改为：

```json
{
  "mcpServers": {
    "database-safe": {
      "command": "database-safe",
      "args": [],
      "env": {}
    }
  }
}
```

### 可用工具

当前 MCP 实际注册的工具名为：`listAllDatabases`、`describeTable`、`listTables`、`query`、`testDatabaseConnection`、`updateDatabaseConnection`。下文请求示例中的字段仍适用；**`addDatabaseConnection` 与 `deleteDatabaseConnection` 本包未向 MCP 暴露**（见上文差异表）。

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

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

请求格式：
```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. 添加数据库连接（本包说明）

本 fork **未**在 MCP 中注册 `addDatabaseConnection`，避免在生产环境通过 MCP 写入/新增本地连接配置（保存位置通常为用户目录下的 `.datawise/database.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. 列出关系型数据库表 (listTables)

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

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

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

请求格式：
```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 (query)

请求格式：
```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`**：本 fork **未**在 MCP 中注册。若需从本地配置中移除连接，可手动维护用户目录下的 `.datawise/database.db`，或在源码中取消 `database-mcp-server.ts` 内对应块注释后自建发布。
- **`disconnectDatabase`**：当前 MCP **未**提供该工具（与上游文档若有出入，以本仓库 `src/database-mcp-server.ts` 为准）。

## 与 Supergateway / HTTP 桥接（stdio）

MCP 在 **stdio** 模式下规定：**标准输出（stdout）只能传输 JSON-RPC**，普通日志若打到 stdout 会破坏握手，表现为网关侧 **`write EPIPE`** 或连接立即断开。本仓库已将运行期 `console.log` 改为 **`console.error`**（写入 stderr），避免污染 MCP 流。

使用 [supergateway](https://www.npmjs.com/package/supergateway) 等工具时，子进程可使用任一并存命令（全局安装本包后）：

- `database-safe` 或 **`database-mcp`**（二者等价，后者便于沿用旧配置），或
- `npx -y @porcorosso0709/database-safe`

请安装 **≥ 1.0.2**，并确保容器/PATH 中能解析到上述命令；若仍写 `database-mcp` 却未安装本包，子进程不存在会导致 **EPIPE**。

## 错误处理

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

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

## 开发说明

### 环境要求

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

### 目录结构

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

### 开发构建

```bash
# 安装依赖
npm install

# 启动 MCP 服务器（TypeScript 源码，需本地依赖）
npm run start-mcp-server

# 等价于发布包入口：通过 bin/cli.js 调 tsx 运行
npm run start
# 或（在已 npm link / 本地安装本包时）
npx database-safe
```

## 发布到 npm（维护者）

1. 登录：`npm whoami`（未登录则 `npm login`）。
2. 在包根目录确认 `package.json` 中 `"name"` 为 `@porcorosso0709/database-safe`，`version` 未与已发布版本重复。
3. 发布公开作用域包：

   ```bash
   npm publish --access public
   ```

4. 若账号开启 **2FA**，需附加一次性密码：

   ```bash
   npm publish --access public --otp=你的6位验证码
   ```

5. 发布后 README 会显示在 [npm 包页](https://www.npmjs.com/package/@porcorosso0709/database-safe) 的 **Readme** 标签下；未弃用旧包时，旧包 `@porcorosso0709/database-mcp` 与 **`database-safe` 是相互独立的两个包名**，使用者需按环境改依赖与 MCP 配置。