aep

⚡ 三行搞定

claude mcp add aep \
  -e AEP_CLIENT_ID=... -e AEP_CLIENT_SECRET=... \
  -e AEP_ORG_ID=...@AdobeOrg -e AEP_SANDBOX_NAME=your-dev-sandbox \
  -- npx -y @focusgts/aep-mcp-server

然后直接向你的 Agent 提出要求：

“创建一个包含 Demographic Details 字段组的架构，然后基于它创建一个数据集。” “摄取这个 NDJSON 文件，并告诉我数据批次何时到达。” “创建一个受众，包含本季度购买过两次的客户，并将其激活。” “删除此电子邮件地址对应的所有记录——先进行试运行。”

除非你主动启用写入功能，否则写入操作默认关闭；而 safe 模式只会在 Adobe 判定为开发环境的沙盒中解锁写入功能。

与众不同的工作循环

flowchart LR
  A["📐 Compose<br/>schema from field groups"] --> B["🗂️ Create<br/>dataset"]
  B --> C["📥 Ingest<br/>batch · upload · complete"]
  C --> D["🎯 Activate<br/>segment → destination"]
  D --> E["🧹 Govern<br/>erasure · expiration · quota"]
  E -. "re-audit the tenant" .-> A

Adobe 的第一方网关可以告诉你 Experience Platform 租户中有什么，但无法创建数据集、写入数据批次、激活受众或提交删除请求。这个服务可以做到这些，并且所有操作都受默认拒绝的保护机制控制。

🧠 工作原理

flowchart LR
  A["AI agent<br/>(Claude · Cursor · Copilot)"] -- MCP / stdio --> B["aep-mcp-server<br/>61 tools"]
  B --> W{{"write guard<br/>fail-closed"}}
  W --> C["Schema Registry · Catalog<br/>Ingestion · Lifecycle · Privacy"]
  C --> F["Your AEP sandbox<br/>platform.adobe.io"]
  B --> J["Journey Optimizer<br/>read-only"]
  J --> K["ajo campaigns"]
  B --> Q["Customer Journey Analytics<br/>read-only, no sandbox"]
  Q --> L["cja.adobe.io"]

Agent 调用工具；服务通过 OAuth Server-to-Server 与 Adobe 的实时 API 通信。写入保护机制位于 HTTP 客户端中，而非每个工具内部，因此所有 61 个工具都受其保护，不会有任何工具遗漏。被拦截的调用绝不会到达 Adobe。

🛡️ 默认安全

三种安全模式。任何模式下都不会限制读取。

safe 如何判定——以及为何不看沙盒名称。 生产沙盒可以有任意名称，而名为 prod 的沙盒也可能不是生产环境。只有 Sandbox Management API 中 Adobe 提供的 type 字段才是判定依据。

默认拒绝。 如果无法确定类型——凭据无法读取沙盒元数据、API 出错，或启动尚未完成——就会禁止写入。凭据不能因为能力更弱而获得写入权限。无法识别的 AEP_MODE 会回退到 safe，因此拼写错误绝不会授予生产环境写入权限。

如果沙盒名称正好是 prod，则无条件拒绝操作，并且会在解析模式之前进行拒绝——因此 AEP_MODE=production 也无法解除限制。仅当你的沙盒确实名为 prod 时，才使用 AEP_I_UNDERSTAND_THIS_WRITES_TO_PROD=true 覆盖限制。这种推断有意采用不对称设计：信任名称来允许写入并不安全，信任名称来拒绝写入则是安全的，因为最坏情况只是拒绝操作，而你可以主动覆盖。

默认完全禁用变更操作，除非设置了 AEP_ALLOW_MUTATIONS=true。这与 AEP_MODE 分开设置是有意为之：选择一种写入模式，不应该同时意味着“是的，你可以修改我的数据”。

启动时始终会显示当前启用的安全模式：

