mcpField
A
Apple Ads MCP

Apple Ads MCP

本地服务
github.com/zelentsov-dev商业与营销7今天更新

关于 Apple Ads MCP

Apple Ads MCP 是面向 Apple Ads Platform API v1 的本地优先 MCP 服务,用于研究和管理 App Store 广告账户。它向 MCP 客户端提供类型化账户工具,并通过预览、限时回执和验证约束变更。

主要功能

  1. 01检查广告系列、应用和账户
  2. 02研究关键词与投放表现
  3. 03类型化报告与账户审计
  4. 04需预览的广告系列操作
  5. 05基于回执的应用与验证

适用场景

  1. 01不作更改地审计广告系列结构
  2. 02发掘关键词机会
  3. 03规划并验证广告系列更新

MCP 相关

向 MCP 客户端开放 Apple Ads 研究、报告和广告系列操作等类型化工具。默认只读;写入须通过配置的权限门控、预览回执和验证。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"zelentsov-dev-apple-ads": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"APPLE_ADS_MCP_CONFIG",
"ghcr.io/zelentsov-dev/apple-ads-mcp:v0.3.8"
],
"env": {
"APPLE_ADS_MCP_CONFIG": "<APPLE_ADS_MCP_CONFIG>"
}
}
}
}
启动命令docker run -i --rm -e APPLE_ADS_MCP_CONFIG ghcr.io/zelentsov-dev/apple-ads-mcp:v0.3.8
需要配置的环境变量
APPLE_ADS_MCP_CONFIGPath to a mounted Apple Ads MCP accounts configuration file.

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
ocighcr.io/zelentsov-dev/apple-ads-mcp:v0.3.8

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

Apple Ads MCP

CI Release Go License

Apple Ads MCP 是一个本地优先的 Model Context Protocol 服务,适用于 Apple Ads Platform API v1。它为 Codex、Claude 和其他 MCP 客户端提供类型化工具,用于研究、检查和安全地操作 App Store 广告账户。

该服务默认只读。凭据保存在你的设备上,每次账户范围的调用都会明确指定配置文件和广告账户,并且每次变更都必须先预览,再使用短时有效的一次性回执。

Apple Ads MCP 是独立的开源软件,与 Apple Inc. 无关联,未获其认可或赞助。Apple Ads 和 App Store 是 Apple Inc. 的商标。

快速开始

在 macOS 或 Linux 上使用 Homebrew 安装已发布的二进制文件:

brew install zelentsov-dev/tap/apple-ads-mcp
apple-ads-mcp version

创建本地只读配置文件。该命令会保存私钥的绝对路径;切勿将私钥粘贴到聊天、问题单、日志或代码仓库中:

apple-ads-mcp config init
apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

使用绝对 Homebrew 路径注册服务,确保桌面应用和 IDE 扩展不依赖继承的 Shell PATH。

Codex:

codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list

Claude Code:

claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads

重启已运行的桌面应用、CLI 会话或 IDE 扩展,然后开始新对话。可以先安全地这样请求:

调用 server_info,然后针对我明确指定的配置文件、广告账户和应用运行 account_health。不要启用写入操作。

其他实用的只读入门请求:

  • “列出我可以投放广告的应用,并说明任何资格缺口。”
  • “审查我当前的 Apple Ads 广告系列结构,不做任何更改。”
  • “寻找关键词机会,并区分 Apple 提供的依据和你的推断。”

当前版本

v0.3.8 是当前版本。此版本使广告系列和广告组的 bidStrategy.bid 架构及运行时验证与 Apple Ads Platform API v1 保持一致(广告系列使用 TargetCpa,广告组使用默认的 Max CPT);将广告系列切换到 MANUAL_CPT 时,会明确发送 "bid": null,以便 Apple 清除之前的 TargetCpa;并在 operations_verify 中规范化十进制金额字符串。请参阅 v0.3.8 版本与迁移说明。

v0.3.5 的版本归档命名、v0.3.4 的按公式限定信任、v0.3.3 的精确路径验证,以及 v0.3.2 的单命令引导均保持不变。

优化绝不会自主进行:该服务没有调度程序,也不会在后台更改支出。只读会话可以建立基准并制定计划。应用计划仍须满足所有写入门控条件、启用具名策略、使用一份回执、通过最新报告和库存漂移检查,并进行逐项验证。

