loogle-scripts/services/loogle-mcp/docs/GUIDA-UTENTI.md

# Guida utenti — Loogle MCP Hub

Questa guida è per **Lucia, Davide e Luca** (e chiunque usi gli assistenti AI collegati a casa).

---

## Cos’è

Loogle MCP è la **memoria di casa** per i tuoi assistenti AI. Permette a ChatGPT, Claude o Gemini di:

- **Ricordare** i tuoi progetti (es. ristrutturazione, studio, hobby)
- **Cercare** documenti che abbiamo già archiviato in Paperless (bollette, manuali, PDF)
- **Salvare** note e riassunti che l’AI produce durante un lavoro, così non devi ripetere tutto ogni volta

I tuoi dati restano **solo sui nostri dispositivi** a casa, non nel cloud dell’AI.

---

## Le tue credenziali

| Nome | Username | Password iniziale |
|------|----------|-------------------|
| Lucia | `lucia` | `lucia` |
| Davide | `davide` | `davide` |
| Luca | `luca` | `luca` |

**Al primo accesso cambia la password:**

1. Apri https://mcp.loogle.it/dashboard
2. Accedi con username e password
3. Sezione **Cambia password** → inserisci la nuova password (minimo 6 caratteri)

Ogni persona vede **solo i propri progetti**. Non puoi vedere (né l’AI) i progetti degli altri familiari.

---

## Collegare ChatGPT

Richiede account **Plus, Pro, Business o Edu**.

1. Apri ChatGPT → **Impostazioni**
2. Attiva **Developer Mode** (se non già attivo)
3. Vai a **Connectors** → **Add MCP Connector**
4. Inserisci l’URL del server:
   ```
   https://mcp.loogle.it/mcp
   ```
5. Clicca **Connect** — si apre una pagina di login Loogle
6. Accedi con **il tuo** username e password (es. `lucia` / la tua nuova password)
7. Autorizza l’accesso

Nelle conversazioni, abilita i tool del connector **Loogle MCP** quando vuoi usare memoria o documenti.

### Esempi di richieste a ChatGPT

- *«Usa list_projects per vedere i miei progetti»*
- *«Leggi il contesto del progetto X e riassumilo»*
- *«Cerca nei documenti di casa informazioni sulla caldaia»*
- *«Salva in save_context questo riepilogo del lavoro fatto oggi»*

---

## Collegare Claude (App / Desktop)

1. Apri Claude → **Settings** → **Connectors**
2. **Add remote MCP server**
3. URL:
   ```
   https://mcp.loogle.it/mcp
   ```
4. Al primo utilizzo: login con le **tue** credenziali Loogle MCP
5. Autorizza

Claude potrà usare gli stessi tool (progetti, ricerca documenti, salvataggio contesto).

### Far usare MCP ogni giorno (Desktop + mobile)

Claude **non** salva il contesto da solo: va istruito una volta e poi richiamato con abitudini brevi.

**1. Istruzioni personalizzate (Desktop e App — stesso account)**  
Settings → **Profile** / **Custom instructions** (o *What should Claude know about you?*) e incolla:

```
Hai il connector Loogle MCP (mcp.loogle.it). Per lavori su casa, documenti, progetti o codice famiglia:
- All’inizio: list_projects → get_project_context sul progetto rilevante.
- Per documenti/bollette/manuali: search_knowledge (non inventare).
- Per codice/runbook Gitea: search_gitea_knowledge o get_file.
- A fine chat utile: save_context (append) con decisioni e next step.
Se non esiste un progetto adatto, create_project prima di salvare.
```

**2. Abilita sempre i tool del connector**  
In ogni chat nuova, assicurati che **Loogle MCP** sia attivo nei tool/connectors (su Desktop a volte va riacceso per conversazione).

**3. Frasi-ancora (funzionano anche da mobile)**  
Usa all’inizio o alla fine, senza ricordare i nomi tool:

- *«Controlla prima su Loogle MCP il mio progetto e i documenti rilevanti.»*
- *«A fine risposta salva su MCP un riepilogo nel progetto giusto.»*
- *«Cerca in Paperless via MCP la bolletta / il manuale …»*
- *«Come sta l’irrigazione / i turni oggi? Usa MCP.»*

**4. Un progetto = un tema**  
Es. «Rinnovo bagno», «Homelab», «Studio». Più il `context.md` è pieno di decisioni reali, più Claude lo riuserà da solo.

**5. Mobile**  
Stesso account = stesse custom instructions. MCP remoto dipende dal supporto app Claude; se i tool non compaiono, usa Desktop/web per i salvataggi e da mobile chiedi almeno *«ricorda di aggiornare MCP quando torno al computer»* oppure ripeti la frase-ancora quando i connector sono disponibili.

