内容
# 🏁 漂移大师 MCP 服务器
一款使用 Node.js、Prisma 和 **模型上下文协议（MCP）** 构建的 AI 原生后端服务。
该项目允许 AI 助手（例如 Cursor、Claude Desktop 或自定义 LLM 代理）作为漂移锦标赛的自主管理器。 与其给予 AI 危险的原始 SQL 访问权限，该服务器提供了一个可扩展的“工具注册表”，具有严格的业务逻辑函数（CRUD）和 Zod 验证。
## 🚀 功能特点
- **MCP 协议集成：** 通过 `stdio` 传输与 AI 助手无缝连接。
- **可扩展架构：** 构建类似于 NestJS/Express 控制器。使用集中式 `工具注册表` 而不是臃肿的 `switch/if` 语句。
- **严格验证：** 所有工具参数在运行时都使用 **Zod** 模式进行验证。
- **Prisma ORM 和 PostgreSQL：** 使用关系模型（飞行员、汽车、活动、资格、战斗）进行强类型数据库访问。
- **隔离集成测试：** 使用 **Jest** 运行的自动化测试套件，针对专用 Dockerized 测试数据库。
- **通用查询工具：** 包括只读动态 Prisma 查询工具，允许 AI 安全地即时获取复杂关系。
## 📂 项目结构
```text
├── src/
│ ├── index.ts # MCP 服务器入口点和 stdio 设置
│ ├── db.ts # Prisma 客户端初始化
│ ├── __tests__/ # Jest 集成测试
│ └── tools/ # 业务逻辑工具（控制器）
│ ├── schemas/ # Zod 验证模式
│ ├── index.ts # 为服务器导出的工具注册表
│ ├── createPilot.ts # 示例：飞行员创建工具
│ └── queryDatabase.ts # 示例：通用只读查询工具
├── prisma/
│ ├── schema.prisma # 数据库模型
│ └── seed.ts # 初始数据库填充脚本
├── docker-compose.yml # 开发和测试数据库
└── package.json
```
## 🛠️ 安装和设置
**1. 克隆仓库并安装依赖：**
```bash
npm install
```
**2. 启动 PostgreSQL 数据库（开发 + 测试）：**
```bash
npm run db:up
```
**3. 配置环境变量：**
将 `.env.example` 重命名为 `.env`，将 `.env.test.example` 重命名为 `.env.test`。
_（确保它们指向正确的 Docker 端口，例如开发环境为 5432，测试环境为 5433）。_
**4. 推送模式并生成 Prisma 客户端：**
```bash
npx prisma db push
npx prisma generate
```
**5. 初始化开发数据库：**
```bash
npx tsx prisma/seed.ts
```
## 🤖 连接到 Cursor / Claude Desktop
要在支持 MCP 的 AI 助手中使用此服务器：
1. 打开 **Cursor 设置** -> 功能 -> MCP。
2. 点击 **+ 添加新的 MCP 服务器**。
3. 命名它：`drift-masters-mcp`。
4. 运行命令（推荐，显式加载 `.env`）：
```bash
/absolute/path/to/project/node_modules/.bin/dotenv -e /absolute/path/to/project/.env -- /absolute/path/to/project/node_modules/.bin/tsx /absolute/path/to/project/src/index.ts
```
替代方案（如果您的 MCP 客户端已经注入环境变量）：
```bash
npx tsx /absolute/path/to/your/project/src/index.ts
```
5. 点击保存并刷新。
连接后，您可以在 AI 聊天中输入自然语言提示，例如：
> _“注册一位新飞行员：James Deane。他驾驶一辆 Nissan Silvia S14.5，配备 2JZ 发动机，输出 950 马力。”_
AI 将自动解析您的提示，选择 `create_pilot` 工具，通过 Zod 验证参数，并使用 Prisma 的嵌套写入功能将数据保存在 PostgreSQL 中。
## 🧪 测试
该项目使用单独的测试数据库，以避免损坏开发数据。
运行集成测试套件：
```bash
npm run test
```
_该命令自动将模式推送到测试数据库并执行 Jest 测试套件，在每次测试运行之间清理表。_
有用的本地命令：
```bash
npm run drift:start # 本地 MCP 开发的监视模式
npm run drift:once # 一次性 MCP 服务器启动
npm run db:down # 停止数据库
npm run db:reset # 从头重新创建数据库容器
```
## 👨💻 作者
**Kostiantyn Shvydkyi**
全栈 Node.js 工程师
[LinkedIn](https://www.linkedin.com/in/kostyantyn-shvydkyi-444a3b22b/) | [GitHub](https://github.com/kshvydkyi)
