MCP Data Lake Agent

MCP数据湖代理

  

使用OpenAI GPT和模型上下文协议（MCP）的人工智能驱动的自然语言数据库查询系统

MCP数据湖代理 是一个智能分析副驾驶，可以将自然语言问题转换为SQL查询，执行它们，并在一个漂亮的web界面中显示结果。不需要SQL知识！

______________________________________________________________________

特性

• 自然语言查询：用简单的英语提问，获取SQL结果
• 多数据库支持：SQLite、PostgreSQL、MySQL、MS SQL Server、MongoDB
• 网络聊天界面：用于交互式分析的干净、深色主题的UI
• MCP服务器：通过模型上下文协议公开数据库工具
• 示例数据库：预加载销售数据以供即时测试
• 实时结果：查看生成的SQL、基本原理和表格数据
• CRUD操作：创建、读取、更新和删除数据库记录

______________________________________________________________________

快速开始

先决条件

• Python 3.8或更高版本
• OpenAI API密钥(在这里买一个)

安装

# 1. Clone the repository
git clone https://github.com/daredevilx616/MCPDataLakeAgent.git
cd MCPDataLakeAgent

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure environment variables
# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env

# Edit .env and add your OpenAI API key:
# OPENAI_API_KEY=sk-your-key-here
# OPENAI_MODEL=gpt-4o-mini

# 4. Launch the web application
python src/web_app.py

# 5. Open your browser to http://localhost:5000

就是这样！ 现在，您可以开始询问有关示例销售数据库的问题。

______________________________________________________________________

使用示例

在web界面中尝试以下示例问题：

Show me all customers
What are the top 5 products by revenue?
How many orders were placed last month?
What is the average order value?
Show me revenue by product category

AI将：

1. 理解你的问题
2. 生成适当的SQL
3. 执行查询
4. 在格式化的表格中显示结果

______________________________________________________________________

项目结构

MCPDataLakeAgent/
├── src/
│   ├── agent_core.py         # AI agent & SQL generation
│   ├── mcp_server.py         # MCP protocol server
│   └── web_app.py            # Flask web application
├── templates/
│   └── index.html            # Web UI
├── data/
│   └── sales.db              # Sample SQLite database
├── .env.example              # Environment template
├── requirements.txt          # Python dependencies
├── mcp.json                  # MCP server configuration
├── connectors.json           # Database connectors
├── README.md                 # This file
├── USER_MANUAL.md            # Detailed documentation
├── TROUBLESHOOTING.md        # Common issues & solutions
├── SUBMISSION.md             # Project overview
└── LICENSE                   # MIT License

______________________________________________________________________

文档

• 用户_手册.md -完整的安装和使用指南
• 故障排除.md -常见问题和解决方案
• 提交.md -项目概况和架构

______________________________________________________________________

高级用法

配置

编辑 .env 自定义：

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o-mini  # Or gpt-4, gpt-3.5-turbo

笔记：

• 代理在第一次调用之前读取模式，并指示模型返回JSON sql 和 rationale
• 结果显示在带有表格和多语句块的聊天气泡中
• 集 OPENAI_MODEL 到 gpt-4 对于更复杂的查询（成本更高）

______________________________________________________________________

运行MCP服务器

与MCP兼容工具集成：

# Start the MCP server
python src/mcp_server.py

服务器默认使用stdio传输，并从中读取数据库路径 mcp.json。配置您的MCP客户端/IDE以使用此工作区。

可用的MCP工具

• describe_schema() -返回用于架构发现的表/列元数据
• run_sql(query) -执行只读SELECT/CTE语句
• create_table(schema_sql) -运行DDL语句以创建新表
• insert_row(table, values) -插入一行作为JSON对象
• update_rows(table, updates, where_clause, params) -使用WHERE筛选器更新行
• delete_rows(table, where_clause, params) -使用WHERE筛选器删除行

______________________________________________________________________

web界面

打开 http://127.0.0.1:5000 一旦Flask开始运行。界面包括：

• 导航轨道：切换数据库连接器面板
• 连接器面板：多数据库配置表单

- SQLite、PostgreSQL、MySQL、MS SQL Server、MongoDB - 活动数据库选择器

• 聊天工作区：交互式查询界面

- 自然语言输入 - 生成的SQL显示 - 基本原理解释 - 带有行数的表格结果

连接器更改已保存到 connectors.json 并同步到 mcp.json 自动。

______________________________________________________________________

示例数据库

包括 data/sales.db 包含：

桌子：

• customers -客户信息
• products -产品目录
• orders -订单记录
• payments -付款交易

此示例数据允许立即进行测试，而无需额外的数据库设置。

______________________________________________________________________

技术栈

• Python 3.8+：核心编程语言
• 烧瓶：Web框架
• OpenAI API：用于NL到SQL转换的GPT模型
• 主控程序：用于AI工具集成的模型上下文协议
• SQLite：嵌入式数据库（支持多数据库）

______________________________________________________________________

将OpenAI代理连接到MCP服务器

配置OpenAI模型代理（具有MCP支持的助理API或响应API）并通过 mcp.json 在您的IDE/工具中，以便代理可以调用 analytics-sqlite.

在运行时，AI代理可以：

1. 呼叫 describe_schema 查找可用表格
2. 通过LLM规划SQL
3. 将SQL发送到 run_sql 获取实时结果
4. 用理由和数据回答用户

这允许在部署到生产环境或添加其他MCP工具之前进行本地迭代。

______________________________________________________________________

故障排除

常见问题和解决方案：

• “未设置OPENAI_API_KEY”：确保 .env 文件存在并且包含有效的API密钥
• “端口5000已在使用中”：停止其他服务或更改端口 web_app.py
• “找不到模块”：运行 pip install -r requirements.txt
• 数据库错误：验证 data/sales.db 存在且路径正确

有关详细的故障排除，请参阅 故障排除.md

______________________________________________________________________

贡献

欢迎投稿！请随时提交问题或拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

______________________________________________________________________

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

致谢

• 开放人工智能 用于GPT API
• Anthropic 用于模型上下文协议
• 烧瓶 优秀文档社区

______________________________________________________________________

支持

• GitHub: https://github.com/daredevilx616/MCPDataLakeAgent
• 问题: https://github.com/daredevilx616/MCPDataLakeAgent/issues
• 文档：参见 用户_手册.md

______________________________________________________________________

内置于❤️ 用于数据分析和人工智能集成