Example Client MCP

客户端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 sync

2. 设置Google Cloud身份验证

选项A：使用应用程序默认凭据（ADC）——推荐

# Authenticate with Google Cloud
gcloud auth application-default login

# Verify authentication
gcloud auth application-default print-access-token

选项B：服务账户密钥文件

1. 在GCP控制台中创建一个服务帐号
2. 授予它 Cloud Run Invoker 角色
3. 下载JSON密钥文件
4. 设置环境变量：

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"
)

设置：

1. 创建服务账户
2. 格兰特 roles/run.invoker
3. 下载JSON密钥
4. 设定 SERVICE_ACCOUNT_KEY_PATH 环境变量

方法3：工作负载身份

最适合于在GKE/Cloud Run上的生产环境部署

在GKE或Cloud Run中运行时，若具备适当的IAM权限，则会自动配置 绑定（或“绑定项”）。

见 src/auth_handler.py 对于包含示例YAML的详细设置说明以及 命令。

环境变量

故障排除

认证错误

问题“无法获取有效凭据”

解决方案：

1. 跑 gcloud auth application-default login
2. 检查服务账户是否具有 roles/run.invoker 许可；权限
3. 验证 GOOGLE_APPLICATION_CREDENTIALS 指向有效文件
4. 确保 Docker 有权访问凭据（检查卷挂载）

MCP 服务不可达

问题“MCP服务健康检查失败”

解决方案：

1. 验证Cloud Run服务URL是否正确
2. 检查网络连接
3. 确保服务账户具有适当的权限
4. 检查Cloud Run服务是否已部署并正在运行

令牌刷新问题

问题“刷新令牌失败”

解决方案:

1. 重新认证： gcloud auth application-default login
2. 检查令牌是否未被撤销
3. 验证服务账户密钥是否仍然有效
4. 检查系统时钟是否已同步

OpenAI API错误

问题“OpenAI API密钥未设置”或速率限制错误

解决方案：

1. 验证 .env 文件已存在，与……一起 OPENAI_API_KEY
2. 请在platform.openai.com上检查API密钥是否有效
3. 确保您有足够的积分/配额
4. 如有需要，实施速率限制

发展

添加依赖项

# 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 访问启用审计日志记录
• 在生产环境中尽可能使用工作负载身份

贡献；做出贡献

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支
3. 做出你的更改
4. 彻底测试
5. 提交一个拉取请求

许可证

MIT 许可证 - 详见 LICENSE 文件

支持

对于问题和疑问：

• 查看上面的故障排除部分
• 审查源代码中的注释示例
• 在GitHub上提交一个问题

致谢

• 采用UV构建，实现快速Python包管理
• 使用OpenAI的功能调用API
• 实现了MCP（模型上下文协议）
• 通过Google Cloud IAM保障安全