AI导哈

自然语言数据库交互客户端

一个自定义MCP客户端，通过OpenAI的LLM技术实现自然语言与数据库的交互，支持多种数据库类型并提供智能SQL生成功能。

  • by Captain-Price-1
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Captain-Price-1/MCP-Test

使用说明

具有OpenAI集成的自定义MCP客户端

一个自定义的MCP（模型上下文协议）客户端，连接到ExecuteAutomation MCP数据库服务器，并使用OpenAI的LLM进行自然语言数据库交互。

🚀 特性

  • 自然语言查询：用简单的英语问有关数据库的问题
  • 语义理解：智能地解释分析问题（例如，“什么是安静时间？”生成GROUP BY查询，而不是文字列选择）
  • 多数据库支持：适用于SQLite、MySQL、PostgreSQL和SQL Server
  • 智能SQL生成：使用聚合、GROUP BY、ORDER BY等生成复杂的分析查询。
  • OpenAI集成：使用GPT-4进行自然语言到SQL的转换
  • 交互式CLI：易于使用的命令行界面
  • 架构自动发现：自动加载数据库架构以生成准确的查询

📋 先决条件

  • Node.js（v18或更高版本）
  • OpenAI API密钥
  • 内置mcp数据库服务器（ExecuteAutomation）
  • 数据库连接（MySQL、PostgreSQL、SQLite或SQL Server）

🔧 安装

# Clone the repository
git clone https://github.com/Captain-Price-1/MCP-Test.git
cd MCP-Test

# Install dependencies
npm install

# Copy environment configuration
cp env.example .env

# Edit .env with your settings
nano .env

⚙️ 配置

编辑 .env 使用您的设置文件：

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini

# MCP Server Path
MCP_SERVER_PATH=../dist/src/index.js

# Database Configuration (MySQL example)
DATABASE_TYPE=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=your_database
DATABASE_USER=your_username
DATABASE_PASSWORD=your_password

🎯 用法

交互模式

npm start

然后问自然语言问题：

  • “预订区的安静时间是什么时候？”
  • “谁是顶级用户？”
  • “显示所有桌子”
  • “上个月下了多少订单？”
  • “查找订单超过5个的客户”

运行测试

# Test semantic query understanding
node test-semantic.js

# Test database connection
node test-connection.js

# Run diagnostic tests
node diagnose-reservations.js

运行示例

node examples/example-usage.js

💡 运作原理

  1. 你问了一个问题 自然语言
  2. OpenAI分析 意图和数据库模式
  3. 生成分析SQL （使用GROUP BY、聚合等）
  4. MCP客户端执行 通过mcp数据库服务器进行查询
  5. 结果已格式化 并向你解释

🎨 查询示例

分析查询

  • “什么是安静的时光？” → 生成： SELECT HOUR(time_column), COUNT(*) FROM table GROUP BY hour ORDER BY COUNT ASC
  • “谁是最大的客户？” → 生成： SELECT customer, COUNT(*) FROM orders GROUP BY customer ORDER BY COUNT DESC LIMIT 10
  • “趋势是什么？” → 使用基于时间的聚合生成查询

直接查询

  • “显示所有用户”
  • “产品表中有多少条记录？”
  • “插入一个名为John Doe的新用户”
  • “将用户表导出到CSV”

📁 项目结构

custom-mcp-client/
├── src/
│   ├── index.js              # Main application entry point
│   ├── mcpClient.js          # MCP client implementation (STDIO transport)
│   ├── openaiService.js      # OpenAI integration with semantic understanding
│   ├── databaseService.js    # High-level database operations wrapper
│   └── test.js               # Test suite
├── examples/
│   └── example-usage.js      # Usage examples
├── package.json              # Dependencies
├── .env.example             # Environment variables template
└── README.md                 # This file

🔑 主要特点

语义查询理解

客户理解 意图 在问题背后，不仅仅是字面上的关键字：

❌ 不良（字面）：“安静的时光”→ SELECT quiet_time FROM table ✅ 良好（语义）：“安静的时光”→ SELECT HOUR(time), COUNT(*) FROM table GROUP BY hour ORDER BY count ASC

智能模式加载

  • 自动发现数据库表和列
  • 为OpenAI提供有关数据类型和关系的上下文
  • 如果模式工具失败，则返回采样数据

多数据库支持

  • SQLite：基于文件的数据库
  • MySQL：包括Laravel应用程序
  • PostgreSQL：支持SSL
  • SQL Server：Windows/Linux兼容

🛠️ 使用的技术

  • Node.js -运行时环境
  • OpenAI API -自然语言处理
  • MCP-SDK -模型上下文协议实现
  • STDIO传输 -基于流程的沟通

📊 用例

  1. Laravel应用程序：连接到Laravel数据库并用自然语言查询
  2. 数据分析：询问有关数据的分析问题
  3. 商业智能：生成报告和见解
  4. 数据库探索：发现表、关系和模式
  5. 快速查询：无需编写SQL即可获取答案

🔒 安全

  • 通过查询验证进行SQL注入保护
  • 敏感数据的环境变量配置
  • 只读模式可用于安全查询
  • 执行前的查询验证

🐛 故障排除

“服务器未连接”

  • 检查mcp数据库服务器是否已构建
  • 验证.env中的MCP_SERVER_PATH

“OpenAI API错误”

  • 验证OPENAI_API_KEY是否正确
  • 检查API密钥权限和计费

“数据库连接失败”

  • 验证数据库是否正在运行
  • 检查连接参数
  • 确保数据库存在且可访问

📝 许可证

MIT许可证

🤝 贡献

欢迎投稿！请打开问题或提交拉取请求。

🙏 致谢

📧 联系

如有疑问或支持，请在GitHub上发布问题。

由以下材料制成❤️ 对于MCP社区

相关 MCP