Bigquery MCP SQL Generator

BigQuery MCP SQL生成器

该项目使用Google ADK和FastMCP为Google BigQuery实现了一个模型上下文协议（MCP）服务器。它提供了一个智能的AI驱动系统，可以将自然语言查询转换为BigQuery数据集的SQL命令，使非技术用户能够在不编写SQL的情况下分析数据。

目录

• 概述
• 建筑
• 组件
• 先决条件
• 设置
• 认证
• 环境变量
• 用法

- 启动MCP服务器 - 运行SQL代理 - 启动Streamlit用户界面 - 启动所有组件

• 测试
• 提供的工具
• 安全
• 发展

概述

BigQuery MCP SQL Generator是一个人工智能驱动的应用程序，它将自然语言处理与BigQuery数据分析连接起来。用户可以用简单的英语询问有关其数据的问题，系统会自动生成并执行适当的SQL查询以检索相关信息。

主要特征包括：

• 使用谷歌的Gemini LLM或OpenAI的GPT模型进行自然语言到SQL的翻译
• 安全访问BigQuery数据集
• 通过web界面进行实时数据分析
• 模块化架构，关注点明确分离
• 全面的可靠性测试套件
• 使用规划代理增强推理能力

建筑

该应用程序遵循四层微服务架构：

graph TD
    A[Streamlit UI]  B(Planning Agent)
    B  C[SQL Agent]
    C  D[(Google Cloud BigQuery)]
    C  E[MCP Server]
    E  D
    F[LLM Provider] -.-> C
    G[LLM Provider] -.-> B

    style A fill:#FFE4B5,stroke:#333
    style B fill:#98FB98,stroke:#333
    style C fill:#87CEEB,stroke:#333
    style E fill:#FFB6C1,stroke:#333
    style D fill:#DDA0DD,stroke:#333
    style F fill:#DDA0DD,stroke:#333,stroke-dasharray: 5 5
    style G fill:#DDA0DD,stroke:#333,stroke-dasharray: 5 5

    linkStyle 0 stroke:#6495ED,stroke-width:2px
    linkStyle 1 stroke:#6495ED,stroke-width:2px
    linkStyle 2 stroke:#32CD32,stroke-width:2px
    linkStyle 3 stroke:#FFA500,stroke-width:2px
    linkStyle 4 stroke:#FFA500,stroke-width:2px
    linkStyle 5 stroke:#9370DB,stroke-width:2px,stroke-dasharray: 5 5
    linkStyle 6 stroke:#9370DB,stroke-width:2px,stroke-dasharray: 5 5

1. 流线型UI：用于自然语言交互的Web界面
2. 规划代理：编排SQL代理并添加智能推理
3. SQL代理 (src/adk_agent.py)：通过MCP服务器生成并执行SQL查询
4. MCP服务器：FastMCP服务器，提供对BigQuery数据集的直接访问并执行SQL查询
5. 谷歌云BigQuery：数据存储和分析平台
6. LLM提供者：可以是基于配置的Google Gemini或OpenAI GPT模型

数据流

简单查询流

1. 用户在Streamlit UI中输入一个简单的查询（例如，“我有哪些数据集？”）
2. Streamlit UI将查询发送给规划代理
3. 规划代理将其标识为简单查询
4. 规划代理将查询直接路由到SQL代理
5. SQL代理通过MCP服务器生成并执行相应的SQL查询
6. SQL代理将结果返回给计划代理
7. 规划代理将结果转发回Streamlit UI
8. Streamlit UI向用户显示结果

复杂查询流

1. 用户在Streamlit UI中输入一个复杂的查询（例如，“分析我的数据中的扇区分布”）
2. Streamlit UI将查询发送给规划代理
3. 规划代理将其识别为需要推理的复杂查询
4. 计划代理将查询发送给SQL代理
5. SQL代理通过MCP服务器生成并执行相应的SQL查询
6. SQL代理将原始数据返回给计划代理
7. 规划代理通过额外的推理和分析来增强结果
8. Planning Agent将增强的结果返回到Streamlit UI
9. 流线型UI向用户显示增强的结果

查询复杂性检测

Planning Agent使用基于关键字的检测来确定查询复杂性：

• 简单查询：基本信息请求（“内容”、“列表”、“显示”）
• 复杂查询：对分析、比较、趋势、模式、见解的请求

组件

1.MCP服务器(src/mcp_server.py)

