# 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
```