Ydirect MCP

Yandex Direct MCP服务器

MCP（模型上下文协议）服务器 Yandex Direct 分析和报告。此服务器提供用于查询分析数据、生成报告和通过标准化MCP界面访问Yandex Direct见解的工具。

🚀 快速开始

先决条件

• Python 3.12+
• 紫外线 （推荐）或pip
• Docker（可选，用于容器化部署）

地方发展

1. 克隆仓库

git clone 
cd ydirect-mcp

1. 安装uv（如果尚未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh

1. 安装依赖项

uv sync

1. 配置环境

cp .env.example .env
# Edit .env with your configuration

1. 运行服务器

uv run python src/server.py

服务器将于启动 http://0.0.0.0:8000 默认情况下。

Docker部署

1. 塑造形象

docker build -t yandex-direct-mcp .

1. 运行容器

docker run -p 8000:8000 \
  -e OTEL_ENDPOINT=http://your-otel-collector:4318/v1/traces \
  -e YANDEX_API_KEY=your_api_key_here \
  yandex-direct-mcp

📡 端点

运行后，服务器将公开以下端点：

• MCP协议: http://0.0.0.0:8000/mcp -用于工具调用的主MCP端点
• 指标: http://0.0.0.0:8000/metrics -Prometheus指标端点
• 健康检查: http://0.0.0.0:8000/health -服务器运行状况

🔧 可用工具

ping -Hello World验证工具

用于验证MCP服务器功能的诊断工具。

目的：验证MCP传输、日志记录、进度报告、跟踪和指标。

参数:

• message （可选，字符串）：要回显的短信

退货:

• 文本： "pong" 或 "pong: "
• 具有状态和可选回声的结构化数据

get_campaign_list

获取所有广告活动及其状态和设置的列表。

参数:

• campaign_ids （可选，list\[int\]）：要筛选的活动ID列表。
• states （可选，list\[str\]）：要过滤的活动状态列表（例如，\[“ON”，“OFF”\]）。

get_campaign_statistics

检索指定活动在日期范围内的详细统计信息。

参数:

• campaign_ids （list\[int\]）：活动ID列表。
• date_from （字符串）：开始日期（YYYY-MM-DD）。
• date_to （字符串）：结束日期（YYYY-MM-DD）。
• group_by （可选，字符串）：按句点分组（“DATE”或“无”）。

get_keyword_performance

为广告系列或广告组中的关键字提供性能指标。

参数:

• date_from （string）：开始日期。
• date_to （string）：结束日期。
• campaign_ids （可选，list\[int\]）：按活动ID筛选。
• ad_group_ids （可选，list\[int\]）：按广告组ID筛选。

manage_campaign_status

开始或停止广告活动。

参数:

• campaign_ids （list\[int\]）：活动ID列表。
• action （string）：“恢复”或“暂停”。

get_account_balance

获取经常账户余额和日常支出。

参数：无

⚙️ 配置

环境变量

所有配置都通过环境变量进行管理。看 .env.example 查看完整列表。

服务器配置

开放遥测配置

Yandex Direct API（未来工具）

获取Yandex Direct API代币

要使用Yandex Direct工具，您需要一个有效的OAuth令牌(YANDEX_API_KEY).

1. 注册您的应用程序:

- 首选 Yandex OAuth 并创建一个新的应用程序。 - 选择“Yandex Direct API”权限。 - 回调URL可以是 https://oauth.yandex.ru/verification_code 对于简单的脚本。

1. 获取OAuth令牌:

- 简单方法（用于测试）: - 首选 https://oauth.yandex.ru/authorize?response_type=token&client_id= - 从URL复制令牌（以开头 y0_...). - 生产方法（OAuth 2.0）: - 获取代码： https://oauth.yandex.ru/authorize?response_type=code&client_id= - 代币兑换： POST https://oauth.yandex.ru/token 和 grant_type=authorization_code.

1. 设置环境变量:

- 添加 YANDEX_API_KEY=your_token_here 给你的 .env 文件。

有关API使用和高级身份验证流的详细信息，请参阅 Yandex Direct API文档.

📊 可观测性

此服务器按照生产最佳实践实现了全面的可观察性。

OpenTetry跟踪

所有工具调用都使用OpenTetry跨度进行跟踪，该跨度包含：

• 工具名称和参数
• 执行状态
• 错误详细信息（如有）
• 每个工具的自定义属性

地方发展：痕迹输出到控制台\ 生产：配置 OTEL_ENDPOINT 将痕迹发送给您的收藏家（Jaeger、Tempo等）

普罗米修斯指标

