AEM MCP Server

联系我 领英 或 给我发邮件 讨论定制！

💡 对于对AEM作为云服务的MCP服务器感兴趣的用户，请查看我的其他GitHub项目： AEMaaCS MCP服务器 -一款全面的读写MCP服务器，专为AEM云服务而设计，具有高级功能和企业级功能。

📜 双重许可：该项目已获得许可 AGPL-3.0 供开源使用。 商业许可证可用 适用于需要使用此软件而没有AGPL义务的组织。看 商业_许可证.md 了解详情。

AEM MCP服务器（AEM-MCP服务器）

](https://nodejs.org/)   

AEM MCP Server是Adobe Experience Manager（AEM）的一个全面的、生产就绪的模型上下文协议（MCP）服务器。它为完整的内容、组件、资产和模板管理提供了35+强大的REST/JSON-RPC API方法，并为人工智能、聊天机器人和自动化工作流提供了高级集成。该项目专为希望以编程方式或通过自然语言界面管理AEM的AEM开发人员、内容团队和自动化工程师而设计。

______________________________________________________________________

目录

• 概述
• 特性
• 快速开始
• 使用示例
• 配置
• API和客户端使用
• AI IDE集成（光标、鼠标等）
• 安全
• 项目结构
• 集成
• 贡献
• 许可证

______________________________________________________________________

概述

• 基于TypeScript的现代AEM MCP服务器
• REST/JSON-RPC API 用于AEM内容、组件和资产操作
• AI/LLM集成 （OpenAI、Anthropic、Ollama、自定义HTTP API）
• 电报机器人 用于会话式AEM管理
• 生产就绪、模块化、可扩展

______________________________________________________________________

特性

🚀 核心能力（35+方法）

页面操作（10种方法）

• 页面生命周期：使用适当的模板集成创建、删除、激活/停用页面
• 内容管理：获取页面内容、属性、文本提取和图像管理
• 页面发现：列出具有深度控制、分页和筛选功能的页面
• 出版：使用树操作激活/停用页面

组件操作（7种方法）

• 组件CRUD：创建、更新、删除和验证组件
• 批量操作：使用验证和回滚支持更新多个组件
• 组件发现：扫描页面以发现所有组件及其属性
• 图像管理：通过验证更新图像路径

资产运营（4种方法）

• DAM管理：上传、更新、删除AEM DAM中的资产
• 元数据操作：获取并更新资产元数据
• 文件处理：支持MIME类型检测的多种文件类型

搜索和查询操作（3种方法）

• 高级搜索：QueryBuilder与全文搜索的集成
• JCR查询：执行带有安全验证的JCR SQL2风格查询
• 增强的页面搜索：具有回退策略的智能搜索

模板操作（2种方法）

• 模板发现：获取站点和路径的可用模板
• 模板分析：详细的模板结构和元数据提取

现场和本地化（3种方法）

• 多站点管理：获取网站、语言大师和可用区域设置
• 本地化支持：跨不同语言和地区管理内容

复制和发布（2种方法）

• 内容复制：将内容复制并发布到选定的区域设置
• 取消发布：从发布环境中删除内容

遗留和公用事业运营（5种方法）

• JCR节点访问：直接节点内容访问和子列表
• 系统实用程序：方法列表、状态检查和工作流管理

🔧 技术特性

• REST和JSON-RPC API：双重API支持以实现最大兼容性
• 交互式仪表板：用于API勘探和测试的基于Web的界面
• 综合测试：内置测试套件，具有自动问题跟踪功能
• 增强的错误处理：具有重试机制的结构化错误响应
• 安全：身份验证、路径验证和安全操作默认值
• 演出：连接池、缓存和优化查询

______________________________________________________________________

快速开始

先决条件

• Node.js 18+
• 访问AEM实例（本地或远程）

安装

cd clone
npm install

构建

npm run build

运行（生产）

npm start

运行（开发、热重新加载）

npm run dev

______________________________________________________________________

使用示例

JSON-RPC API示例

1.列出路径下的所有页面

curl -u admin:admin \
  -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "listPages",
    "params": {
      "siteRoot": "/content/mysite",
      "depth": 2,
      "limit": 10
    }
  }'

2.使用模板创建新页面

