# Database MCP Server

一个基于 Model Context Protocol (MCP) 的数据库连接服务器，支持多种数据库的统一访问和管理。

## 功能特性

### 支持的数据库

- **MySQL** - 完整支持
- **PostgreSQL** - 完整支持
- **Vastbase G100** - 完整支持（基于 PostgreSQL 适配）
- **ClickHouse** - 完整支持（支持无密码连接）
- **Oracle** - 基础支持（需要 OCI 库）
- **SQL Server** - 基础支持（使用 tedious 驱动）

### 核心功能

- **连接管理** - 连接池、心跳检测、自动回收
- **CRUD 操作** - select、insert、update、delete、count
- **元数据查询** - list_tables、describe_table、get_table_indexes、list_databases
- **SQL 执行** - 参数化查询、执行计划分析
- **事务管理** - begin_transaction、commit、rollback（支持隔离级别）
- **高级查询** - GROUP BY、HAVING、ORDER BY

### 安全特性

- **SQL 注入防护** - SQL 解析校验、危险操作拦截
- **数据脱敏** - 敏感字段自动脱敏（手机号、身份证、邮箱等）
- **限流保护** - 令牌桶限流、并发查询限制
- **熔断机制** - 自动熔断、故障恢复
- **查询超时** - 超时控制、慢查询检测
- **大表保护** - WHERE 条件强制、执行计划分析

### 日志审计

- **审计日志** - 完整记录所有工具调用
- **查询日志** - 记录 SQL 执行详情
- **错误日志** - 详细的错误追踪
- **日志轮转** - 自动轮转、保留期管理

---

## 快速开始

### 安装

```bash
# 克隆项目
git clone <repository-url>
cd database-mcp-server

# 安装依赖
npm install

# 构建
npm run build
```

### 配置

复制环境变量配置文件：

```bash
cp .env.example .env
```

编辑 `.env` 文件配置必要参数：

```bash
# 连接管理配置
CONNECTION_MAX_CONNECTIONS_PER_CLIENT=3
CONNECTION_IDLE_TIMEOUT=600000
CONNECTION_MAX_LIFETIME=1800000

# 查询配置
QUERY_TIMEOUT=30000

# 日志配置
LOG_LEVEL=info
LOG_DIR=./logs
```

### 启动

```bash
# 开发模式
npm run dev

# 生产模式
npm start

# 或直接运行构建后的文件
node dist/index.js
```

---

## MCP 工具列表

### 连接管理

| 工具 | 描述 |
|------|------|
| `connect` | 连接到数据库 |
| `disconnect` | 断开当前连接 |
| `get_connection` | 获取连接状态 |

### 元数据查询

| 工具 | 描述 |
|------|------|
| `list_databases` | 列出所有数据库 |
| `list_tables` | 列出所有表 |
| `describe_table` | 查看表结构 |
| `get_table_indexes` | 获取索引信息 |

### CRUD 操作

| 工具 | 描述 |
|------|------|
| `select` | 查询数据（支持 GROUP BY/HAVING） |
| `insert` | 插入数据 |
| `update` | 更新数据 |
| `delete` | 删除数据 |
| `count` | 统计行数 |

### SQL 执行

| 工具 | 描述 |
|------|------|
| `execute_sql` | 执行原始 SQL |
| `get_query_plan` | 获取执行计划 |

### 事务管理

| 工具 | 描述 |
|------|------|
| `begin_transaction` | 开始事务 |
| `commit` | 提交事务 |
| `rollback` | 回滚事务 |

### 高级功能

| 工具 | 描述 |
|------|------|
| `get_server_info` | 获取服务器信息 |
| `truncate_table` | 清空表（危险操作） |
| `get_security_status` | 获取安全中间件状态 |

---

## 使用示例

### 1. 连接数据库

```json
{
  "tool": "connect",
  "arguments": {
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "database": "test_db",
    "username": "root",
    "password": "password"
  }
}
```

### 2. 查询数据

```json
{
  "tool": "select",
  "arguments": {
    "table": "users",
    "columns": ["id", "name", "email"],
    "where": {
      "status": "active",
      "age": { "gte": 18 }
    },
    "orderBy": [{"column": "created_at", "direction": "desc"}],
    "limit": 10
  }
}
```

### 3. 分组聚合

```json
{
  "tool": "select",
  "arguments": {
    "table": "orders",
    "columns": ["user_id", "count(*) as total", "sum(amount) as revenue"],
    "groupBy": ["user_id"],
    "having": { "count(*)": { "gt": 5 } }
  }
}
```

### 4. 执行事务

```json
{
  "tool": "begin_transaction",
  "arguments": {
    "isolationLevel": "READ_COMMITTED"
  }
}

{
  "tool": "insert",
  "arguments": {
    "table": "accounts",
    "values": {"user_id": 1, "balance": 100}
  }
}

{
  "tool": "update",
  "arguments": {
    "table": "accounts",
    "values": {"balance": 50},
    "where": {"user_id": 2}
  }
}

{
  "tool": "commit"
}
```

