🧠 SQL MCP客户端
基于React的AI代理客户端，利用 模型上下文协议（MCP） 通过自然语言查询与SQL数据库交互。该应用程序通过使用基于Node.js的智能AI代理将自然语言请求转换为SQL命令，弥合了用户和数据库之间的差距。
📋 项目概述
SQL MCP客户端 是一个前端应用程序，它：
- 接受自然语言查询 -用户用简单的英语（或其他语言）键入问题
- 与AI代理通信 -由MCP（模型上下文协议）支持的Node.js后端
- 执行SQL查询 -AI代理将自然语言转换为SQL
- 与SQL数据库交互 -使用MCP工具在数据库上安全执行查询
- 返回格式化结果 -以用户友好的JSON格式显示结果
建筑
┌─────────────────────────────────────────────────────────────┐
│ React Frontend (This App) │
│ 🧠 SQL MCP Agent User Interface │
└──────────────────────┬──────────────────────────────────────┘
│
HTTP/REST API
localhost:4000
│
┌──────────────────────▼──────────────────────────────────────┐
│ Node.js AI Agent Backend │
│ (MCP - Model Context Protocol) │
│ │
│ - Receives natural language query │
│ - Processes with AI/LLM │
│ - Uses MCP Tools to interact with database │
│ - Returns structured results │
└──────────────────────┬──────────────────────────────────────┘
│
MCP Tools
│
┌──────────────────────▼──────────────────────────────────────┐
│ SQL Database │
│ (PostgreSQL, MySQL, SQLite, etc.) │
│ │
│ - Tables, Indexes, Constraints │
│ - Data Storage and Retrieval │
│ - Query Execution │
└─────────────────────────────────────────────────────────────┘✨ 主要特点
用户界面
- ✅ 自然语言输入 -用简明英语键入查询
- ✅ 实时反馈 -处理过程中出现“正在发送…”指示器
- ✅ 键盘快捷键 -媒体
Ctrl+Enter（或Cmd+Enter在Mac上）发送查询 - ✅ 格式化结果 -JSON格式的响应，语法突出显示
- ✅ 错误处理 -清除调试错误消息
- ✅ 无障碍设计 -WCAG 2.1 AA符合ARIA标签
后端集成
- ✅ MCP协议 -AI代理通信的模型上下文协议
- ✅ AI驱动 -利用语言模型来理解自然语言
- ✅ 安全SQL执行 -MCP工具确保数据库交互的安全
- ✅ 灵活的数据库支持 -适用于各种SQL数据库
- ✅ 结构化响应 -返回机器可读的查询结果
🚀 快速开始
先决条件
- Node.js 14+和npm 6+
- 后端MCP代理 运行于
http://localhost:4000 - 数据库 MCP代理已配置并可访问
安装
# Clone the repository
git clone
cd sql-mcp-client
# Install dependencies
npm install发展
# Start the React development server
npm start应用程序将在以下时间打开 http://localhost:3000.
使用应用程序
- 键入自然语言查询 在文本区域中：
Show me the top 5 users by registration date
Get all orders from the last month
List products with inventory below 10 units- 发送查询 通过：
- 点击“发送”按钮，或 - 按压 Ctrl+Enter （Windows/Linux）或 Cmd+Enter （Mac）
- 查看结果 -带有查询结果和元数据的API响应显示在下面
- 查看错误消息 -如果出现问题，您将收到一条明确的错误消息
📊 运作原理
请求流
User Input (Natural Language)
↓
┌─────┐
│ App │ (React Component)
└──┬──┘
│ sends POST request
↓
API Endpoint: /api/agent
Payload: { message: "user query" }
↓
┌──────────────┐
│ MCP Agent │ (Node.js Backend)
│ │
│ 1. Parse NL │
│ 2. Call LLM │
│ 3. Generate │
│ SQL │
└──┬───────────┘
│
↓
┌─────────────────────┐
│ MCP Tools │
│ │
│ - ExecuteSQL tool │
│ - QuerySchema tool │
│ - DescribeTable tool│
└──┬─────────────────┘
│
↓
┌──────────────┐
│ SQL Database │
└──┬───────────┘
│
↓
Query Results
↓
Response JSON
↓
Display in App交互示例
用户输入：
Show me the top 5 most active users后端流程：
- MCP代理接收查询
- AI模型解释：“最活跃”=按活动指标排序
- 生成SQL：
SELECT * FROM users ORDER BY activity_count DESC LIMIT 5 - MCP工具执行查询
- 数据库返回结果
用户输出：
{
"query": "SELECT * FROM users ORDER BY activity_count DESC LIMIT 5",
"results": [
{ "id": 1, "name": "Alice", "activity_count": 450 },
{ "id": 2, "name": "Bob", "activity_count": 389 },
...
]
}🧪 测试
运行测试
# Run all tests in watch mode
npm test
# Run tests once and exit
npm test -- --no-watch
# Run tests with coverage report
npm test -- --coverage测试覆盖率
- ✅ 42个单元和集成测试
- ✅ 100%组件覆盖率
- ✅ API交互测试
- ✅ 错误处理测试
- ✅ 可访问性测试
🏗️ 项目结构
sql-mcp-client/
├── public/ # Static files
│ ├── index.html # HTML entry point
│ └── favicon.ico
├── src/ # Source code
│ ├── App.js # Main React component
│ ├── App.css # Component styles
│ ├── App.test.js # Component tests
│ ├── App.integration.test.js # Integration tests
│ ├── index.js # React DOM entry
│ ├── reportWebVitals.js # Performance metrics
│ ├── setupTests.js # Test configuration
│ └── testUtils.js # Testing utilities
├── package.json # Dependencies and scripts
└── README.md # This file🔧 可用脚本
npm start
在开发模式下运行应用程序 http://localhost:3000. 当您进行更改时，页面会重新加载。
npm test
在交互式观察模式下启动测试运行器。 按 a 运行所有测试，或 q 退出。
npm run build
在 build 文件夹。 为了获得最佳性能，对构建进行了缩减和优化。
npm run eject
警告：这是不可逆转的！ 从Create React App弹出以访问配置文件。
🌐 API端点
该应用程序与MCP代理后端通信：
端点： POST http://localhost:4000/api/agent
请求格式：
{
"message": "natural language query here"
}响应格式：
{
"query": "Generated SQL query",
"results": [ { /* data */ } ],
"metadata": { /* optional */ }
}🔐 安全考虑
- SQL注入防护 -MCP代理应验证并参数化所有查询
- 认证 -为生产环境实施API身份验证
- 速率限制 -考虑增加费率限制以防止滥用
- 查询验证 -MCP代理应在执行前验证生成的SQL
- 数据库权限 -确保数据库用户具有适当的权限
🎨 定制
更改API终结点
编辑 src/App.js 并更新 API_BASE_URL:
const API_BASE_URL = 'http://your-api-host:port/api/agent';修改文本区域占位符
编辑 src/App.js 并更新 TEXTAREA_PLACEHOLDER:
const TEXTAREA_PLACEHOLDER = 'Your custom prompt text';调整文本区域大小
编辑 src/App.js 并更新 TEXTAREA_ROWS:
const TEXTAREA_ROWS = 6; // Default is 4📚 文档
有关详细的文档和优化细节，请参阅：
- 代码_样式_用户名.md -开发标准
- 代码_IMPROVEMENTS.md -代码增强
- 测试_验证_报告.md -测试文件
- INDEX.md -完整项目索引
🛠️ 依赖项
核心依赖关系
- 反应 （19.2.0）-用户界面框架
- 反应dom （19.2.0）-React渲染
- 轴 （1.13.2）-HTTP客户端
- 反应脚本 （5.0.1）-构建脚本
开发依赖关系
- @测试库/react （16.3.0）-React测试工具
- @测试库/jest-dom -DOM匹配器
- 玩笑 -测试框架
🚀 部署
生产建设
npm run build这在 build/ 文件夹。
部署步骤
- 确保MCP代理后端正在运行且可访问
- 更新
API_BASE_URL如果部署到其他服务器 - 构建生产版本：
npm run build - 部署
build/文件夹到您的托管服务 - 如果前端和后端位于不同的源上，则配置CORS
🐛 故障排除
无法连接到API
- 验证MCP代理后端是否正在运行
http://localhost:4000 - 检查CORS配置
- 在中确保API终结点正确
App.js
查询未返回结果
- 检查来自MCP代理的数据库连接
- 验证生成的SQL语法
- 查看后端日志是否有错误
测试失败
# Clear cache and reinstall dependencies
rm -rf node_modules package-lock.json
npm install
npm test📖 了解更多
📄 许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
🤝 贡献
欢迎投稿！请遵循代码样式指南，并确保在提交pull请求之前通过所有测试。
📞 支持
有关问题、疑问或建议，请：
______________________________________________________________________
最后更新时间： 2025年11月 状态： ✅ 生产就绪