使用说明

AI精品助理MCP客户端

使用Google ADK（代理开发工具包）和模型上下文协议（MCP）构建的AI购物助手，连接到在线精品微服务。使用 ai精品店assit mcp 用于MCP服务器功能的PyPI包。

为 GKE十周年黑客马拉松 -演示如何在Google Kubernetes引擎上使用代理AI功能来增强现有的微服务应用程序。

建筑
黑客马拉松项目
- 满足挑战要求
- 使用的技术
特性
产品演示
构建于
先决条件
- 促进地方发展
- 用于GKE部署
快速开始
使用示例
MCP服务器集成
配置
- 环境变量
- Kubernetes的秘密
Docker部署
- 构建和推送
- Kubernetes资源
GKE部署
故障排除
- 常见问题
- 调试

1.建筑

系统架构图

关键架构组件

数据流：

用户请求 → ADK Web用户界面→ ADK代理
人工智能处理 → 双子座2.0闪光灯→ MCP工具选择
MCP通信 → 标准协议→ MCP服务器
微服务调用 → gRPC客户端→ 在线精品服务
响应组件 → MCP服务器→ ADK代理→ Web用户界面

沟通模式：

Web用户界面↔ 代理人： ADK Web服务器协议
代理↔ MCP服务器： 带JSON-RPC的Stdio（标准输入/标准输出）
MCP服务器↔ 微服务： gRPC（协议缓冲区）
基础设施： Kubernetes服务发现

MCP集成

代理使用MCP将所有Online Boutique微服务功能作为可用工具公开。

2.黑客马拉松项目

此项目是为 GKE十周年黑客马拉松，这挑战了开发人员通过在现有应用程序之上构建代理人工智能功能，而无需修改核心应用程序代码，来“为微服务提供人工智能升级”。

满足挑战要求

基础应用程序： 在线精品微服务演示
平台： 用于部署的Google Kubernetes引擎（GKE）
AI模型： 谷歌双子座2.0 Flash通过ADK
外部组件： 与现有API交互的新容器化AI助手
无核心修改： 原始在线精品店代码保持不变
代理框架： 使用ADK（代理开发工具包）和MCP（模型上下文协议）服务器和客户端

使用的技术

必修的：

谷歌Kubernetes引擎（GKE） -容器编排平台
谷歌人工智能模型 -Gemini 2.0 Flash用于对话式人工智能

推荐（已使用）：

代理开发工具包（ADK） -代理框架和web界面
模型上下文协议（MCP） -与微服务API的通信

3.特点

AI购物助手

自然语言搜索 -使用会话语言搜索产品
价格筛选 -按价格范围筛选产品（“50美元以下”、“廉价商品”）
产品推荐 -根据用户行为获取建议
视觉购物 -产品图片和视觉浏览体验
上下文广告 -相关宣传内容

电子商务功能

产品目录 -通过gRPC服务浏览和搜索产品
购物车 -添加/删除商品，查看购物车内容
结账过程 -使用默认付款/运费完成结账
订单确认 -带有跟踪信息的订单摘要
货币兑换 -国际货币支持
电子邮件通知 -订单确认电子邮件

MCP协议特性

工具发现 -自动检测可用的微服务功能
类型安全 -通过MCP进行强类型函数调用
错误处理 -跨服务边界的优雅错误处理
会话管理 -与微服务的持久连接

4.产品演示

通过AI精品助理体验完整的用户旅程：

1.ADK Web界面

干净、现代的ADK网络界面为购物提供了直观的聊天体验。

2.购物对话

用于浏览产品、添加购物车和结账的自然语言交互。

3.产品推荐

基于产品关系和购物行为的人工智能“你可能也喜欢”建议。

4.可视化产品浏览

具有图像、描述和直接添加到购物车功能的丰富产品显示。

5.内置

程式语言

Python 3.11 -ADK代理和MCP集成的主要后端语言
YAML -Kubernetes清单和配置文件
Bash -部署和自动化脚本
标记语言 -文档和README

人工智能和代理框架

谷歌代理开发工具包（ADK）1.14.1 -用于AI编排的核心代理框架
模型上下文协议（MCP）1.12.1 -代理和工具之间的通信协议
双子座2.0闪光灯 -谷歌最新的自然语言处理法学硕士
谷歌人工智能平台API -人工智能模型访问和推理

