# 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-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP-DB Bridge

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

## 核心特性

- **MCP 协议集成** — 基于 Solon AI MCP，支持 Streamable HTTP 和 STDIO 两种通道，可为任何 MCP 兼容 AI 客户端提供数据库操作能力
- **三级安全模型** — DQL（查询）可直连执行 / DDL（表结构变更）强制审核 / DML（数据变更）强制审核，危险关键字自动拦截
- **Web 管理控制台** — 内置 Dashboard，管理数据源配置、审核请求
- **多数据源** — 支持 MySQL、PostgreSQL，HikariCP 连接池，空闲连接自动回收
- **密码加密存储** — AES-GCM 加密存储数据源密码
- **审核审计** — SQLite 存储审核记录，全程可追溯

## 架构概览

```
AI Client (Claude/Copilot/etc)
        │
        ▼  MCP (Streamable HTTP / STDIO)
┌───────────────────┐
│   MCP Tools       │  listDatasources / executeDql / submitDdl / submitDml / queryAuditStatus
└───────┬───────────┘
        │
   ┌────┴────┐
   │ DQL     │── 直连执行（可选审核）
   │ DDL/DML │── 提交审核队列 → 人工 Web 审批 → 执行
   └────┬────┘
        │
   ┌────┴────────────────┐
   │  HikariCP 连接池      │
   │  MySQL / PostgreSQL  │
   └─────────────────────┘
```

## 技术栈

| 组件         | 技术                                                    |
| ------------ | ------------------------------------------------------- |
| 框架         | Solon 3.6.8                                             |
| MCP SDK      | solon-ai-mcp 0.8.0                                      |
| 连接池       | HikariCP 5.1.0                                          |
| ORM (审计库) | MyBatis-Plus 3.5.9 + SQLite                             |
| JSON         | Snack3 / Jackson                                        |
| 加密         | AES-GCM                                                 |
| Java         | 17+                                                     |
| 构建         | Maven 3.9+ (maven-shade-plugin 打 Fat Jar)              |

## 快速开始

### 构建

```bash
# JDK 17+
mvn package -DskipTests
```

产物: `target/mcp-db-bridge-1.0.0-SNAPSHOT.jar`

### 启动

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

首次启动自动创建 `data/` 目录和 SQLite 审计库。

### 访问

| 端点               | 说明                  |
| ------------------ | --------------------- |
| 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 Tools

| Tool                | 说明                                         |
| ------------------- | -------------------------------------------- |
| `listDatasources`   | 列出所有可用数据源及状态                        |
| `executeDql`        | 执行 DQL 查询（SELECT/SHOW/DESCRIBE/EXPLAIN）  |
| `submitDdl`         | 提交 DDL 到审核队列                            |
| `submitDml`         | 提交 DML（INSERT/UPDATE/DELETE）到审核队列      |
| `queryAuditStatus`  | 查询审核请求状态                                |

## 配置说明

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

```yaml
mcp-db-bridge:
  server:
    port: 8080

  dql:
    audit-enabled: false    # 查询是否开启审核
    timeout: 30000          # 查询超时 (ms)
    max-rows: 1000          # 最大返回行数
    read-only: true         # 强制只读

  ddl:
    audit-enabled: true     # DDL 强制审核
    danger-keywords:        # 危险关键字拦截
      - DROP
      - TRUNCATE

  dml:
    audit-enabled: true     # DML 强制审核
    danger-keywords:
      - DELETE
      - UPDATE
      - TRUNCATE
      - DROP

  crypto:
    secret-key: ""          # AES 密钥，空则用默认值；也可通过环境变量 MCP_DB_BRIDGE_SECRET_KEY 设置

  admin:
    username: admin
    password: admin123
```

## 工作流

### 查询流程 (DQL)

```
AI 发起 executeDql → SQL 类型校验 → （可选审核）→ 直连执行 → 返回结果
```

### 变更流程 (DDL/DML)

```
AI 发起 submitDdl/submitDml → 危险关键字检查 → 写入审核队列 → 返回请求ID
                                                          ↓
                                             Web Dashboard 人工审批
                                                          ↓
                                              通过 → 执行 / 驳回 → 记录
```

## 项目结构

```
src/main/java/cn/ingrun/mcpdb/
├── App.java                    # 启动入口
├── config/                     # 配置类 (AppConfig, Dql/Ddl/Dml 子配置)
├── entity/                     # MyBatis-Plus 实体 (SQLite 审计库)
├── mapper/                     # MyBatis-Plus Mapper
├── mcp/
│   └── McpServerTool.java      # MCP Tool 定义
├── model/                      # 领域模型
├── service/
│   ├── DatasourceManager.java  # 数据源生命周期管理
│   ├── SqlExecutor.java        # SQL 执行引擎
│   ├── AuditEngine.java        # 审核引擎
│   └── AuditPersistence.java   # 审核持久化
├── util/                       # 工具类 (SQL 校验、AES 加密)
├── web/
│   ├── config/                 # BasicAuth 过滤器
│   ├── controller/             # REST 控制器 + 审核 Dashboard
│   └── dto/                    # 数据传输对象
└── resources/
    ├── app.yml                 # 应用配置
    └── static/                 # Web 前端静态资源
```

## License

MIT