客户端MCP - 配备MCP工具访问权限的OpenAI代理
一个基于Python的项目，利用UV（可能是指某种工具或框架，但在此上下文中未明确说明，故保留原样）为OpenAI代理提供访问BigQuery的权限 通过在Google Cloud Run上运行的IAM（身份和访问管理）保护的MCP（模型上下文协议）工具 认证。
建筑学
┌─────────────────┐
│ OpenAI Agent │
│ (GPT-4) │
└────────┬────────┘
│
│ Function Calling
│
┌────────▼────────┐
│ MCP Client │
│ (auth + HTTP) │
└────────┬────────┘
│
│ IAM Auth + HTTPS
│
┌────────▼────────────────────────────────────────┐
│ Cloud Run MCP Service │
│ https://bigquery-mcp-prod-729200795925... │
│ │
│ ┌──────────────┐ │
│ │ BigQuery MCP │ │
│ │ Tools │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────┘特点/特性
- 🤖 表示机器人。 OpenAI智能体使用GPT-4结合函数调用实现任务自动化
- 🔐 IAM 认证通过自动令牌安全访问Cloud Run
刷新
- 🛠️（工具或螺丝刀的符号，常用于表示需要工具或维修） MCP集成自动工具发现与执行
- 🐳 表示“海豚”或“海豚脸”。在中文网络语境中，这个表情符号常被用来表达可爱、俏皮或者特定的情绪，类似于“哈哈”或“噗嗤”这样的笑声表情，但带有海豚的元素，给人一种活泼、友善的感觉。所以，简单来说，🐳 就是“海豚”或“海豚脸”的意思，用来传达一种轻松愉快的氛围。 Docker 支持完成Docker Compose设置，以便轻松部署
- 🔄 旋转（或循环） 令牌管理在令牌过期前自动刷新
- 📝（记录/笔记） 多种认证方法支持ADC（应用交付控制器）、服务账户密钥和工作负载
身份
先决条件
- Python 3.11及以上版本
- UV（紫外线）快速Python包安装器
(安装)
- Docker & Docker Compose （用于容器化部署）
- Google Cloud SDK（Google 云软件开发工具包） （用于认证）
- OpenAI API密钥
设置
1. 克隆并安装依赖项
# Navigate to project directory
cd client-mcp
# Install dependencies using UV
uv sync2. 设置Google Cloud身份验证
选项A：使用应用程序默认凭据（ADC）——推荐
# Authenticate with Google Cloud
gcloud auth application-default login
# Verify authentication
gcloud auth application-default print-access-token选项B：服务账户密钥文件
- 在GCP控制台中创建一个服务帐号
- 授予它
Cloud Run Invoker角色 - 下载JSON密钥文件
- 设置环境变量：
export SERVICE_ACCOUNT_KEY_PATH=/path/to/key.json选项C：工作负载身份（适用于GKE/Cloud Run）
参见其中的注释示例 src/auth_handler.py 请参阅详细的设置说明。
3. 设置OpenAI API密钥
# Create .env file
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env运行应用程序
本地开发（含UV）
# Activate virtual environment
source .venv/bin/activate
# Run the application
python src/main.py
# Or with a custom task
python src/main.py "Show me the schema of the users table"Docker Compose（推荐）
# Build and run
docker compose up
# Run in detached mode
docker compose up -d
# View logs
docker compose logs -f
# Stop
docker compose down带有自定义任务的 Docker Compose
编辑 docker-compose.yml 并修改命令：
command: python src/main.py "Your custom task here"使用示例
示例1：列出可用数据集
# In main.py, set task_description to:
"List all available BigQuery datasets and tables"示例2：查询数据
"Query the sales data for the last 30 days and provide a summary"示例3：模式检查
"Show me the schema of the users table in the analytics dataset"示例4：复分析
"Analyze the top 10 products by revenue in Q4 and create a summary report with insights"项目结构
client-mcp/
├── pyproject.toml # UV project configuration
├── docker-compose.yml # Docker Compose configuration
├── Dockerfile # Container image definition
├── .env # Environment variables (create this)
├── .gitignore # Git ignore patterns
├── .dockerignore # Docker ignore patterns
├── README.md # This file
└── src/
├── __init__.py # Package initialization
├── main.py # Application entry point
├── auth_handler.py # Cloud Run IAM authentication
├── mcp_client.py # MCP protocol client
└── agent.py # OpenAI agent with tool calling认证方法
方法1：使用应用程序默认凭据（主要）
最适合用于本地开发、GCE（Google Compute Engine）、Cloud Run、GKE（Google Kubernetes Engine）
handler = CloudRunTokenHandler()设置:
gcloud auth application-default login方法2：服务账户密钥文件
最适合于持续集成/持续部署（CI/CD），特定服务账户要求
handler = CloudRunTokenHandler(
service_account_key_path="/path/to/key.json"
)设置：
- 创建服务账户
- 格兰特
roles/run.invoker - 下载JSON密钥
- 设定
SERVICE_ACCOUNT_KEY_PATH环境变量
方法3：工作负载身份
最适合于在GKE/Cloud Run上的生产环境部署
在GKE或Cloud Run中运行时，若具备适当的IAM权限，则会自动配置 绑定（或“绑定项”）。
见 src/auth_handler.py 对于包含示例YAML的详细设置说明以及 命令。
环境变量
| 变量 | 是否必需 | 描述 |
|---|---|---|
OPENAI_API_KEY 好的，以下是原文内容的翻译： | ||
SERVICE_ACCOUNT_KEY_PATH | 编号 | 服务帐户JSON密钥路径（方法2） |
GOOGLE_APPLICATION_CREDENTIALS | 编号 | 凭证文件路径（自动检测） |
故障排除
认证错误
问题“无法获取有效凭据”
解决方案：
- 跑
gcloud auth application-default login - 检查服务账户是否具有
roles/run.invoker许可；权限 - 验证
GOOGLE_APPLICATION_CREDENTIALS指向有效文件 - 确保 Docker 有权访问凭据（检查卷挂载）
MCP 服务不可达
问题“MCP服务健康检查失败”
解决方案：
- 验证Cloud Run服务URL是否正确
- 检查网络连接
- 确保服务账户具有适当的权限
- 检查Cloud Run服务是否已部署并正在运行
令牌刷新问题
问题“刷新令牌失败”
解决方案:
- 重新认证：
gcloud auth application-default login - 检查令牌是否未被撤销
- 验证服务账户密钥是否仍然有效
- 检查系统时钟是否已同步
OpenAI API错误
问题“OpenAI API密钥未设置”或速率限制错误
解决方案：
- 验证
.env文件已存在，与……一起OPENAI_API_KEY - 请在platform.openai.com上检查API密钥是否有效
- 确保您有足够的积分/配额
- 如有需要，实施速率限制
发展
添加依赖项
# Add to pyproject.toml first
# Then sync
uv sync运行测试（未来）
# Install dev dependencies
uv sync --dev
# Run tests
pytest代码质量
# Format code
ruff format .
# Lint code
ruff check .安全注意事项
- 永远不要承诺
.env将文件或服务帐户密钥纳入版本控制 - 定期轮换服务帐户密钥
- 使用最小权限的IAM角色
- 为 Cloud Run 访问启用审计日志记录
- 在生产环境中尽可能使用工作负载身份
贡献；做出贡献
- 为仓库创建分支（或：克隆仓库）
- 创建一个特性分支
- 做出你的更改
- 彻底测试
- 提交一个拉取请求
许可证
MIT 许可证 - 详见 LICENSE 文件
支持
对于问题和疑问：
- 查看上面的故障排除部分
- 审查源代码中的注释示例
- 在GitHub上提交一个问题
致谢
- 采用UV构建，实现快速Python包管理
- 使用OpenAI的功能调用API
- 实现了MCP（模型上下文协议）
- 通过Google Cloud IAM保障安全