内容
# MCP ActiveView（只读）
Servidor MCP，暴露 **ActiveView 外部 API**（`https://external-api.activeview.app`）给 Claude。它是一个 **只读包装器**：网络助手只进行 `GET` 请求，因此没有任何工具可以创建、修改或删除数据。
使用 [FastMCP](https://gofastmcp.com)（Python）构建，**stdio**（本地）传输。
## 暴露内容（12种工具，均只读）
**价格规则**
- `get_price_rules` — 站点的价格规则。
**按域名报告**
- `get_report_by_domain` — 指标（收入、展示次数、eCPM、匹配率...）。
- `get_kvp_report_by_domain` — 按 GAM 键分组的指标。
- `get_session_kvp_report_by_domain` — 会话 KVP（Snowflake）。
- `get_custom_gam_report_by_domain` — 自定义 GAM 报告，带有可选择维度/指标。
**按网络报告**（多个域名，带有 `domains` 过滤器）
- `get_report_by_network`
- `get_kvp_report_by_network`
- `get_custom_gam_report_by_network`
**重定向（A/B 测试）**
- `list_redirect_domains` — 带有路径的重定向域名。
- `get_redirect_path` — 路径详情。
- `get_redirect_path_mappings` — 流量分割（网址 + %）。
- `get_redirect_path_mapping_logs` — 分割变更历史。
> 💰 **微单位：** GAM 收入字段（`*_revenue`）以微单位表示（1,000,000 = 1 货币单位）。请除以 1,000,000。工具已在描述中提醒 Claude。
## 要求
- **Python ≥ 3.10**（推荐 3.12）。macOS 默认的 Python 3.9 **不可用**。
- **git** 用于克隆。
- **ActiveView API 密钥**，格式为 `token:secret`（完整的 bearer，带冒号）。
- 可选但推荐：[`uv`](https://docs.astral.sh/uv/)（使用 `brew install uv` 安装）。
如果您不需要 `uv`，下面有 `python -m venv` + `pip` 的替代方法。
## 分步安装（Claude Code）
### 1. 克隆仓库
```bash
git clone https://github.com/TU-USUARIO/mcp-activeview.git
cd mcp-activeview
```
### 2. 创建虚拟环境并安装依赖
使用 **uv**（推荐）：
```bash
uv venv --python 3.12 .venv
uv pip install --python .venv -r requirements.txt
```
或使用 **venv + pip** 标准（无 uv）：
```bash
python3.12 -m venv .venv # 或 python3，如果您的 3 已经 ≥3.10
./.venv/bin/pip install -r requirements.txt
```
### 3. 获取 API 密钥
从 ActiveView 面板获取。**这是一个单独的值**，格式为 `token:secret`：两个部分用冒号（`:`）分隔。复制整个密钥，**包括冒号**。例如：
```ini
# 示例（虚构值）。粘贴您的实际密钥：
ACTIVEVIEW_API_KEY=ab12cd34ef56...:9f8e7d6c...
```
在指南中，您将看到占位符 `tu_token:tu_secret`；请用您的实际密钥替换它。
> 每个用户使用 **自己的** 密钥。密钥 **永远** 不会进入仓库。
### 4. 在 Claude Code 中注册服务器
从 **仓库目录**（以便 `$(pwd)` 解析绝对路径）：
```bash
claude mcp add activeview \
--scope user \
--env ACTIVEVIEW_API_KEY=tu_token:tu_secret \
--env ACTIVEVIEW_NETWORK_CODE=YOUR_NETWORK_CODE \
-- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"
```
- `--scope user` 使其在 **所有项目** 中可用。如果您只想在当前项目中使用它，请使用 `--scope local`（默认）。
- `ACTIVEVIEW_NETWORK_CODE` 是 **可选的**：如果您设置了它，您将能够在查询中不重复网络代码的情况下请求报告（请参见下面的部分）。如果您不想要默认值，请删除它。
### 5. 验证
```bash
claude mcp list
```
应显示 `activeview: … ✔ Connected`。然后，在 Claude Code 中，请求类似的内容：
> "给我 `tu-dominio.com` 昨天的印象"
如果它用数据响应，则表示它正在工作。
## 默认网络代码（可选）
您可以使用 `ACTIVEVIEW_NETWORK_CODE` 设置默认的 `network_code`。如果您这样做，工具可以 **不带 `network_code`** 调用；显式值始终优先于默认值。
它适用于 `--env`（步骤 4）和本地 `.env` 文件：
```bash
cp .env.example .env
# 编辑 .env：
# ACTIVEVIEW_API_KEY=tu_token:tu_secret
# ACTIVEVIEW_NETWORK_CODE=YOUR_NETWORK_CODE # 可选，主要属性的网络代码
```
> ⚠️ 单个默认网络代码仅涵盖 **该网络** 的域名。对于其他网络的域名，请在查询中传递其 `network_code`。
**`--env` 还是 `.env`？** 最安全的做法是在 `claude mcp add` 中使用 `--env`（密钥存储在 Claude 配置中，而不是项目中）。`.env` 适用于本地测试，并且 **被 git 忽略**（永远不会上传）。如果变量已经来自 MCP 客户端，则它优先于 `.env` 中的变量。
## 替代：Claude Desktop
在 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"activeview": {
"command": "/绝对路径/到/mcp-activeview/.venv/bin/python",
"args": ["/绝对路径/到/mcp-activeview/server.py"],
"env": {
"ACTIVEVIEW_API_KEY": "tu_token:tu_secret",
"ACTIVEVIEW_NETWORK_CODE": "YOUR_NETWORK_CODE"
}
}
}
}
```
直接使用 `.venv` 中的 `python` 最为稳健。添加后请重启客户端。
## 在本地测试（无 Claude）
```bash
# FastMCP 可视化检查（用于手动调用工具的 Web UI）：
ACTIVEVIEW_API_KEY=tu_token:tu_secret ./.venv/bin/fastmcp dev server.py
# 或直接启动 stdio，就像 Claude 一样：
ACTIVEVIEW_API_KEY=tu_token:tu_secret ./.venv/bin/python server.py
```
## 安全
该服务器设计为 **安全**：
- **只读，保证构建。** 网络助手（`_get`）仅使用 `httpx.get`。代码中没有 `post`/`put`/`patch`/`delete`，因此任何工具都无法创建、修改或删除数据。所有工具都宣布 `readOnlyHint: True`。
- **固定主机。** 所有请求都发送到 `https://external-api.activeview.app`；服务器不接受任意 URL 或主机。
- **输入验证。** `network_code` 必须是数字，而 `domain` 只允许 `[A-Za-z0-9.-]`。这阻止了路径注入（`../`、`?`、`#`、`@`、`/`）到请求的 URL 中。
- **API 密钥从不版本控制。** `.env` 在 `.gitignore` 中；仓库中只有带有占位符的 `.env.example`。密钥通过环境变量传递，**不** 记录在日志中。
- **无代码执行或磁盘访问。** 服务器仅进行 HTTP GET 读取；不写入文件，不执行 shell，不触及您的系统。
**安装最佳实践：
- 将您的 `ACTIVEVIEW_API_KEY` 当作密码。如果您通过命令行传递了它，请记住它可能保留在 shell 历史记录中；`.env` 或机密管理器更安全。
- 如果您认为您的密钥已泄露，**轮换** 在 ActiveView 中；仓库中的密钥永远不应该出现在提交中。
- 在安装前检查 `requirements.txt`（依赖项：`fastmcp`、`httpx`、`python-dotenv`）。
## 故障排除
| 症状 | 可能原因 / 解决方案 |
|---|---|
| `claude mcp list` 显示 `✘ Failed to connect` | `python`/`server.py` 路径错误，或 venv 无依赖项。重新执行步骤 2 并使用 **绝对** 路径。 |
| VSCode 中出现“fastmcp not installed”警告 | 选择 `.venv/bin/python` 解释器（命令面板 → “Python: Select Interpreter”）。 |
| 工具返回 `401` | API 密钥无效或已撤销。检查 `ACTIVEVIEW_API_KEY`（格式 `token:secret`）。 |
| `Invalid network_code` / `Invalid domain` | 值包含不允许的字符。`network_code` 为数字；`domain` 只允许字母/数字/点/破折号。 |
| `No network_code given…` | 您未传递 `network_code`，且未配置 `ACTIVEVIEW_NETWORK_CODE`。 |
| `python3.12: command not found` | 安装 Python 3.12（`brew install python@3.12`）或使用 ≥3.10 的其他版本。 |
## 关于“自定义 GAM”报告的说明
Postman 集合中包含两种变体，其片段顺序不同（`gam/custom` vs `custom/gam`）。与真实 API 确认后，两种情况下正确的顺序均为 **`gam/custom`**：
- 按域名 → `/report/gam/custom/{network}/{domain}`
- 按网络 → `/report/gam/custom/{network}`