curl -u admin:admin \
  -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "createPage",
    "params": {
      "parentPath": "/content/mysite/en",
      "title": "New Product Page",
      "template": "/conf/mysite/settings/wcm/templates/page-template"
    }
  }'

3.更新组件属性

curl -u admin:admin \
  -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "updateComponent",
    "params": {
      "componentPath": "/content/mysite/en/home/jcr:content/root/container/text",
      "properties": {
        "text": "Updated content",
        "textIsRich": true
      }
    }
  }'

4.搜索内容

curl -u admin:admin \
  -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "searchContent",
    "params": {
      "type": "cq:Page",
      "fulltext": "product",
      "path": "/content/mysite",
      "limit": 20
    }
  }'

5.将资产上传到DAM

curl -u admin:admin \
  -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "uploadAsset",
    "params": {
      "parentPath": "/content/dam/mysite/images",
      "fileName": "hero-image.jpg",
      "fileContent": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "mimeType": "image/jpeg",
      "metadata": {
        "dc:title": "Hero Image",
        "dc:description": "Main hero image for homepage"
      }
    }
  }'

REST API示例

1.获取所有可用方法

curl -u admin:admin http://localhost:3001/api/methods

2.获取方法详细信息

curl -u admin:admin http://localhost:3001/api/methods/createPage

3.通过REST执行方法

curl -u admin:admin \
  -X POST http://localhost:3001/api/methods/listPages \
  -H 'Content-Type: application/json' \
  -d '{
    "siteRoot": "/content/mysite",
    "depth": 1,
    "limit": 10
  }'

方法类别和示例

页面操作

• createPage -使用适当的模板集成创建页面
• deletePage -使用强制选项删除页面
• listPages -列出具有深度和分页的页面
• getPageContent -提取完整页面内容
• getPageProperties -获取页面元数据和属性
• activatePage / deactivatePage -发布/取消发布页面
• getAllTextContent / getPageTextContent -提取文本内容
• getPageImages -提取图像参考

组件操作

• validateComponent -应用前验证组件更改
• updateComponent -通过验证更新组件属性
• scanPageComponents -发现页面上的所有组件
• createComponent -向页面添加新组件
• deleteComponent -移除组件
• updateImagePath -更新图像组件引用
• bulkUpdateComponents -以原子方式更新多个组件

资产运营

• uploadAsset -将带有元数据的文件上传到DAM
• updateAsset -更新资产元数据和内容
• deleteAsset -从DAM中删除资产
• getAssetMetadata -检索资产元数据

搜索操作

• searchContent -具有灵活参数的查询生成器搜索
• executeJCRQuery -执行JCR查询（QueryBuilder包装器）
• enhancedPageSearch -具有回退功能的智能页面搜索

模板操作

• getTemplates -列出网站的可用模板
• getTemplateStructure -获取详细的模板结构

网站和本地化

• fetchSites -获取所有可用网站
• fetchLanguageMasters -获取网站的语言大师
• fetchAvailableLocales -获取可用区域设置

交互式仪表板

访问web仪表板 http://localhost:3001/dashboard 用于：

• 交互式方法测试
• 参数验证
• 响应可视化
• API 文档
• 批量测试能力

______________________________________________________________________

配置

环境变量

创建一个 .env 项目根目录中的文件包含以下内容（根据需要编辑）：

AEM_HOST=http://localhost:4502
AEM_SERVICE_USER=admin
AEM_SERVICE_PASSWORD=admin
MCP_PORT=8080
GATEWAY_PORT=3001
MCP_USERNAME=admin
MCP_PASSWORD=admin

MCP客户端配置

基于AI的代码编辑器或自定义客户端示例：

{
  "mcpServers": {
    "aem-mcp": {
      "command": "node",
      "args": [
        "absolute path to dist/mcp-server.js"
      ]
    }
  }
}

高级配置选项

# Optional: Advanced AEM Configuration
AEM_SITES_ROOT=/content
AEM_ASSETS_ROOT=/content/dam
AEM_TEMPLATES_ROOT=/conf
AEM_XF_ROOT=/content/experience-fragments
AEM_PUBLISHER_URLS=http://localhost:4503
AEM_DEFAULT_AGENT=publish
AEM_ALLOWED_COMPONENTS=text,image,hero,button,list,teaser,carousel
AEM_QUERY_MAX_LIMIT=100
AEM_QUERY_DEFAULT_LIMIT=20
AEM_QUERY_TIMEOUT=30000
AEM_MAX_DEPTH=5