此版本支持 Apple 提供的四种 App Store 广告版位:

  • 搜索结果
  • 搜索标签
  • Today 标签
  • 产品页面

版位是否可用仍取决于所选账户、应用、店面、创意素材以及 Apple 的资格响应。不可用的版位会报告为 not_eligible;该服务不会尝试绕过 Apple 的验证。

关键词和否定关键词是搜索结果版位的资源。Platform API 会拒绝搜索结果广告系列中明确创建的 Ad 资源,因此该版位需通过其广告系列、广告组、关键词和产品页面配置进行操作;其他版位的明确广告仍受资格限制。每个应用和广告账户只能有一个默认产品页面创意素材,因此操作人员应查询并重复使用该素材,而不要尝试创建重复项。

功能一览

类别主要工具
访问与就绪状态auth_check、ad_accounts_list、ad_account_get、advertiser_resources_list、account_health
App 与店面apps_search、apps_get、apps_eligibility、app_locale_details、supported_app_languages、app_store_geo_search
广告资源campaigns_query、ad_groups_query、keywords_query、negative_keywords_query、ads_query、creatives_query、shared_budgets_query、campaign_inventory
诊断拒登原因、广告系列状态原因、更改历史记录、账户和广告系列审计
调研关键词、短语、类别、目标 CPA 建议、搜索热度、展示份额
报告类型化的广告系列、广告组、广告、关键词和搜索词报告
广告系列操作创建/更新、预算、国家/地区、排期、暂停和恢复预览
广告组操作创建/更新、排期、定向、Search Match、出价、已弃用的 CPA 上限、暂停和恢复预览
关键词单个和批量定向/否定关键词的创建/更新、出价、暂停和恢复预览
广告与创意类型化的 App Store 创意和广告的创建/更新、暂停和恢复预览
建议每日预算和目标 CPA 的读取、应用预览和忽略预览
优化命名的本地策略、28 天基准、学习/活动计划、组合预览/应用/验证,以及有界历史记录
共享预算仅 LOC 的类型化创建/更新/分配/取消分配预览,使用私有本地计费资料
生命周期分别受限的广告系列、广告组、关键词、否定关键词、广告、创意和共享预算删除预览
验证operations_inspect、operations_apply、operations_verify 和直接资源回读

每个列表最多返回 200 个条目,并使用 next 分页。响应包含简洁文本和 MCP structuredContent;不会公开原始 Apple 信封数据和计费联系人 PII。

不提供原始请求工具、账户/委托变更、自动调度器、Apple Maps 界面,也不支持旧版 Campaign Management API v5。

安全模型

只有通过所有关卡后才能执行写入:

  1. Apple API 用户具有兼容的写入角色。
  2. 服务以 --allow-writes 启动。
  3. 所选配置文件的 allowWrites: true。
  4. 专用的 *_preview 工具会验证账户、应用、店面、版位、币种和载荷。
  5. operations_apply 收到同一份未过期的回执。
  6. 受影响的库存仍与预览期间捕获的状态一致。

预览回执在十分钟后过期,且只能用于一次 apply。完整回执记录被清理后,有界墓碑记录仍会保留明确的过期状态。每份变更回执都会为其目标 ID 绑定规范化对象范围,并保留精确的读取指纹;创建和父级删除还会绑定受影响的库存及有界级联范围。因此,涉及重叠对象的通用、批量、删除、推荐、共享预算和优化验证形态无法并发执行。独立的广告组库存仍可并行处理。批量回执会返回逐项的 applied、failed 或 unknown 状态。一份定向关键词批量回执可以包含多个逐项广告组,同时仍只发送一个 Apple 批量请求。Apple 可能只接受部分批次;服务绝不承诺回滚。如果优化 apply 的结果尚未确定,经过清理的恢复方案会保存在仅所有者可见的本地历史记录中,以便 operations_verify 在进程重启或常规预览驱逐后对所提供的回执进行核对。

同一库存快照中的独立预览会在首次 apply 后有意产生状态漂移。若相关关键词创建必须作为一个整体应用,请将它们放入同一批量预览;服务不会削弱这一失败关闭不变量。

