Google Cloud MCP Toolbox Demo

此仓库包含一个小型演示代理，该代理使用Google Gemini嵌入式向量和MCP Toolbox的MongoDB工具集来实现一个“在线杂货代理”。该代理展示了如何使用向量搜索在库存中查找产品、将产品添加到购物车（MongoDB集合）以及获取购物车总计（聚合购物车集合）。

• mongodb-groceries-agent/: 包含演示代理的实现代码（agent.py）和包初始化文件。
• tools.yaml: MongoDB工具集的定义文件。

运行前准备

在运行演示之前，请确保您的机器上已安装并可用以下内容：

• Python 3.10+（推荐使用3.11）
• pip（或等效的Python包管理器）
• MCP Toolbox服务器（请参阅安装说明）
• 具有访问GenAI服务权限的Google API密钥（设置为环境变量GOOGLE_API_KEY）
• MongoDB部署（支持Atlas免费M0集群——请参阅下面的说明）

设置免费的MongoDB Atlas M0集群

您可以创建一个免费的（M0）MongoDB Atlas集群。请按照以下步骤操作：

1. 在浏览器中打开Atlas注册页面。

2. 注册一个免费的MongoDB账户，或者如果您已有账户，则登录。

3. 点击“创建集群”并选择免费层（M0 / 共享）。

4. 选择云提供商和区域（默认值对于演示来说是合适的）。

5. 创建数据库用户：转到“数据库访问”并添加一个具有密码的用户。保存这个用户名/密码——您将在连接字符串中需要它。

6. 允许您的IP地址：转到“网络访问”并添加您的当前IP或0.0.0.0/0以进行测试（不建议用于生产环境）。

7. 点击“连接”，选择“连接您的应用”，并复制提供的连接字符串。

   将连接字符串用作tools.yaml中的uri，或者更优选地通过环境变量设置它。示例连接字符串如下：

   mongodb+srv://<username>:<password>@<your-cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority
   

   注意：用来自Atlas的值替换<username>、<password>、<your-cluster>和<dbname>。对于本地测试，您也可以使用本地MongoDB服务器。

8. 将示例杂货产品数据导入名为products的集合，在名为groceries的数据库中。您可以使用提供的sample_data/groceries.json文件，并通过MongoDB Atlas UI或mongosh导入它。

mongoimport --uri="<your-connection-string>" --db="grocery_store" --collection="inventory" --file="grocery_store.inventory.json" --jsonArray

配置

在运行代理之前，请设置以下环境变量：

• GOOGLE_API_KEY — 您的Google GenAI API密钥

示例（macOS / zsh）：

export GOOGLE_API_KEY="your-google-api-key"

运行演示代理

1. 安装依赖项（如果此仓库是更大项目的一部分，请适当调整）。从项目根目录开始：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt  # 如果存在requirements文件；否则手动安装所需包

2. 启动工具箱服务器：

./toolbox --tools-file "tools.yaml"

3. 确保Toolbox服务器正在运行并且可以在http://127.0.0.1:5000访问。

4. 运行代理代码（此演示文件旨在由启动代理的编排脚本导入）。要快速尝试简单的运行或导入模块：

adk web

根据需要调整调用来集成代理到管理代理生命周期的运行时环境中。

agent.py做了什么

• 从环境读取GOOGLE_API_KEY并将其设置在os.environ中供Google GenAI客户端使用。
• 创建一个genai.Client()和一个指向http://127.0.0.1:5000的Toolbox客户端。
• 提供generate_embeddings(query)以使用gemini-embedding-001生成嵌入向量。
• 提供find_similar_products(query)，该函数通过toolkit工具find_similar_documents对名为vector_index的索引和字段gemini_embedding执行向量搜索。
• 构建一个配置为使用这些工具的Agent，并加载来自toolkit的grocery-shopping-toolset。

故障排除

• 如果从GenAI收到身份验证错误，请确认GOOGLE_API_KEY已设置且有效。
• 如果Toolbox客户端无法连接，请确认ToolboxSync服务器正在运行并在配置的地址可达。
• 如果出现MongoDB连接问题，请检查您的Atlas IP允许列表和数据库用户凭据。

贡献者 ✨

<!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tr> <td align="center"> <a href="https://www.linkedin.com/in/sis0k0/"> <img src="https://gips0.baidu.com/it/u=274577454,2659783082&fm=3081&app=3081&f=JPEG?w=460&h=460" width="100px;" alt=""/><br /> _{<b>Stanimira Vlaeva</b>} </a><br /> </td> </tr> </table> <!-- markdownlint-restore --> <!-- prettier-ignore-end -->

免责声明

自行承担风险使用；非支持的MongoDB产品