# MySQL MCP Server with Kimi AI

基于 NestJS + TypeScript + MySQL 的 MCP 服务器，集成 Kimi AI 实现自然语言数据库操作。

## 功能特性

- ✅ 严格遵循 MCP 协议标准
- ✅ 支持数据库增删查改操作
- ✅ 集成 Kimi AI（通过 prompt 工程实现工具调用）
- ✅ SSE 流式响应
- ✅ 生产级安全措施（SQL 注入防护、表白名单、查询限制）
- ✅ 前端聊天测试界面

## 项目结构

```
mysql-mcp-server/
├── src/
│   ├── main.ts                    # 应用入口
│   ├── app.module.ts              # 根模块
│   ├── config/                    # 配置模块
│   │   ├── config.module.ts
│   │   └── config.service.ts
│   ├── database/                  # 数据库模块
│   │   ├── database.module.ts
│   │   └── database.service.ts
│   ├── mcp/                       # MCP 服务模块
│   │   ├── mcp.module.ts
│   │   └── mcp-server.service.ts
│   └── chat/                      # 聊天 API 模块
│       ├── chat.module.ts
│       ├── chat.controller.ts
│       ├── chat.service.ts
│       └── kimi.service.ts
├── frontend/                      # 前端测试界面
│   ├── index.html
│   └── app.js
├── init-database.sql              # 数据库初始化脚本
├── .env                           # 环境变量配置
└── package.json
```

## 快速开始

### 1. 初始化数据库

```bash
mysql -u root -p123456 < init-database.sql
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 配置环境变量

已创建 `.env` 文件，包含：
- 数据库连接信息
- Kimi API 密钥
- 安全配置

### 4. 编译项目

```bash
pnpm run build
```

### 5. 启动服务

#### 方式 A：Chat API 服务（带前端 SSE）

```bash
pnpm start
```

服务将启动：
- Chat API: http://localhost:3000
- MCP Server: 自动启动（子进程）
- 前端测试：打开 `frontend/index.html`

#### 方式 B：独立 MCP Server（给 Kiro/Claude 用）

```bash
pnpm run start:mcp
```

这会启动一个通过 stdio 通信的 MCP Server，可以被 Kiro IDE、Claude Desktop 等 MCP 客户端调用。

详细配置请查看 [MCP-SETUP.md](./MCP-SETUP.md)

## MCP 工具列表

1. **list_tables** - 列出所有表
2. **get_schema** - 获取表结构
3. **query_database** - 执行 SELECT 查询
4. **insert_record** - 插入数据
5. **update_record** - 更新数据
6. **delete_record** - 删除数据

## 安全特性

- ✅ SQL 注入防护（参数化查询）
- ✅ 表权限控制（可配置允许访问的表和只读表）
- ✅ 操作权限控制（可配置每个表允许的操作）
- ✅ 查询结果限制（最多 1000 条）
- ✅ 禁止危险 SQL 关键字（DROP TABLE, DROP DATABASE, TRUNCATE 等）
- ✅ 审计日志（记录所有操作和数据变更）
- ✅ 数据变更追踪（记录修改前后的数据对比）
- ✅ 输入验证

详细配置请查看 [PERMISSIONS.md](./PERMISSIONS.md)

## 使用示例

在聊天界面中输入：

- "查询所有用户"
- "插入一个新用户，用户名是 test，邮箱是 test@example.com，年龄是 25"
- "更新 id 为 1 的用户年龄为 30"
- "删除 id 为 3 的用户"
- "显示 users 表的结构"

## 架构说明

本项目采用真正的 MCP 协议架构：

```
┌─────────────────┐         ┌──────────────────┐
│  MCP Server     │         │  Chat API        │
│  (独立进程)      │←────────│  (NestJS)        │
│  stdio 通信     │  MCP    │  SSE to 前端     │
└─────────────────┘ Client  └──────────────────┘
         ↑
         │ stdio
    ┌────┴─────┐
    │   Kiro   │
    │  Claude  │
    └──────────┘
```

- **MCP Server**：独立运行，通过 stdio 通信，符合 MCP 标准
- **Chat API**：作为 MCP Client，连接到 MCP Server
- **前端 SSE**：通过 Chat API 获取流式响应

## 技术栈

- NestJS 10.x
- TypeScript 5.x
- TypeORM 0.3.x
- MySQL 8.x
- @modelcontextprotocol/sdk（标准 MCP 协议）
- Kimi API (Moonshot AI)

## 开发模式

```bash
pnpm run dev
```

## 配置文档

- [MCP-SETUP.md](./MCP-SETUP.md) - MCP Server 配置指南（Kiro/Claude）
- [PERMISSIONS.md](./PERMISSIONS.md) - 权限和安全配置

## 注意事项

1. 确保 MySQL 服务已启动
2. 确保 Kimi API Key 有效
3. 生产环境请修改 API_KEY 和数据库密码
4. 可通过 `database-permissions.json` 调整表权限
5. 所有操作都会记录到 `logs/audit.log`