### 5. 查看安全状态

```json
{
  "tool": "get_security_status",
  "arguments": {}
}
```

---

## 配置说明

### 完整配置文件 (config/default.yaml)

```yaml
connectionManager:
  maxConnectionsPerClient: 3
  idleTimeout: 600000      # 10 分钟
  maxLifetime: 1800000     # 30 分钟
  heartbeatInterval: 120000
  pool:
    min: 0
    max: 5
    acquireTimeout: 10000
    idleTimeout: 60000

query:
  maxRows: 1000
  maxResultSize: 10485760  # 10MB
  timeout: 30000
  requireWhereForLargeTables: true
  largeTableThreshold: 1000000
  maxJoins: 5
  maxSubqueryDepth: 3

rateLimit:
  requestsPerSecond: 10
  concurrentQueries: 5
  burstSize: 20

circuitBreaker:
  enabled: true
  errorThreshold: 50
  windowSize: 100
  timeout: 300000

security:
  sensitiveFields:
    hide: [password, passwd, secret, token, api_key, private_key]
    mask: [phone, id_card, credit_card, email]
  blockedSqlPatterns:
    - DROP\s+(TABLE|DATABASE)
    - TRUNCATE\s+
    - GRANT\s+
    - REVOKE\s+

audit:
  enabled: true
  filePath: ./logs/audit.log
  rotate: daily
  retention: 180
  logQueryParams: true
  logSql: true
  logResult: false
  logSlowQueries: true
  slowQueryThreshold: 1000
```

### 数据脱敏配置

敏感字段分为两类：

1. **hide** - 完全隐藏，不出现在结果中
   - password, passwd, secret, token, api_key, private_key

2. **mask** - 部分脱敏显示
   - phone: 138****1234
   - id_card: 110101********1234
   - credit_card: 6222 **** **** 1234
   - email: j***@example.com

### 限流熔断配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| requestsPerSecond | 10 | 每秒请求数限制 |
| concurrentQueries | 5 | 并发查询数限制 |
| burstSize | 20 | 突发流量大小 |
| errorThreshold | 50 | 错误阈值（触发熔断） |
| timeout | 300000 | 熔断超时（毫秒） |

---

## 开发

### 项目结构

```
database-mcp-server/
├── src/
│   ├── index.ts              # 入口文件
│   ├── server.ts             # MCP 服务器
│   ├── connection/           # 连接管理
│   │   ├── manager.ts
│   │   ├── pool.ts
│   │   └── string-builder.ts
│   ├── tools/                # MCP 工具实现
│   │   ├── connection.ts
│   │   ├── metadata.ts
│   │   ├── crud.ts
│   │   ├── sql.ts
│   │   └── transaction.ts
│   ├── middleware/           # 安全中间件
│   │   ├── data-masking.ts   # 数据脱敏
│   │   ├── rate-limiter.ts   # 限流熔断
│   │   └── security.ts       # 安全集成
│   ├── logger/               # 日志系统
│   │   ├── audit.ts
│   │   ├── query.ts
│   │   └── error.ts
│   └── types/                # 类型定义
│       ├── config.ts
│       └── database.ts
├── tests/
└── dist/
```

### 运行测试

```bash
# 运行所有测试
npm test

# 监听模式
npm run test:watch

# 生成覆盖率报告
npm run test:coverage
```

### 构建

```bash
# 编译 TypeScript
npm run build

# 清理并重新编译
npm run clean && npm run build
```

### 代码检查

```bash
# ESLint
npm run lint

# 格式化代码
npm run format
```

---

## MCP 客户端配置

本服务器支持标准的 MCP 协议，可以在各种 AI 工具和客户端中使用。以下是详细的配置说明。

### 传输方式

Database MCP Server 使用 **Stdio** 传输方式（标准输入输出，用于本地进程通信）。

### Claude Code 配置

Claude Code 是 Anthropic 官方的 CLI 工具，支持 MCP 协议。

#### 配置位置

- **全局配置**: `~/.claude/settings.json`
- **项目配置**: `.claude/settings.local.json`

#### 配置示例

在项目目录中创建或编辑 `.claude/settings.local.json`：

```json
{
  "mcpServers": {
    "database-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/database-mcp-server/dist/index.js"]
    }
  }
}
```

#### 使用步骤

1. **构建项目**
   ```bash
   cd /path/to/database-mcp-server
   npm run build
   ```

2. **配置 Claude Code**
   ```bash
   # 在项目目录中
   mkdir -p .claude
   # 创建配置文件
   ```

3. **启动 Claude Code**
   ```bash
   claude
   ```

4. **验证连接**
   ```
   在对话中输入：/mcp
   查看已连接的 MCP 服务器
   ```

#### 使用示例

```
用户：连接到 MySQL 数据库
Claude: 使用 database-mcp 的 connect 工具...

用户：查询 users 表中的所有数据
Claude: 使用 select 工具查询...
```