变更请求超时后不会重试。除非 operations_verify 和直接回读确认实际状态,否则结果为 committed_unverified,或逐项状态为 unknown。

推荐 apply 操作必须明确提供 maximumAmount。推荐币种必须与广告账户一致,建议金额不得超过上限,并且在 apply 前会重新读取推荐和推广的广告系列。

不可逆删除还需通过五项额外关卡:--allow-deletes、配置文件中的 allowDeletes: true、仅限会话的 APPLE_ADS_ALLOW_DELETES=true、精确的预期对象名称或关键词文本,以及专用删除回执。广告系列和父级对象必须处于 PAUSED 状态;级联库存有范围限制并经过哈希处理;创意不得存在引用它们的广告;共享预算不得有任何分配。结果不明确时绝不重试 DELETE。

发布验证

v0.3.8 版本要求通过完整的兼容性套件、MCP stdio 契约测试、单元测试和 HTTP 测试、竞态检测器、静态分析、漏洞和机密扫描,以及分发验证。跨平台 CI 在 macOS、Linux 和 Windows 上运行。

此版本在 CI 中使用合成验收;针对实时 Apple Ads API v1 的运行时确认属于单独的所有者控制门槛。2026-08-31,v0.3.6 P2 只读矩阵以及一个经单独授权、包含 2 和 28 个项目的 PAUSED 定向关键词批量测试数据,均通过了 Apple Ads API v1 验收。两个汇总回执均已应用,并直接验证了每个返回的关键词 ID;在写入验收期间,广告系列和广告组始终保持 PAUSED。

此前 v0.3.x 的实时验收确认了只读优化基线和计划、PAUSED 测试数据的创建与回读、预算/出价/策略更新、暂停/恢复、回执漂移检查、项目验证,以及对一次性广告系列、广告组、关键词和否定关键词的删除。所有保留的测试数据始终处于 PAUSED 状态,支出为零。

依赖账户的路径有明确的证据边界:

  • 本版本中,主动应用优化计划和更改 MAX_CONVERSIONS 仍仅通过自动化测试验证。优化器建议要求满足现有的历史数据最低要求;对于用户明确请求的预览,则会显示统计准备度尚未确立的警告,同时保留契约验证和写入门槛。
  • 共享预算的创建/更新/分配/删除仍仅通过契约和 HTTP 测试验证,因为实时验收账户使用 PAYG;Apple 要求使用 LOC。
  • 默认产品页广告和创意的删除已确认为 not_eligible,因为 Apple 不允许单独删除这些资源。

这些边界不会削弱默认安全模型:不受支持或缺乏充分证据的操作会安全失败,不会返回成功的空响应。

安装

平台HomebrewGitHub 存档OCI 镜像
macOS arm64 / amd64是.tar.gz仅限 Linux 容器
Linux arm64 / amd64是.tar.gz是
Windows arm64 / amd64否.zip仅限 Linux 容器
Homebrew

官方 tap 会安装经过校验和固定的版本二进制文件:

brew install zelentsov-dev/tap/apple-ads-mcp

之后可使用以下命令升级到后续版本:

brew update
brew upgrade apple-ads-mcp
GitHub 版本

从 GitHub Releases 下载适用于你平台的存档。版本发布包含 SHA-256 校验和及 SPDX SBOM。

Apple 芯片示例:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.8/apple-ads-mcp_darwin_arm64_0.3.8.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.8/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_darwin_arm64_0.3.8.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Windows 用户应验证 checksums.txt,解压对应的 ZIP,并使用可执行文件的绝对路径进行注册。

OCI 镜像
docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.3.8

该镜像默认运行 serve --stdio。以只读方式挂载 accounts.json 及其引用的私钥。

从源代码构建
git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./apple-ads-mcp ./cmd/apple-ads-mcp

需要 Go 1.26.10 或更高版本。

Apple API 设置

Apple Ads API 访问权限与 App Store Connect 访问权限相互独立。Apple Ads 账户管理员必须添加具有适当角色的 API 用户。在需要更改广告系列之前,建议使用 API Account Read Only。

在本地生成 ES256 密钥对:

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

仅将公钥上传到 Apple Ads。切勿将私钥粘贴到 Agent 对话、问题、日志或代码仓库中。Apple 注册密钥后,记录 Apple Ads 界面中显示的客户端 ID、团队 ID 和密钥 ID。

