SQL MCP Agent

SQL MCP代理

一个由AI驱动的SQL代理，连接到MySQL数据库，并允许通过OpenAI的GPT模型进行自然语言查询。代理根据用户请求自动对数据库执行CRUD操作。

特性

• 🤖 AI驱动：使用OpenAI的GPT-3.5-turbo来理解自然语言查询
• 📊 自动模式检测：动态加载数据库模式并向AI提供上下文
• 🔧 CRUD操作：通过自然语言创建、读取、更新、删除用户记录
• 🛡️ 安全参数处理：使用参数化查询来防止SQL注入
• 📝 JSON响应格式：将AI响应结构化为JSON，以实现可靠的解析

先决条件

• Node.js（v18或更高版本）
• MySQL数据库（v5.7或更高版本）
• OpenAI API密钥

安装

1. 克隆存储库

   git clone https://github.com/preetwarraich1990/sql-mcp-agent.git
   cd sql-mcp-agent

1. 安装依赖项

   npm install

1. 创建一个 .env 文件 在项目根目录中：

   DATABASE_URL=mysql://root@localhost:3306/users
   OPENAI_API_KEY=your_openai_api_key_here

1. 设置数据库 （如果尚未创建）：

   CREATE DATABASE users;

   USE users;

   CREATE TABLE User (
     id INT AUTO_INCREMENT PRIMARY KEY,
     email VARCHAR(191) NOT NULL UNIQUE,
     password VARCHAR(191) NOT NULL,
     createdAt DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
     updatedAt DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)
   );

配置

环境变量

数据库连接字符串格式

mysql://[username]:[password]@[host]:[port]/[database]

• 用户名：MySQL用户（默认值： root)
• 密码：MySQL密码（如果没有密码，则可选）
• 主机：数据库主机（默认值： localhost)
• 端口：MySQL端口（默认值： 3306)
• 数据库：数据库名称（默认值： users)

运行应用程序

启动服务器：

node server.js

预期产量：

✅ SQL Agent API running on http://localhost:4000
📝 POST /api/agent - Send SQL queries via AI agent

API使用

端点： POST /api/agent

向AI代理发送自然语言查询。

请求示例：

curl -X POST http://localhost:4000/api/agent \
  -H "Content-Type: application/json" \
  -d '{"message": "Create a user with email john@example.com and password secret123"}'

请求正文：

{
  "message": "your natural language query here"
}

响应示例：

{
  "schema": "Table \"User\": id (int), email (varchar(191)), password (varchar(191)), createdAt (datetime(3)), updatedAt (datetime(3))",
  "aiCommand": {
    "tool": "createUser",
    "parameters": {
      "email": "john@example.com",
      "password": "secret123"
    }
  },
  "toolResult": {
    "success": true,
    "id": 1
  }
}

可用工具

AI代理可以根据您的请求使用以下工具：

1. fetchData

从数据库中检索用户。

查询示例：

• “获取所有用户”
• “显示前5个用户”
• “获取用户记录”

参数：

• limit （可选，数字）：要返回的最大记录数（默认值：10）

2. 创建用户

在数据库中创建新用户。

查询示例：

• “使用电子邮件创建用户test@example.com密码密码123“
• “添加新用户：john@example.com使用密码john123“

参数：

• email （必填，字符串）：用户的电子邮件地址
• password （必填，字符串）：用户密码
• createdAt （可选，字符串）：创建时间戳（ISO格式）
• updatedAt （可选，字符串）：更新时间戳（ISO格式）

3. 更新数据

通过电子邮件更新现有用户的信息。

查询示例：

• “更新密码john@example.com新护照123“
• “更改密码test@example.com秘密456”

参数：

• email （必填，字符串）：用户的电子邮件地址（用于标识要更新的用户）
• password （可选，字符串）：新密码
• createdAt （可选，字符串）：新创建时间戳
• updatedAt （可选，字符串）：新的更新时间戳

4. 通过电子邮件获取用户信息

通过电子邮件地址检索特定用户。

查询示例：

• “获取用户john@example.com"
• “显示带有电子邮件的用户test@example.com"
• “获取用户详细信息admin@example.com"

参数：

• email （必填，字符串）：要检索的用户电子邮件地址

5. 删除数据

从数据库中删除用户。

查询示例：

• “删除用户john@example.com"
• “删除带有电子邮件的用户olduser@example.com"

参数：

• email （必填，字符串）：要删除的用户电子邮件地址

数据库模式

该应用程序与 User 桌子在 users 数据库：

CREATE TABLE User (
  id INT AUTO_INCREMENT PRIMARY KEY,
  email VARCHAR(191) NOT NULL UNIQUE,
  password VARCHAR(191) NOT NULL,
  createdAt DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
  updatedAt DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3)
);

表格列

故障排除

错误：“找不到模块'@modelcontextprotocol/sdk'”

npm install @modelcontextprotocol/sdk

错误：“数据库连接被拒绝”

• 检查MySQL是否正在运行： mysql -u root -p -h localhost
• 验证 DATABASE_URL 在 .env 匹配您的设置
• 确保数据库和表存在

错误：OpenAI的“401未经授权”

• 验证您的 OPENAI_API_KEY 是正确的
• 检查您的API密钥是否可以访问GPT-3.5-turbo模型

错误：“AI响应格式无效”

• AI模型未返回有效的JSON
• 试着更清楚地重新表述你的问题
• 在检查OpenAI API状态https://status.openai.com

AI代理请求表模式

• 确保您的系统提示包含数据库架构
• 验证 getDatabaseSchema() 功能正常工作
• 检查数据库连接和权限

项目结构

sql-mcp-agent/
├── server.js              # Main application file
├── package.json           # Project dependencies
├── .env                   # Environment variables (create this)
└── README.md             # This file

依赖项

• express -Web框架
• cors -跨源资源共享中间件
• mysql2/promise -MySQL数据库驱动程序
• dotenv -环境变量加载器
• openai -OpenAI API客户端
• @modelcontextprotocol/sdk -模型上下文协议

安全考虑

⚠️ 重要安全注意事项：

1. 永不承诺 .env 到版本控制 -添加到 .gitignore
2. 使用环境变量 用于敏感数据（API密钥、数据库凭据）
3. 参数化查询 -该应用程序使用参数化查询来防止SQL注入
4. 输入验证 -所有参数在执行前都已清除
5. 密码存储 -在存储之前考虑哈希密码（不包括在本演示中）

未来的增强功能

• \[\]添加密码哈希（bcrypt）
• \[\]添加身份验证/授权
• \[\]支持更复杂的查询（连接、聚合）
• \[\]API端点的速率限制
• \[\]查询日志和审计跟踪
• \[\]支持多个表/数据库

许可证

麻省理工学院

支持

对于问题或疑问：

1. 检查上面的故障排除部分
2. 查看OpenAI API文档
3. 查看MySQL和Node.js文档
4. 访问

______________________________________________________________________

由以下材料制成❤️ 使用Express、MySQL和OpenAI