mc-skills/catalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
catalog/repos/adcontextprotocol--adcp.md

15 KiB
Raw Blame History

广告自动化开放协议

广告技术 MCP协议 AI自动化 程序化广告 开放标准

AdCP - 广告自动化开放标准

基于 MCP 和 A2A 协议的广告自动化开放标准

GitHub stars Documentation npm version MCP Compatible

AdCP 通过提供一套统一的、AI 驱动的协议，彻底革新广告自动化领域，支持所有主流广告平台。

文档

访问 adcontextprotocol.org 查看完整文档。

什么是 AdCP？

广告上下文协议（Ad Context Protocol，AdCP）是一套广告自动化开放标准，使 AI 助手能够通过自然语言与广告平台进行交互。AdCP 定义了基于 MCP 和 A2A 传输层的领域专属任务和数据结构：

  • 🔌 统一广告 API - 面向所有广告平台的单一接口
  • 🤖 AI 驱动自动化 - 专为自然语言广告活动管理而生
  • 📊 跨平台分析 - 跨所有平台的标准化报告
  • 🔓 开放标准 - 无厂商锁定，社区驱动开发
  • ⚡ 程序化就绪 - 专为现代广告技术工作流设计

快速示例

无需在复杂界面中导航，直接说：

"找到对高端跑步鞋感兴趣的优质运动爱好者受众信号，并在 Scope3 上激活。"

AI 助手会自动处理：

  • 跨平台信号发现
  • 透明定价比较
  • 在决策平台上直接激活

可用协议

🎯 信号激活协议 - RFC/v0.1

使用自然语言发现并激活数据信号。

  • 自然语言发现："对可持续时尚感兴趣的高收入千禧一代"（受众信号）
  • 情境信号："高可见度的优质汽车内容"
  • 多维度组合：结合地理、时间和行为信号
  • 多平台激活：跨 DSP 和数据平台部署
  • 透明定价：CPM 和收益分成模式
  • 实时状态：跟踪激活和部署进度

📍 精选协议 - 即将推出

基于情境和品牌安全要求精选媒体库存。

💰 媒体购买协议 - RFC/v0.1

跨平台以编程方式执行并优化媒体购买。

快速开始

安装客户端库

JavaScript/TypeScript

npm install @adcp/client

Python

pip install adcp

面向平台提供商

实现 AdCP，为您的客户启用 AI 驱动的工作流：

  1. 阅读规范：信号协议
  2. 实现 MCP 服务器：参考参考实现
  3. 测试您的实现：使用验证测试套件

面向广告主和代理商

使用支持 AdCP 的平台配合您的 AI 助手：

  1. 检查平台支持：查看哪些平台支持 AdCP
  2. 配置您的 AI：将支持 AdCP 的平台连接到 Claude、GPT 或其他助手
  3. 开始使用：用自然语言描述您的营销目标

仓库结构

adcontextprotocol/
├── mintlify-docs/          # Mintlify 文档 (docs.adcontextprotocol.org)
│   ├── docs/              # 协议文档
│   │   ├── signals/       # 信号协议
│   │   ├── media-buy/     # 媒体购买协议
│   │   └── creatives/     # 创意协议
├── server/                # Express 服务器
│   ├── src/              # TypeScript 服务器代码
│   └── public/           # 静态 HTML 页面（主页、注册表 UI）
├── static/               # 静态资源
│   └── schemas/          # JSON 模式
├── registry/             # 代理注册表
│   ├── creative/         # 创意代理
│   ├── media-buy/        # 媒体购买代理
│   └── signals/          # 信号代理
└── README.md            # 本文件

社区

工作组

加入我们的工作组，共同塑造广告协议的未来：

  • 每月例会：每月第一个星期三
  • GitHub 讨论：加入对话
  • 邮件列表：announcements@adcontextprotocol.org

贡献

我们欢迎来自以下方面的贡献：

  • 平台提供商：实现并改进协议
  • 代理商和广告主：分享用例和反馈
  • 开发者：贡献代码、文档和示例
  • 行业专家：帮助定义标准和最佳实践

详见 CONTRIBUTING.md。

参考实现

平台实现

当前支持

  • 参考实现：完整的 MCP 服务器示例
  • Scope3：完整信号激活协议支持
  • 更多平台：其他平台将于 2025 年第一季度接入

本地开发