配置

以交互方式创建配置档:

apple-ads-mcp config init

默认配置路径为 ~/.config/apple-ads-mcp/accounts.json:

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false,
      "allowDeletes": false
    }
  ]
}

在 POSIX 系统上,配置文件和私钥必须仅限所有者访问:

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

验证身份验证并发现可访问的广告帐户:

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

配置优先级依次为 --config、APPLE_ADS_MCP_CONFIG、默认文件,然后是单配置档 APPLE_ADS_* 环境变量。支持的单配置档变量包括 APPLE_ADS_PROFILE、APPLE_ADS_CLIENT_ID、APPLE_ADS_TEAM_ID、APPLE_ADS_KEY_ID、APPLE_ADS_PRIVATE_KEY_PATH、APPLE_ADS_AD_ACCOUNT_ID、APPLE_ADS_ALLOW_WRITES 和 APPLE_ADS_ALLOW_DELETES。对于基于文件的配置档,环境变量不会暗中授予持久的写入或删除权限。

连接 MCP 客户端

服务使用 stdio,并且仅向 stdout 写入 MCP JSON-RPC:

apple-ads-mcp serve --stdio

对于带有 CLI 的客户端,优先使用二进制文件的绝对路径。

Codex 全局配置:

codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list

Codex Desktop、Codex CLI 和 IDE 扩展共享相同的主机配置。添加服务后,重启正在运行的客户端并开启新对话。

Claude Code 用户配置:

claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads

Claude 项目配置可以使用仓库的 .mcp.json,但每个工作区/服务都可能要等用户批准后才能使用。批准后,从 /mcp 重新连接或重启 Claude Code。

适用于没有注册命令的客户端的通用 MCP 配置:

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

如果客户端未继承 Homebrew 或 shell 的 PATH,请将 apple-ads-mcp 替换为可执行文件的绝对路径。在 Apple silicon 上,Homebrew 默认路径为 /opt/homebrew/bin/apple-ads-mcp;在 Intel macOS 上,通常为 /usr/local/bin/apple-ads-mcp。

插件和技能包

发布归档包含 .codex-plugin/plugin.json、.mcp.json 和 apple-ads-operator 技能。这些文件为兼容的插件加载器描述服务和安全操作工作流,但它们本身不会安装可执行文件、注册 MCP 服务或授予 Apple Ads 访问权限。此仓库目前未通过公开的 Codex 插件市场分发;使用 Homebrew 并在客户端注册是受支持的公开设置方式。

验证连接

重启客户端后,确认 apple-ads 已启用或已连接,并让它调用 server_info。本地凭据准备就绪后,使用明确的配置档和帐户调用 auth_check、ad_accounts_list 和 account_health。

所有设置验证都必须保持只读。排查安装或身份验证问题时,不要添加 --allow-writes、--allow-deletes、allowWrites 或 allowDeletes。

故障排除
  • 找不到可执行文件: 在客户端配置中使用 "$(brew --prefix)/bin/apple-ads-mcp",而不是仅填写命令。
  • 服务已存在: 仅移除该客户端现有的 apple-ads 条目,然后使用绝对路径重新添加。
  • Claude 显示待批准: 批准项目 MCP 服务,从 /mcp 重新连接,并开启新对话。
  • 正在运行的客户端仍然没有工具: 更改 MCP 配置后,完全重启桌面应用、CLI 会话或 IDE 扩展。
  • 身份验证失败: 在本地运行 apple-ads-mcp auth doctor --profile <profile>,并确认文件权限和非机密标识符;切勿将私钥粘贴到聊天中。
  • Homebrew 拒绝下载的本地 formula: 从可信的 tap 安装:brew install zelentsov-dev/tap/apple-ads-mcp。
Agent 主导的设置

只有在用户批准后,Agent 才能诊断并执行安装。它应验证二进制文件、使用绝对路径、注册指定范围的客户端、重启客户端,并在完成只读健康检查后停止。它绝不能索要私钥内容,也不能暗中启用变更权限。

为单个会话启用写入

保持持久配置文件为只读。对于一个明确授权的操作员会话,启用两个本地开关:

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

