Backup automatico script del 2026-08-23 12:04

2026-08-23 12:04:16 +02:00
1 parent 11823447a2
commit 795a15a7b6
@@ -0,0 +1,289 @@
+# 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).
+
+---
+
+## 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`.
+
+---
+
+## 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
+```