本仓库运行一个统一的 Express 服务器，从单一进程提供所有服务：

  • 🏠 主页 - /
  • 🤖 代理注册表 - /registry - 浏览并测试所有 AdCP 代理
  • 📋 AdAgents 管理器 - /adagents - 验证和创建 adagents.json 文件
  • 📚 Mintlify 文档 - 完整协议文档
  • 📄 JSON 模式 - /schemas/*
  • 🔧 REST API - /api/*
  • 📡 MCP 协议 - /mcp

前置条件

  • Node.js 18+
  • Docker（用于本地数据库）
  • npm 或 yarn

快速开始

1. 安装依赖

npm install

2. 环境配置

复制环境模板并配置密钥：

cp .env.local.example .env.local

3. 数据库设置（必需）

# 在 Docker 中启动 PostgreSQL
docker-compose up -d

# 运行迁移
npm run db:migrate

4. 启动开发环境

方式一：一起运行所有服务（推荐）

npm run dev

启动内容：

  • HTTP 服务器（蓝色）- 应用运行在 3000 端口
  • Mintlify 文档（绿色）- 文档运行在 3333 端口
  • Stripe CLI（紫红色）- Webhook 转发（如已配置 Stripe）

方式二：单独运行各服务

# 终端 1：启动服务器
npm start

# 终端 2：启动文档（可选）
npm run start:mintlify

# 终端 3：启动 Stripe Webhook（可选，如已配置 Stripe）
npm run start:stripe

访问地址

数据库操作

# 运行迁移
npm run db:migrate

其他命令

# 运行测试
npm test

# 类型检查
npm run typecheck

# 构建 TypeScript
npm run build

# 以 MCP 模式启动（stdio）
npm start:mcp

环境变量

所有环境变量在服务器启动时验证。完整模板请参见 .env.local.example。

服务器配置：

  • PORT - 服务器端口（默认：3000）
  • NODE_ENV - 环境（development|production）
  • MODE - 服务器模式（http|mcp）
  • LOG_LEVEL - 日志级别（trace|debug|info|warn|error|fatal，开发默认：debug，生产默认：info）

数据库配置（必需）：

  • DATABASE_URL - PostgreSQL 连接字符串（必需）
  • DATABASE_SSL - 启用 SSL（默认：false）
  • DATABASE_SSL_REJECT_UNAUTHORIZED - 验证 SSL 证书（启用 SSL 时默认：true）
  • DATABASE_MAX_POOL_SIZE - 连接池大小（默认：20）
  • DATABASE_IDLE_TIMEOUT_MS - 空闲超时（默认：30000）
  • DATABASE_CONNECTION_TIMEOUT_MS - 连接超时（默认：5000）

认证（注册表功能必需）：

  • WORKOS_API_KEY - WorkOS API 密钥（必需）
  • WORKOS_CLIENT_ID - WorkOS OAuth 客户端 ID（必需）
  • WORKOS_COOKIE_PASSWORD - 会话加密密钥，最少 32 个字符（必需）
  • WORKOS_REDIRECT_URI - OAuth 回调 URL（默认：http://localhost:3000/auth/callback）

计费（可选 - Stripe）：

  • STRIPE_SECRET_KEY - Stripe 密钥（sk_test_... 或 sk_live_...）
  • STRIPE_PUBLISHABLE_KEY - Stripe 公钥（pk_test_... 或 pk_live_...）
  • STRIPE_PRICING_TABLE_ID - 订阅 UI 的 Stripe 定价表 ID
  • STRIPE_WEBHOOK_SECRET - Webhook 签名密钥（whsec_...，开发环境由 Stripe CLI 自动提供）

注意： 注册表现仅支持数据库存储。运行服务器必须提供 DATABASE_URL。如果启动时数据库不可用，服务器将立即失败（快速失败行为），确保不会在缺少数据持久化的情况下意外运行。

本地 Stripe 测试

使用 npm run dev 或 npm run start:stripe 时，Stripe CLI 会将 Webhook 转发至 localhost:3000/api/webhooks/stripe 并在控制台打印 Webhook 签名密钥。使用测试卡号 4242 4242 4242 4242 创建订阅。

触发测试事件：

stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated

分析与商业智能

AdCP 集成了由 Metabase 驱动的分析功能，用于追踪收入、客户健康指标和订阅分析。

配置 Metabase

  1. 启动 Metabase 容器：
docker-compose -f docker-compose.metabase.yml up -d

Metabase 将在 http://localhost:3001 可用

  1. 初始设置（仅首次）：

    • 打开 http://localhost:3001
    • 创建管理员账户
    • 进入 Admin → Settings → Embedding
    • 启用"在其他应用中嵌入"
    • 复制嵌入密钥

  2. 在 .env.local 中添加 Metabase 配置：

METABASE_SITE_URL=http://localhost:3001
METABASE_SECRET_KEY=<your-secret-key-from-metabase>

  1. 连接 PostgreSQL 数据库：

    • 在 Metabase 中：Admin → Databases → Add database
    • 类型：PostgreSQL
    • 主机：host.docker.internal（Mac/Windows）或 172.17.0.1（Linux）
    • 端口：5432（或 docker-compose 中的 PostgreSQL 端口）
    • 数据库：adcp_registry
    • 用户名：adcp
    • 密码：localdev

  2. 创建第一个仪表板：

    • 在 Metabase 中新建仪表板（如"收入分析"）
    • 使用预置分析视图添加查询（参见 ANALYTICS.md）
    • 启用仪表板嵌入（分享 → 嵌入 → 启用）
    • 从 URL 记录仪表板 ID（如 /dashboard/2 → ID 为 2）

  3. 配置嵌入仪表板：

# 添加到 .env.local
METABASE_DASHBOARD_ID=2
  1. 重启开发服务器并访问分析：
npm run dev

访问 http://localhost:3000/admin/analytics 查看嵌入仪表板！

填充测试收入数据

向分析功能填充测试数据：

# 填充测试收入事件用于分析
psql $DATABASE_URL -f scripts/seed-test-revenue.sql

将创建以下示例数据：

  • 初始订阅付款
  • 数月内的循环付款
  • 示例退款
  • 所有分析视图的数据

分析文档

关于以下内容的详细信息：

  • 可用分析视图（收入、客户健康、订阅）
  • 示例 SQL 查询
  • 仪表板模板
  • 故障排查

详见 ANALYTICS.md

生产环境分析

推荐方式：直接 SQL 访问

对于低流量场景，使用预置分析视图直接查询生产数据库：

可用分析视图：

  • monthly_revenue_summary - 按月收入趋势
  • customer_health - 活跃订阅和客户状态
  • product_revenue - 按产品细分收入
  • revenue_events - 单笔收入交易记录

查询示例：

-- 月度收入趋势（近 12 个月）
SELECT month, total_revenue / 100.0 as revenue_usd
FROM monthly_revenue_summary
ORDER BY month DESC LIMIT 12;

-- 活跃订阅数量
SELECT COUNT(*) FROM customer_health
WHERE subscription_status = 'active';

-- 按产品划分收入
SELECT product_name, total_revenue / 100.0 as total_usd
FROM product_revenue
ORDER BY total_revenue DESC;

访问生产数据库：

# 从 Fly.io 密钥获取连接字符串
fly ssh console --app adcp-docs -C "echo \$DATABASE_URL"

# 使用 psql 连接
psql <DATABASE_URL>

/admin/analytics 仪表板使用 SQL 视图提供内置分析，无需外部 BI 工具。

安全要求

生产环境必须使用 HTTPS：

⚠️ 重要：会话 Cookie 和认证令牌在生产和预发环境中必须通过 HTTPS 传输。

  • 设置 NODE_ENV=production 以启用安全 Cookie
  • 使用反向代理（nginx、Caddy 或云负载均衡器）终止 TLS
  • 从 Let's Encrypt 或您的证书提供商获取 SSL 证书
  • 将 WORKOS_REDIRECT_URI 更新为 https:// 方案

开发环境设置：

在本地开发中，为方便起见 Cookie 通过 HTTP 发送。这仅在 localhost 上可接受。对于预发环境，即使使用自签名证书也应始终使用 HTTPS。

生成安全密钥：

# 生成 WORKOS_COOKIE_PASSWORD（最少 32 个字符）
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Docker 部署

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
ENV NODE_ENV=production
EXPOSE 3000
CMD ["npm", "start"]

许可证

广告上下文协议规范采用 Apache 2.0 许可证。

联系方式

  • 一般咨询：hello@adcontextprotocol.org
  • 技术支持：support@adcontextprotocol.org
  • 安全问题：security@adcontextprotocol.org
  • 合作洽谈：partnerships@adcontextprotocol.org

使用场景

面向广告技术公司

  • 构建统一的广告自动化工具
  • 通过单一 API 集成多个平台
  • 启用 AI 驱动的广告工作流
  • 创建兼容 MCP 的广告服务器

面向代理商和广告主

  • 跨所有平台自动化广告活动管理
  • 使用自然语言进行广告操作
  • 获取统一的分析和报告
  • 降低集成和维护成本

面向发布商和广告网络

  • 通过标准化协议开放库存
  • 启用 AI 助手集成
  • 参与自动化广告生态系统
  • 一次实现，兼容所有 AI 工具

关键词

广告自动化、程序化广告 API、MCP 广告集成、AI 广告工作流、统一广告平台 API、广告协议标准、模型上下文协议广告、跨平台广告自动化

链接

由广告技术社区用心构建。