MCP计算器服务器+谷歌ADK代理
一个完整的解决方案，用于将带有计算器工具的模型上下文协议（MCP）服务器部署到Google Cloud Run，并使用Google的代理开发工具包（ADK）将其与Vertex AI客户支持代理集成。
📋 目录
🎯 概述
本项目演示了如何：
- 构建MCP服务器 -基于Python的MCP服务器，带有计算器工具（加、减、乘、除、百分比、幂、sqrt）
- 部署到云端运行 -使用Terraform将MCP服务器容器化并部署到Google Cloud Run
- 创建AI代理 -使用Google ADK构建一个客户支持聊天机器人，并可访问计算器工具
- 部署到顶点AI -将代理部署到顶点AI代理引擎
🏗️ 建筑
┌─────────────────────────────────────────────────────────────┐
│ Vertex AI Agent Engine │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Customer Support Agent (Google ADK) │ │
│ │ - Gemini 2.0 Flash │ │
│ │ - Customer support personality │ │
│ │ - Function calling enabled │ │
│ └────────────────┬───────────────────────────────────────┘ │
│ │ │
└───────────────────┼───────────────────────────────────────────┘
│
│ HTTPS
│
┌───────────────────▼───────────────────────────────────────────┐
│ Google Cloud Run │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ MCP Calculator Server │ │
│ │ - FastAPI HTTP/SSE transport │ │
│ │ - Calculator tools (add, subtract, multiply, etc.) │ │
│ │ - Auto-scaling │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐
│ Infrastructure (Terraform) │
│ - Artifact Registry │
│ - IAM Service Accounts │
│ - Cloud Run Services │
│ - Vertex AI Resources │
└────────────────────────────────────────────────────────────────┘✨ 特性
MCP服务器
- 7计算器工具：加、减、乘、除、幂、平方、百分比
- HTTP/SSE传输：与Cloud Run和Vertex AI兼容
- 错误处理：正确的验证和错误消息
- 健康检查：内置健康检查端点
- 自动缩放：不使用时缩放为零
顶点AI代理
- 客户支持个性：友好且乐于助人的聊天机器人
- 函数调用：使用MCP计算器工具
- 双子座2.0闪光灯：快速高效的模型
- 安全设置：已启用内容筛选
- 对话示例：预配置的测试场景
基础设施
- 地形IaC：所有基础设施均定义为代码
- 制品库：安全的容器图像存储
- 服务帐户：适当的IAM和安全
- 自动化部署：一次指挥部署
📦 先决条件
所需工具
- 谷歌云帐户 已启用计费
- gcloud命令行界面 （v450.0.0+）- 安装
- 地形 （v1.5.0+）- 安装
- 码头工人 （可选，用于本地测试）- 安装
- Python 3.11+ - 安装
- 制造 （为方便起见，可选）
- jq （可选，用于测试）- 安装
启用Google Cloud API
Terraform配置将自动启用以下功能：
- 云运行API
- 工件注册表API
- 云构建API
- Vertex AI API
- IAM API
需要权限
您的GCP帐户需要以下角色：
roles/owner或者：
- roles/run.admin - roles/artifactregistry.admin - roles/iam.serviceAccountAdmin - roles/cloudbuild.builds.builder - roles/aiplatform.admin
🚀 快速开始
1.克隆和配置
# Clone the repository
cd /path/to/google-adk-mcp
# Copy and edit Terraform variables
cp terraform/terraform.tfvars.example terraform/terraform.tfvars
nano terraform/terraform.tfvars # Add your project_id2.使用Google Cloud进行身份验证
# Login to gcloud
gcloud auth login
gcloud auth application-default login
# Set your project
gcloud config set project YOUR_PROJECT_ID3.部署一切
# Option A: Using the deployment script (recommended)
chmod +x scripts/deploy.sh
cd scripts && ./deploy.sh
# Option B: Using Make
make deploy
# Option C: Manual step-by-step (see Detailed Setup below)4.测试MCP服务器
# Using the test script
chmod +x scripts/test-mcp-server.sh
./scripts/test-mcp-server.sh
# Or manually
export MCP_URL=$(cd terraform && terraform output -raw mcp_server_url)
curl $MCP_URL/health
curl $MCP_URL/tools📁 项目结构
google-adk-mcp/
├── mcp-server/ # MCP Calculator Server
│ ├── src/
│ │ ├── calculator_server.py # Core MCP server with tools
│ │ └── http_server.py # FastAPI HTTP wrapper
│ ├── Dockerfile # Container image definition
│ ├── requirements.txt # Python dependencies
│ └── .dockerignore
│
├── terraform/ # Infrastructure as Code
│ ├── main.tf # Main Terraform configuration
│ ├── variables.tf # Input variables
│ ├── outputs.tf # Output values
│ ├── versions.tf # Provider versions
│ └── terraform.tfvars.example # Example configuration
│
├── agent/ # Vertex AI Agent Configuration
│ ├── agent_config.yaml # Agent configuration
│ ├── deploy_agent.py # Agent deployment script
│ └── prompts/
│ └── system_prompt.txt # System instructions
│
├── scripts/ # Deployment Scripts
│ ├── deploy.sh # Main deployment script
│ └── test-mcp-server.sh # Testing script
│
├── Makefile # Convenience commands
└── README.md # This file🔧 详细设置
步骤1：配置地形变量
编辑 terraform/terraform.tfvars:
project_id = "your-gcp-project-id"
region = "us-central1"
# Optional customizations
mcp_server_name = "mcp-calculator-server"
vertex_ai_agent_name = "customer-support-agent"
agent_display_name = "Customer Support Agent"
# Security settings
enable_public_access = false # Keep false for production
labels = {
environment = "production"
managed-by = "terraform"
project = "mcp-calculator"
}步骤2：初始化地形
cd terraform
terraform init第三步：规划基础设施
terraform plan审查计划的变更。您应该看到：
- 工件注册表存储库
- 2个服务帐户
- 云运行服务
- IAM绑定
步骤4：应用基础设施
terraform apply类型 yes 以确认。这创造了所有的基础设施。
步骤5：构建和部署MCP服务器
# Get the image name from Terraform
export DOCKER_IMAGE=$(terraform output -raw docker_image_name)
# Build and push using Cloud Build
cd ../mcp-server
gcloud builds submit --tag $DOCKER_IMAGE步骤6：更新云运行服务
cd ../terraform
terraform apply -auto-approve这将使用新构建的映像更新Cloud Run服务。
步骤7：部署顶点AI代理
cd ../agent
# Install Python dependencies
pip install google-cloud-aiplatform pyyaml requests
# Run deployment script
python3 deploy_agent.py \
--project-id YOUR_PROJECT_ID \
--location us-central1 \
--mcp-server-url $(cd ../terraform && terraform output -raw mcp_server_url) \
--service-account $(cd ../terraform && terraform output -raw vertex_ai_agent_service_account)按照输出说明完成Vertex AI控制台中的代理设置。
🧪 测试
测试MCP服务器端点
# Get MCP server URL
export MCP_URL=$(cd terraform && terraform output -raw mcp_server_url)
# Health check
curl $MCP_URL/health
# List available tools
curl $MCP_URL/tools | jq '.'
# Test addition
curl -X POST $MCP_URL/tools/add \
-H "Content-Type: application/json" \
-d '{"arguments": {"a": 5, "b": 3}}' | jq '.'
# Test percentage calculation
curl -X POST $MCP_URL/tools/percentage \
-H "Content-Type: application/json" \
-d '{"arguments": {"number": 100, "percent": 15}}' | jq '.'自动化测试
# Run all tests
chmod +x scripts/test-mcp-server.sh
./scripts/test-mcp-server.sh测试顶点AI代理
- 首选 顶点AI控制台
- 导航到代理生成器
- 查找您的“客户支持代理”
- 使用聊天界面测试：
对话示例：
You: Hi! I need help calculating a discount.
Agent: I'd be happy to help with that calculation! What's the original price and discount percentage?
You: The item is $120 and I have a 15% discount code.
Agent: [Uses percentage tool] With a 15% discount on $120, you save $18. Your final price would be $102.💻 发展
地方发展
在本地运行MCP服务器：
cd mcp-server
pip install -r requirements.txt
cd src
python http_server.py服务器将在以下时间可用 http://localhost:8080
发出命令
make help # Show all available commands
make init # Initialize Terraform
make plan # Terraform plan
make apply # Terraform apply
make build # Build and push Docker image
make deploy # Full deployment
make test # Test MCP server
make dev # Run local development server
make clean # Clean temporary files
make destroy # Destroy all infrastructure🐛 故障排除
常见问题
1.“权限被拒绝”错误
# Grant necessary permissions
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member=user:YOUR_EMAIL \
--role=roles/owner2.云运行服务不可访问
# Check if public access is needed (not recommended for production)
# Edit terraform/terraform.tfvars:
enable_public_access = true
# Then apply
cd terraform && terraform apply3.Docker构建失败
# Authenticate Docker with Artifact Registry
gcloud auth configure-docker us-central1-docker.pkg.dev
# Try building locally first
cd mcp-server
docker build -t test-mcp-server .
docker run -p 8080:8080 test-mcp-server4.地形状态问题
# If you need to recreate a resource
cd terraform
terraform state rm google_cloud_run_v2_service.mcp_server
terraform apply日志和监控
# View Cloud Run logs
gcloud run services logs read mcp-calculator-server --region us-central1
# View Cloud Build logs
gcloud builds list --limit=10
gcloud builds log
# View Vertex AI logs
gcloud logging read "resource.type=aiplatform.googleapis.com" --limit=50💰 成本估算
云运行
- 免费层：200万次请求/月
- 计算：每vCPU秒约0.00002400美元
- 记忆~$0.00000250 每 GiB 秒
- 请求：每百万次请求约0.40美元
- 预计：中低使用率为0-10美元/月
制品库
- 存储：每月每GB 0.10美元
- 预计：0.10美元/月
顶点AI
- 双子座2.0闪光灯：每100万输入代币约0.075美元
- 代理引擎：预览定价（查看最新价格）
- 预计：10-50美元/月，具体取决于使用情况
估计总成本
- 低使用：10-20美元/月
- 适度使用：20-60美元/月
- 高使用率：60-200美元/月
🔒 安全
已实施的最佳实践
- 无公共访问：默认情况下，MCP服务器需要身份验证
- 服务帐户：具有最低权限的专用服务帐户
- 国际机械师协会：适当的基于角色的访问控制
- 仅限HTTPS：所有流量均已加密
- 内容安全：已启用顶点AI安全设置
- 输入验证：所有计算器输入均已验证
安全检查列表
- \[\]检查IAM权限
- \[\]保持
enable_public_access = false - \[\]使用VPC服务控制进行生产
- \[\]启用Cloud Armor以保护DDoS
- \[\]设置云日志和监控
- \[\]配置异常活动警报
- \[\]定期更新依赖关系
- \[\]对敏感数据使用秘密管理器
📚 其他资源
🤝 贡献
欢迎投稿！请随时提交问题或拉取请求。
📄 许可证
本项目按原样提供，用于教育和示范目的。
✅ 后续步骤
部署后：
- ✅ 测试MCP服务器端点
- ✅ 完成顶点AI代理设置
- ✅ 使用示例对话测试代理
- ✅ 在GCP控制台中监控成本
- ✅ 设置警报和监控
- ✅ 定制代理个性和工具
- ✅ 根据需要添加更多计算器工具
- ✅ 与您的应用程序集成
______________________________________________________________________
内置❤️ 使用谷歌云、顶点AI和MCP