通信协议

gRPC -用于微服务通信的高性能RPC框架
协议缓冲区 -数据序列化和服务定义
JSON-RPC -MCP协议传输层
标准协议 -ADK到MCP服务器通信
HTTP/HTTPS -Web界面和API通信

容器和编排

码头工人 -应用打包容器平台
谷歌Kubernetes引擎（GKE） -容器编排平台
Kubernetes -容器编排和服务发现
kubectl 的 -Kubernetes命令行工具

云服务

谷歌云平台（GCP） -主要云提供商
谷歌容器注册表（GCR） -容器图像存储
谷歌云API -平台服务集成
Kubernetes引擎API -集群管理

Web和应用程序服务器

ADK Web服务器 -内置代理web界面
Uvicorn -用于Python应用程序的ASGI服务器
快速API -现代Python web框架（通过ADK）

网络和入口

Nginx入口控制器 -HTTP（S）负载平衡和路由
Kubernetes服务 -内部服务发现和负载平衡
Kubernetes入口 -外部HTTP（S）访问管理
负载平衡器服务 -外部IP分配

微服务（在线精品店）

产品目录服务 -产品搜索和目录管理
购物车服务 -购物车操作
推荐服务 -基于人工智能的产品建议
航运服务 -发货报价和订单履行
货币服务 -多币种支持和转换
支付服务 -付款处理和验证
电子邮件服务 -订单确认和通知
结账服务 -完成订单处理工作流程
广告服务 -情境广告和促销

开发工具

Git -版本控制系统
GitHub -代码库和协作
PyPI -Python包分发（ai精品助手mcp）
点 -Python包管理器

包依赖

谷歌广告==1.14.1 -谷歌代理开发工具包
ai精品助理mcp==1.0.4 -自定义MCP服务器包
grpcio -gRPC Python库
协议缓冲区 -协议缓冲区Python支持
请求： -HTTP客户端库
优维康 -ASGI服务器实现

6.先决条件

促进地方发展

Python 3.11+
谷歌云命令行界面（gcloud）
kubectl 的 （用于微服务访问）
Google API密钥 用于Gemini访问

用于GKE部署

Docker 桌面版
kubectl 的 为您的GKE集群配置
GKE集群 在线精品服务正在运行

7.快速入门

1.克隆和设置

git clone https://github.com/arjunprabhulal/ai-boutique-assit-mcp-client.git
cd ai-boutique-assit-mcp-client

# Install dependencies
pip install -r requirements.txt

2.地方发展

# Set your Google API key
export GOOGLE_API_KEY="your-google-api-key"

# Run the agent locally
adk run ai-boutique-assit

# Or run with web interface
adk web ai-boutique-assit --host 0.0.0.0 --port 8000

3.MCP服务器配置

MCP服务器由ADK代理自动调用：

McpToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="boutique-mcp-server",
            args=["--stdio"]
        ),
        timeout=180
    )
)

8.使用示例

产品搜索

"Show me trending products"
→ AI calls list_products MCP tool
→ Displays product gallery with images and pricing
→ Includes contextual advertisements and recommendations

购物车

"Add 2 coffee mugs to my cart"
→ AI searches for "coffee mugs" via search_products tool
→ Calls add_item_to_cart with product ID and quantity
→ Shows updated cart with get_cart tool

视觉购物

"Show me images of sunglasses"
→ AI calls get_product_with_image tool
→ Downloads and displays product images
→ Shows product details with add-to-cart options

9.MCP服务器集成

服务器调用

当代理启动时，它会自动：

执行 boutique-mcp-server --stdio 作为子流程
通过stdio连接（stdin/stdout通信）
MCP服务器加载所有微服务gRPC客户端和功能
功能作为MCP工具公开给代理
用户请求触发MCP工具对微服务的调用

这 boutique-mcp-server 命令由提供 ai精品店assit mcp 软件包安装。

可用的MCP工具

MCP服务器公开了这些微服务功能：

工具类别

产品目录工具：

list_products -列出所有可用产品
search_products -按关键字搜索产品
get_product -获取特定产品详细信息
get_product_with_image -获取带有图像下载的产品
filter_products_by_price -按价格范围筛选产品

购物车工具：

