loogle-scripts/services/loogle-mcp/docs/GITEA-TOKEN.md

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)

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:

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:

GITEA_API_URL=http://192.168.128.81:3002

I link nei risultati restano su GITEA_URL pubblico.

Fallback admin

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:

cd /home/daniely/docker/loogle-mcp && docker compose up -d --build

---

Verifica

/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:

"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

/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

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

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:

docker exec loogle-mcp python3 /srv/scripts/setup_gitea_p4_repos.py

Verifica P4

docker exec loogle-mcp python3 /srv/scripts/test_gitea_p4.py