# mcp-db-bridge

**Repository Path**: ingrun/mcp-db-bridge

## Basic Information

- **Project Name**: mcp-db-bridge
- **Description**: AI 安全操作数据库的中间层 —— 通过 MCP 协议暴露数据库操作工具给 AI 客户端，DDL/DML 操作自带人工审核流程。

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP-DB Bridge

[![Java](https://img.shields.io/badge/Java-17%2B-orange)](https://adoptium.net/)
[![Solon](https://img.shields.io/badge/Solon-3.6.8-blue)](https://solon.noear.org/)
[![MCP](https://img.shields.io/badge/MCP-0.8.0-green)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**MCP 数据库桥接服务** — AI 安全操作数据库的中间层。通过 MCP 协议向 AI 客户端暴露数据库操作能力，DDL/DML 操作内置人工审核流程，解决 AI 直接操作生产库的安全风险。

---

## 目录

- [背景](#背景)
- [核心特性](#核心特性)
- [架构](#架构)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [MCP Tools](#mcp-tools)
- [REST API](#rest-api)
- [工作流](#工作流)
- [安全模型](#安全模型)
- [项目结构](#项目结构)
- [技术栈](#技术栈)

---

## 背景

大语言模型在数据查询、报表生成、数据库管理等场景展现了巨大潜力，但现有方案存在以下痛点：

| 问题 | 说明 |
|------|------|
| **安全风险高** | AI 直连生产库执行 SQL，DDL 误操作可能导致数据丢失 |
| **审核缺失** | AI 生成的 DDL 缺乏人工审核，变更不可追溯 |
| **多源管理难** | 多套数据库环境需多个连接配置，AI 无统一入口 |
| **上下文混乱** | AI 无法区分"查哪个库"，容易串库操作 |
| **无法干预** | 对 AI 生成的 SQL 无法人工编辑和确认 |

MCP-DB Bridge 作为 AI 与数据库之间的安全中间层，提供**可配置的分级安全策略**和**完整的人机协同审核流程**。

### 用户角色

| 角色 | 描述 | 核心场景 |
|------|------|---------|
| **AI Agent** | LLM 通过 MCP 协议调用服务 | 查询数据、提交 DDL/DML、选择数据源 |
| **DBA / 开发者** | 人工审核方 | 审核 DDL、编辑 SQL、批准/驳回、手动执行 SQL |
| **系统管理员** | 配置方 | 管理数据源、设置审核策略、查看审计日志 |

---

## 核心特性

- **MCP 原生集成** — 基于 solon-ai-mcp，支持 Streamable HTTP + STDIO 双通道，兼容任何 MCP 客户端
- **三级安全模型** — DQL 直连执行 / DDL 强制审核 / DML 强制审核，危险关键字自动拦截
- **人机协同审核** — DDL/DML 提交到审核队列，管理员可编辑 SQL 后批准或驳回
- **Web 管理控制台** — 仪表盘、数据源管理、审核队列、SQL 工作台、审计日志
- **多数据源** — 支持 MySQL、PostgreSQL，HikariCP 连接池按需创建，空闲自动回收
- **密码加密** — AES-256-GCM 加密存储数据源密码，密钥支持环境变量注入
- **完整审计** — SQLite 持久化存储所有操作记录，不可删除，全程可追溯
- **Basic Auth** — Web 管理控制台需要登录认证

---

## 架构

```
┌──────────────────┐
│   AI Client      │  (Claude / Copilot / 任意 MCP Host)
└────────┬─────────┘
         │  MCP Protocol (Streamable HTTP / STDIO)
         ▼
┌─────────────────────────────────────────────┐
│              MCP-DB Bridge                  │
│                                             │
│  ┌─────────────┐  ┌──────────────────────┐  │
│  │ MCP Tools   │  │   Web Dashboard      │  │
│  │ 5 tools     │  │   (BasicAuth)        │  │
│  └──────┬──────┘  └──────────┬───────────┘  │
│         │                    │              │
│  ┌──────┴────────────────────┴──────────┐   │
│  │          Service Layer               │   │
│  │  ┌──────────┐ ┌──────────┐ ┌───────┐ │   │
│  │  │AuditEngine│ │SqlExecutor│ │DS Mgmt│ │   │
│  │  └──────────┘ └──────────┘ └───────┘ │   │
│  └───────────────────┬──────────────────┘   │
│                      │                      │
│  ┌───────────────────┴──────────────────┐   │
│  │  HikariCP Connection Pools           │   │
│  │  (per-datasource, lazy init)         │   │
│  └───────────────────┬──────────────────┘   │
│                      │ JDBC                 │
└──────────────────────┼─────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
   ┌────────┐    ┌──────────┐   ┌────────┐
   │ MySQL  │    │PostgreSQL│   │  ...   │
   └────────┘    └──────────┘   └────────┘
```

### 数据隔离

| 存储层 | 技术 | 用途 |
|--------|------|------|
| SQLite (`data/audit.db`) | MyBatis-Plus 管理 | 数据源配置、审核记录、操作日志 |
| 业务数据源 (MySQL/PG) | HikariCP 动态连接池 | 实际的 SQL 执行目标 |

---

## 快速开始

### 环境要求

- **Java 17+** （推荐 Eclipse Temurin / Adoptium）
- **Maven 3.9+**

### 构建

```bash
git clone <repo-url> && cd mcp-db-bridge

# JDK 17
mvn package -DskipTests
```

产物：`target/mcp-db-bridge-1.0.0-SNAPSHOT.jar`（Fat Jar，包含所有依赖）

### 启动

```bash
java -jar target/mcp-db-bridge-1.0.0-SNAPSHOT.jar
```

首次启动自动创建 `data/` 目录和 SQLite 审计库，控制台输出：

```
======================================
MCP-DB Bridge 启动完成
Web UI:  http://localhost:8080
MCP:     http://localhost:8080/mcp (Streamable HTTP)
======================================
```

### 访问

| 端点 | 说明 |
|------|------|
| `http://localhost:8080` | Web 管理控制台首页 |
| `http://localhost:8080/mcp` | MCP Streamable HTTP 端点 |

管理员默认账号：**`admin`** / **`admin123`**

### 接入 AI 客户端

在你的 MCP 客户端配置中添加：

```json
{
  "mcpServers": {
    "db-bridge": {
      "type": "streamableHttp",
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

常见 MCP Host 示例：

- **Claude Desktop**: 编辑 `claude_desktop_config.json`
- **VS Code Copilot**: `.vscode/mcp.json`
- **WorkBuddy / CodeBuddy**: `~/.workbuddy/mcp.json`

接入后 AI 即可通过 MCP 发现并使用 `listDatasources`、`executeDql`、`submitDdl`、`submitDml`、`queryAuditStatus` 五个工具。

---

## 配置说明

配置文件：`src/main/resources/app.yml`

### 服务配置

```yaml
mcp-db-bridge:
  server:
    port: 8080              # HTTP 端口
```

### DQL（查询）策略

```yaml
  dql:
    audit-enabled: false    # 是否开启 DQL 审核（默认关）
    timeout: 30000          # 查询超时 (ms)
    max-rows: 1000          # 最大返回行数，防止 OOM
    read-only: true         # 强制只读连接
```

### DDL（结构变更）策略

```yaml
  ddl:
    audit-enabled: true     # 强制审核
    danger-keywords:        # 危险操作额外告警
      - DROP
      - TRUNCATE
    auto-approve-timeout: 0 # 超时自动审批（0 = 禁用）
```

### DML（数据变更）策略

```yaml
  dml:
    audit-enabled: true     # 强制审核
    timeout: 30000
    danger-keywords:
      - DELETE
      - UPDATE
      - TRUNCATE
      - DROP
```

### 密码加密

```yaml
  crypto:
    secret-key: ""          # 留空使用默认密钥
```

生产环境建议通过环境变量注入：

```bash
export MCP_DB_BRIDGE_SECRET_KEY="your-secure-key"
```

### 管理员账号

```yaml
  admin:
    username: admin
    password: admin123
```

### 连接池

```yaml
  pool:
    idle-timeout: 1800000   # 空闲连接回收时间 (ms)，默认 30 分钟
```

### SQLite 审计库（MyBatis-Plus）

```yaml
solon.dataSources:
  audit!:
    class: "com.zaxxer.hikari.HikariDataSource"
    driverClassName: org.sqlite.JDBC
    jdbcUrl: jdbc:sqlite:./data/audit.db

mybatis.audit:
  mappers:
    - "cn.ingrun.mcpdb.mapper"
  configuration:
    mapUnderscoreToCamelCase: true
  globalConfig:
    banner: false
```

---

## MCP Tools

服务通过 MCP 协议向 AI 暴露 5 个工具：

### `listDatasources`

列出所有可用数据源及运行状态（无需参数）。

```
输出示例:
可用数据源 (2 个):
  ▸ prod-mysql  [MYSQL]  已连接
  ▸ dev-pg  [POSTGRESQL]  已禁用
```

### `executeDql`

在指定数据源上执行 DQL 查询（SELECT / SHOW / DESCRIBE / EXPLAIN）。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasource` | string | 是 | 数据源标识符 |
| `sql` | string | 是 | SQL 查询语句 |

返回列名、行数据（最多 20 行预览）、实际行数、执行耗时。

### `submitDdl`

提交 DDL 语句到审核队列，等待人工审核后执行。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasource` | string | 是 | 数据源标识符 |
| `sql` | string | 是 | DDL 语句（CREATE / ALTER / DROP 等） |
| `description` | string | 否 | 变更说明 |

返回 `请求ID`，用于后续查状态。

### `submitDml`

提交 DML 语句（INSERT / UPDATE / DELETE）到审核队列。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `datasource` | string | 是 | 数据源标识符 |
| `sql` | string | 是 | DML 语句 |
| `description` | string | 否 | 变更说明 |

### `queryAuditStatus`

查询审核请求的当前状态。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `requestId` | string | 是 | 提交审核时返回的请求 ID |

返回状态、SQL 类型、原始 SQL、审核人、审核意见等。

---

## REST API

Web 管理控制台使用的后端 API。所有接口返回统一格式 `{ code: int, message: string, data: T }`。

### 数据源管理 — `/api/datasources`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/datasources` | 获取数据源列表（含连接状态） |
| `POST` | `/api/datasources` | 新增数据源 |
| `PUT` | `/api/datasources/{name}` | 编辑数据源 |
| `DELETE` | `/api/datasources/{name}` | 删除数据源 |
| `POST` | `/api/datasources/{name}/test` | 测试已有数据源连通性 |
| `POST` | `/api/datasources/test` | 按配置测试连通性（不保存） |
| `PATCH` | `/api/datasources/{name}/toggle` | 启用/禁用数据源 |

数据源配置字段：`name`, `type`（MYSQL/POSTGRESQL/SQLITE）, `jdbcUrl`, `username`, `password`, `maxPoolSize`, `enabled`

### 仪表盘 — `/api/dashboard`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/dashboard/stats` | 统计数据（数据源数、待审核数、今日执行数、状态分布） |

### 审核队列 — `/api/audit`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/audit/queue` | 待审核列表 |
| `GET` | `/api/audit/{id}` | 审核请求详情 |
| `PUT` | `/api/audit/{id}/sql` | 编辑 SQL |
| `POST` | `/api/audit/{id}/approve` | 批准（含危险操作确认） |
| `POST` | `/api/audit/{id}/reject` | 驳回（需填写原因） |

### SQL 工作台 — `/api/workbench`

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/workbench/execute` | 人工执行 SQL（DQL 直连，DDL/DML 走审核） |

### 审计日志 — `/api/audit/logs`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/audit/logs` | 分页查询审计日志（支持 `page`, `pageSize`, `status`, `datasource`, `sqlType` 筛选） |

---

## 工作流

### DQL 查询流程

```
AI 调用 executeDql
  → 校验 datasource 有效性
  → 校验 SQL 类型为 DQL
  → （可选审核，默认关闭）
  → HikariCP 连接池获取只读连接
  → 执行查询，限制返回行数
  → 返回结果（列名 + 数据 + 耗时）
  → 写入审计日志
```

### DDL/DML 审核流程

```
AI 调用 submitDdl / submitDml
  → 校验 datasource 有效性
  → 校验 SQL 类型
  → 危险关键字检查
  → 写入审核队列（SQLite 持久化）
  → 返回 请求ID 给 AI
  
管理员在 Web Dashboard:
  → 查看待审核列表
  → （可选）编辑 SQL
  → 批准 → 执行 DDL/DML → 记录结果
  → 驳回 → 填写原因 → 记录驳回
  
AI 调用 queryAuditStatus 轮询结果
```

### 审核状态机

```
PENDING ──批准──▶ APPROVED ──执行──▶ EXECUTED
    │                                  │
    │                                  └──执行失败──▶ FAILED
    │
    └──驳回──▶ REJECTED
```

---

## 安全模型

| 层级 | 操作类型 | 默认策略 | 可配置 |
|------|---------|---------|--------|
| **DQL** | SELECT / SHOW / DESCRIBE / EXPLAIN | 直连执行 | 可开启审核 |
| **DDL** | CREATE / ALTER / DROP / TRUNCATE | 强制审核 | 可关闭 |
| **DML** | INSERT / UPDATE / DELETE | 强制审核 | 可关闭 |

### 多层保护机制

1. **SQL 类型校验** — 拒绝非对应类型的语句（如用 `executeDql` 执行 DROP）
2. **只读连接** — DQL 默认使用只读事务，防止隐式写入
3. **危险关键字** — DROP / TRUNCATE 在审核界面弹出额外确认
4. **行数限制** — DQL 最大返回 1000 行，防止 OOM
5. **密码加密** — AES-256-GCM，密钥可环境变量注入
6. **审计不可删** — SQLite 记录的审计日志不可通过 API 删除
7. **Basic Auth** — Web 管理控制台需登录

---

## 项目结构

```
mcp-db-bridge/
├── data/                          # 运行时数据（自动创建）
│   └── audit.db                   # SQLite 审计库
├── doc/                           # 设计文档
│   ├── PRD-MCP数据库服务.md        # 产品规格文档
│   ├── mcp-db-bridge-ui.html      # UI 原型
│   └── audit-report.html          # 审计报告原型
├── test_endpoints.py              # API 端点回归测试脚本
├── pom.xml                        # Maven 配置
│
└── src/main/
    ├── java/cn/ingrun/mcpdb/
    │   ├── App.java                       # 启动入口
    │   │
    │   ├── config/                        # 配置绑定
    │   │   ├── AppConfig.java             # 全局配置（端口/加密/密码/子模块）
    │   │   ├── DatasourceConfig.java      # 单个数据源配置
    │   │   ├── DqlConfig.java             # DQL 策略配置
    │   │   ├── DdlConfig.java             # DDL 策略配置
    │   │   ├── DmlConfig.java             # DML 策略配置
    │   │   └── MybatisPlusPluginConfig.java  # SQLite 审计库 DB 初始化
    │   │
    │   ├── entity/                        # MyBatis-Plus 实体（审计库）
    │   │   ├── DatasourceConfigEntity.java
    │   │   └── AuditRequestEntity.java
    │   │
    │   ├── mapper/                        # MyBatis-Plus Mapper
    │   │   ├── DatasourceConfigMapper.java
    │   │   └── AuditRequestMapper.java
    │   │
    │   ├── mcp/
    │   │   └── McpServerTool.java         # MCP Tool 定义（5 个工具）
    │   │
    │   ├── model/                         # 领域模型
    │   │   ├── AuditRequest.java          # 审核请求
    │   │   ├── AuditStatus.java           # 审核状态枚举
    │   │   ├── AuditStatusCount.java      # 状态计数统计
    │   │   ├── DatasourceInfo.java        # 数据源运行信息
    │   │   ├── DbType.java                # 数据库类型枚举
    │   │   ├── ExecutionResult.java       # SQL 执行结果
    │   │   └── SqlType.java               # SQL 类型枚举
    │   │
    │   ├── service/                       # 核心业务逻辑
    │   │   ├── DatasourceManager.java     # 数据源生命周期（CRUD + 连接池）
    │   │   ├── SqlExecutor.java           # SQL 执行引擎
    │   │   ├── AuditEngine.java           # 审核引擎（提交/批准/驳回/编辑/查询）
    │   │   ├── AuditPersistence.java      # 审核持久化（SQLite 读写）
    │   │   ├── DatasourcePersistence.java # 数据源配置持久化
    │   │   └── AuditLogService.java       # 审计日志查询
    │   │
    │   ├── util/                          # 工具类
    │   │   ├── SqlValidator.java          # SQL 类型检测 + 危险关键字
    │   │   ├── AesEncryptor.java          # AES-GCM 加密/解密
    │   │   └── Utils.java                 # 通用工具
    │   │
    │   ├── exception/                     # 自定义异常
    │   │   ├── AuditRequiredException.java
    │   │   ├── DatasourceDisabledException.java
    │   │   ├── DatasourceNotFoundException.java
    │   │   └── SqlExecutionException.java
    │   │
    │   └── web/                           # Web 层
    │       ├── config/
    │       │   └── BasicAuthFilter.java    # 登录认证过滤器
    │       ├── controller/
    │       │   ├── RootController.java     # 首页 + 登录
    │       │   ├── DashboardController.java
    │       │   ├── DatasourceController.java
    │       │   ├── AuditController.java
    │       │   ├── AuditLogController.java
    │       │   └── SqlWorkbenchController.java
    │       └── dto/
    │           ├── ApiResponse.java        # 统一响应体
    │           └── DatasourceDto.java      # 数据源请求/响应 DTO
    │
    └── resources/
        ├── app.yml                        # 应用配置
        ├── logback.xml                    # 日志配置
        ├── mapper/
        │   └── AuditRequestMapper.xml     # MyBatis XML 映射
        └── static/
            ├── index.html                 # 管理控制台 SPA
            └── login.html                 # 登录页
```

---

## 技术栈

| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 框架 | Solon | 3.6.8 | 轻量 Java 应用框架 |
| MCP SDK | solon-ai-mcp | — | MCP 服务端实现 |
| 服务器 | smart-http | — | Solon 内嵌 |
| 连接池 | HikariCP | 5.1.0 | 业务数据源连接池 |
| ORM | MyBatis-Plus | 3.5.9 | 管理 SQLite 审计库 |
| 审计存储 | SQLite (sqlite-jdbc) | 3.45.3.0 | 配置 + 审核 + 日志 |
| JSON | Snack3 + Jackson | 2.17.1 | 序列化 / 反序列化 |
| 加密 | AES-256-GCM | — | 数据源密码加密 |
| JDBC | MySQL + PostgreSQL | 8.3.0 / 42.7.3 | 业务数据源驱动 |
| 日志 | Logback + SLF4J | 1.5.6 / 2.0.16 | 日志框架 |
| 构建 | Maven Shade Plugin | 3.5.2 | Fat Jar 打包 |
| Java | 17 (LTS) | — | 编译 + 运行 |
| 测试 | Python 3 | — | 端点回归测试 |

---

## 测试

```bash
# 启动服务后运行端点回归测试
python test_endpoints.py
```

输出：

```
======================================================================
MCP-DB Bridge 端点测试
======================================================================
  PASS  GET    /                                 → 200
  PASS  GET    /index.html                       → 200
  PASS  GET    /api/datasources                  → 200
  PASS  POST   /api/datasources                  → 200
  ...
======================================================================
总计: 15  |  通过: 15  |  失败: 0
全部测试通过！
======================================================================
```

---

## License

MIT