此操作本身不会更改任何内容。每次变更仍需明确指定 profile、adAccountId,并经过专用预览、回执应用和验证。

配置按需优化

创建一个命名的本地策略:

apple-ads-mcp optimization policy init
apple-ads-mcp optimization policy validate --name mature-product-balanced
apple-ads-mcp optimization doctor --policy mature-product-balanced

策略存储在 ~/.config/apple-ads-mcp/optimization-policies.json 中,权限模式为 0600。每项策略绑定一个配置文件、一个广告帐户、一个推广应用,以及至多 20 个广告系列 ID。learning 模式不需要业务目标,只返回证据。active 模式需要设置 targetInstallCPA、总预算和单个广告系列每日预算上限,以及对预算、出价、策略、暂停、恢复和重新测试的明确权限。允许更改出价的策略还必须设置正数的帐户货币 maxBid;每日预算上限绝不会被用作出价上限。

balanced 预设要求恰好 28 个连续且已完成的 UTC 日期,并以昨天结束;它会将最近 7 天与之前的 7 天进行比较,应用 72 小时冷却期,通常建议 10% 的变更,且每次运行的变更幅度绝不超过 20%。报告证据缺失、重复、日期为未来、格式错误或溢出时,操作将安全失败。只有当搜索结果中的 Search Match 库存符合条件,且 14 天内平均每天至少有 5 次轻点安装时,它才会建议 MAX_CONVERSIONS。它绝不会建议删除。

典型的 Agent 工作流:

  1. 在只读服务中调用 optimization_baseline 和 optimization_plan。
  2. 将 Apple 建议与计算得出的操作分别审查。
  3. 启动获授权的写入会话,并调用 optimization_plan_preview。
  4. 检查 OperationImpact,应用同一回执一次,然后调用 operations_verify。
  5. 检查 ~/.local/share/apple-ads-mcp/optimization/ 下有界的本地历史记录。

在首次向 Apple 写入之前,服务会在进程间文件锁的保护下,持久保存一条与回执哈希绑定的 applying 意图和经过净化的类型化验证方案。POSIX 提交会同步包含该文件的目录;Windows 使用带写入穿透语义的替换操作。结果未知、验证无法得出结论或历史记录更新中断时,后续优化计划都会被阻止,直到 operations_verify 对所有受影响项目完成明确核对。恢复机制可在进程重启和内存中的回执过期后继续工作,但需要操作员提供原始的不透明回执。核对结果为 matched 或 matched_after 的操作会从原始意图/应用时间开始计算冷却期;matched_before 则不会。只有在已验证、由优化器发起的暂停仍具有相同的 Apple modificationTime 时,广告系列才可自动恢复;之后任何手动变更都会撤销该权限。优化历史记录不会存储任何回执、凭据、原始 Apple 信封或账单联系人信息。

共享预算和生命周期操作

只有当 Apple 报告账户的付款模式为 LOC 时,才能修改共享预算。创建和更新操作会将预算专门绑定到明确选定的广告账户。广告系列分配工具会保留无关的现有分配;跨账户共享预算则会安全失败。请在本地初始化私有账单数据:

apple-ads-mcp billing profile init

~/.config/apple-ads-mcp/billing-profiles.json 的权限必须为 0600。MCP 输入中只包含本地 billingProfile 名称。工具输出、日志、历史记录或收据预览中不会返回买家姓名和电子邮件地址。PAYG 账户会返回 not_eligible,且不会尝试写入。

对于明确授权的破坏性维护会话:

APPLE_ADS_ALLOW_WRITES=true \
APPLE_ADS_ALLOW_DELETES=true \
apple-ads-mcp serve --stdio --allow-writes --allow-deletes

所选的文件型配置文件必须已包含 allowDeletes: true;只有当前进程可以通过 APPLE_ADS_ALLOW_WRITES=true 启用 allowWrites。服务端和会话的删除门控彼此独立。请使用专用的 *_delete_preview,对照完整的级联影响和确切的预期文本,执行一次,然后确认 deleted: true。请勿将生命周期操作纳入优化计划。

