daniele/loogle-scripts
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
795a15a7b608ac47d4c3835c012b435d4f0aef34
loogle-scripts/services/loogle-mcp/docs/GUIDA-UTENTI.md
T

290 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```
Reference in new issue View Git Blame Copy Permalink