mcp-ad-server 0.0.2

MCP服务器用于处理广告投放数据

广告投放数据平台 MCP 服务

项目概述

这是一个基于 Model Context Protocol (MCP) 的广告投放数据服务器，为 LLM 应用提供智能的广告数据查询和分析能力。通过标准化的MCP协议，LLM可以直接调用广告投放相关的数据查询工具，获取业务洞察和决策支持。

✨ 核心特性

• 🔧 MCP工具集成：提供广告查询、素材分析、指标推荐等MCP工具
• 📊 智能指标推荐：基于业务场景自动推荐相关指标组合
• 🎯 多维数据查询：支持按时间、媒体、分组等维度查询数据
• 📈 89个业务指标：涵盖投放、转化、留存、财务等全链路指标
• 🔗 标准协议支持：完全遵循MCP协议，支持Claude Desktop等客户端
• ⚡ 异步高性能：基于异步架构，支持并发数据查询

🚀 快速开始

# 1. 克隆项目
git clone <repository-url> && cd mcp

# 2. 设置API Token
export BI_API_TOKEN="your_token_here"

# 3. 安装并运行测试
uv sync && uv run python tests/test_server.py

Claude Desktop集成

{
  "mcpServers": {
    "ad-analytics": {
      "command": "/usr/bin/python3",
      "args": ["/path/to/mcp/run_server.py"],
      "env": {"BI_API_TOKEN": "your_token"}
    }
  }
}

⚠️ 重要提示：如果遇到 spawn python ENOENT 错误，请使用完整的 Python 路径（用 which python3 查找）而非 python 命令。Claude Desktop 的 PATH 环境变量与终端不同。

## 📁 项目结构

mcp/ ├── 📄 README.md # 项目说明（本文档） ├── 📄 USER_GUIDE.md # 用户使用手册 ├── 📄 DEVELOPMENT.md # 开发者指南 ├── 📄 ARCHITECTURE.md # 系统架构设计 ├── 🚀 run_server.py # 服务启动脚本 ├── 🧪 tests/ # 测试文件 │ ├── test_server.py # 集成测试 │ ├── test_config.py # 配置测试 │ └── test_dotenv.py # 环境变量测试 │ ├── 💻 src/mcp_ad_server/ # 主要源码 │ ├── main.py # 服务器主入口 │ ├── config.py # 配置管理 │ ├── services/ # 业务服务层 │ │ └── api_client.py # BI API客户端 │ ├── managers/ # 数据管理层 │ │ ├── base.py # Manager基础类 │ │ ├── indicator_manager.py # 指标管理器 │ │ └── propmap_manager.py # 字段映射管理器 │ ├── tools/ # MCP工具实现 │ │ ├── ad_query.py # 广告查询工具 │ │ ├── material_query.py # 素材查询工具 │ │ └── indicator_recommend.py # 指标推荐工具 │ ├── resources/ # MCP资源实现 │ │ ├── indicator_resources.py # 指标资源 │ │ ├── mapping_resources.py # 映射资源 │ │ └── config_resources.py # 配置资源 │ └── prompts/ # MCP提示实现（计划中） │ ├── 📊 data/ # 数据文件（从zhibiao迁移） │ ├── indicators/ # 89个指标定义文件 │ ├── groups/ # 7个指标分组文件 │ └── propmap/ # API字段映射文件 │ └── 📚 docs/ # 原始API文档 └── api/ # API接口文档 ├── GetAdCountList/ # 广告数据统计接口 └── GetMaterialCountList/ # 素材数据统计接口

## 🛠️ MCP 工具功能

### 1. query_ad_data - 广告数据查询
查询广告投放效果数据，支持多维度筛选和分组统计。

**参数**：
- `start_date/end_date`: 查询时间范围 (YYYY-MM-DD)
- `indicators`: 查询指标列表（中文名称）
- `media`: 媒体渠道筛选（gdt、tt、bd等）
- `group_key`: 分组维度（广告ID、项目ID等）
- `hours_24`: 24小时维度查询，支持单天和多天并发查询

**返回结构**：
- `data.columns`: 列名列表（已做中文映射）
- `data.rows`: 二维数组格式的数据行，对应columns顺序
- `data.total`: 当前返回的数据条数
- `data.summary`: 汇总数据（如果存在）

### 2. query_material_data - 素材数据查询
查询广告素材效果和质量数据，支持素材质量筛选。

**参数**：
- `start_date/end_date`: 查询时间范围
- `indicators`: 查询指标列表
- `creative_users`: 创意人筛选
- `producers`: 制作人筛选
- `is_low_quality`: AD优/低质素材筛选
- `is_inefficient`: 低效素材筛选

**返回结构**：同广告数据查询

### 3. recommend_indicators - 智能指标推荐
基于业务场景智能推荐相关指标组合。

**支持场景**：
- `"投放启动"` - 新广告投放决策
- `"效果监控"` - 投放效果实时监控
- `"短期评估"` - 首日到7日价值评估
- `"深度分析"` - 长期价值和留存分析
- `"数据对账"` - 平台数据核对
- `"风险预警"` - 终止决策预警
- `"财务核算"` - 财务相关指标

## ✨ 系统特性

