Clarity

Server MCP per Microsoft Clarity 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, 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:

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

./deploy/install.sh [email protected]

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)

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:

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

Poi:

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

# 1. Service attivo
ssh [email protected] '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.