SAFE MODE — sandbox is a development sandbox, so writes are ENABLED.
SAFE MODE — sandbox is PRODUCTION, so writes are BLOCKED. Reads work normally.
SAFE MODE — sandbox type could not be confirmed, so writes are BLOCKED (fail-closed).
READ-ONLY MODE — no write, update, or delete will be performed in any sandbox.
PRODUCTION MODE — writes permitted against ANY sandbox, including production.

按工具设置确认门槛

写入操作并非一律设有门槛——一律设门槛会让 Agent 无法使用。门槛设在不可逆且影响范围广的操作上，并且每项检查都在任何网络调用之前进行：

确认信息会注明目标。 带有数据集 ID 的短语——对于记录删除，还会带上身份信息的哈希——无法从一次调用复制到另一次调用。通用的 "I understand this is irreversible" 只需输入一次，就能批准任何删除操作。

身份值绝不会离开进程。 aep_create_record_delete 返回计数、命名空间名称和摘要——绝不会返回你传入的电子邮件地址或设备 ID。记录删除请求本质上是一份真实人员名单；会回显这些信息的工具，会将它们复制到触及的每份对话记录和日志中。

批次创建和文件上传有意不设门槛：这些写入是增量式的，且可恢复。多余的批次可以不完成；已写入的数据则可通过 Data Hygiene 工具移除。

工具注解

每个工具都带有 MCP 注解——readOnlyHint、destructiveHint、idempotentHint、openWorldHint——这些注解与构建工具描述的元数据来自同一来源，因此两者不会出现偏差。

这些是面向客户端的提示，并非强制措施——上方的防护机制才负责执行。它们的价值在于，Claude Desktop 这样的客户端会使用 destructiveHint 来判断何时应暂停并询问人工。没有这些提示时，aep_delete_profile 看起来就和 aep_list_schemas 一样。测试会精确断言破坏性工具列表，因此新增第九个工具是有意为之，而非疏忽。

🛠️ 61 个工具

所有工具都使用 aep_ 前缀和 verb_noun 命名。🔒 表示会更改状态 · 🔥 表示具有破坏性。

数据建模与摄取

治理 — 隐私、生命周期与事件路由

由此解锁的工作流

端到端摄取数据 — create_schema → create_dataset → create_batch → upload_batch_file → complete_batch → get_batch_status

构建并激活受众群体 — create_segment → estimate_segment_size → list_destinations → create_destination_connection → activate_segment

处理删除请求 — get_profile_by_identity → create_record_delete → get_work_order_status

按计划停用数据 — create_dataset_expiration → list_dataset_expirations → update_dataset_expiration → cancel_dataset_expiration

每个工具实际在实时租户上运行过的内容，记录在 docs/VALIDATION-MATRIX.md 中——包括那些有文档且经过模拟、但刻意从未执行的接口，以及原因。

Adobe Journey Optimizer（2）

AJO 是单独授权的独立 Adobe 产品——因此使用 ajo_ 前缀，让授权失败一目了然。

刻意不提供写入操作。相关路由确实存在，但对于一个会向真实用户发送消息的产品，发布未经验证的写入路径并不值得。

📊 AEC-Bench — 你的 Agent 真能正常工作吗？

这个领域里的每个 MCP 服务都用工具数量来描述。它衡量的是覆盖面，而非能力：五十个工具全都返回 404，得分也高于十个能正常工作的工具。

bench/ 是一个 Agent 基准测试，用来衡量另一件事——给定一项真实任务和一个实时租户，Agent 能否完成任务？你又能证明这一点吗？

npm run bench          # tier 1, read-only, safe on any tenant
npm run bench:write    # tier 2, creates and removes what it creates

当前结果：第 1 级 5/5，第 2 级 2/2，零残留。 第 3 级（不可逆）已定义，但刻意留空——其任务不可取消，可能耗时 30 天；运行基准测试并不是执行这类任务的好理由。

对于我们尚未构建支持的任务，我们预计得分会很低。这正是设计初衷。

📈 客户旅程分析（10）

