Content
# MCP ActiveView (read-only)
Servidor MCP que expone la **ActiveView External API** (`https://external-api.activeview.app`)
a Claude. Es un wrapper de **solo lectura**: el helper de red solo hace `GET`, así que
ninguna tool puede crear, modificar ni borrar datos.
Hecho con [FastMCP](https://gofastmcp.com) (Python), transporte **stdio** (local).
---
## Qué expone (12 tools, todas de lectura)
**Price rules**
- `get_price_rules` — reglas de precio de un sitio.
**Reportes por dominio**
- `get_report_by_domain` — métricas (revenue, impressions, eCPM, match rate…).
- `get_kvp_report_by_domain` — métricas agrupadas por una key de GAM.
- `get_session_kvp_report_by_domain` — KVP de sesiones (Snowflake).
- `get_custom_gam_report_by_domain` — reporte GAM con dimensiones/métricas a elección.
**Reportes por network** (varios dominios con el filtro `domains`)
- `get_report_by_network`
- `get_kvp_report_by_network`
- `get_custom_gam_report_by_network`
**Redirects (A/B testing)**
- `list_redirect_domains` — dominios de redirect con sus paths.
- `get_redirect_path` — detalle de un path.
- `get_redirect_path_mappings` — split de tráfico (url + %).
- `get_redirect_path_mapping_logs` — historial de cambios del split.
> 💰 **Micros:** los campos de revenue de GAM (`*_revenue`) vienen en *micros*
> (1.000.000 = 1 unidad de moneda). Divídelos entre 1.000.000. Las tools ya se lo
> recuerdan a Claude en su descripción.
---
## Requisitos
- **Python ≥ 3.10** (recomendado 3.12). El Python 3.9 que trae macOS por defecto **no** sirve.
- **git** para clonar.
- **Una API key de ActiveView**, en formato `token:secret` (el bearer completo, con los dos puntos).
- Opcional pero recomendado: [`uv`](https://docs.astral.sh/uv/) (instala con `brew install uv`).
Si no quieres `uv`, abajo tienes la variante con `python -m venv` + `pip`.
---
## Instalación paso a paso (Claude Code)
### 1. Clonar el repo
```bash
git clone https://github.com/TU-USUARIO/mcp-activeview.git
cd mcp-activeview
```
### 2. Crear el entorno virtual e instalar dependencias
Con **uv** (recomendado):
```bash
uv venv --python 3.12 .venv
uv pip install --python .venv -r requirements.txt
```
O con **venv + pip** estándar (sin uv):
```bash
python3.12 -m venv .venv # o python3 si tu 3 ya es ≥3.10
./.venv/bin/pip install -r requirements.txt
```
### 3. Conseguir tu API key
La sacas de tu panel de ActiveView. **Es un único valor** con la forma
`token:secret`: dos partes separadas por dos puntos (`:`). Lo copias entero,
**incluidos los dos puntos**. Por ejemplo:
```ini
# Ejemplo (valores inventados). Pega tu clave real entera:
ACTIVEVIEW_API_KEY=ab12cd34ef56...:9f8e7d6c...
```
En esta guía verás el placeholder `tu_token:tu_secret`; sustitúyelo por tu clave real.
> Cada persona usa **su propia** key. La key **nunca** va dentro del repo.
### 4. Registrar el servidor en Claude Code
Desde la **carpeta del repo** (para que `$(pwd)` resuelva las rutas absolutas solo):
```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` lo deja disponible en **todos tus proyectos**. Usa `--scope local`
(por defecto) si solo lo quieres en el proyecto actual.
- `ACTIVEVIEW_NETWORK_CODE` es **opcional**: si lo pones, podrás pedir reportes sin
repetir el network code en cada consulta (ver sección abajo). Quítalo si no quieres
un valor por defecto.
### 5. Verificar
```bash
claude mcp list
```
Debe mostrar `activeview: … ✔ Connected`. Luego, dentro de Claude Code, pídele algo como:
> "Dame las impresiones de ayer en `tu-dominio.com`"
Si responde con datos, está funcionando.
---
## Network code por defecto (opcional)
Puedes fijar un `network_code` por defecto con `ACTIVEVIEW_NETWORK_CODE`. Si lo haces,
las tools se pueden llamar **sin pasar `network_code`** cada vez; un valor explícito en
la llamada siempre tiene prioridad sobre el por defecto.
Funciona tanto por `--env` (paso 4) como en un fichero `.env` local:
```bash
cp .env.example .env
# edita .env:
# ACTIVEVIEW_API_KEY=tu_token:tu_secret
# ACTIVEVIEW_NETWORK_CODE=YOUR_NETWORK_CODE # opcional, el de tu propiedad principal
```
> ⚠️ Un único network code por defecto solo cubre los dominios **de esa red**. Para
> dominios de otra red, pasa su `network_code` en la consulta.
**¿`--env` o `.env`?** Lo más limpio es `--env` en `claude mcp add` (la key vive en la
config de Claude, no en el proyecto). El `.env` es cómodo para pruebas locales y está
**ignorado por git** (no se sube nunca). Si una variable ya viene del cliente MCP, esa
gana sobre la del `.env`.
---
## Alternativa: Claude Desktop
En `claude_desktop_config.json`:
```json
{
"mcpServers": {
"activeview": {
"command": "/ruta/absoluta/a/mcp-activeview/.venv/bin/python",
"args": ["/ruta/absoluta/a/mcp-activeview/server.py"],
"env": {
"ACTIVEVIEW_API_KEY": "tu_token:tu_secret",
"ACTIVEVIEW_NETWORK_CODE": "YOUR_NETWORK_CODE"
}
}
}
}
```
Usar el `python` del `.venv` directamente es lo más robusto. Reinicia el cliente tras añadirlo.
---
## Probarlo en local (sin Claude)
```bash
# Inspector visual de FastMCP (UI web para invocar las tools a mano):
ACTIVEVIEW_API_KEY=tu_token:tu_secret ./.venv/bin/fastmcp dev server.py
# O lanzarlo en stdio tal cual lo lanzará Claude:
ACTIVEVIEW_API_KEY=tu_token:tu_secret ./.venv/bin/python server.py
```
---
## Seguridad
Este servidor está pensado para ser **seguro por diseño**:
- **Solo lectura, garantizado por construcción.** El único helper de red (`_get`) usa
exclusivamente `httpx.get`. No existe ningún `post`/`put`/`patch`/`delete` en el código,
así que ninguna tool puede crear, modificar ni borrar datos. Todas las tools se anuncian
con `readOnlyHint: True`.
- **Host fijo.** Todas las peticiones van a `https://external-api.activeview.app`; el
servidor no acepta URLs ni hosts arbitrarios.
- **Validación de entradas.** `network_code` debe ser numérico y `domain` solo admite
`[A-Za-z0-9.-]`. Esto bloquea intentos de inyección de path (`../`, `?`, `#`, `@`, `/`)
en la URL de la petición.
- **La API key nunca se versiona.** `.env` está en `.gitignore`; el repo solo trae
`.env.example` con placeholders. La key se pasa por variable de entorno y **no** se
registra en logs.
- **Sin ejecución de código ni acceso a disco.** El servidor solo hace peticiones HTTP GET
de lectura; no escribe ficheros, no ejecuta shell, no toca tu sistema.
**Buenas prácticas al instalarlo:**
- Trata tu `ACTIVEVIEW_API_KEY` como una contraseña. Si la pasaste por línea de comandos,
recuerda que puede quedar en el historial del shell; preferible `.env` o un gestor de secretos.
- Si crees que tu key se ha filtrado, **rótala** en ActiveView; la del repo nunca debería
aparecer en un commit.
- Revisa `requirements.txt` antes de instalar (dependencias: `fastmcp`, `httpx`, `python-dotenv`).
---
## Troubleshooting
| Síntoma | Causa probable / solución |
|---|---|
| `claude mcp list` muestra `✘ Failed to connect` | Ruta del `python`/`server.py` mal, o venv sin dependencias. Reejecuta el paso 2 y usa rutas **absolutas**. |
| Aviso "fastmcp not installed" en VSCode | Selecciona el intérprete `.venv/bin/python` (Command Palette → "Python: Select Interpreter"). |
| Las tools devuelven `401` | API key inválida o revocada. Comprueba `ACTIVEVIEW_API_KEY` (formato `token:secret`). |
| `Invalid network_code` / `Invalid domain` | El valor llevaba caracteres no permitidos. `network_code` es numérico; `domain` solo letras/dígitos/puntos/guiones. |
| `No network_code given…` | No pasaste `network_code` y no hay `ACTIVEVIEW_NETWORK_CODE` configurado. |
| `python3.12: command not found` | Instala Python 3.12 (`brew install python@3.12`) o usa otro ≥3.10. |
---
## Nota sobre los reportes "Custom GAM"
La colección Postman traía las dos variantes con el orden de segmentos distinto
(`gam/custom` vs `custom/gam`). Confirmado contra la API real, el orden correcto en
ambas es **`gam/custom`**:
- por dominio → `/report/gam/custom/{network}/{domain}`
- por network → `/report/gam/custom/{network}`