# Optional: AI Integration (if needed)
# OPENAI_API_KEY=your-openai-key
# TELEGRAM_BOT_TOKEN=your-telegram-bot-token

______________________________________________________________________

API和客户端使用

• REST/JSON-RPC：通过HTTP端点公开所有AEM操作
• 支持的操作：页面/资产CRUD、组件验证/更新、搜索、推出、发布、文本/图像提取等
• AI/LLM：向服务器发送自然语言命令（通过API或Telegram）
• 电报机器人：使用连接您的机器人 TELEGRAM_BOT_TOKEN 并与您的AEM实例聊天

______________________________________________________________________

AI IDE集成（光标、鼠标等）

AEM MCP服务器与支持MCP协议的现代AI IDE和代码编辑器兼容，例如 光标 和 克莱恩.

如何连接：

1. 安装并运行AEM MCP服务器 如上所述。
2. 配置IDE 连接到MCP服务器。光标/线示例：

- 打开IDE的MCP服务器设置。 - 使用以下命令添加新服务器： - 类型： 自定义MCP - 命令： node - Args： ["/absolute/path/to/dist/mcp-server.js"] - 端口： 8080 （或按配置） - 认证： 使用 MCP_USERNAME/MCP_PASSWORD 从你的 .env

1. 重新启动IDE 并连接。IDE现在将能够：

- 列出、搜索和管理AEM内容 - 运行MCP方法（CRUD、搜索、推出等） - 如果启用，则使用AI/LLM功能

自定义MCP客户端

• 您可以用任何支持HTTP/JSON-RPC的语言构建自己的MCP客户端。
• 看 使用示例 用于API调用模式。
• 使用基本身份验证进行身份验证(MCP_USERNAME/MCP_PASSWORD).
• 所有MCP方法均可通过 /api 终点。

______________________________________________________________________

安全

• 所有操作都需要授权（请参阅 MCP_USERNAME/MCP_PASSWORD)
• 基于环境的安全部署配置
• 所有破坏性操作都需要明确的参数和验证

______________________________________________________________________

项目结构

• src/ --TypeScript源代码
• dist/ --编译的JS输出

______________________________________________________________________

集成

• AI/LLM：OpenAI、Anthropic、Ollama、自定义HTTP API
• 电报：基于聊天的AEM管理

______________________________________________________________________

贡献

欢迎投稿！请打开问题或提取错误修复、功能或文档改进请求。

______________________________________________________________________

故障排除

常见问题

连接问题

# Test AEM connection
curl -u admin:admin http://localhost:4502/libs/granite/core/content/login.html

# Check server health
curl http://localhost:3001/health

身份验证问题

• 在中验证AEM凭据 .env 文件
• 检查MCP_USERNAME和MCP_PASSWORD是否访问API
• 确保AEM用户具有足够的权限

页面创建问题

• 没有jcr的空页面：内容：使用正确的模板参数
• 作者中不可见的页面：确保模板存在且有效
• 找不到模板：验证模板路径和权限

组件更新失败

• 未找到组件：验证组件路径是否存在
• 更新失败：检查组件属性和验证
• 权限不足：确保用户具有写访问权限

性能优化

• 使用分页 limit 大型结果集的参数
• 设置适当 depth 页面列表的值
• 配置 AEM_QUERY_TIMEOUT 用于慢速查询
• 对多个组件更新使用批量操作

调试

# Enable debug logging
DEBUG=aem-mcp:* npm run dev

# Check detailed health status
curl http://localhost:3001/health

# List all available methods
curl -u admin:admin http://localhost:3001/api/methods

常见用例

内容迁移

// 1. List source pages
const pages = await listPages({ siteRoot: '/content/source', depth: 3 });

// 2. Create target pages with templates
for (const page of pages.data.pages) {
  await createPage({
    parentPath: '/content/target',
    title: page.title,
    template: '/conf/target/settings/wcm/templates/page'
  });
}

// 3. Copy components
const components = await scanPageComponents({ pagePath: sourcePage });
for (const component of components.data.components) {
  await createComponent({
    pagePath: targetPage,
    componentType: component.resourceType,
    properties: component.properties
  });
}

批量内容更新