现在，一个 OAuth 凭据即可用于三项 Adobe 服务。 将 Customer Journey Analytics API 添加到拥有 AEP_CLIENT_ID 的同一个 Developer Console 项目中，cja_* 工具便会启用——无需第二个密钥，也无需单独认证。

AEP 沙盒和 CJA 公司并非一回事

CJA 客户端绝不会发送 x-sandbox-name。 CJA 没有沙盒概念，附加该请求头充其量毫无意义，在跟踪记录中还会造成误导。

公司发现，以及为什么可能无法成功

Adobe 文档中所述的发现端点是 GET https://analytics.adobe.io/discovery/me。该主机属于 Adobe Analytics——这是与 CJA 不同的产品。 拥有 CJA 权限但没有 Analytics 权限的凭据会在此处收到 403003 Api Key is invalid：密钥本身没有问题，只是没有 Analytics 权限。CJA 没有自己的发现功能。

实际上，这不会造成任何阻碍：CJA 仅凭 x-gw-ims-org-id 就能响应所有资源，因此公司 ID 是可选的。

# Optional. Omit it and CJA scopes by IMS org, which is what works by default.
CJA_GLOBAL_COMPANY_ID=your-global-company-id

cja_list_companies 会报告当前使用的上下文，以及发现功能是否可用。如果发现结果返回多个公司且未设置覆盖项，它会拒绝选择——静默选择第一个会导致后续所有报告都指向错误的公司。

运行探测和实时测试

node scripts/probe-cja.mjs --env .env          # read-only, sanitized output
CJA_LIVE_TESTS=1 npm test -- tests/integration/cja-live.test.ts

除非设置 CJA_LIVE_TESTS=1，否则实时测试会跳过，因此 npm test 始终可在隔离环境中运行。这些测试是只读的，绝不会输出凭据或完整的 Adobe 响应。

如实说明当前限制

• 没有修改工具。 此部分按设计仅提供只读功能。
• 仅有 CJA 权限的凭据无法使用发现功能，如上所述。这不是工具的缺陷。
• cja_get_connection 未经验证——验证租户没有任何连接，也绝不会伪造 ID 来制造通过的结果。
• 维度和指标的分页不起作用。 CJA 会将它们包装在一个看似支持分页的 content 信封中，但 limit 和 page 会被忽略——已通过实时验证，无论如何都会返回全部 38 个维度。search、limit 和 offset 由客户端应用，输出中也会说明这一点。

🥊 与 Adobe 第一方 Experience Platform 工具对比

Adobe 通过 CX Coworker Gateway 提供第一方工具。这是一款真正不错的产品，如果你只需要询问有关租户的问题，就使用它。

关于 Journey Optimizer 和 CJA： Adobe 为两者分别提供了第一方 MCP 服务，因此上表有意不声称它们“未涵盖”——那样说是不准确的。该服务的新增价值在于，一个凭据即可覆盖这三者，并且提供 Adobe 网关不支持的 AEP 写入路径。这里的 AJO 和 CJA 工具为只读。

受众和目标位置也有提供，但位于同一网关上独立的 Real-Time CDP 工具集中；而且 Adobe 明确表示，该处同样不支持创建、激活、更新或删除受众、目标位置和数据流。整个网关都遵循只读限制。

两者互为补充，而非竞争关系：将 Adobe 网关用于受治理的读取操作，将此服务用于写入。

Adobe 的数据摘自其 Experience Platform 工具页面（最后更新于 2026 年 7 月 17 日）：search_datasets、search_class_relations、search_data_access、search_data_lake、search_dule、search_query_service、search_audit、search_allowed_ip_ranges。这是一个 Beta 版本，后续会有变化——请查看其文档以了解当前数据。读写权限的差异才是长期存在的区别，而非数量。

🔌 将其添加到你的工具中

claude mcp add aep \
  -e AEP_CLIENT_ID=... -e AEP_CLIENT_SECRET=... \
  -e AEP_ORG_ID=...@AdobeOrg -e AEP_SANDBOX_NAME=your-dev-sandbox \
  -- npx -y @focusgts/aep-mcp-server

