AI导哈

自然语言数据库查询工具

一个利用Gemini LLM和Model Context Protocol (MCP)进行自然语言数据库查询和探索的应用程序。

  • by RamachandraMurthy
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 RamachandraMurthy/test-dynamic-sql

使用说明

聊天数据应用程序

一个强大的自然语言界面，用于使用Gemini LLM和模型上下文协议（MCP）查询和探索数据库。

文档

概述

此应用程序允许用户使用自然语言与数据库进行交互。它利用谷歌的Gemini模型，通过自定义MCP服务器生成标准文本到SQL和高级工具调用。

两种聊天模式

UI并排展示了两种不同的聊天体验，因此您可以比较有和没有MCP层的相同NLP到SQL功能：

侧栏项目 它演示了什么 端点
聊天 直接NLP→ SQL → data.您的问题直接转到Gemini，它生成一个SQLite查询，后端对该查询运行 employees 和 departments 桌子。没有MCP，没有工具，没有聊天记录。 POST /query
MCP聊天 双重用途助理。Gemini根据每条消息决定问题是一般聊天（直接回答）还是数据库问题（通过MCP服务器发布的工具路由）。MCP服务器拥有SQL生成；LLM从不直接接触数据库。对话上下文得以保留，因此后续工作得以进行。后端可能会运行 几种型号↔刀具轮 在一个请求（上限）中，直到模型生成文本答案——当模型链接工具或在看到结果后需要再次传递时非常有用。 POST /mcp-chat

MCP聊天中的响应徽章显示 direct 当没有调用工具时 mcp_tool 当至少一个MCP工具被调用时。机器人消息以 小型HTML安全标记子集 （粗体、斜体、内联代码、列表、段落）。用以下方法清除卡住或嘈杂的线 DELETE /mcp-chat/session/{session_id}.

特性

  • 自然语言查询问“谁在工程部门工作？”或“给我看看前三名的薪水”之类的问题，并获得实时SQL结果。
  • MCP集成：用途 FastMCP 3.x 随着 可流式传输HTTP （默认服务器URL http://127.0.0.1:8001/mcp).数据库工具(query_database, get_database_schema, get_table_raw_data)暴露于LLM Pydantic类型的输出 因此discovery返回一个清晰的JSON合约。工具在启动时从以下位置聚合 MCP_SERVER_REGISTRY 在 backend/main.py；添加另一个基本URL以注册更多服务器。
  • 架构资源管理器：动态查看数据库结构和表定义。
  • 原始数据查看器：直接从UI检查表的内容。
  • 自愈数据库：SQLite数据库(backend/chat_data.db)在应用程序启动时自动初始化和播种。

技术栈

  • 前端：普通JavaScript、HTML5、CSS3
  • 后端：FastAPI（Python）
  • AI/LLM：谷歌双子座(gemini-flash-latest)
  • 主控程序：Python版FastMCP 3.x（可流式传输） 超文本传输协议 运输；MCP端点路径 /mcp)
  • 数据库：SQLite

入门指南

先决条件

设置

  1. 克隆仓库:

    git clone <repository-url>
cd test-dynamic-sql

  2. 安装依赖项:

    pip install -r requirements.txt

  3. 配置环境变量: 创建 .env 根目录中使用Gemini API密钥的文件：

    GEMINI_API_KEY=your_api_key_here

运行应用程序

该项目包括方便的PowerShell脚本来管理服务器：

开始：

.\start_server.ps1

停止：

.\stop_server.ps1

启动脚本将：

  1. 启动 MCP服务器 在端口上 8001 （可流式传输的HTTP MCP端点 http://127.0.0.1:8001/mcp --在中注册的URL MCP_SERVER_REGISTRY 用于工具发现）
  2. 等待 直到端口8001接受连接，这样FastAPI的启动工具发现就不会与MCP进程竞争
  3. 启动 API主服务器 （FastAPI+静态前端）打开 http://127.0.0.1:8000 通过 uvicorn

打开浏览器 http://127.0.0.1:8000 开始使用该应用程序。

项目结构

  • backend/：核心逻辑
    • main.py：FastAPI应用程序和LLM编排
    • mcp_server.py：FastMCP服务器实施
    • database.py：SQLite数据库管理和种子
    • llm_service.py：直接SQL生成服务
  • frontend/：UI文件
    • index.html, style.css, app.js
  • start_server.ps1：服务器启动的自动化脚本
  • stop_server.ps1：服务器关闭的自动化脚本
  • requirements.txt：Python依赖关系

相关 MCP