操作限制

  • Apple 未提供公开的 Ads API 沙盒。线上变更验收需手动进行、明确启用,使用名称清晰的 PAUSED 测试数据,且绝不纳入自动 CI。
  • 不同账户和店面支持的资格、建议、热门程度、推荐、报告和创意各不相同。
  • 新账户可能没有目标 CPA 或每日预算建议。
  • Apple 会验证广告系列和对象名称;网页 UI 与 API 可能接受不同的标点符号。
  • Apple 不允许在广告系列名称中使用竖线字符(|);请改用带连字符且易读的名称。创建广告组时,必须提供符合 ISO 8601 格式、采用广告账户时区的 startTime。
  • 报告可能会延迟,且在开始投放前一直为空。
  • Apple 不允许单独删除使用 Default Product Page 的广告(CAN_NOT_DELETE_DPP_CREATIVE_AD)。服务端会在预览期间返回 not_eligible;生命周期删除仅适用于可丢弃的 Custom Product Page 广告和创意。
  • 试用和订阅归因由你的归因技术栈负责;仅凭 Apple Ads Platform API 无法证明关键词到试用的归因关系。
已知 Apple API 响应

截至 2026-08-25,该服务端使用的文档所述 v1 请求格式在实际验收期间出现了两种可重复的上游行为:

  • 即使 keyword_suggestions 和 target_cpa_suggestions 对同一自有应用有效,phrase_suggestions 和 category_suggestions 对 SUGGESTION 查询仍可能返回 Apple HTTP 500。
  • 在新账户或完全暂停的账户上,impression_share 可能返回 Apple HTTP 400。账户所有者控制的验收账户未提供代码或诊断详情;公开复现也报告过代码 INVALID_VALUE。近期缺少投放可能与此有关,但这并非 Apple 已确认的前提条件或解决方法。

服务端会将这些响应作为有界的结构化 Apple 错误返回,不会将其转换为空结果或成功结果。对于 4xx,会保留安全的 Apple 代码、消息和详情字段;不会返回请求正文、凭据、任意字段或 5xx 正文。请求格式与当前 Apple Ads Platform API和官方 Apple Java 客户端一致。类似的公开 v1 复现记录见 App Store Connect CLI PR #2057 和 PR #2020。Apple 更改 API 后,或账户积累了有意义的投放记录后,请重新检查。

兼容性

v0.3 保留了所有 v0.2.1 工具名称和架构,并新增了优化、共享预算变更、出价策略和生命周期工具。v0.3.1 在启用出价权限时新增必填项 maxBid,并采用失败时关闭的协调规则;请参阅 v0.3.1 迁移说明。v0.3.2 仅更改分发和引导流程。v0.3.3 将发布验证切换为精确的 tap 公式路径,v0.3.4 为 Homebrew 6 新增限定于公式的信任机制,v0.3.5 则将语义版本号放在归档名称末尾,以明确 Homebrew 版本检测。v0.3.6 保留现有工具名称和兼容的旧版输入,同时新增类型化别名、查询快捷方式、诊断功能和更严格的必需作用域;请参阅 v0.3.6 说明。v0.3.7 新增了感知请求头的请求速率控制、上下文相关的出价验证、报告分组修正,以及持久化的预览警告;请参阅 v0.3.7 说明。v0.3.8 将广告系列和广告组的 bidStrategy.bid 要求分开,在将广告系列切换到 MANUAL_CPT 时通过 "bid": null 清除 TargetCpa,并在 operations_verify 中规范化十进制金额字符串;请参阅 v0.3.8 说明。较旧的客户端还应阅读 v0.3 说明 和 v0.2 说明。

v1.0 之前,公共工具架构尚未冻结。API 系列的作用域和操作状态记录在机器可读的操作矩阵中。官方 Java 客户端基线和 App Store 端点清单记录在 upstream-baseline.json 中。

开发

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run honnef.co/go/tools/cmd/[email protected] -checks 'all,-ST1000,-ST1005' ./...
go run golang.org/x/vuln/cmd/[email protected] ./...
go run github.com/zricethezav/gitleaks/[email protected] dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/[email protected] check
go run github.com/rhysd/actionlint/cmd/[email protected]
npx --yes [email protected] '**/*.md'
python3 scripts/validate_distribution.py
python3 scripts/audit_upstream.py

请参阅 CONTRIBUTING.md、SECURITY.md 和路线图。

许可证

MIT

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。