{
  "mcpServers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@focusgts/aep-mcp-server"],
      "env": {
        "AEP_CLIENT_ID": "...",
        "AEP_CLIENT_SECRET": "...",
        "AEP_ORG_ID": "...@AdobeOrg",
        "AEP_SANDBOX_NAME": "your-dev-sandbox"
      }
    }
  }
}

{
  "mcpServers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@focusgts/aep-mcp-server"],
      "env": {
        "AEP_CLIENT_ID": "...",
        "AEP_CLIENT_SECRET": "...",
        "AEP_ORG_ID": "...@AdobeOrg",
        "AEP_SANDBOX_NAME": "your-dev-sandbox"
      }
    }
  }
}

{
  "servers": {
    "aep": {
      "command": "npx",
      "args": ["-y", "@focusgts/aep-mcp-server"],
      "env": {
        "AEP_CLIENT_ID": "...",
        "AEP_CLIENT_SECRET": "...",
        "AEP_ORG_ID": "...@AdobeOrg",
        "AEP_SANDBOX_NAME": "your-dev-sandbox"
      }
    }
  }
}

🔐 凭据

前往 developer.adobe.com/console 获取：创建项目 → 添加 Experience Platform API → OAuth Server-to-Server。

AEP_SANDBOX_NAME 刻意不设默认值。 过去它会回退到 prod，这意味着配置文件漏掉一行时，所有请求（包括读取请求）都会在没有警告的情况下静默指向生产环境。不存在安全的默认值：在错误环境中读写数据之前，错误的猜测和正确的设置无法区分。允许显式设为 prod；这是一个明确且有意的选择，而且写入保护仍会拒绝在该环境中执行变更操作。

沙盒范围限定。 每个工具都会发送 x-sandbox-name，Query Service 会将其数据库推导为 <AEP_SANDBOX_NAME>:all。

🧾 许可权益

并非每个 Adobe 组织都为所有 AEP 产品购买了许可。工具返回 AEP_403 通常意味着缺少许可权益，而非凭据错误。

🏗️ 架构

全程采用 TypeScript strict、@modelcontextprotocol/sdk + zod、stdio 传输，每个请求均无状态。

flowchart LR
  C["MCP client<br/>Claude · Cursor<br/>Copilot · ChatGPT"]
  T["aep-mcp-server<br/><b>61 tools</b><br/>14 categories"]
  G{{"write guard<br/>fail-closed"}}
  A1["Schema Registry<br/>· Catalog"]
  A2["Batch Ingestion"]
  A3["UPS · Segmentation<br/>· Destinations"]
  A4["Data Lifecycle<br/>· Privacy"]
  IMS[/"Adobe IMS<br/>OAuth S2S"/]

  C -- "stdio · JSON-RPC 2.0" --> T
  T -- "every call, no exceptions" --> G
  IMS -. "token cache · 401 re-auth" .-> T
  G -- "HTTPS · Bearer · x-sandbox-name" --> A1
  G --> A2
  G --> A3
  G --> A4

采用 OAuth Server-to-Server，配备去重令牌缓存、带 PII 脱敏的结构化 pino 日志、指数退避重试、401 自动重新认证、可用的游标分页、结构化 AEP_{status} 错误代码，以及优雅关闭生命周期。所有日志均输出到 stderr — stdout 专用于 MCP JSON-RPC 流。

🧪 开发

git clone https://github.com/Focus-GTS/aep-mcp-server.git
cd aep-mcp-server && npm install && npm run build && npm test

npm run dev          # tsx src/server.ts (hot-reload)
npm test             # vitest — 509 tests
npm run typecheck    # tsc --noEmit
npm run tools        # print the registered tool surface

npm run test:live 会针对真实 IMS 组织和沙盒运行只读冒烟测试，以端到端验证凭据、许可权益和沙盒范围限定。它不会调用任何破坏性工具，并要求 AEP_SANDBOX_NAME 指向非生产沙盒。

🧩 Focus GTS Adobe 套件的一部分