Kaminari Ad

@kaminari-ad/mcp

适用于 Kaminari Ad 的官方模型上下文协议（MCP）服务——由 Kaminari Click 背后的团队打造的广告验证平台。

让 AI Agent（Cursor、Claude Desktop、Cline 及任何兼容 MCP 的客户端）通过 API 密钥直接对接你的 Kaminari Ad 工作区，启动扫描、查看结果、管理广告系列和策略，以及读取警报。

一键安装

Cursor

了解服务的功能以及如何连接任意客户端：Kaminari Ad MCP 概览。

Claude Desktop

下载 kaminari-ad-mcp.mcpb → 双击安装。Claude Desktop 会显示 API 密钥配置表单。

Claude Code（命令行）

claude mcp add kaminari-ad -- npx -y @kaminari-ad/mcp
export KAMINARI_AD_API_KEY=your-key

完整安装文档请参阅下方的快速入门。

---

快速入门

1. 注册并获取 API 密钥

1. 在 https://app.kaminari.ad/signup 注册（免费方案，无需银行卡）。
2. 登录后，前往 Settings → API Keys 并生成一个新密钥，或者让现有的 AI 助手（使用临时登录）调用 create_api_key 工具——两种方式的结果相同。
3. 密钥只会显示一次。请复制保存。完整密钥会立即在服务器端进行哈希处理。

密钥是随机的不透明字符串——没有规定的前缀或固定长度。请将整个值视为原始机密，并原样粘贴到客户端配置中。

提示：评估人员／Anthropic Software Directory 审核人员可发邮件至 [email protected]，向团队申请一个预置了示例扫描、广告系列和警报的沙盒测试账户。

2a. 本地安装（stdio 传输）

添加到 MCP 客户端配置中（Cursor：~/.cursor/mcp.json；Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "kaminari-ad": {
      "command": "npx",
      "args": ["-y", "@kaminari-ad/mcp"],
      "env": {
        "KAMINARI_AD_API_KEY": "<your-kaminari-ad-api-key>",
      },
    },
  },
}

重启客户端。你应该会在 MCP 服务列表中看到 kaminari-ad，其中提供了 108 个工具。

2b. 托管 HTTP 传输（无需安装）

对于云端 Agent 或没有本地 Node 运行时的客户端，可连接托管端点：

{
  "mcpServers": {
    "kaminari-ad": {
      "url": "https://mcp.kaminari.ad/mcp",
      "headers": {
        "Authorization": "Bearer <your-kaminari-ad-api-key>",
      },
    },
  },
}

2c. OAuth 2.0（Claude 目录、第三方 Agent）

托管服务会在 https://mcp.kaminari.ad/.well-known/oauth-protected-resource 发布 RFC 9728 受保护资源元数据，并指向 Kaminari Ad Authorization Server （https://app.kaminari.ad）。对 /mcp 的任何未经身份验证的请求都会返回 WWW-Authenticate: Bearer resource_metadata="…" 标头，以便符合规范的 MCP 客户端（Claude.ai、Claude Code、第三方 Agent）通过 PKCE S256 + Dynamic Client Registration（RFC 7591）完成 OAuth 2.0 授权码流程。

# Discovery — works without any credential
curl -sk https://mcp.kaminari.ad/.well-known/oauth-protected-resource

# Triggering the WWW-Authenticate hint
curl -isk https://mcp.kaminari.ad/mcp -X POST \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

API 密钥仍是 CLI 和一次性脚本的推荐方式——OAuth 仅适用于需要按应用征求同意并按应用撤销授权的交互式 Agent。两种 Bearer 类型都会访问同一个 /mcp 端点；服务会将令牌原样转发给 API，由 API 判断该令牌是由哪种凭据类型签发的。

---

工具

共 109 个工具，覆盖 Kaminari Ad 的公共 /api/v1 接口。每个工具都带有 MCP 行为注释（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint），以便 MCP 客户端在执行破坏性操作前发出警告。完整列表如下，按领域划分：