### 🔧 数据处理特性
- **自动总计项处理**: 智能识别和分离后端返回的总计数据
- **LLM优化数据结构**: 提供中文映射的数据格式，便于LLM理解和分析
- **参数别名兼容**: 支持历史参数名向下兼容（如 `appid` ↔ `app_id`）
- **Pydantic类型安全**: 完整的参数验证和数据类型转换

### 📊 数据返回格式
```json
{
  "success": true,
  "data": {
    "columns": ["日期", "消耗", "新增注册", "新增付费"],
    "rows": [
      ["2024-01-01", 100.5, 50, 5],
      ["2024-01-02", 120.0, 60, 8],
      ["2024-01-03", 80.0, 40, 3]
    ],
    "total": 3,            // 当前返回的数据条数
    "summary": {...}       // 汇总数据（如果后端提供）
  },
  "metadata": {...}        // 查询元数据
}

🔄 版本管理

• API客户端版本: v0.0.1
• BI API版本: v0.2.07
• 语义化版本控制: 主版本兼容性保证

📋 MCP 资源访问

指标相关资源

• mcp://indicators/{指标名称} - 获取单个指标详细定义
• mcp://groups/{组ID} - 获取指标组信息
• mcp://config/groups - 获取所有指标组概览

配置相关资源

• mcp://propmap/{API名称} - 获取API字段映射关系
• mcp://config/media_channels - 获取支持的媒体渠道
• mcp://config/group_keys - 获取支持的分组维度

📊 指标体系架构

目前的业务场景指标组

指标组	核心用途	主要指标示例
投放启动决策	判断是否开始投放新广告	激活率、注册成本、创角成本、3秒播放率
投放效果监控	监控投放中广告实时效果	消耗、点击率、新增注册、新增付费
短期价值评估	评估首日到7日用户价值	首日ROI、7日ROI、新增付费率、新增ARPPU
深度价值分析	评估用户长期价值	累计ROI、留存率、生命周期价值
平台数据对账	核对各平台上报数据	平台充值、平台付费人数、数据差异
终止决策预警	判断是否需要停止投放	成本预警、ROI预警、质量预警
财务核算结算	财务结算相关	分成后ROI、实际消耗、结算金额

🔌 客户端集成示例

Claude Desktop 使用

配置完成后，可直接在Claude Desktop中进行对话查询：

请帮我分析一下2025年1月1-7日腾讯广点通渠道的广告投放效果，
重点关注ROI表现和用户转化情况。

程序化调用

# 使用MCP Python SDK
from mcp import ClientSession

async with ClientSession("stdio", ["python", "run_server.py"]) as session:
    # 查询广告数据
    result = await session.call_tool("query_ad_data", {
        "start_date": "2025-01-01",
        "end_date": "2025-01-07",
        "indicators": ["消耗", "新增注册", "首日ROI"],
        "media": ["gdt"]
    })

    # 获取指标推荐
    recommendations = await session.call_tool("recommend_indicators", {
        "business_scenario": "投放启动"
    })

🌐 支持的媒体渠道

渠道代码	渠道名称	渠道代码	渠道名称
gdt	广点通	tt	今日头条
bd	百度	bdss	百度搜索
bz	B站	zh	知乎
uc	UC	dx	抖小广告量
sphdr	视频号达人	xt	星图
gg	谷歌	nature	自然量

📚 文档指南

本项目提供完整的文档体系，请根据您的角色选择合适的文档：

角色	推荐文档	用途
最终用户/运营	USER_GUIDE.md	安装使用、功能操作、业务应用
开发者/贡献者	DEVELOPMENT.md	开发环境、编码规范、扩展开发
架构师/技术负责人	ARCHITECTURE.md	系统设计、组件架构、技术决策

🚀 阅读建议

1. 想要快速使用服务：直接阅读 USER_GUIDE.md 的"快速开始"部分
2. 想要贡献代码：先阅读 ARCHITECTURE.md 了解设计，再看 DEVELOPMENT.md 学习开发规范
3. 想要了解技术架构：重点阅读 ARCHITECTURE.md

🔧 技术特点

• 现代Python架构：基于Python 3.11+
• 模块化设计：清晰的层次分离，Manager模式管理数据
• 标准协议支持：遵循MCP协议规范
• 高性能异步：使用Python 3.11+ TaskGroup实现多天24小时数据并发查询，查询性能提升10-20倍
• 模块化扩展：清晰的组件注册机制，便于添加新工具和资源
• 完整测试覆盖：包含单元测试和集成测试

📈 更新日志

• 2025-08-11: 完善API客户端功能，支持参数别名兼容、自动总计项处理、Pydantic数据验证
• 2025-08-07: 重构文档体系，实现完整MCP服务架构
• 2025-08-07: 初始化项目结构，整理指标体系
• 2025-08-05: 添加API响应示例文件

🤝 技术支持

如有问题或建议，请联系：

• 技术问题：钉钉 AI 开发团队
• 业务咨询：广告投放团队
• 功能建议：通过内部反馈渠道提交

📋 TODO (低优先级)

• 指标配置优化：games/目录中存在72.8%的指标重复，可考虑抽取为分层指标集(base + extensions)以简化配置和维护

---

注意：本项目中的指标分组和推荐算法为测试版本，实际使用时需要与投放团队对接校准业务逻辑。