模型上下文协议服务器使用FastMCP构建，并提供对BigQuery数据集的直接访问。它公开了几个工具：

• list_dataset_ids：列出项目中的所有BigQuery数据集
• get_dataset_info：获取特定数据集的元数据
• list_table_ids：列出数据集中的所有表
• get_table_info：获取特定表的元数据
• execute_sql：对BigQuery执行SQL查询

服务器使用HTTP流协议和服务器发送事件（SSE）进行实时通信。

2.SQL代理(src/adk_agent.py)

SQL代理纯粹专注于生成和执行SQL查询。它

• 接收规划代理的结构化请求
• 使用LLM（谷歌的Gemini或OpenAI的GPT）生成适当的SQL查询
• 根据请求决定使用哪些MCP工具
• 格式化并执行工具调用
• 处理结果并生成结构化响应

3.规划代理(src/planning_agent.py)

规划代理协调SQL代理并添加智能推理：

• 分析用户查询以确定复杂性
• 将简单查询直接路由到SQL代理
• 通过额外的推理和分析增强复杂的查询
• 将SQL结果与业务见解相结合
• 提供更复杂的用户体验

4.流线型用户界面(src/streamlit_ui.py)

使用Streamlit构建的基于web的用户界面，允许用户：

• 输入有关其数据的自然语言查询
• 查看对话历史记录
• 查看规划代理的格式化结果和增强分析

5.配置(src/config.py)

集中式配置管理，加载所有环境变量并将其提供给所有组件。

6.法学硕士经理(src/llm_manager.py)

支持Google Gemini和OpenAI模型的不同LLM提供商的统一接口。

7.主要应用(src/main.py)

应用程序的入口点，可以启动单个组件或整个系统。

先决条件

• Python 3.8+
• 启用BigQuery API的Google云项目
• 具有BigQuery权限的服务帐户（用于生产）

设置

1. 创建虚拟环境：

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

1. 安装依赖项：

   pip install -r requirements.txt

1. 配置环境变量：

复制示例配置文件并根据您的环境进行自定义：

   cp .env.example .env

然后编辑 .env 文件来设置您的特定配置值：

- 设置您的Google Cloud项目ID - 设置BigQuery数据集和表名 - 为LLM功能设置API密钥（Google或OpenAI） - 根据需要配置其他设置

认证

BigQuery MCP服务器支持多种身份验证方法：

1. 服务帐户密钥文件 （推荐用于生产）：

- 在Google Cloud Console中创建服务帐户 - 下载JSON密钥文件 - 集 GOOGLE_APPLICATION_CREDENTIALS 在 .env 到密钥文件的路径

1. 应用程序默认凭据 （用于开发）：

- 安装并初始化Google Cloud SDK - 跑 gcloud auth application-default login

1. 工作负载身份联合 （对于GCP环境）：

- 在Google Cloud中配置工作负载身份联合

环境变量

可以在中配置以下环境变量 .env 文件：

• PROJECT_ID：您的谷歌云项目ID（默认值：vertical-hook-453217-j9）
• DATASET_ID：您的BigQuery数据集名称（默认：IndianAPI）
• TABLE_ID：您的BigQuery表名（默认：IndianAPI）
• GOOGLE_APPLICATION_CREDENTIALS：服务帐户密钥文件的路径（可选）
• REGION：谷歌云区域（默认值：us-central1）
• MCP_HOST：MCP服务器主机（默认：localhost）
• MCP_PORT：MCP服务器端口（默认值：8000）
• MCP_DEBUG：启用调试模式（默认值：False）
• ADK_MODEL：ADK代理模型（默认：gemini-2.5-flash）
• ADK_AGENT_NAME：ADK代理名称（默认：bigquery_analytics_agent）
• STREAMLIT_HOST：Streamlit UI主机（默认：localhost）
• STREAMLIT_PORT：流线型UI端口（默认值：8501）
• LLM_PROVIDER：要使用的LLM提供程序（“gemini”或“openai”，默认值：gemini）
• GOOGLE_API_KEY：Gemini LLM功能的Google API密钥（如果使用Gemini，则需要）
• OPENAI_API_KEY：GPT模型的OpenAI API密钥（如果使用OpenAI，则需要）
• OPENAI_MODEL：要使用的OpenAI模型（默认值：gpt-4-turbo）

用法

启动MCP服务器

启动MCP服务器：

