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

# Guida amministratore — Daniele

Guida operativa per gestire e usare Loogle MCP Hub.

---

## Accesso rapido

| Cosa | URL / comando |
|------|----------------|
| Dashboard admin | https://mcp.loogle.it/dashboard (login `daniele`) |
| Health | `curl -sf https://mcp.loogle.it/health` |
| Log gateway | `docker logs -f loogle-mcp` |
| Log indexer | `docker logs -f loogle-mcp-indexer` |
| Compose | `cd /home/daniely/docker/loogle-mcp` |

---

## Configurazione iniziale (checklist)

- [x] Stack Docker avviato (`docker compose up -d`)
- [x] DNS Pi-hole: `mcp.loogle.it` → `192.168.128.85`
- [x] NPM proxy host 30 + TLS Let's Encrypt
- [ ] Token Paperless in `.env` — vedi [PAPERLESS-TOKEN.md](PAPERLESS-TOKEN.md) (Profilo utente, non «Applicazione social»)
- [ ] `MCP_JWT_SECRET` robusto in `.env`
- [ ] Ollama su DS920 con `ollama pull nomic-embed-text`
- [ ] Qdrant su DS920 (opzionale, vedi compose extrema)
- [ ] Password cambiate per tutta la famiglia
- [ ] Ogni familiare ha collegato almeno un client AI

**Script utili:**
```bash
sudo /home/daniely/rete/scripts/setup-mcp-dns-npm.sh   # DNS + NPM
./scripts/deploy.sh                                     # rebuild + restart
/home/daniely/rete/scripts/npm-failover-route.sh normal # upstream failover
```

---

## Come usare tu (Daniele)

### Dashboard

1. https://mcp.loogle.it/dashboard — login `daniele`
2. Vedi progetti, audit log completo, revoca refresh token (sezione admin)

### Con Cursor / Claude / ChatGPT

Stesso URL MCP: `https://mcp.loogle.it/mcp`

**Cursor** — aggiungi in `.cursor/mcp.json` del progetto:
```json
{
  "mcpServers": {
    "loogle-mcp": {
      "url": "https://mcp.loogle.it/mcp"
    }
  }
}
```

### Workflow consigliato per un task

1. **create_project** — es. «Homelab MCP», tag `rete`, `2026`
2. Lavori con l’AI (Cursor, Claude, ecc.)
3. **save_context** — a fine sessione salvi decisioni e stato
4. **search_knowledge** — recuperi doc da Paperless quando serve
5. **search_context** — ritrovi discussioni passate semanticamente

### Tool solo admin

- `reindex_document` — forza re-indicizzazione di un doc Paperless
- Revoca token refresh da dashboard
- Audit log di tutti gli utenti via `/api/audit`

---

## Gestione utenti

Gli utenti sono in SQLite (`loogle_mcp.db`). Password hash PBKDF2.

| Utente | Admin | Reset password |
|--------|-------|----------------|
| daniele | sì | dashboard o diretto DB |
| lucia, davide, luca | no | dashboard (self-service) |

Password iniziale = username. `must_change_password` è attivo al primo login consigliato.

Per aggiungere utenti in futuro: estendi `FAMILY_USERS` in `app/auth.py` e redeploy.

---

## Paperless → knowledge base

Vedi guida completa: [PAPERLESS-TOKEN.md](PAPERLESS-TOKEN.md)

**Non usare** i token «Applicazione social» dell'admin Django (schermata nell'immagine): servono al login OAuth web di Paperless, non all'API REST MCP.

**Usa** i token API utente: docs.loogle.it → menu utente → **Profilo** → pulsante freccia circolare accanto a «Token API».

Configura in `.env` (un token per ogni account Paperless della famiglia):

```bash
PAPERLESS_API_TOKEN_DANIELE=<token account Daniele>
PAPERLESS_API_TOKEN_LUCIA=<token account Lucia>
PAPERLESS_API_TOKEN_DAVIDE=<token account Davide>
PAPERLESS_API_TOKEN_LUCA=<token account Luca>
```

Ogni familiare genera il proprio token da docs.loogle.it → **Profilo** → Token API. Se un utente non ha ancora account Paperless, lascia la riga vuota finché non lo crei.

Alternativa: solo `PAPERLESS_API_TOKEN=` con token admin (Daniele superuser) — tutti gli utenti MCP condividono lo stesso scope.

Riavvia indexer:
```bash
cd /home/daniely/docker/loogle-mcp && docker compose restart loogle-mcp loogle-mcp-indexer
```

**Visibilità documenti (tag Paperless):**
- Tag `personal` / `privato` → solo collection personale del owner
- Senza tag personali → `kb_shared_family` (tutti in famiglia)

---

## Embedding e Qdrant

| Componente | Dove | Note |
|----------|------|------|
| Ollama | DS920 `:11434` | `OLLAMA_EMBED_MODEL=nomic-embed-text` |
| Qdrant | DS920 `:6333` | Non gira su Pi5 (limitazione ARM) |
| Fallback | `/data/vector_fallback.db` | Automatico se Qdrant non raggiungibile |

Deploy Qdrant su DS920:
```bash
# sul DS920, path mirror extrema
docker compose -f /volume1/extrema/compose/extrema-ds920/loogle-mcp-compose.yml up -d qdrant
```

---

## DNS e NPM — cosa è stato configurato

**Pi-hole** (`/etc/pihole/pihole.toml`):
```
"192.168.128.85 mcp.loogle.it"
```

**NPM** proxy host ID 30:
- Dominio: `mcp.loogle.it`
- Backend: `192.168.128.80:8700`
- Cert: `npm-65`

**Failover** (`npm-routes.conf`):
```
30|mcp.loogle.it|8700|pi1|pi1|local|ds920
```

Se reinstalli NPM da zero, riesegui:
```bash
sudo /home/daniely/rete/scripts/setup-mcp-dns-npm.sh
/home/daniely/sync-npm-full.sh   # sync Pi2 + DS920
```

---

## Monitoraggio e backup

- **Failover status:** probe `mcp_ok` / `mcp_be` in `failover-status.sh`
- **Runbook incidenti:** `/home/daniely/rete/ha/RUNBOOK-mcp.md`
- **Backup restic:** `/home/daniely/rete/infra-monitor/mcp-restic-backup.sh`

---

## Onboarding famiglia

Invia a ciascuno:

- [Guida utenti](GUIDA-UTENTI.md) — istruzioni semplici per ChatGPT/Claude/Gemini
- URL dashboard per cambio password
- Username personale (non condividere password)

Progetto demo già creato per ogni utente (es. `progetti-personali` per Lucia).

---

## Documentazione tecnica

- [Architettura e parametri](ARCHITETTURA.md)
- [Onboarding client AI (dettaglio)](ONBOARDING.md)
- [Runbook HA](/home/daniely/rete/ha/RUNBOOK-mcp.md)