// Update multiple text components
const updates = [
  {
    componentPath: '/content/site/page1/jcr:content/text1',
    properties: { text: 'Updated content 1' }
  },
  {
    componentPath: '/content/site/page2/jcr:content/text2',
    properties: { text: 'Updated content 2' }
  }
];

await bulkUpdateComponents({
  updates,
  validateFirst: true,
  continueOnError: false
});

资产管理工作流程

// 1. Upload assets
await uploadAsset({
  parentPath: '/content/dam/project',
  fileName: 'hero.jpg',
  fileContent: base64Content,
  metadata: { 'dc:title': 'Hero Image' }
});

// 2. Update page to use new asset
await updateComponent({
  componentPath: '/content/site/home/jcr:content/hero',
  properties: { fileReference: '/content/dam/project/hero.jpg' }
});

// 3. Publish changes
await activatePage({ pagePath: '/content/site/home' });

搜索和发现

// Find pages by content
const results = await searchContent({
  type: 'cq:Page',
  fulltext: 'product launch',
  path: '/content/mysite'
});

// Get detailed page information
for (const result of results.data.results) {
  const content = await getPageContent({ pagePath: result.path });
  const components = await scanPageComponents({ pagePath: result.path });
}

API 参考

认证

所有API终结点都需要HTTP基本身份验证：

Authorization: Basic base64(username:password)

响应格式

所有回复均遵循以下结构：

{
  "success": true,
  "operation": "methodName",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    // Method-specific response data
  }
}

错误处理

错误响应包括结构化信息：

{
  "success": false,
  "operation": "methodName",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {},
    "recoverable": true,
    "retryAfter": 5000
  }
}

错误处理最佳实践

AEM MCP服务器遵循REST API最佳实践，在响应主体中返回具有结构化错误信息的HTTP 200状态代码。这种方法有几个好处：

1. 一致的响应格式：所有响应，无论是否成功，都遵循相同的JSON结构
2. 详细错误信息：错误响应包括特定代码、消息和详细信息
3. 客户端处理：客户端可以轻松地以编程方式解析和处理错误
4. 可恢复错误与致命错误：The recoverable 标志指示重试是否可能成功
5. 重试指导：适当时， retryAfter 建议等待一段时间后重试

客户端代码中的错误处理示例：

async function callMcpMethod(method, params) {
  const response = await fetch(`/api/methods/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(params)
  });
  
  const result = await response.json();
  
  if (!result.success) {
    // Handle error based on error code and details
    console.error(`Error in ${method}:`, result.error.message);
    
    if (result.error.recoverable && result.error.retryAfter) {
      // Implement retry logic
      console.log(`Retrying after ${result.error.retryAfter}ms`);
      await new Promise(resolve => setTimeout(resolve, result.error.retryAfter));
      return callMcpMethod(method, params); // Recursive retry
    }
    
    throw new Error(`${result.error.code}: ${result.error.message}`);
  }
  
  return result.data;
}

常见错误代码：

许可证

开源许可证（AGPL-3.0）

该项目根据 GNU Affero通用公共许可证v3.0（AGPL-3.0）.

这意味着：

• ✅ 免费使用、修改和分发
• ✅ 如果您将修改后的版本作为网络服务运行 必须提供源代码 对于用户
• ✅ 所有修改也必须根据AGPL-3.0获得许可
• ✅ 非常适合开源项目和内部使用

阅读完整许可证： 许可证

商业许可证

需要在没有AGPL义务的情况下使用此软件吗？

我们为希望实现以下目标的组织提供商业许可证：

• ❌ 将修改保密
• ❌ 集成到专有系统中，无需披露来源
• ✅ 获得优先支持和自定义功能
• ✅ 获得法律保护和赔偿

定价从XXX美元/年开始 带着一个 免费30天评估许可证.

了解更多： 商业_许可证.md

商业许可联系人：

• 📧 电子邮件： indrasish00@gmail.com
• 💼 领英： linkedin.com/in/indrasish/

______________________________________________________________________

为什么双重许可？

该模型使我们能够：

1. 支持开源社区 使用免费、强大的工具
2. 提供企业级支持 面向商业用户
3. 继续开发 有可持续的资金
4. 确保合规性 具有明确的许可条款

如果您不确定需要哪种许可证， 联系我们 以供指导。