python src/main.py server

服务器将在上启动并侦听HTTP连接 http://localhost:8000.

运行SQL代理

运行连接到MCP服务器的SQL代理：

python src/adk_agent.py "Your question here"

备注：要获得完整的LLM功能，请在中配置API密钥 .env 文件。 如果没有此密钥，代理将仅支持基本功能。在配置了API密钥的情况下， LLM将自动确定使用哪些工具并生成适当的SQL查询 基于你的自然语言问题。

启动Streamlit用户界面

启动Streamlit UI进行自然语言交互：

python src/main.py ui

用户界面将在 http://localhost:8501.

启动所有组件

要一次启动所有组件，请使用启动脚本：

./start_system.sh

这将在后台启动MCP服务器，在前台启动Streamlit UI。

注意：您也可以单独启动组件：

python src/main.py server  # Start MCP server
python src/main.py ui      # Start Streamlit UI

Docker部署

MCP服务器可以部署为Docker容器，以便于部署和扩展。

Docker文件

所有与Docker相关的文件都位于\目录：

• docker/Dockerfile.mcp：MCP服务器的Dockerfile
• docker/docker-compose.mcp.yml：Docker编写文件，便于部署
• docker/start_mcp_docker.sh：用于构建和运行容器的Shell脚本
• docker/DOCKER_INSTRUCTIONS.md：详细的部署说明

构建Docker镜像

cd docker
docker build -f Dockerfile.mcp -t bigquery-mcp-server .

使用Docker运行

cd docker
docker run -p 8000:8000 \
  -e PROJECT_ID=your-project-id \
  -e DATASET_ID=your-dataset-id \
  -e TABLE_ID=your-table-id \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials.json \
  -v /path/to/your/credentials.json:/app/credentials.json:ro \
  bigquery-mcp-server

使用Docker Compose运行

cd docker
docker-compose -f docker-compose.mcp.yml up

看 docker/DOCKER_INSTRUCTIONS.md 了解详细的部署说明。

测试

该项目包括在 tests/ 目录：

1. 单元测试 (tests/test_mcp.py)：单独测试所有组件

- 进口验证 - 环境变量验证 - BigQuery客户端初始化 - MCP工具定义 - 错误处理 - FastMCP集成

1. 集成测试 (tests/integration_test.py)：测试实际的BigQuery操作

- 数据集列表 - 数据集信息检索 - 表格列表 - SQL查询执行 - MCP工具验证

1. 演示脚本 (tests/demo_mcp.py)：演示具有详细输出的功能

- 完整的工作流程演示 - 详细方法输出 - 工具验证

1. HTTP测试 (tests/test_mcp_http.py)：测试基于HTTP的MCP服务器

- 服务器连接 - 工具可用性

运行所有测试：

python tests/run_all_tests.py

运行单独的测试套件：

python tests/test_mcp.py
python tests/integration_test.py
python tests/demo_mcp.py
python tests/test_mcp_http.py

提供的工具

MCP服务器公开了以下工具：

1. list_dataset_ids：列出项目中的所有BigQuery数据集
2. get_dataset_info：获取特定数据集的元数据
3. list_table_ids：列出数据集中的所有表
4. get_table_info：获取特定表的元数据
5. execute_sql：对BigQuery执行SQL查询

与ADK代理集成

要将此MCP服务器与Google ADK代理一起使用：

1. 在一个终端中启动MCP服务器
2. 在ADK代理中，将MCPToolset添加到代理的工具中：

from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import SseConnectionParams

# Add to your agent's tools
MCPToolset(
    connection_params=SseConnectionParams(
        url='http://localhost:8000'
    )
)

安全

该项目实施了多项安全措施来保护敏感信息：

1. 环境变量：所有敏感配置都存储在环境变量中，而不是硬编码
2. Git忽略：敏感文件，如 .env Python缓存文件被排除在版本控制之外
3. API密钥保护：API密钥仅在本地使用，从不提交到存储库
4. 凭证管理：服务帐户密钥通过文件路径引用，不存储在代码库中

重要：切勿提交以下敏感文件 .env 包含用于版本控制的API密钥或凭证。始终使用 .env.example 模板代替。

发展

要修改服务器，请执行以下操作：

1. 编辑文件 src/ 添加新工具或修改现有工具的目录
2. 运行测试： python tests/run_all_tests.py
3. 启动服务器： python src/main.py server