• 账户（14）— get_account、update_org、list_org_users、invite_user、update_user_role、remove_user、transfer_ownership、list_org_roles、create_custom_role、list_account_labels、update_account_labels、list_api_keys、create_api_key、revoke_api_key
• 扫描（13）— list_scans、get_scan、list_scan_children、create_scan、create_bulk_scans、recheck_scans、cancel_scan、get_scan_screenshot、get_scan_creative_screenshot、get_scan_landing_screenshot、get_scan_creative_html、get_scan_creative_video、get_scan_vast_xml
• 广告活动（10）— list_campaigns、list_campaigns_picker、get_campaign、create_campaign、update_campaign、archive_campaign、unarchive_campaign、cancel_campaign、run_campaign、list_campaign_runs
• 广告活动组（10）— list/get/create/update/run/cancel/archive/unarchive + pause_campaign_group_schedule、resume_campaign_group_schedule
• 运行（3）— get_run、list_run_scans、cancel_run（使用 list_campaign_runs 枚举某个广告活动的运行记录——该 API 没有独立的 /runs 索引）
• 标签（5）— list_tags、get_tag_definition、update_tag_definition、delete_tag_definition、list_scan_tags
• 自定义规则（7）— list_custom_rules、get_custom_rule、create_custom_rule、update_custom_rule、delete_custom_rule、test_custom_rule、test_custom_rules_batch
• 自定义分类体系（7）— list_custom_taxonomies、get_custom_taxonomy、create_custom_taxonomy、update_custom_taxonomy、delete_custom_taxonomy、restore_custom_taxonomy、parse_custom_taxonomy_text
• 策略集（11）— list_policy_sets、get_policy_set、create_policy_set、update_policy_set、delete_policy_set、request_policy_set_approval、unpublish_policy_set、set_default_policy_set、list_policy_set_campaigns、attach_policy_set_campaigns、detach_policy_set_campaigns
• 警报（4）— list_alerts、update_alert_status、bulk_update_alert_status、get_alert_stats
• Webhook（11）— list_webhooks、get_webhook、create_webhook、update_webhook、delete_webhook、list_webhook_event_types、list_webhook_deliveries、test_webhook、rotate_webhook_secret、replay_webhook_delivery、bulk_replay_webhook
• 计费（4）— get_billing_summary、list_usage、get_usage_summary、list_balance_history
• 开票（2）— list_invoices、get_invoice_pdf
• 警报通知（5）— list_alert_destinations、delete_alert_destination、set_alert_destination_version、get_campaign_alert_overrides、set_campaign_alert_overrides
• 参考数据（3）— list_geos、list_emulators、get_proxy_targeting

截图（get_scan_screenshot、get_scan_creative_screenshot、get_scan_landing_screenshot）以 MCP 内联 image 块的形式返回；get_invoice_pdf 和 get_scan_creative_video 则以内联资源块的形式返回——无需二次获取，也无需预签名 URL。两个文本文件（get_scan_creative_html、get_scan_vast_xml）会以字符串形式返回，模型可直接读取。网关会限制所有文件下载的大小——文本文件为 256 KiB，二进制文件为 8 MiB——并会在读取过程中拒绝超出限制的文件，而不是先缓冲再拒绝。

未提供（有意如此）：公开营销表单。这些表单用于接收针对 kaminari.ad 本身的匿名提交，并非面向 Agent 的能力。

示例 Agent 提示词

以下三个提示词分别使用不同的工具组合，并展示了典型的 Agent 工作流：

1. “扫描 https://news.example.com/article-promo，检查美国、英国、德国的移动设备配置文件，并标记任何重定向到付费墙的情况。” 涉及 list_emulators → create_bulk_scans → 等待 → list_scans（status=completed）→ get_scan → list_scan_tags。
2. “创建一个活动，每小时重新检查一次 brand-x.com 的主页，检查地区为日本和美国；如果出现恶意软件标签，就通过 Slack 提醒我。” 涉及 list_emulators → list_policy_sets（查找包含 malware 的规则集）→ create_campaign（schedule_enabled=true）→ attach_policy_set_campaigns → list_alert_destinations → set_campaign_alert_overrides（mode: "override"，并指定 Slack 目标）。
3. “我上个月在广告验证上花了多少钱？哪些活动产生了这笔费用？” 涉及 get_usage_summary → list_usage（包含 date_from/date_to）→ 按 scan_id 分组 → get_scan → get_campaign 以确定归属。

服务器本身提供完整的机器可读工具列表——使用任意 MCP 客户端连接并调用 tools/list。

---

安全性与租户隔离

托管的 HTTP 端点由单个进程为多个组织提供服务。我们非常重视跨租户隔离：

