# MCP Server DB

[![TypeScript](https://img.shields.io/badge/TypeScript-4.9.5-blue.svg)](https://www.typescriptlang.org/)
[![License: ISC](https://img.shields.io/badge/License-ISC-green.svg)](https://opensource.org/licenses/ISC)
[![npm version](https://img.shields.io/npm/v/mcp-server-db.svg)](https://www.npmjs.com/package/mcp-server-db)
[![Downloads](https://img.shields.io/npm/dm/mcp-server-db.svg)](https://www.npmjs.com/package/mcp-server-db)
[![GitHub stars](https://img.shields.io/github/stars/qgao233/mcp-server-db.svg)](https://github.com/qgao233/mcp-server-db/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/qgao233/mcp-server-db.svg)](https://github.com/qgao233/mcp-server-db/network)
[![GitHub issues](https://img.shields.io/github/issues/qgao233/mcp-server-db.svg)](https://github.com/qgao233/mcp-server-db/issues)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/qgao233/mcp-server-db/pulls)
[![Node.js CI](https://github.com/qgao233/mcp-server-db/workflows/Node.js%20CI/badge.svg)](https://github.com/qgao233/mcp-server-db/actions)
[![codecov](https://codecov.io/gh/qgao233/mcp-server-db/branch/main/graph/badge.svg)](https://codecov.io/gh/qgao233/mcp-server-db)

这是一个基于 Model Context Protocol (MCP) 的服务器项目，用于连接数据库并提供数据库操作功能。

## 目录

- [功能特点](#功能特点)
- [安装](#安装)
- [运行](#运行)
- [可用功能](#可用功能)
- [开发](#开发)
- [注意事项](#注意事项)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 功能特点

- 使用 TypeScript 实现
- 基于 MCP TypeScript SDK
- 支持多种数据库连接：
  - MySQL
  - PostgreSQL
  - SQL Server
- 使用 stdio 作为传输层
- 提供数据库查询和执行命令的工具
- 完整的错误处理和日志记录

## 安装


1. 克隆项目：
```bash
git clone <repository-url>
cd mcp-server-db
```

2. 安装依赖：
```bash
npm install
```

## 运行

### 方式一：本地 npm 运行

```bash
npm run dev <type> <host> <port> <database> <username> <password>
```

例如：
```bash
# MySQL
npm run dev mysql localhost 3306 mydb root mypassword

# PostgreSQL
npm run dev postgresql localhost 5432 mydb postgres secret

# SQL Server
npm run dev sqlserver localhost 1433 mydb sa Password123!
```

### 方式二：本地 npx 运行

在项目目录下使用 npx 运行：
```bash
# 先构建项目
npm run build

# 使用 npx 运行
cd dist
npx . <type> <host> <port> <database> <username> <password>
```

注意：
1. 需要先构建项目生成 JavaScript 文件，因为 npx 不能直接运行 TypeScript 文件
2. 需要在 dist 目录下运行 npx 命令
3. 参数说明：
   - type: 数据库类型（mysql、postgresql 或 sqlserver）
   - host: 数据库主机地址（如：localhost）
   - port: 数据库端口号
     - MySQL: 默认 3306
     - PostgreSQL: 默认 5432
     - SQL Server: 默认 1433
   - database: 数据库名称
   - username: 数据库用户名
   - password: 数据库密码


### 方式三：在 Cursor 中配置

1. 打开 Cursor 设置
2. 找到 MCP 配置部分
3. 添加新的 MCP 服务器配置：


使用 npx（示例配置）：
```json
{
  "mcpServers": {
    "mysql-dev": {
      "command": "npx",
      "args": ["/path/to/mcp-server-db/dist/.", "mysql", "localhost", "3306", "mydb", "root", "password"],
      "transport": "stdio"
    },
    "postgres-dev": {
      "command": "npx",
      "args": ["/path/to/mcp-server-db/dist/.", "postgresql", "localhost", "5432", "mydb", "postgres", "password"],
      "transport": "stdio"
    },
    "sqlserver-dev": {
      "command": "npx",
      "args": ["/path/to/mcp-server-db/dist/.", "sqlserver", "localhost", "1433", "mydb", "sa", "Password123!"],
      "transport": "stdio"
    }
  }
}
```

配置说明：
- 服务器标识符（如：`mysql-dev`）：可自定义，建议包含数据库类型
- `command`: 执行命令（使用 `npx`）
- `args`: 命令参数数组，依次为：
  1. 项目路径
  2. 数据库类型：`mysql`、`postgresql` 或 `sqlserver`
  3. 主机地址（如：localhost）
  4. 端口号（根据数据库类型选择合适的默认端口）
  5. 数据库名称
  6. 用户名
  7. 密码
- `transport`: 传输方式，使用 "stdio"


### 参数说明

- `host`: 数据库主机地址（如：localhost）
- `port`: 数据库端口号（如：3306）
- `database`: 数据库名称
- `username`: 数据库用户名
- `password`: 数据库密码

## 可用功能

### MCP 工具

服务器提供以下工具：

1. `query` - 执行 SQL 查询
   - 参数：
     - `sql`: SQL 查询语句（必需）
     - `values`: 查询参数值（可选）

2. `execute` - 执行 SQL 命令
   - 参数：
     - `sql`: SQL 命令（必需）
     - `values`: 命令参数值（可选）

### MCP 提示词

服务器提供以下 AI 提示词模板：

1. `sql-query` - SQL查询生成
   - 功能：根据描述生成安全、标准的SQL查询语句
   - 参数：
     - `action`: 操作类型（select/insert/update/delete）
     - `table`: 表名
     - `fields`: 字段列表（可选）
     - `conditions`: 查询条件（可选）
     - `description`: 额外的需求描述（可选）
   - 示例：
     ```json
     {
       "action": "select",
       "table": "users",
       "fields": ["id", "name", "email"],
       "conditions": "age > 18",
       "description": "需要分页，每页10条记录"
     }
     ```

2. `table-schema` - 表结构设计
   - 功能：根据业务需求设计合适的数据库表结构
   - 参数：
     - `table`: 表名
     - `description`: 表的用途描述
     - `requirements`: 具体需求列表
   - 示例：
     ```json
     {
       "table": "orders",
       "description": "存储电商系统的订单信息",
       "requirements": [
         "需要记录订单的基本信息（订单号、创建时间、状态等）",
         "需要关联用户信息",
         "需要存储订单商品明细",
         "需要记录支付和配送信息",
         "需要支持订单状态变更历史追踪"
       ]
     }
     ```

3. `sql-review` - SQL代码审查
   - 功能：审查SQL语句的性能、安全性和最佳实践
   - 参数：
     - `sql`: 要审查的SQL语句
     - `context`: 相关上下文信息（可选）
   - 示例：
     ```json
     {
       "sql": "SELECT * FROM orders o LEFT JOIN users u ON o.user_id = u.id WHERE o.status = 'pending'",
       "context": "这是订单列表查询接口使用的SQL，需要支持高并发访问"
     }
     ```

## 开发

- 使用 `npm run dev` 在开发模式下运行服务器
- 项目使用 TypeScript 开发，源代码在 `src` 目录下
- 使用单例模式管理配置、数据库连接和服务器实例

### 项目结构

```
mcp-server-db/
├── src/
│   ├── adapters/      # 数据库适配器
│   ├── config/        # 配置文件
│   ├── mcp/          # MCP 服务器核心
│   ├── services/     # 业务服务
│   ├── types/        # 类型定义
│   └── utils/        # 工具函数
├── package.json
└── tsconfig.json
```

## 注意事项

### 数据库连接
- MySQL
  - 默认端口：3306
  - 典型用户名：root
  - 连接示例：`mysql localhost 3306 mydb root password`

- PostgreSQL
  - 默认端口：5432
  - 典型用户名：postgres
  - 连接示例：`postgresql localhost 5432 mydb postgres password`

- SQL Server
  - 默认端口：1433
  - 典型用户名：sa
  - 连接示例：`sqlserver localhost 1433 mydb sa Password123!`

### 一般注意事项
- 确保提供正确的数据库连接信息（类型、主机地址、端口号等）
- 确保目标数据库服务器正在运行并可访问
- 确保提供的数据库凭据正确
- 使用 Ctrl+C 优雅地停止服务器

## 贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

本项目采用 ISC 许可证 - 查看 [LICENSE](LICENSE) 文件了解更多详情。

## 联系我

如有问题或建议，请提交 [Issue](https://github.com/qgao233/mcp-server-db/issues)。