**6. Verifica**  
Dashboard https://mcp.loogle.it/dashboard → ultime azioni: devono comparire `get_project_context` / `save_context` / `search_knowledge` dopo le chat.

---


## Collegare Cursor IDE

1. Crea o modifica `~/.cursor/mcp.json` (globale) oppure `.cursor/mcp.json` nel progetto:

```json
{
  "mcpServers": {
    "loogle-mcp": {
      "url": "https://mcp.loogle.it/mcp",
      "auth": {
        "CLIENT_ID": "cursor",
        "scopes": [
          "context:read", "context:write",
          "knowledge:read", "knowledge:write",
          "gitea:read", "gitea:write",
          "home:read", "irrigation:read", "turni:read"
        ]
      }
    }
  }
}
```

2. **Riavvia Cursor completamente** (esci dall’app, non solo chiudi la finestra)
3. **Cursor Settings** → **Tools & MCP** → **Connect** su `loogle-mcp` (**una sola volta**, attendi 10–15 s)
4. Si apre il browser su **Loogle MCP — Login** → accedi con le **tue** credenziali MCP
5. In chat, chiedi all'AI di usare i tool (`list_projects`, `search_knowledge`, …)

### Cursor: «Unauthorized» nei log

| Log Cursor | Significato |
|------------|-------------|
| `MCP OAuth redirect` + `Unauthorized` | **Normale prima del login** — clicca **Connect** e completa il browser |
| `Redirect URI non consentito` | Errore server (già risolto) — riprova **Reconnect** |
| `credentials cleared` | Hai cliccato Connect/Disconnect in loop — riavvia Cursor e riprova una volta |

**Password:** se hai cambiato quella iniziale, usa quella attuale (es. admin `daniele` non usa più `daniele`/`daniele`). Verifica su https://mcp.loogle.it/dashboard

**Se il browser non si apre:** prova la config con `"CLIENT_ID": "cursor"` sopra, oppure apri manualmente https://mcp.loogle.it/dashboard per testare le credenziali.

---

## Collegare Gemini

**Gemini CLI** (da terminale / PC):

1. Apri il file di configurazione MCP di Gemini (es. `~/.gemini/settings.json`)
2. Aggiungi:

```json
{
  "mcpServers": {
    "loogle-mcp": {
      "url": "https://mcp.loogle.it/mcp"
    }
  }
}
```

3. Al primo avvio completa il login OAuth nel browser con le tue credenziali

L’app Gemini mobile potrebbe non supportare ancora MCP remoto; in quel caso usa ChatGPT o Claude.

---

## Dashboard web

Indirizzo: **https://mcp.loogle.it/dashboard**

Da qui puoi:

- Vedere l’elenco dei **tuoi progetti**
- **Cambiare password**
- Consultare le **ultime azioni** che l’AI ha fatto (audit log)

---

## Come usarlo nel quotidiano

### 1. Crea un progetto per ogni tema importante

Chiedi all’AI:

> «Crea un progetto chiamato "Rinnovo bagno" con tag casa, 2026»

(Usa il tool `create_project` — l’AI lo farà automaticamente se il connector è attivo.)

### 2. Lavora e fai salvare la memoria

A fine sessione:

> «Salva in save_context un riepilogo di quello che abbiamo deciso oggi, nel progetto rinnovo-bagno»

La prossima volta l’AI potrà rileggere tutto con `get_project_context`.

### 3. Cerca documenti di casa

> «Cerca in search_knowledge la bolletta luce dell’ultimo trimestre»

> «Trova nel archivio documenti il manuale della caldaia»

(I documenti devono essere già in Paperless su docs.loogle.it.)

### 4. Cerca tra i tuoi appunti passati

> «search_context: cosa avevamo deciso sul parquet?»

### 5. Codice e runbook su Gitea

> «list_repos: quali repository ho su git.loogle.it?»

> «get_file su daniele/rete ha/RUNBOOK-failover.md»

> «search_code tier-b nel repo daniele/rete»

### 6. Progetto MCP collegato al codice

> «create_project "Infra Rete" con gitea_repo daniele/rete e seed_from_gitea true»

> «link_project_repo sul progetto homelab-loogle → daniele/rete»

> «get_project_context sul progetto attivo» — include README e elenco file in `docs/` dal repo collegato

> «search_gitea_knowledge: come funziona il failover tier-b?»

> «reindex_gitea_repo daniele/rete» — forza aggiornamento indicizzazione