---

### Cline (VS Code 扩展) 配置

Cline 是一个 VS Code 扩展，支持 MCP 协议。

#### 配置位置

在 VS Code 中打开设置，搜索 "Cline"，找到 MCP 配置项。

或者编辑 VS Code 设置文件：
- **Windows**: `%APPDATA%\Code\User\settings.json`
- **macOS**: `~/Library/Application Support/Code/User/settings.json`
- **Linux**: `~/.config/Code/User/settings.json`

#### 配置示例

```json
{
  "cline.mcpServers": [
    {
      "name": "database-mcp",
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/database-mcp-server/dist/index.js"]
    }
  ]
}
```

#### 使用步骤

1. **安装 Cline 扩展**
   - 打开 VS Code
   - 搜索 "Cline" 并安装

2. **配置 MCP 服务器**
   - 打开 VS Code 设置
   - 搜索 "MCP"
   - 添加服务器配置

3. **验证连接**
   - 打开 Cline 面板
   - 查看 MCP 服务器状态

---

### OpenCode 配置

OpenCode 是一个开源的 MCP 客户端。

#### 配置位置

- **macOS/Linux**: `~/.opencode/config.json`
- **Windows**: `%USERPROFILE%\.opencode\config.json`

#### 配置示例

```json
{
  "mcp": {
    "servers": {
      "database": {
        "command": "node",
        "args": ["/path/to/database-mcp-server/dist/index.js"]
      }
    }
  }
}
```

#### 使用步骤

1. **安装 OpenCode**
   ```bash
   npm install -g @opencode/core
   ```

2. **配置 MCP 服务器**
   ```bash
   mkdir -p ~/.opencode
   # 创建 config.json 文件
   ```

3. **启动 OpenCode**
   ```bash
   opencode
   ```

---

### Cursor 配置

Cursor 是支持 MCP 协议的 AI 代码编辑器。

#### 配置位置

在 Cursor 中打开设置，搜索 "MCP"。

#### 配置示例

在项目根目录创建 `.cursor/mcp.json`：

```json
{
  "servers": [
    {
      "name": "database-mcp",
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/../database-mcp-server/dist/index.js"]
    }
  ]
}
```

#### 使用步骤

1. **打开 Cursor 设置**
   - File → Preferences → Settings

2. **搜索 MCP**
   - 找到 "MCP Servers" 配置项

3. **添加服务器**
   - 点击 "Add Server"
   - 填写配置信息

4. **验证**
   - 在 Cursor 中打开 AI 对话框
   - 输入 "@database 查询..." 测试

---

### Windsurf 配置

Windsurf 是支持 MCP 的代码编辑器。

#### 配置位置

- **配置目录**: `~/.windsurf/mcp-config.json`

#### 配置示例

```json
{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": ["/path/to/database-mcp-server/dist/index.js"]
    }
  }
}
```

---

### 常见问题排查

#### 1. 服务器无法启动

**检查路径**:
```bash
# 确认构建文件存在
ls -la dist/index.js

# 重新构建
npm run build
```

**检查权限**:
```bash
# Windows
# 以管理员身份运行 VS Code 或终端

# macOS/Linux
chmod +x dist/index.js
```

#### 2. 连接超时

- 检查服务器日志
- 确认端口未被占用
- 检查防火墙设置

#### 3. 工具不可见

- 确认 MCP 服务器已正确连接
- 在客户端中刷新 MCP 连接
- 检查服务器日志输出

---

## 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| CONNECTION_MAX_CONNECTIONS_PER_CLIENT | 3 | 每客户端最大连接数 |
| CONNECTION_IDLE_TIMEOUT | 600000 | 空闲超时（毫秒） |
| CONNECTION_MAX_LIFETIME | 1800000 | 最长存活时间（毫秒） |
| QUERY_TIMEOUT | 30000 | 查询超时（毫秒） |

---

## 安全注意事项

1. **数据库权限** - 使用最小权限原则创建专用数据库用户
2. **敏感数据** - 根据实际需求配置敏感字段列表
3. **日志安全** - 避免在生产环境日志中记录查询结果
4. **网络隔离** - 建议将服务器部署在内网环境

---

## 故障排查

### 常见问题

**1. 连接失败**
- 检查数据库服务是否运行
- 验证连接参数（host、port、credentials）
- 检查防火墙设置

**2. 查询超时**
- 增加 `QUERY_TIMEOUT` 配置
- 优化 SQL 查询性能
- 检查数据库负载

**3. 限流触发**
- 检查 `get_security_status` 查看限流状态
- 调整 `requestsPerSecond` 配置

### 日志位置

- 审计日志：`./logs/audit.log`
- 错误日志：`./logs/error.log`
- 查询日志：`./logs/query.log`

---

## License

MIT

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 0.1.0 | 2026-03-05 | 初始版本，支持 MySQL/PostgreSQL/Vastbase/ClickHouse |