# 广告自动化开放协议

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

# AdCP - 广告自动化开放标准

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

[![GitHub stars](https://img.shields.io/github/stars/adcontextprotocol/adcp?style=social)](https://github.com/adcontextprotocol/adcp)
[![Documentation](https://img.shields.io/badge/docs-adcontextprotocol.org-blue)](https://adcontextprotocol.org)
[![npm version](https://img.shields.io/npm/v/@adcp/client)](https://www.npmjs.com/package/@adcp/client)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)

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

## 文档

访问 [adcontextprotocol.org](https://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
```bash
npm install @adcp/client
```
- **NPM 包**：[@adcp/client](https://www.npmjs.com/package/@adcp/client)
- **GitHub**：[adcp-client](https://github.com/adcontextprotocol/adcp-client)

#### Python
```bash
pip install adcp
```
- **PyPI 包**：[adcp](https://pypi.org/project/adcp/)

### 面向平台提供商

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

1. **阅读规范**：[信号协议](https://adcontextprotocol.org/docs/signals/specification)
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 讨论**：[加入对话](https://github.com/adcontextprotocol/adcp/discussions)
- **邮件列表**：announcements@adcontextprotocol.org

### 贡献

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

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

详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。

## 参考实现

- [信号代理](https://github.com/adcontextprotocol/signals-agent)
- [销售代理](https://github.com/adcontextprotocol/salesagent)

## 平台实现

### 当前支持

- **参考实现**：完整的 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. 安装依赖
```bash
npm install
```

#### 2. 环境配置

复制环境模板并配置密钥：
```bash
cp .env.local.example .env.local
```

#### 3. 数据库设置（必需）

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

# 运行迁移
npm run db:migrate
```

#### 4. 启动开发环境

**方式一：一起运行所有服务（推荐）**
```bash
npm run dev
```

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

**方式二：单独运行各服务**
```bash
# 终端 1：启动服务器
npm start

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

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

### 访问地址

- http://localhost:3000 - 主页
- http://localhost:3000/registry - 代理注册表
- http://localhost:3000/adagents - AdAgents.json 管理器
- http://localhost:3000/schemas/v1/index.json - 模式注册表
- http://localhost:3000/api/agents - REST API
- http://localhost:3333 - Mintlify 文档（单独运行时）

### 数据库操作

```bash
# 运行迁移
npm run db:migrate
```

### 其他命令

```bash
# 运行测试
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` 创建订阅。

**触发测试事件：**
```bash
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
```

### 分析与商业智能

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

#### 配置 Metabase

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

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

2. **初始设置**（仅首次）：
   - 打开 http://localhost:3001
   - 创建管理员账户
   - 进入 Admin → Settings → Embedding
   - 启用"在其他应用中嵌入"
   - 复制嵌入密钥

3. **在 `.env.local` 中添加 Metabase 配置：**
```bash
METABASE_SITE_URL=http://localhost:3001
METABASE_SECRET_KEY=<your-secret-key-from-metabase>
```

4. **连接 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`

5. **创建第一个仪表板：**
   - 在 Metabase 中新建仪表板（如"收入分析"）
   - 使用预置分析视图添加查询（参见 [ANALYTICS.md](./ANALYTICS.md)）
   - 启用仪表板嵌入（分享 → 嵌入 → 启用）
   - 从 URL 记录仪表板 ID（如 `/dashboard/2` → ID 为 `2`）

6. **配置嵌入仪表板：**
```bash
# 添加到 .env.local
METABASE_DASHBOARD_ID=2
```

7. **重启开发服务器并访问分析：**
```bash
npm run dev
```

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

#### 填充测试收入数据

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

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

将创建以下示例数据：
- 初始订阅付款
- 数月内的循环付款
- 示例退款
- 所有分析视图的数据

#### 分析文档

关于以下内容的详细信息：
- 可用分析视图（收入、客户健康、订阅）
- 示例 SQL 查询
- 仪表板模板
- 故障排查

详见 [ANALYTICS.md](./ANALYTICS.md)

#### 生产环境分析

**推荐方式：直接 SQL 访问**

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

**可用分析视图：**
- `monthly_revenue_summary` - 按月收入趋势
- `customer_health` - 活跃订阅和客户状态
- `product_revenue` - 按产品细分收入
- `revenue_events` - 单笔收入交易记录

**查询示例：**
```sql
-- 月度收入趋势（近 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;
```

**访问生产数据库：**
```bash
# 从 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。

**生成安全密钥：**

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

### Docker 部署

```dockerfile
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](./LICENSE) 许可证。

## 联系方式

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

## 使用场景

### 面向广告技术公司
- 构建统一的广告自动化工具
- 通过单一 API 集成多个平台
- 启用 AI 驱动的广告工作流
- 创建兼容 MCP 的广告服务器

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

### 面向发布商和广告网络
- 通过标准化协议开放库存
- 启用 AI 助手集成
- 参与自动化广告生态系统
- 一次实现，兼容所有 AI 工具

## 关键词

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

## 链接

- **官网**：[adcontextprotocol.org](https://adcontextprotocol.org)
- **API 文档**：[任务参考](https://adcontextprotocol.org/docs/media-buy/task-reference/index)
- **MCP 集成**：[MCP 指南](https://adcontextprotocol.org/docs/protocols/mcp-guide)
- **规范**：[信号协议 RFC](https://adcontextprotocol.org/docs/signals/specification)
- **讨论**：[GitHub 讨论](https://github.com/adcontextprotocol/adcp/discussions)
- **问题反馈**：[提交 Issue](https://github.com/adcontextprotocol/adcp/issues)

---

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