Yandex Direct + Metrica MCP 服务器（Python 实现）

使用说明 (Markdown 格式)

• 项目简介

  • 该仓库实现了一个 MCP 服务器，面向 LLM 客户端暴露资源、工具和提示模板等上下文数据，底层集成了 Yandex Direct、Yandex Metrica、Wordstat、Audience 的 API 访问能力，并提供安全的写入保护、账户注册表、以及基于 HF（Human-Friendly）工具的扩展交互。

• 主要功能点

  • MCP 核心能力：
    • 资源(Query/Read) 与 数据访问：暴露 Direct/Metrica/Wordstat/Audience 相关的资源集合，支持按账号/前置条件获取数据。
    • 工具注册与执行：定义并执行各种 Direct/Metrica/Audience 的操作工具，支持原始 API 调用以及 HF 友好层的工具。
    • Prompt/模板渲染：提供用于 LLM 交互的提示模板与渲染能力（dashboard 相关）。
    • 会话与权限管理：实现写保护、账户注册表、两阶段写入等安全机制。
  • 多账户与授权：
    • 账户 registry（accounts）支持按 account_id 映射 Direct Client-Login 和 Metrica 计数器等默认值。
    • 支持 Yandex OAuth 以及多种令牌来源（access_token/refresh_token）。
  • 多传输协议入口：
    • 标准 MCP JSON-RPC 风格接口（通过 MCP 库处理 list_tools、call_tool）。
    • 支持 stdio、SSE/WS 等传输通道入口。
  • HF（Human-Friendly）工具集：
    • 提供直观的人类友好工具入口，例如 direct.hf.、metrica.hf.、join.hf.* 等，便于在 Claude Code 等环境中使用。
  • dashboards 与数据集：
  • Option1/Option2 的 dashboard 方案实现与数据集定义，支持日常分析和跨账户交互。

• 安装步骤

  • 克隆仓库并进入项目目录。
  • 使用 Python 虚拟环境安装并就地开发：
    • 创建并激活虚拟环境
    • 安装并以开发模式运行：pip install -e .
  • 配置依赖与环境变量（详见仓库侧文档中的 README/Docs）。
  • 启动 MCP 服务器（示例命令（请根据实际环境调整）：使用环境变量配置后，通过仓库提供的入口脚本启动，详见下方“服务器配置”中的示例）。
  • 连接客户端：MCP 客户端通过 JSON-RPC 调用服务器暴露的工具与资源。

• 服务器配置（JSON 格式，便于 MCP 客户端加载） 注意：以下 JSON 仅为示例，实际部署需结合运行环境和你的容器/进程管理器进行调整。 { "server_name": "yandex-direct-metrica-mcp", "command": "python", "args": [ "-m", "mcp_yandex_ad.server", "--env-file", "/path/to/.env", "--transport", "stdio|sse", // 根据实际传输模式选择，如 "stdio"、"sse"、"websocket" "--port", "8000" ], "notes": "入口脚本根据仓库实现提供的默认入口，env 文件用于 OAuth/token 配置。客户端无需直接将 secrets 写入此配置。" }

• 基本使用方法

  • 启动后，客户端可以通过 JSON-RPC 调用服务器暴露的工具（如列出工具、调用工具、获取账户信息等）。
  • 使用 HF 工具时，请在调用前确保相应的配置与权限已经开启（HF 功能、写入保护等）。
  • 多账户场景下，可以通过 accounts_registry 和 account_id 进行上下文切换，服务器会在执行工具时应用对应账户的默认 Direct/Metrica 设置。

• 注意事项

  • 确保在生产环境中妥善管理 OAuth tokens、客户端 secrets，避免将凭证写入代码库或日志中。
  • 理解并遵循仓库中关于 Public/Pro 版本的差异，了解写保护和两阶段写入的工作方式。