# 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}`