add_item_to_cart -将商品添加到用户购物车
get_cart -检索购物车内容
empty_cart -清除购物车内容

订单处理工具：

place_order -处理完整订单
initiate_checkout -开始结账流程

附加维修工具：

list_recommendations -获取产品推荐
get_ads -检索上下文广告
get_shipping_quote -获取运费预估
ship_order -处理装运
charge_card -处理付款
convert_currency -货币兑换
send_order_confirmation -发送确认电子邮件

10.配置

环境变量

AI助手连接到这些微服务：

服务	默认端口	环境变量
产品目录	3550	`PRODUCT_CATALOG_SERVICE`
购物车服务	7070	`CART_SERVICE`
建议	8080	`RECOMMENDATION_SERVICE`
发货	50051	`SHIPPING_SERVICE`
货币	7000	`CURRENCY_SERVICE`
付款	50051	`PAYMENT_SERVICE`
电子邮件	5000	`EMAIL_SERVICE`
结账	5050	`CHECKOUT_SERVICE`
广告服务	9555	`AD_SERVICE`

Kubernetes的秘密

创建Google API访问所需的机密：

kubectl create secret generic google-api-key \
  --from-literal=api-key="your-google-api-key"

11.Docker部署

构建和推送

# Build for AMD64 (GKE compatibility)
docker build --platform linux/amd64 -t gcr.io/$PROJECT_ID/ai-boutique-assistant:latest .

# Push to Google Container Registry
docker push gcr.io/$PROJECT_ID/ai-boutique-assistant:latest

Kubernetes资源

部署： ai-boutique-mcp
服务： ai-boutique-mcp-service （8000端口上的集群IP）
进入： ai-boutique-mcp-ingress （使用 ingress-nginx-mcp 类）

12.GKE部署

入口设置

部署使用专用入口控制器来避免冲突：

# Install separate nginx controller
kubectl apply -f ingress-nginx-mcp-clean.yaml

# Wait for controller to be ready
kubectl wait --namespace ingress-nginx-mcp \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=120s

# Get external IP
kubectl get service ingress-nginx-mcp-controller -n ingress-nginx-mcp

部署命令

快速部署：

export PROJECT_ID="your-gcp-project-id"
./deploy.sh

手动部署：

# Build and push
docker build --platform linux/amd64 -t gcr.io/$PROJECT_ID/ai-boutique-assistant:$(date +%s) .
docker push gcr.io/$PROJECT_ID/ai-boutique-assistant:$(date +%s)

# Deploy to Kubernetes
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml

访问应用程序

部署后，访问您的AI助手：

http://[EXTERNAL-IP]/

获取外部IP：

kubectl get ingress ai-boutique-mcp-ingress

13.故障排除

常见问题

MCP连接错误

# Check if MCP server package is installed
pip show ai-boutique-assit-mcp

# Verify stdio mode configuration
kubectl logs -l app=ai-boutique-mcp

坏网关（502）

# Check pod status
kubectl get pods -l app=ai-boutique-mcp

# Verify service endpoints
kubectl describe service ai-boutique-mcp-service

入口不工作

# Check ingress controller
kubectl get pods -n ingress-nginx-mcp

# Verify ingress configuration
kubectl describe ingress ai-boutique-mcp-ingress

端口冲突

# Kill conflicting processes
pkill -f "kubectl.*port-forward"
lsof -ti:8000 | xargs kill -9

调试

# Application logs
kubectl logs -l app=ai-boutique-mcp -f

# Ingress controller logs
kubectl logs -n ingress-nginx-mcp -l app.kubernetes.io/component=controller

# Check microservice connectivity
kubectl exec -it deployment/ai-boutique-mcp -- curl http://productcatalogservice:3550

额外资源

黑客松

GKE十周年黑客马拉松 -这个项目是为黑客马拉松而建的

项目组成部分

参考文献

测试说明

测试的先决条件

所需设置

Google API密钥 用于Gemini 2.0闪存访问
Python 3.11+ 本地安装
Docker 桌面版 正在运行（用于容器化测试）
kubectl 的 已配置（用于GKE测试）

环境设置

# Clone the repository
git clone https://github.com/arjunprabhulal/ai-boutique-assit-mcp-client.git
cd ai-boutique-assit-mcp-client

# Install dependencies
pip install -r requirements.txt

