# 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 `` 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= PAPERLESS_API_TOKEN_LUCIA= PAPERLESS_API_TOKEN_DAVIDE= PAPERLESS_API_TOKEN_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)