用于AI集成的AEM资产服务器
Adobe Experience Manager（AEM）资产API的双重实施服务器：
- REST API (
rest-api/)-通过操作（FastAPI）为ChatGPT自定义GPT - MCP 服务器 (
mcp-server/)-用于支持MCP的ChatGPT自定义GPT（FastMCP）
这两种实现共享相同的核心AEM客户端逻辑，并提供相同的功能。
🏗️ 建筑
aem-assets-mcp-server/
├── rest-api/ ← REST API implementation (Vercel)
│ ├── app/ - FastAPI application
│ ├── requirements.txt
│ └── vercel.json
├── mcp-server/ ← MCP Server implementation (Cloud Run)
│ ├── app/ - FastMCP application
│ ├── Dockerfile
│ └── requirements.txt
├── shared/ ← Common AEM client logic
│ ├── aem_client.py - AEM API client
│ ├── jwt_auth.py - JWT authentication
│ ├── models.py - Data models
│ └── constants.py - Configuration constants
└── .github/workflows/ - CI/CD pipelines🚀 特性
这两种实现都提供了与AEM资产交互的相同工具：
- 列出文件夹 -浏览AEM资产存储库中的文件夹
- 按文件夹列出资产 -获取特定文件夹中的所有资产
- 获取资产详细信息 -检索特定资产的详细信息，包括元数据
- 更新资产元数据 -更新单个资产的元数据字段
- 批量更新元数据 -更新文件夹中所有资产的元数据
🎯 我应该使用哪种实现？
| 功能 | REST API（Vercel） | MCP服务器（云运行） |
|---|---|---|
| 目标平台 | ChatGPT操作 | 支持MCP的ChatGPT |
| 协议 | HTTP REST | 基于SSE的JSON-RPC |
| 部署 | Vercel（无服务器） | 谷歌云运行（容器） |
| 模式 | OpenAPI 3.0 | MCP协议 |
| 最适合 | 标准ChatGPT集成 | 原生MCP客户端（ChatGPT、克劳德桌面） |
建议：
- 使用 REST API 如果您通过操作与ChatGPT自定义GPT集成（最常见）
- 使用 MCP 服务器 如果您的ChatGPT支持本机MCP协议连接
📋 先决条件
AEM访问
- Adobe Experience Manager资产作者API访问
- AEM基本URL（例如。， https://author-pXXXXXX-eXXXXXXX.adobeaemcloud.com) - OAuth服务器到服务器凭据 （现代 /adobe/* API）： - 客户端ID - 客户端密钥 - JWT服务帐户凭据 （经典 /api/assets API - 带有私钥的服务帐户JSON文件 - 看 GET_CREDENTIALS.md 详细设置
REST API要求
- Python 3.12+
- Vercel帐户（用于部署）
- 带有自定义GPT的ChatGPT Plus/Pro
MCP服务器要求
- Python 3.12+
- 码头工人
- 谷歌云平台帐户
gcloud命令行界面- GitHub帐户（用于CI/CD）
🛠️ 技术栈
共享组件
- Python 3.12 -核心语言
- HTTPX -异步HTTP客户端
- 派丹蒂克 -数据验证
- 双重认证:
- OAuth服务器到服务器（现代AEM API） - JWT服务帐户（经典AEM API）
REST API堆栈
- 快速API -现代异步web框架
- 维塞尔 -无服务器部署
MCP服务器堆栈
- 快速MCP -MCP协议实现
- 码头工人 -集装箱化
- 谷歌云运行 -容器托管
- 地形 -基础设施即代码
- GitHub操作 -CI/CD
📁 项目结构
.
├── rest-api/ # REST API Implementation (Vercel)
│ ├── app/
│ │ ├── __init__.py
│ │ └── main.py # FastAPI application
│ ├── requirements.txt
│ ├── vercel.json # Vercel deployment config
│ └── openapi-schema.json # ChatGPT Actions schema
├── mcp-server/ # MCP Server Implementation (Cloud Run)
│ ├── app/
│ │ ├── __init__.py
│ │ └── main.py # FastMCP application
│ ├── requirements.txt
│ └── Dockerfile # Container configuration
├── shared/ # Shared AEM Client Logic
│ ├── __init__.py
│ ├── aem_client.py # AEM API client (OAuth + JWT)
│ ├── jwt_auth.py # JWT Service Account auth
│ ├── models.py # Pydantic data models
│ └── constants.py # Configuration constants
├── terraform/ # Infrastructure as Code
│ ├── main.tf
│ ├── variables.tf
│ └── terraform.tfvars.example
├── .github/workflows/ # CI/CD Pipelines
│ ├── deploy-cloud-run.yml # MCP Server → Cloud Run
│ ├── terraform-apply.yml # Terraform deployment
│ └── test.yml # Testing workflow
├── vercel.json # Root Vercel config (points to rest-api/)
└── README.md🚀 快速开始
选择您的实施路径：
选项A:用于ChatGPT操作的REST API
本地开发
- 克隆仓库:
cd "SC Practice 20260130 - Assets MCP"- 创建虚拟环境:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项:
pip install -r rest-api/requirements.txt- 配置环境:
# Copy example env
cp rest-api/env.example .env
# Edit with your AEM credentials
# Required:
# - AEM_BASE_URL
# - AEM_CLIENT_ID
# - AEM_CLIENT_SECRET
# - AEM_SERVICE_ACCOUNT_JSON (path to service-account.json)
nano .env看 GET_CREDENTIALS.md 了解如何获取您的证书。
- 本地运行REST API:
cd rest-api
uvicorn app.main:app --reload访问 http://localhost:8000 查看服务器信息。
部署到 Vercel
看 部署_仓库.md 详细说明。
选项A：本地部署（最快）
# Install Vercel CLI
npm i -g vercel
# Deploy (from project root)
vercel
# Add environment variables via Vercel dashboard:
# - AEM_BASE_URL
# - AEM_CLIENT_ID
# - AEM_CLIENT_SECRET
# - AEM_SERVICE_ACCOUNT_JSON (paste JSON content)
# Deploy to production
vercel --prod选项B：GitHub操作（自动CI/CD）
设置一次，然后在每次推送时自动部署 main:
- 获取Vercel凭据（请参阅 部署_仓库.md)
- 添加GitHub机密：
- VERCEL_TOKEN - VERCEL_ORG_ID - VERCEL_PROJECT_ID
- 推至
main或手动触发工作流
您的API将在以下网址提供： https://your-project.vercel.app/api/mcp
在以下位置使用OpenAPI模式 rest-api/openapi-schema.json 配置ChatGPT操作。
______________________________________________________________________
选项B：用于本地MCP支持的MCP服务器
本地开发
- 安装MCP服务器依赖项:
pip install -r mcp-server/requirements.txt- 配置环境 （与REST API相同）：
cp rest-api/env.example .env
nano .env # Add your AEM credentials- 在本地运行MCP服务器:
cd mcp-server
python -m app.mainMCP服务器将从端口8080上的SSE传输开始。
部署到Google Cloud Run
看 DEPLOYMENT_CLOUDRUN.md 详细说明。
使用GitHub操作的快速步骤:
- 设置GCP项目并启用API
- 配置工作负载身份联合 （参见 CLOUD_RUN_SETUP_GUIDE.md)
- 添加GitHub机密:
- GCP_PROJECT_ID - GCP_REGION - GCP_WORKLOAD_IDENTITY_PROVIDER - GCP_SERVICE_ACCOUNT - AEM_BASE_URL - AEM_CLIENT_ID
- 创建GCP机密:
echo -n "your_client_secret" | gcloud secrets create aem-client-secret --data-file=-
echo -n "$(cat service-account.json)" | gcloud secrets create aem-service-account-json --data-file=-- 触发器部署:
- 转到GitHub操作→ “部署到Google Cloud Run”→ “运行工作流”
您的MCP服务器将在以下网址提供： https://aem-assets-mcp-server-xxxxx.run.app
使用MCP服务器URL从ChatGPT连接。
______________________________________________________________________
🧪 测试
测试REST API
# List folders
curl -X POST http://localhost:8000/api/mcp \
-H "Content-Type: application/json" \
-d '{"tool": "list_folders", "arguments": {"path": "/"}}'
# List assets in a folder
curl -X POST http://localhost:8000/api/mcp \
-H "Content-Type: application/json" \
-d '{"tool": "list_assets_by_folder", "arguments": {"folderPath": "/MyFolder"}}'测试MCP服务器
看 测试.md 获取全面的测试指南，包括：
- API直接AEM测试
- JWT令牌生成
- MCP检查器使用
______________________________________________________________________
🔧 配置
两种实现都使用相同的环境变量：
| 变量 | 描述 | 必填 | 示例 |
|---|---|---|---|
AEM_BASE_URL | AEM作者实例URL | ✅ | https://author-pXXXXXX.adobeaemcloud.com |
AEM_CLIENT_ID | OAuth客户端ID | ✅ | a41e805f8c3042d3bba66ff1c05f1e94 |
AEM_CLIENT_SECRET | OAuth客户端密码 | ✅ | p8e-xxx... |
AEM_SERVICE_ACCOUNT_JSON | JWT服务帐户（文件路径或JSON字符串） | ✅ | ./service-account.json |
API端点和作用域 配置在 shared/constants.py:
- 现代API：
/adobe/assets,/adobe/folders（OAuth） - 经典API：
/api/assets（JWT） - IMS令牌：
https://ims-na1.adobelogin.com/ims/token/v3 - 范围：
openid,AdobeID,aem.assets.author,aem.folders
______________________________________________________________________
📚 文档
- GET_CREDENTIALS.md -如何获得AEM证书
- JWT_SETUP.md -JWT服务帐户设置
- 部署_仓库.md -将REST API部署到Vercel
- DEPLOYMENT_CLOUDRUN.md -MCP服务器部署到云运行
- CLOUD_RUN_SETUP_GUIDE.md -详细的云运行设置
- 测试.md -测试指南
- 位置_开发.md -当地发展提示
______________________________________________________________________
🤝 ChatGPT集成
对于REST API（ChatGPT操作）
- 在ChatGPT中创建自定义GPT
- 转到“配置”→ “行动”
- 从导入架构
rest-api/openapi-schema.json - 将服务器URL设置为Vercel部署
- 使用以下提示进行测试：
- “列出/content/dam/中的所有文件夹” - “显示MyFolder文件夹中的资产” - “更新资产XYZ的描述”
用于MCP服务器（本机MCP）
- 在支持MCP的ChatGPT中创建自定义GPT
- 使用您的Cloud Run URL配置MCP连接
- MCP服务器将自动公开所有工具
- 使用相同的自然语言提示进行测试
______________________________________________________________________
🔐 安全说明
- 永不承诺
.env文件或service-account.json - 将GitHub Secrets用于CI/CD
- 使用GCP密钥管理器进行云运行
- 将Vercel环境变量用于Vercel部署
- 定期轮换凭据
- 查看AEM用户权限
______________________________________________________________________
🐛 故障排除
常见问题
问题：JWT身份验证在Cloud Run中不起作用
- 原因:
AEM_SERVICE_ACCOUNT_JSON必须包含JSON字符串，而不是文件路径 - 修复：使用JSON内容创建机密：
gcloud secrets create aem-service-account-json --data-file=service-account.json
问题：秘密管理员的权限被拒绝
- 原因：Cloud Run服务帐户缺少权限
- 修复：赠款
roles/secretmanager.secretAccessor:
gcloud secrets add-iam-policy-binding aem-client-secret \
--member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"问题：403禁止AEM
- 原因：身份验证不正确或权限不足
- 修复：验证凭据，检查AEM用户是否具有正确的产品配置文件（AEM管理员）
问题：Vercel部署失败
- 原因：重组后的路径问题
- 修复：确保
vercel.json指向rest-api/app/main.py
看 测试.md 了解更多故障排除步骤。
______________________________________________________________________
📝 许可证
MIT许可证-有关详细信息，请参阅许可证文件
______________________________________________________________________
🙏 致谢
- Adobe Experience Manager资产API
- FastAPI和FastMCP团队
- 模型上下文协议规范
______________________________________________________________________
选项2：使用Terraform
cd terraform
# Copy and edit variables
cp terraform.tfvars.example terraform.tfvars
nano terraform.tfvars
# Initialize Terraform
terraform init
# Preview changes
terraform plan
# Deploy infrastructure
terraform apply选项3：手动部署Docker
# Build and tag
docker build -t gcr.io/YOUR_PROJECT/aem-mcp-server .
---
Made with ❤️ for AEM + AI Integration