# Set your Google API key
export GOOGLE_API_KEY="your-google-api-key"

局部测试

1.测试MCP服务器安装

# Verify MCP server package is installed
pip show ai-boutique-assit-mcp

# Test MCP server can start
boutique-mcp-server --help

预期产量：

usage: boutique-mcp-server [-h] [--port PORT] [--stdio] [--http]
AI Boutique Assistant MCP Server

2.在本地测试ADK代理

# Start the ADK agent
adk run ai-boutique-assit

预期行为：

代理以“正在运行代理botiq_ai_axist”开头
MCP服务器在stdio模式下自动生成
客服以问候回应“嗨”
键入“exit”停止

3.测试ADK Web界面

# Start web interface
adk web ai-boutique-assit --host 0.0.0.0 --port 8000

预期行为：

Web服务器启动于http://localhost:8000
浏览器显示ADK网络聊天界面
可以与AI购物助手互动

特性测试

购物功能测试用例

1.产品搜索

输入： “显示热门产品”
预期： 客服电话 list_products MCP工具，返回包含名称、价格和描述的产品列表

2.价格过滤

输入： “查找50美元以下的产品”
预期： 客服电话 filter_products_by_price MCP工具，只退回50美元以下的产品

3.加入购物车

输入： “将2个杯子添加到我的购物车”
预期： 特工先搜索“杯子”，然后打电话 add_item_to_cart 带有产品ID和数量

4.查看购物车

输入： “显示我的购物车”
预期： 客服电话 get_cart MCP工具，返回带有产品详细信息的购物车商品

5.视觉购物

输入： “给我看太阳镜的图片”
预期： 客服电话 get_product_with_image MCP工具，下载并展示产品图片

6.结账流程

输入： “我想结账”
预期： 代理商使用默认的发货/付款详细信息，呼叫 place_order MCP工具

集成测试场景

完成购物流程测试

开始对话： “嗨，我想购物”
浏览产品： “显示热门产品”
特定搜索： “查找咖啡杯”
加入购物车： “将2个杯子添加到我的购物车”
查看购物车： “我的车里有什么？”
获取建议： 车展相关产品是否应该
结账： “我想结账”
确认订单： 验证订单详细信息和跟踪

Docker测试

1.测试Docker构建

# Build container
docker build --platform linux/amd64 -t ai-boutique-assistant:test .

# Test container locally
docker run -e GOOGLE_API_KEY="your-key" -p 8000:8000 ai-boutique-assistant:test

2.测试容器健康状况

# Check container health
docker ps
docker logs <container-id>

GKE部署测试

1.测试应用部署

# Deploy application
export PROJECT_ID="your-project-id"
./deploy.sh

# Check deployment status
kubectl get pods -l app=ai-boutique-mcp
kubectl get service ai-boutique-mcp-service
kubectl get ingress ai-boutique-mcp-ingress

2.测试外部访问

# Get external IP
EXTERNAL_IP=$(kubectl get ingress ai-boutique-mcp-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo "Testing: http://$EXTERNAL_IP/"

# Test connectivity
curl -I http://$EXTERNAL_IP/

测试验证检查表

基本功能

[]ADK代理启动时没有错误
[]MCP服务器连接成功
[]可访问的Web界面
[]可以发送/接收消息

购物功能

[]产品搜索返回结果
[]价格过滤工作正常
[]添加到购物车功能正常
[]购物车视图正确显示商品
[]出现建议
[]结账过程完成
[]订单确认显示

技术集成

[]所有18+MCP工具可用
[]与所有9个微服务的gRPC连接
[]无连接超时
[]正确的错误处理

已知测试数据

该应用程序使用测试数据进行演示：

测试用户

用户ID: “阿君”
电子邮件： "customer@boutique.com"

测试付款（仅限演示）

信用卡： "4432-8015-6152-0454"
CVV： 672
到期： 01/2030

测试发货（仅演示）

地址： 加利福尼亚州山景城露天剧场公园路1600号，邮编94043

注：所有支付和个人数据仅用于测试目的，不由真实支付系统处理。

作者

阿琼·普拉布拉尔

介质： https://medium.com/@帕布哈拉尔
github： https://github.com/arjunprabhulal

贡献

复刻仓库
创建要素分支
进行更改
在本地和GKE上进行测试
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。