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,209 @@
+# Token Gitea per Loogle MCP
+
+## Cosa usare: Personal Access Token (PAT)
+
+Gitea espone l'API REST su `https://git.loogle.it/api/v1/` con header:
+
+```
+Authorization: token <token>
+```
+
+Ogni utente Gitea ha i propri repository e permessi. L'hub MCP usa un token **per utente famiglia**, come Paperless.
+
+---
+
+## Dove generarlo
+
+Per ogni utente che deve usare i tool Gitea da Claude/Cursor (daniele, lucia, …):
+
+1. Accedi a https://git.loogle.it con quell'account
+2. **Impostazioni** → **Applicazioni** → **Genera nuovo token**
+3. Nome suggerito: `loogle-mcp`
+4. Scope minimi:
+   - `read:repository` — list_repos, get_file, search_code, list_issues, get_issue, RAG
+   - `write:repository` — **P4:** create_or_update_file
+   - `write:user` — **P4:** create_gitea_repo (`POST /user/repos`)
+   - `write:issue` — create_issue
+   - `read:user` — consigliato per `/user/repos`
+5. Copia il token (mostrato una sola volta) in `.env`
+
+### Alternativa CLI (admin, sul nodo con Gitea attivo)
+
+```bash
+docker exec -u git gitea gitea admin user generate-access-token \
+  --username daniele \
+  --token-name loogle-mcp \
+  --scopes 'read:repository,write:repository,write:issue,write:user,read:user'
+```
+
+---
+
+## Configurazione in Loogle MCP
+
+Modifica `/home/daniely/docker/loogle-mcp/.env`:
+
+```env
+GITEA_URL=https://git.loogle.it
+GITEA_API_TOKEN_DANIELE=
+GITEA_API_TOKEN_LUCIA=
+GITEA_API_TOKEN_DAVIDE=
+GITEA_API_TOKEN_LUCA=
+```
+
+| Utente MCP | Variabile `.env` | Account Gitea |
+|------------|------------------|---------------|
+| Daniele | `GITEA_API_TOKEN_DANIELE` | daniele |
+| Lucia | `GITEA_API_TOKEN_LUCIA` | lucia |
+| Davide | `GITEA_API_TOKEN_DAVIDE` | davide |
+| Luca | `GITEA_API_TOKEN_LUCA` | luca |
+
+### URL API interno (opzionale)
+
+Se `https://git.loogle.it` non è raggiungibile dal container MCP (rete LAN, failover), imposta un URL diretto:
+
+```env
+GITEA_API_URL=http://192.168.128.81:3002
+```
+
+I link nei risultati restano su `GITEA_URL` pubblico.
+
+### Fallback admin
+
+```env
+GITEA_API_TOKEN=<token-admin>
+```
+
+Tutti gli utenti MCP useranno lo stesso token (sconsigliato salvo test).
+
+---
+
+## Tool MCP Gitea
+
+| Tool | Scope | Descrizione |
+|------|-------|-------------|
+| `list_repos` | gitea:read | Repository accessibili |
+| `get_file` | gitea:read | Legge file o elenca directory |
+| `search_code` | gitea:read | Cerca nel codice (API `/search/code` o fallback tree) |
+| `list_issues` | gitea:read | Issue aperte/chiuse |
+| `get_issue` | gitea:read | Dettaglio issue |
+| `create_issue` | gitea:write | Crea issue |
+| `create_gitea_repo` | gitea:write | Crea repo sotto l'utente MCP corrente |
+| `create_or_update_file` | gitea:write | Commit singolo di un file (create/update via Contents API) |
+
+Dopo modifica `.env`:
+
+```bash
+cd /home/daniely/docker/loogle-mcp && docker compose up -d --build
+```
+
+---
+
+## Verifica
+
+```bash
+/home/daniely/docker/loogle-mcp/scripts/test_gitea_integration.py
+```
+
+Oppure da MCP (con token OAuth): tool `list_repos` e `get_file` su `daniele/rete`.
+
+---
+
+## Collegamento progetto ↔ repository (P2)
+
+Ogni progetto MCP può referenziare un repo Gitea in `meta.json`:
+
+```json
+"gitea_repo": "daniele/rete"
+```
+
+### Tool
+
+| Tool | Azione |
+|------|--------|
+| `create_project` | Parametri opzionali `gitea_repo`, `seed_from_gitea` |
+| `link_project_repo` | Collega, cambia repo o scollega (`gitea_repo` vuoto) |
+| `get_project_context` | Aggiunge blocco `gitea` con README, `docs/` e issue aperte |
+
+### Seed README
+
+Con `seed_from_gitea: true` il README del repo viene importato in `context.md` (una sola volta, marker `<!-- seed:gitea ... -->`).
+
+### Verifica P2
+
+```bash
+/home/daniely/docker/loogle-mcp/scripts/test_project_gitea_p2.py
+```
+
+---
+
+## RAG su repository Gitea (P3)
+
+Il worker `loogle-mcp-indexer` indicizza periodicamente file testo dai repo Gitea (`.md`, `.py`, `.sh`, …) in collection Qdrant dedicate:
+
+| Collection | Contenuto |
+|------------|-----------|
+| `gitea_shared_family` | Repo non privati |
+| `gitea_personal_{user}` | Repo privati dell'owner |
+
+### Config `.env`
+
+```env
+GITEA_INDEX_ENABLED=yes
+GITEA_INDEX_REPOS_DANIELE=daniele/rete,daniele/loogle-scripts
+GITEA_INDEX_MAX_FILES_PER_REPO=150
+GITEA_INDEX_MAX_FILE_BYTES=120000
+```
+
+Se `GITEA_INDEX_REPOS_{USER}` è vuoto → tutti i repo accessibili via API.
+
+### Tool MCP
+
+| Tool | Descrizione |
+|------|-------------|
+| `search_gitea_knowledge` | Ricerca semantica solo su Gitea |
+| `search_knowledge` | Include Paperless + contesti + Gitea |
+| `list_gitea_indexed_files` | Stato indicizzazione |
+| `reindex_gitea_repo` | Forza re-index di un repo |
+
+### Verifica P3
+
+```bash
+docker exec loogle-mcp python3 /srv/scripts/test_gitea_rag_p3.py
+```
+
+---
+
+## Scrittura su Gitea (P4)
+
+L'AI può creare repository e committare singoli file via API Gitea (senza git push locale).
+
+| Tool | Scope | Azione |
+|------|-------|--------|
+| `create_gitea_repo` | gitea:write | Crea repo sotto l'utente MCP autenticato |
+| `create_or_update_file` | gitea:write | Crea o aggiorna un file (Contents API + commit) |
+
+Regole:
+
+- Scrittura consentita solo su repo di cui l'utente è **owner** (salvo admin MCP).
+- Dopo scrittura, opzionalmente re-indicizza il file nel RAG (`reindex: true` default).
+- Token Gitea: `write:user` (create repo) + `write:repository` (file).
+
+### Workspace davide e luca
+
+| Utente | Repo Gitea | Progetto MCP |
+|--------|------------|--------------|
+| davide | `davide/progetti` | Progetti Davide |
+| luca | `luca/progetti` | Progetti Luca |
+
+Setup iniziale:
+
+```bash
+docker exec loogle-mcp python3 /srv/scripts/setup_gitea_p4_repos.py
+```
+
+### Verifica P4
+
+```bash
+docker exec loogle-mcp python3 /srv/scripts/test_gitea_p4.py
+```
+