> [!IMPORTANT]
> **Superseded by [seo-stack-mcp](https://github.com/Raffaele86/seo-stack-mcp)** — the same tools plus GSC, GA4, Bing Webmaster and Microsoft Clarity unified in a single `uvx`-installable MCP server with local credentials. This repo remains as the remote-SSE variant.

# MCP Clarity — Microsoft Clarity Data Export API

Server MCP per [Microsoft Clarity](https://clarity.microsoft.com/) ospitato su CT102, registrato come upstream `clarity` del `mcp-gateway` con tag `analytics`.

## Architettura

| Voce | Valore |
|---|---|
| Stack | Python 3.12 + FastMCP (`mcp==1.27.0`) + Starlette + uvicorn |
| Porta | 8091 |
| Working dir | `/opt/clarity-mcp/` (CT102) |
| Stato persistente | `/var/lib/clarity-mcp/{cache.db,quota.json}` |
| Systemd | `clarity-mcp.service` |
| Endpoint API | `GET https://www.clarity.ms/export-data/api/v1/project-live-insights` |
| Auth | `Authorization: Bearer <CLARITY_TOKEN>` (uno per progetto) |
| Quota | **10 chiamate/giorno/progetto**, reset UTC (hard stop locale a 9) |
| Tag gateway | `analytics` |

## Tool esposti

| Tool | Cosa fa |
|---|---|
| `clarity_traffic(project?, days=1, dimension="OS")` | Sessions / bot % / pages-per-session per dimensione |
| `clarity_popular_pages(project?, days=1, limit=20)` | Top URL per visite |
| `clarity_engagement(project?, days=1, dimension="URL", limit=20)` | Engagement time + scroll depth |
| `clarity_dead_clicks(project?, days=1, limit=20)` | Top URL con click su elementi non interattivi |
| `clarity_rage_clicks(project?, days=1, limit=20)` | Top URL con click ripetuti veloci (frustrazione) |
| `clarity_excessive_scroll(project?, days=1, limit=20)` | Top URL con scroll eccessivo |
| `clarity_quickback_clicks(project?, days=1, limit=20)` | Top URL con bounce immediato |
| `clarity_script_errors(project?, days=1, limit=20)` | JS errors + error clicks per URL |
| `clarity_breakdown(dimension1, project?, days=1, dimension2?, dimension3?)` | Raw breakdown libero (power user) |
| `clarity_quota_status()` | Quota residua oggi (locale, niente API call) |
| `clarity_list_projects()` | Progetti configurati nel server |

**Cache condivisa**: tutti i tool URL-based (`popular_pages`, `dead_clicks`, `rage_clicks`, `excessive_scroll`, `quickback_clicks`, `script_errors`, `engagement` con dimension=URL) usano la stessa chiave cache → **1 chiamata API alimenta 7 tool**.

## Configurazione

### 1. Generare il token Clarity

1. Vai su [clarity.microsoft.com](https://clarity.microsoft.com), apri il progetto.
2. **Settings → Data Export → Generate new API token**.
3. Dai un nome (4-32 char, no spazi, no `@#$%&*!`).
4. Copia il token (mostrato una sola volta).

Solo gli **admin** del progetto possono generare token.

### 2. Variabili `.env`

Copia `.env.example` in `.env` e compila:

```bash
PORT=8091
CLARITY_TOKENS={"calcolatorigratis":"eyJhbG..."}
CLARITY_DEFAULT_PROJECT=calcolatorigratis
CLARITY_CACHE_DB_PATH=/var/lib/clarity-mcp/cache.db
CLARITY_QUOTA_PATH=/var/lib/clarity-mcp/quota.json
CLARITY_CACHE_TTL=21600
CLARITY_DAILY_LIMIT=9
CLARITY_WARNING_THRESHOLD=7
```

Multi-progetto: aggiungi chiavi al JSON, es. `{"calcolatorigratis":"...", "tuttoseo":"..."}`. Le chiamate prendono `project="alias"` come primo parametro.

## Deploy su CT102

```bash
./deploy/install.sh root@192.168.1.107
```

Lo script: rsync della working dir, crea `.venv`, installa requirements, crea `/var/lib/clarity-mcp`, installa il systemd unit e fa restart. Se `.env` non esiste su CT102, lo copia dall'esempio (poi va compilato con il token).

### Avvio manuale (debug locale)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
PORT=8091 CLARITY_TOKENS='{"test":"<token>"}' python clarity_server.py
curl http://localhost:8091/
```

## Registrazione nel mcp-gateway

Su CT102, append in `/etc/mcp-gateway/upstreams.yaml`:

```yaml
- name: clarity
  url: http://127.0.0.1:8091/sse
  tags:
    - analytics
```

Poi:

```bash
systemctl restart mcp-gateway
curl -s https://mcp.calcolatorigratis.com/healthz | grep clarity
```

Visibile in Claude Code come `mcp__mcp-gateway__clarity__*`.

## Verifica end-to-end

```bash
# 1. Service attivo
ssh root@192.168.1.107 'systemctl status clarity-mcp'

# 2. Homepage / health
curl http://192.168.1.107:8091/

# 3. SSE endpoint
curl -H "Accept: text/event-stream" http://192.168.1.107:8091/sse

# 4. Gateway
curl -s https://mcp.calcolatorigratis.com/healthz

# 5. Da Claude Code (sessione con tag analytics caricato)
# → chiamare mcp__mcp-gateway__clarity__clarity_list_projects
# → chiamare mcp__mcp-gateway__clarity__clarity_quota_status
# → chiamare mcp__mcp-gateway__clarity__clarity_traffic
```

## Troubleshooting

| Sintomo | Causa | Fix |
|---|---|---|
| `401 Unauthorized` | Token scaduto o non valido | Rigenerare in clarity.microsoft.com → Data Export |
| `403 Forbidden` | Token non admin | Solo admin del progetto può generare token Data Export |
| `429 Too Many Requests` | Superato 10/giorno (lato API) | Reset mezzanotte UTC, riusa la cache (`clarity_quota_status`) |
| `Quota esaurita per X oggi` | Superato `CLARITY_DAILY_LIMIT` (lato locale) | Stesso effetto del 429, aspetta reset UTC |
| `Progetto 'X' non configurato` | Alias non in `CLARITY_TOKENS` | Aggiungere `{"X":"<token>"}` al `.env` e restart |
| Tool ritorna `(nessun dato)` | Niente sessioni nel range | Normale su siti a basso traffico — controllare in dashboard Clarity |

## Vincoli API ricordare

- `numOfDays` ∈ {1, 2, 3} (ultime 24/48/72h, niente date arbitrarie).
- Max 3 dimensioni per request.
- Risposta max 1.000 righe, **non paginabile**.
- 10 chiamate/giorno/progetto, reset UTC.
- Dimensioni valide: `Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, URL`.