# mcp-db

**Repository Path**: self-testing-oxchen/mcp-db

## Basic Information

- **Project Name**: mcp-db
- **Description**: 创造区别于传统的数据库客户端工具，能嵌入到智能开发助手工具流中，充分发掘ai潜力
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp-db

> 面向 AI 开发工作流的本地数据库客户端

mcp-db 是一个本地运行的桌面数据库客户端工具,同时内嵌 MCP server,让外部 AI 助手(Claude / Cursor 等)能**受控**地操作数据库。此外,GUI 内嵌 AI 对话框,用户可直接用自然语言查询/操作数据。

## 特性

### 🖥️ 传统数据库客户端 GUI(JavaFX)
- 连接管理:分组、测试、动态表单(按数据库类型展示特有参数)
- SQL 工作台:多 Tab、语法高亮、表/列名补全、查询取消
- 结果表格:虚拟滚动、可编辑单元格、插入/删除行、导出(CSV/JSON/SQL)
- 表结构浏览:库/表/字段/索引

### 🔌 内嵌 MCP server
- 通过 HTTP 暴露数据库能力给外部 AI 助手
- 支持 **SSE** 与 **streamable-http** 两种 transport
- **逐连接权限控制**:级别(只读/读写/全权限)+ 操作白/黑名单
- 静态 token 认证,默认仅本机监听(可开局域网)
- 操作日志持久化,可配置保留时长

### 🤖 内嵌 AI 对话框
- 自然语言查询/操作数据库
- 可配置模型端点:支持公网云或**公司内网**模型(OpenAI/Anthropic/Response 协议)
- 建会话时勾选注入库/表结构,未覆盖的按需工具探索
- **只读自动执行,写操作需用户确认**
- 多会话管理,历史持久化

### 🔒 本地优先与安全
- 配置存本地 SQLite,敏感字段 AES-256-GCM 加密
- 主密码派生(PBKDF2)解锁,无主密码无法解密
- 数据不出本机(选内网模型时)

## 支持的数据库

| 数据库 | 类型 |
|--------|------|
| PostgreSQL | 关系型 |
| MySQL | 关系型 |
| 达梦 | 关系型(国产) |
| TDengine | 时序 |
| InfluxDB 1.x | 时序 |
| InfluxDB 2.x | 时序 |
| Redis | KV |
| MongoDB | 文档 |

## 技术栈

- **语言**:Kotlin(JVM 21)
- **GUI**:JavaFX
- **构建**:Gradle(Kotlin DSL)
- **并发**:Kotlin 协程
- **配置存储**:SQLite
- **加密**:PBKDF2WithHmacSHA256 + AES-256-GCM
- **打包**:jpackage(Windows / macOS / Linux)

## 项目结构

```
mcp-db/
├── mcp-db-core      核心抽象:配置/加密/存储/驱动抽象/连接池
├── mcp-db-mcp       MCP HTTP server:token 认证/JSON-RPC/transport
├── mcp-db-drivers   8 种数据库驱动实现
├── mcp-db-gui       JavaFX 桌面 GUI
├── mcp-db-app       应用入口
└── docs/
    ├── project-description/   架构/接口/部署/使用/数据文档
    └── superpowers/           设计文档与实现计划
```

## 快速开始

### 环境要求
- JDK 21(项目已配 JVM toolchain,Gradle 自动定位,无需手动设 JAVA_HOME)

### 构建与运行

```bash
./gradlew build              # 构建 + 测试
./gradlew :mcp-db-app:run    # 运行(GUI 模式,需显示器)
```

### 主密码

首次启动弹出"设置主密码"窗口(强度要求:≥8 位 + 字母 + 数字)。后续启动输入主密码解锁。主密码丢失无法找回,只能重置(清空加密凭证)。测试可设环境变量 `MCPDB_MASTER_PASSWORD` 跳过首屏。

### 接入 AI 助手(Claude Code / Cursor)

1. 启动 GUI → 解锁 → 点左侧"MCP 管理"按钮 → Token Tab → 新建 Token → 点"显示 token"复制明文
2. 在 AI 客户端的 MCP 配置(`.mcp.json`)填入:
   ```json
   {
     "mcpServers": {
       "mcp-db": {
         "type": "http",
         "url": "http://127.0.0.1:9470/mcp",
         "headers": { "Authorization": "Bearer <你的 token>" }
       }
     }
   }
   ```
3. 在 GUI 新建一个 PostgreSQL 连接(host/port/db/user/password),保存后会自动暴露到 MCP tools/list
4. 重启 AI 客户端会话(让 `.mcp.json` 在启动时加载),AI 即可通过 5 个工具(list_databases/list_tables/describe_table/execute_query/execute_update)操作你授权的连接

> Redis 连接额外暴露 `redis_pipeline` 工具(批量执行命令,逐条权限判定,任一条被拒整批不执行)。
> transport 模式可在 MCP 配置 Tab 切换:SSE(`/sse`+`/messages`)、streamable-http(`/mcp`)、BOTH(默认)。

## 文档

- [架构文档](docs/project-description/system-architecture.md)
- [接口文档](docs/project-description/api.md)
- [部署文档](docs/project-description/deploy.md)
- [使用手册](docs/project-description/userguide.md)
- [数据文档](docs/project-description/data.md)
- [设计文档](docs/superpowers/specs/2026-08-20-mcp-db-design.md)
- [更新日志](CHANGELOG.md)

## 当前状态

- **阶段 0(地基)✅**:工程骨架、配置库、加密体系、仓储层、驱动抽象、MCP server 骨架
- **阶段 1a(后端)✅**:PostgreSQL 驱动、无状态权限引擎、5 个 MCP 工具、SSE/streamable 双传输、全层活动日志、多 token。真连 Claude Code 验收通过
- **阶段 1b(GUI 工作台)✅**:JavaFX 解锁首屏、连接管理、SQL 工作台、结果表格(只读+导出+排序)。打通 PostgreSQL
- **阶段 1c(MCP 面板)✅**:MCP 配置面板、token 管理 CRUD、活动日志监控、连接编辑、transport 三模式区分。真连 Claude Code 完整验收通过
- **阶段 2(关系型横向)✅**:`AbstractJdbcDriver` 公共基类、MySQL/达梦/TDengine 三驱动、GUI 工作台改用 `DriverRegistry`、连接表单动态切换
- **阶段 3a(Redis)✅**:首个 NoSQL 驱动(Lettuce 客户端 + 命令分类器 + `redis_pipeline` 定制工具,逐条权限判定)、GUI 表单加 redis

215 个测试全绿。

> 注:README 上方"特性"章节描述的是**完整产品愿景**,部分功能(语法高亮/可编辑单元格/AI 对话框/打包)尚未实现,见后续阶段。

后续阶段:NoSQL/时序剩余(MongoDB/InfluxDB)→ 内嵌 AI 对话框 → 打磨与打包。

## 许可证

(待定)