服务器在以下位置公开与Prometheus兼容的指标 /metrics:

tool_calls_total

工具调用计数器

• 标签： tool_name, status （已启动、成功、验证错误、错误）

calculation_errors_total

刀具执行错误计数器

• 标签： tool_name, error_type （验证、计算）

api_calls_total

外部API调用计数器（未来工具）

• 标签： service, endpoint, status

日志记录

带有表情符号指示器的结构化日志记录，可轻松进行可视化解析：

• 🏁 流程启动
• 🔍 验证
• 🎯 处理
• 📦 格式化
• ✅ 成功
• ❌ 错误

🏗️ 建筑

项目结构

ydirect-mcp/
├── src/
│   ├── mcp_instance.py      # Single FastMCP instance
│   ├── server.py            # Main entry point, tracing init
│   ├── config.py            # Configuration and environment
│   ├── metrics.py           # Prometheus metrics definitions
│   └── tools/               # MCP tools (one per file)
│       ├── __init__.py
│       ├── hello.py         # Ping tool
│       └── utils.py         # Shared utilities
├── openspec/                # OpenSpec change proposals
├── pyproject.toml           # Python project configuration
├── Dockerfile               # Container image
├── .env.example             # Environment template
├── env_options.json         # Environment documentation
├── mcp_tools.json           # Tool specifications
└── README.md                # This file

关键设计原则

1. 单个FastMCP实例：所有工具都注册了一个 mcp 实例在 mcp_instance.py
2. 每个文件一个工具：每个工具都位于其自己的文件中 src/tools/
3. 异步一切：所有工具都是异步函数，使用 async def
4. 类型安全：Pydantic Field 对于所有经过验证的参数
5. 上下文日志记录：所有工具使用 ctx: Context 用于进度和日志记录
6. 错误映射：标准MCP错误代码通过 McpError:

- -32602：无效参数/验证错误 - -32603：内部/意外错误

1. 可观察性优先：每个工具上的OTel跨度和Prometheus指标
2. 仅限流式HTTP：运输已锁定 streamable-http
3. 安全：没有硬编码的秘密，非root Docker用户，没有文件系统写入

🔐 安全

• 所有配置的环境变量（没有硬编码的秘密）

• Docker容器以非root用户身份运行(mcp，UID 1000）

• 没有运行时文件系统写入

• 使用Pydantic进行输入验证

🧪 测试

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Type checking
uv run mypy src

# Linting
uv run ruff check src

📚 开发指南

此项目遵循中定义的严格代理开发规则 AGENTS.md 和 .rules.关键要求：

• 异步工具功能 和 async def
• Pydantic场 用于参数验证
• 上下文用法 (ctx: Context)用于记录和进度
• 进度报告 0%、25%、50%、75%、100%
• Mcp错误 对于标准代码的所有错误
• OpenTetry跨度 包装工具逻辑
• 普罗米修斯指标 可观察性

有关详细指南，请参阅：

• AGENTS.md -代理开发规则
• openspec/project.md -OpenSpec工作流
• openspec/AGENTS.md -MCP特定标准

🗺️ 路线图

第一阶段：基础骨架✅

• \[x\] 具有可流式传输http的基础服务器
• \[x\] 你好，世界 ping 工具
• \[x\] OpenTetry跟踪
• \[x\] 普罗米修斯指标
• \[x\] Docker支持

第二阶段：Yandex直接工具✅

• \[x\] get_campaign_list：获取所有广告活动及其状态和设置的列表。
• \[x\] get_campaign_statistics：检索指定活动在日期范围内的详细统计信息，包括展示次数、点击次数、点击率和成本。
• \[x\] get_keyword_performance：为广告系列或广告组中的关键字提供性能指标。
• \[x\] manage_campaign_status：开始或停止广告活动。
• \[x\] get_account_balance：获取经常账户余额和日常支出。

第3阶段：高级功能（未来）

• \[\]批量报告生成
• \[\]数据导出工具
• \[\]自定义仪表板
• \[\]多柜台支持

📖 参考文献

• 模型上下文协议（MCP）
• FastMCP框架
• Yandex Direct API
• OpenTelemetry Python
• Prometheus客户端Python

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

欢迎投稿！请遵循OpenSpec工作流程：

1. 在中创建更改建议 openspec/changes//
2. 用场景定义需求
3. 执行以下代理规则
4. 更新文档(README.md, mcp_tools.json, env_options.json)
5. 提交带有测试的PR

💬 支持

对于问题、疑问或功能请求，请在GitHub上打开问题。

______________________________________________________________________

内置于❤️ 使用FastMCP和OpenTetry