---
name: mcp-analytics-operator
description: >
  Operate analytics-node safely for local AI usage analytics across Codex,
  Copilot, Claude, MCP, skills and hooks.
  Use when the task needs usage summaries, model/token checks, runtime event
  analysis, source scans, privacy-safe troubleshooting, or controlled deletion
  of imported analytics data. Do not use to retrieve prompt or response content.
---

# MCP Analytics Operator

Skill per usare `analytics-node` come strumento locale e privacy-first di analisi dell'utilizzo AI. Serve per interrogare sessioni, modelli, token disponibili, eventi MCP, skill e hook, senza leggere o restituire contenuti conversazionali.

## Quick Routing

Usa questa skill quando serve:

- verificare uso locale di Codex, Copilot e Claude;
- produrre riepiloghi per sorgente, modello, periodo o progetto;
- controllare token nativi quando presenti nei log locali;
- analizzare eventi MCP, skill hint e hook;
- capire se una sorgente va scansionata o risincronizzata;
- cancellare dati analytics gia' importati dal DB locale.

Non usarla per:

- recuperare prompt, risposte, titoli chat o snippet;
- fare export documentali;
- stimare costi/pricing se non esiste una funzione dedicata;
- leggere token, file auth, cookie o credential store;
- analizzare codice applicativo o DB business: in quel caso passa agli skill specialistici.

## Regole Permanenti

1. Prima usa tool read-only come `analytics_status`, `analytics_summary`, `analytics_models`, `analytics_sessions` e `analytics_events`.
2. Usa `analytics_scan` solo quando i dati sono obsoleti, una sorgente e' assente o l'utente chiede aggiornamento.
3. Non chiedere mai contenuti chat: il server analytics non deve salvare o restituire prompt, risposte, titoli, snippet o raw JSON.
4. Tratta i token come dati nativi disponibili solo quando presenti nei log; non stimare token mancanti.
5. Distingui sempre uso effettivo MCP da hint: `McpHint` e' evento hook, non chiamata MCP reale.
6. Distingui `SkillHint` da uso reale di skill: la skill registra hint operativi, non conferme di esecuzione salvo evento strutturato esplicito.
7. Per cancellazioni usa sempre dry-run prima dell'esecuzione e richiedi conferma esplicita del piano.
8. Se una sorgente genera warning, segnala il warning senza inventare dati mancanti.
9. Non esporre path locali salvo richiesta esplicita di debug tramite tool che lo supportano.
10. Mantieni gli output sintetici e orientati ad azione: periodo, sorgenti, conteggi, warning, prossimi controlli.

## Workflow Base

1. `analytics_status` per verificare DB, feature, conteggi e ultimo stato noto.
2. `analytics_summary` per una vista aggregata su sorgenti, sessioni ed eventi.
3. `analytics_models` per distribuzione modelli e token nativi disponibili.
4. `analytics_events` per MCP, skill hint e hook.
5. `analytics_sessions` solo se serve elenco sessioni senza contenuti.
6. `analytics_scan` solo quando serve aggiornare il DB locale.
7. `analytics_delete_imported` solo dopo dry-run e conferma piano.

## Contratto sorgenti

Sorgenti supportate:

```text
codex
copilot
hook_log
claude
```

Regole:

- usa solo nomi canonici con underscore;
- usa `client_surface` quando serve distinguere `cli`, `desktop`, `vscode`, `vscode_insiders`, `code`, `unknown`;
- non usare alias con trattino nei tool MCP;
- se una sorgente non e' disponibile localmente, segnala assenza come warning o skip, non come errore bloccante salvo richiesta esplicita;
- non leggere file auth o token delle sorgenti.

## Cancellazione dati importati

Per cancellare dati dal DB analytics:

1. eseguire dry-run con filtri `sources` e periodo;
2. leggere `delete_plan_id` e conteggi previsti;
3. chiedere conferma utente se l'impatto e' quello atteso;
4. rieseguire con `confirm_delete: true` e `confirm_plan_id`;
5. se il piano e' cambiato, interrompere e rifare dry-run.

Non cancellare mai file originali di Codex, Copilot, Claude o hook log. La cancellazione riguarda solo righe SQLite di `analytics-node`.

## Troubleshooting

- Se `analytics_status` indica DB non disponibile, verificare `ANALYTICS_DB_PATH` e permessi directory.
- Se non compaiono sessioni, eseguire `analytics_scan` sulla sorgente interessata e controllare warning.
- Se una sorgente e' assente, verificare che il client sia installato e abbia dati locali leggibili.
- Se i token sono zero, controllare se il client espone token nativi nei log: non stimare.
- Se `hook_log` non produce eventi, verificare che gli hook Sophia scrivano `events.jsonl`.
- Se una cancellazione non parte, rifare dry-run e controllare `confirm_plan_id`.
- Se una sorgente cambia formato, trattarla come warning parser e non forzare import non sicuro.

## Sinergie

- con `mcp-technical-analyst`: per correlare analytics con requisiti, ticket, repo o decisioni operative;
- con `mcp-code-reviewer`: per verificare che patch su `analytics-node` rispettino spec, privacy e test;
- con `mcp-docs-navigator`: per aggiornare documentazione indicizzata dopo modifiche a README o guide;
- con `mcp-memory-operator`: per salvare decisioni operative validate, non dati analytics grezzi.

## References

- [references/analytics-workflow.md](references/analytics-workflow.md)
- [references/privacy-rules.md](references/privacy-rules.md)
- [references/deletion-playbook.md](references/deletion-playbook.md)