### 7. Ricerca semantica su runbook Git (RAG)

> «search_gitea_knowledge failover su daniele/rete»

> «search_knowledge keepalived VIP» — cerca anche in Paperless e Gitea indicizzati

L'indexer in background indicizza `.md`, script e config dai repo collegati (vedi `docs/GITEA-TOKEN.md` sezione P3).

### 8. Casa, rete e Home Assistant (P5)

> «get_home_weather: che tempo fa a casa?»

> «get_network_overview: qualcosa è offline in rete?»

> «get_network_failover_status: com'è lo scenario failover?»

> «get_ha_entity switch.pompa_pozzo» — stato entità Home Assistant (solo lettura)

> «search_ha_entities caldaia»

### 9. Irrigazione e turni (P6)

> «get_irrigation_status: programma irrigazione oggi»

> «get_irrigation_zones: quali zone sono attive?»

> «get_my_shifts: i miei turni di lavoro questo mese»

> «list_turni_doctors» — elenco medici in Turni-Live

### 10. Ricerca storica app (P7)

> «search_apps_knowledge irrigazione prato ieri»

> «search_knowledge valvola pozzo» — include anche Irrigazione/Turni indicizzati

Dettagli tecnici e configurazione: `docs/APPS-INTEGRATION.md`.

### 11. Contesti condivisi con la famiglia

Alcuni progetti sono di tutti, per esempio **Stampa 3D famiglia — Bambu Lab X2D**: stampante,
filamenti, piatti, costi e regole di lavoro sono gli stessi per chiunque progetti un oggetto.
Compaiono in `list_projects` con `shared: true` e chiunque li può leggere e aggiornare.

> «Leggi il contesto condiviso della stampa 3D X2D e aiutami a progettare un portapenne»

> «Ho comprato 2 kg di PETG nero a 18 €/kg: aggiorna la dotazione nel contesto X2D»

Quando cambia qualcosa (acquisti, accessori, prezzi, regole) l'assistente aggiorna la sezione
esistente invece di aggiungere note che la contraddicono: da quel momento vale per tutti.
Ogni modifica registra chi l'ha fatta.

Per creare un nuovo contesto condiviso:

> «create_project "Viaggio estate 2027" con shared true»

Per condividere un tuo progetto esistente: *«share_project rinnovo-bagno»*. Solo chi l'ha
condiviso (o Daniele) può archiviarlo o riportarlo personale.

---

## Cosa può e non può fare

| Può | Non può |
|-----|---------|
| Leggere i **tuoi** progetti | Vedere progetti di altri familiari |
| Cercare documenti **famiglia** e **personali** (secondo tag Paperless) | Modificare Paperless o cancellare PDF |
| Aggiungere testo alla **tua** memoria progetto | Accedere senza login OAuth |
| Cercare semanticamente (capisce il significato, non solo parole esatte) | Funzionare senza internet verso casa* |
| Leggere codice e issue da **Gitea** (repo a cui hai accesso) | Push/commit git via MCP (usa git normalmente) |
| Meteo/rete da **Loogle Casa**, sensori **Home Assistant** (lettura) | Controllare luci/valvole via MCP (solo lettura HA) |
| Stato **irrigazione** e **turni** (se configurati per te) | Modificare programmi irrigazione o turni via MCP |

\*Da fuori casa serve VPN WireGuard (`vpn.loogle.it`) o connessione alla rete di casa.

---

## Problemi comuni

| Problema | Cosa fare |
|----------|-----------|
| Login fallisce | Verifica username/password; reset da dashboard |
| ChatGPT non trova il server | URL esatto: `https://mcp.loogle.it/mcp` (con https) |
| «Knowledge vuota» | I documenti Paperless potrebbero non essere ancora indicizzati — chiedi a Daniele |
| Token scaduto | Riconnetti il connector OAuth (disconnect + connect) |
| Cursor «Unauthorized» | Clicca **Connect** una volta; login browser; usa config con `"CLIENT_ID": "cursor"` |
| Sito non raggiungibile | Sei in VPN/rete casa? Prova https://mcp.loogle.it/health |

---

## Contatti

Per problemi tecnici (token Paperless, servizio down, nuovo progetto di gruppo): **Daniele**.

Per la password dimenticata: chiedi a Daniele (admin) o usa il dashboard se ricordi quella vecchia.

---

## Scheda rapida

```
URL MCP:     https://mcp.loogle.it/mcp
Dashboard:   https://mcp.loogle.it/dashboard
Login:       il tuo username (lucia / davide / luca)
Primo passo: cambia password → collega ChatGPT o Claude → crea un progetto
```