AEM Assets MCP Server

用于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 如果您通过操作与ChatGPT自定义GPT集成（最常见）
• 使用 MCP 服务器 如果您的ChatGPT支持本机MCP协议连接

📋 先决条件

AEM访问

1. 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

本地开发

1. 克隆仓库:

cd "SC Practice 20260130 - Assets MCP"

1. 创建虚拟环境:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项:

pip install -r rest-api/requirements.txt

1. 配置环境:

# 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 了解如何获取您的证书。

1. 本地运行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:

1. 获取Vercel凭据（请参阅 部署_仓库.md)
2. 添加GitHub机密：

- VERCEL_TOKEN - VERCEL_ORG_ID - VERCEL_PROJECT_ID

1. 推至 main 或手动触发工作流

您的API将在以下网址提供： https://your-project.vercel.app/api/mcp

在以下位置使用OpenAPI模式 rest-api/openapi-schema.json 配置ChatGPT操作。

______________________________________________________________________

选项B：用于本地MCP支持的MCP服务器

本地开发

1. 安装MCP服务器依赖项:

pip install -r mcp-server/requirements.txt

1. 配置环境 （与REST API相同）：

cp rest-api/env.example .env
nano .env  # Add your AEM credentials

1. 在本地运行MCP服务器:

cd mcp-server
python -m app.main

MCP服务器将从端口8080上的SSE传输开始。

部署到Google Cloud Run

看 DEPLOYMENT_CLOUDRUN.md 详细说明。

使用GitHub操作的快速步骤:

1. 设置GCP项目并启用API
2. 配置工作负载身份联合 （参见 CLOUD_RUN_SETUP_GUIDE.md)
3. 添加GitHub机密:

- GCP_PROJECT_ID - GCP_REGION - GCP_WORKLOAD_IDENTITY_PROVIDER - GCP_SERVICE_ACCOUNT - AEM_BASE_URL - AEM_CLIENT_ID

1. 创建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=-

1. 触发器部署:

- 转到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检查器使用

______________________________________________________________________

🔧 配置

两种实现都使用相同的环境变量：

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操作）

1. 在ChatGPT中创建自定义GPT
2. 转到“配置”→ “行动”
3. 从导入架构 rest-api/openapi-schema.json
4. 将服务器URL设置为Vercel部署
5. 使用以下提示进行测试：

- “列出/content/dam/中的所有文件夹” - “显示MyFolder文件夹中的资产” - “更新资产XYZ的描述”

用于MCP服务器（本机MCP）

1. 在支持MCP的ChatGPT中创建自定义GPT
2. 使用您的Cloud Run URL配置MCP连接
3. MCP服务器将自动公开所有工具
4. 使用相同的自然语言提示进行测试

______________________________________________________________________

🔐 安全说明

• 永不承诺 .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