内容
# GCP Org 导航器 — ADK + MCP
一个 AI 代理，允许您用简单的中文查询您的 **GCP 组织层次结构**（组织、文件夹、项目、IAM 策略）- 使用 [谷歌代理开发工具包（ADK）](https://adk.dev) 和自定义 [MCP](https://modelcontextprotocol.io) 服务器支持的 Cloud Resource Manager API 构建。
> 📖 完整教程： [Medium 文章链接]
---
## 功能
向代理提问，例如：
- *"列出组织中的所有文件夹"*
- *"查找带有 env=production 标签的所有项目"*
- *"项目 my-project 的 IAM 策略是什么？"*
- *"给我组织层次结构的完整清单"*
代理自动决定调用哪个工具，如果需要，链式调用多个工具，并返回干净的 Markdown 表格。
---
## 架构
```
用户（浏览器）
│ HTTP（ADK 开发界面）
ADK LlmAgent ─── gemini-2.5-flash
│ stdio（MCPToolset → 子进程）
FastMCP 服务器 （mcp_server.py）
│ gRPC / REST（应用程序默认凭证）
Cloud Resource Manager API
```
---
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `list_organizations` | 列出调用者有权访问的所有 GCP 组织 |
| `list_folders(parent)` | 列出组织或文件夹下的文件夹 |
| `get_folder(folder_id)` | 获取特定文件夹的详细信息 |
| `list_projects(parent)` | 列出组织或文件夹下的项目 |
| `search_projects(query)` | 组织范围的项目搜索，带有过滤器语法 |
| `get_project(project_id)` | 获取特定项目的详细信息 |
| `get_org_iam_policy(org_id)` | 获取组织节点的 IAM 绑定 |
| `get_project_iam_policy(project_id)` | 获取项目的 IAM 绑定 |
---
## 先决条件
- Python 3.12+
- 具有 `resourcemanager.organizations.search` 权限的 GCP 组织
- 已安装并认证的 `gcloud` CLI
```bash
# 认证
gcloud auth application-default login
# 启用 Vertex AI（用于 Gemini）
gcloud services enable aiplatform.googleapis.com --project=YOUR_PROJECT
```
---
## 设置
```bash
# 克隆仓库
git clone https://github.com/jitu028/gcp-org-navigator-mcp.git
cd gcp-org-navigator-mcp
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装依赖项
pip install -r requirements.txt
# 配置环境
cp .env.example .env
# 编辑 .env 文件，填写您的项目 ID
```
---
## 运行
### 选项 A — 烟雾测试（无代理，验证 API 访问）
```bash
python smoke_test.py
```
### 选项 B — ADK 网页界面（聊天界面）
```bash
adk web --port 8080
```
打开 http://localhost:8080，选择 **`org_navigator`**，开始聊天。
---
## 配置
复制 `.env.example` 到 `.env` 并填写您的值：
```env
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=您的项目 ID
GOOGLE_CLOUD_LOCATION=us-central1
```
---
## 所需 IAM 权限
认证账户需要在 **组织级别** 拥有以下权限：
- `resourcemanager.organizations.search`
- `resourcemanager.organizations.getIamPolicy` （用于组织 IAM 策略工具）
- `resourcemanager.folders.list` / `resourcemanager.folders.get`
- `resourcemanager.projects.list` / `resourcemanager.projects.get`
- `resourcemanager.projects.getIamPolicy` （用于项目 IAM 策略工具）
涵盖这些权限的预定义角色：`roles/resourcemanager.organizationViewer`，`roles/resourcemanager.folderViewer`
---
## 项目结构
```
.
├── __init__.py ← ADK 包注册（必需）
├── agent.py ← ADK LlmAgent 通过 MCPToolset 连接到 MCP
├── mcp_server.py ← FastMCP 服务器，暴露 8 个 Resource Manager 工具
├── smoke_test.py ← 直接工具测试（无需代理）
├── requirements.txt ← Python 依赖项
├── .env.example ← 环境变量模板
└── README.md
```
---
## 参考资料
- [ADK 文档](https://google.github.io/adk-docs/)
- [ADK MCP 工具](https://google.github.io/adk-docs/tools/mcp-tools/)
- [模型上下文协议](https://modelcontextprotocol.io)
- [Cloud Resource Manager API](https://cloud.google.com/resource-manager/docs/overview)
- [Resource Manager Python 客户端](https://cloud.google.com/python/docs/reference/resourcemanager/latest/google.cloud.resourcemanager_v3)
- [应用程序默认凭证](https://cloud.google.com/docs/authentication/provide-credentials-adc)
- [Vertex AI 模型版本](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions)
---
## 许可证
Apache 2.0