• MCP 服务是严格的无状态、逐请求直通服务。它会将你的 Authorization 标头原样转发给 Kaminari Ad API，并且不会在请求之间存储任何租户状态。
• 不使用缓存，也不在内存中存储按任何租户相关信息索引的数据。
• HTTP 模式下启动时会拒绝 KAMINARI_AD_API_KEY 环境变量（仅限 stdio 模式）——不存在默认备用令牌。
• 会话 ID 与初始化会话的 Bearer 的 SHA-256 哈希绑定；使用不同的 Bearer 重用会话会被拒绝。
• 绝不会记录 Bearer。只记录其 8 个字符的哈希前缀以便关联。
• 请参阅 tests/isolation/，了解每次 CI 运行都会执行、用于落实上述所有规则的回归测试套件。

如需报告安全问题，请参阅 SECURITY.md。

---

开发

Docker 方式（构建无需本地安装 Node，但主机端提交钩子请参阅 CONTRIBUTING）：

make check           # lint + format-check + typecheck + arch-gates + test-cov
make test            # full test suite
make test-unit       # unit only
make test-isolation  # tenant-isolation suite

如果主机上安装了 Node >=22.19.0，也可以直接使用 npm（与 engines.node 一致；.nvmrc 固定了次版本，以确保开发环境与 CI 一致）。此软件包严格要求 22.19.0，因为 [email protected] 需要 node:worker_threads 提供 markAsUncloneable（Node 22.19+）。

npm ci --legacy-peer-deps
npm run lint && npm run typecheck && npm test

开发工作流以及如何添加工具，请参阅 CONTRIBUTING.md。

维护者会在私有 GitLab 实例上运行完整的开发检查（集成测试、部署自动化、生产环境冒烟测试），并将仓库镜像到 GitHub。GitHub Actions 上的公开 CI（.github/workflows/ci.yml）会在每个社区 PR 上运行 lint、类型检查、单元测试、构建和包大小检查，让贡献者无需访问内部基础设施即可快速获得通过或失败的反馈。推送标签（v*.*.*）会触发 .github/workflows/release.yml，通过 OIDC 来源证明将软件包发布到 npm、创建 GitHub Release，并将 server.json 发布到官方 MCP Registry。

---

稳定性

此软件包的公共接口包括：

1. CLI 二进制文件 kaminari-ad-mcp 及其 --transport stdio|http 标志、.env.example 中记录的环境变量，以及退出代码（0 / 1 致命错误 / 2 配置无效）。
2. 每个已注册工具所实现的 MCP 线协议（工具名称、输入架构、输出结构、注解）。未来主版本中弃用的工具至少会继续运行一个次要版本，并在控制台发出警告。

其他所有内容——从 dist/bin.d.ts 导出的 TypeScript 类型、深层导入、内部类结构——都不属于公共契约，并且可能在任何版本中发生变化。请将此软件包视为 CLI，而非库。

我们对上述两项遵循语义化版本规范。各版本的记录请参阅 CHANGELOG.md。

---

隐私

• **MCP 服务自身收集的数据：**除其转发的 Authorization 标头外，不收集任何数据。HTTP 传输是无状态的——不会持久化会话；每个请求都会通过自身的 Bearer 独立进行身份验证。唯一的内存状态是按 sha256(bearer) 键控的漏桶限流器。
• **转发至 Kaminari Ad 的数据：**每次工具调用都会通过 HTTPS 直接转发至 /api/v1。适用 Kaminari Ad 隐私政策：https://kaminari.ad/privacy。
• **日志：**结构化的 pino 输出；HTTP 模式下使用 JSON。完整的 Bearer 令牌会被屏蔽；日志行中只会记录 bearer_hash = sha256(token).slice(0,8)，以及 request_id、tool_name、api_status、elapsed_ms。不会记录工具输入（其中可能包含客户扫描 ID / URL）。
• **遥测：**无。OSS 构建使用 NoopErrorReporter。我们不会捆绑 Sentry、OpenTelemetry 导出器或 PostHog。

报告安全或隐私问题，请参阅 SECURITY.md。

了解更多

• Kaminari Ad MCP 概览 — 介绍 Agent 可通过该服务执行的操作，以及各客户端的设置方法。
• MCP 服务开发者文档 — 介绍传输方式、身份验证和 OAuth 连接应用。
• REST API 快速入门 — 介绍每个工具都会调用的 /api/v1 接口。
• 恶意广告、自动重定向和隐藏行为检测 — 介绍扫描判定可能标记的内容。
• 广告技术栈中的 DarkSword：iOS 漏洞利用链 — Kaminari Ad 团队的研究。

许可证

MIT — 详见 LICENSE。