212 lines
6.4 KiB
Markdown
212 lines
6.4 KiB
Markdown
# 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
|
||
|
||
### Digest giornaliero agenti → `homelab-loogle`
|
||
|
||
Ogni sera (cron `22:45` su Pi-1) lo script `scripts/export_daily_agent_digest.py` aggiorna un blocco `<!-- daily-digest:YYYY-MM-DD -->` sul progetto **homelab-loogle**, con:
|
||
|
||
- query e conclusioni dagli agent transcript Cursor
|
||
- tool MCP usati (audit_log)
|
||
- commit git del giorno (`rete`, `loogle-mcp`)
|
||
- sync `~/.cursor/plans/*.plan.md` → `artifacts/plans/` + indice in `context.md` (solo i piani toccati quel giorno compaiono nel digest)
|
||
|
||
Claude (e Cursor) lo leggono con `get_project_context` su `homelab-loogle`.
|
||
|
||
```bash
|
||
cd /home/daniely/docker/loogle-mcp
|
||
python3 scripts/export_daily_agent_digest.py --dry-run
|
||
python3 scripts/export_daily_agent_digest.py --force --no-index
|
||
# opzionale: indicizza il blocco in Qdrant ctx_* (più lento, Ollama)
|
||
python3 scripts/export_daily_agent_digest.py --force
|
||
```
|
||
|
||
Log: `data/daily-digest.log`. Idempotente; `--force` sovrascrive il giorno.
|
||
|
||
### 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)
|