README aktualisiert: stdio-Setup statt Docker/Pangolin

Gitea MCP Connector/README.md

@@ -1,105 +1,59 @@
 # Gitea MCP Connector
 
-Stellt die [Forgejo/Gitea](https://git.vogt.de.com)-API als MCP-Server (Model Context Protocol) per HTTP bereit, damit Claude (claude.ai / Claude Desktop) lesend und schreibend auf Repositories, Issues, Pull Requests, Wiki-Seiten etc. zugreifen kann.
+Stellt die [Forgejo/Gitea](https://git.vogt.de.com)-API als MCP-Server (Model Context Protocol) bereit, damit Claude (Claude Desktop) lesend und schreibend auf Repositories, Dateien, Issues, Pull Requests etc. zugreifen kann.
 
-Basiert auf dem Open-Source-Projekt [ronmi/forgejo-mcp](https://github.com/ronmi/forgejo-mcp).
+Basiert auf dem Open-Source-Projekt [Sqcows/forgejo-mcp](https://github.com/Sqcows/forgejo-mcp) (npm-Paket `@ric_/forgejo-mcp`).
 
-## Architektur
+## Architektur (aktuell: stdio, lokal)
 
 ```
-Claude Desktop (mcp-remote Bridge, --header X-Api-Key)
+Claude Desktop
-        │  HTTPS
+        │  STDIO (lokaler Prozess, kein Netzwerk-Exposure)
         ▼
-Pangolin Reverse Proxy (gitea-mcp.vogt.de.com)
+npx @ric_/forgejo-mcp
-  - terminiert TLS
+        │  REST-API + FORGEJO_TOKEN
-  - prüft HTTP-Header X-Api-Key
-        │  HTTP intern
         ▼
-gitea-mcp Container (Docker, Port 8080, HTTP-Transport)
+Gitea/Forgejo-Instanz (git.vogt.de.com)
-        │
-        ▼
-Gitea/Forgejo-Instanz (git.vogt.de.com) via REST-API + FORGEJOMCP_TOKEN
 ```
 
-## Docker Compose
+**Wichtig:** Dieses Setup läuft rein lokal auf dem jeweiligen Client-Rechner über die `npx`-STDIO-Anbindung von Claude Desktop – es gibt keinen extern erreichbaren HTTP-Endpunkt, keinen Reverse Proxy und keinen `X-Api-Key`-Schutz mehr nötig, weil nichts öffentlich exponiert wird.
 
-```yaml
+*Frühere Version dieses Dokuments beschrieb ein Docker/Pangolin-basiertes Remote-Setup (`gitea-mcp.vogt.de.com`, HTTP-Transport, `X-Api-Key`-Header). Dieses Setup wurde stillgelegt, da für den aktuellen Anwendungsfall (nur lokaler Zugriff von einem Gerät) unnötig komplex und fehleranfällig (Session-Konflikte bei mehrfachen `mcp-remote`-Neustarts). Falls in Zukunft wieder Remote-/Multi-Geräte-Zugriff benötigt wird, kann der Docker-Weg reaktiviert werden – Details siehe Git-Historie dieser Datei.*
-services:
-  gitea-mcp:
-    image: ronmi/forgejo-mcp:latest
-    container_name: gitea-mcp
-    restart: always
-    command: http --address :8080 --server https://git.vogt.de.com
-    environment:
-      FORGEJOMCP_TOKEN: '${FORGEJOMCP_TOKEN}'
-    ports:
-      - '8081:8080'
-```
 
-`.env`:
+## Claude Desktop Konfiguration
-```
-FORGEJOMCP_TOKEN=<Gitea/Forgejo API-Token, idealerweise von einem dedizierten Service-User>
-```
 
-## Reverse Proxy (Pangolin)
+In `claude_desktop_config.json` (Menü *Konnektoren → Lokale MCP-Server → Config bearbeiten*):
-
-- **Target:** `http://<docker-host-ip>:8081`
-- **Domain:** `gitea-mcp.vogt.de.com`
-- **Pfad:** `/` (kein Pfad-Rewrite – die volle URL für Claude lautet `https://gitea-mcp.vogt.de.com/mcp`)
-- **Absicherung:** HTTP-Header-Regel, identisch zum Muster bei `mealie-mcp`:
-  - Header-Name: `X-Api-Key`
-  - Value: zufälliger Secret-String (`openssl rand -hex 32`)
-  - Ohne korrekten Header blockt Pangolin den Request bereits auf Proxy-Ebene, bevor er den Container erreicht.
-
-**Wichtig:** `FORGEJOMCP_TOKEN` (App-Token gegenüber der Gitea-API) und `X-Api-Key` (Pangolin-Proxy-Secret) sind zwei unabhängige Werte und dürfen nicht verwechselt werden – genau wie bei `MEALIE_API_TOKEN` vs. `X-Api-Key` beim Mealie-Connector.
-
-## Verbindung mit Claude
-
-Wie beim Mealie-Connector läuft die Verbindung über die **lokale `mcp-remote`-Bridge in Claude Desktop**, da claude.ai-Custom-Connectors keine zuverlässige Möglichkeit bieten, eigene HTTP-Header mitzugeben.
-
-In der Claude-Desktop-Config (`claude_desktop_config.json`, Menü *Konnektoren → Lokale MCP-Server → Config bearbeiten*):
 
 ```json
 {
   "mcpServers": {
     "gitea": {
       "command": "npx",
-      "args": [
+      "args": ["@ric_/forgejo-mcp"],
-        "mcp-remote",
-        "https://gitea-mcp.vogt.de.com/mcp",
-        "--header",
-        "X-Api-Key:${GITEA_MCP_KEY}"
-      ],
       "env": {
-        "GITEA_MCP_KEY": "<gleicher Secret-Wert wie im Pangolin-Header>"
+        "FORGEJO_URL": "https://git.vogt.de.com",
+        "FORGEJO_TOKEN": "<Gitea/Forgejo Personal Access Token>"
       }
     }
   }
 }
 ```
 
-Danach Claude Desktop neu starten. Die Gitea-Tools (Repos, Issues, Pull Requests, Wiki, Releases, …) stehen dann in jedem Chat zur Verfügung.
+`FORGEJO_TOKEN`: Personal Access Token aus Gitea, erstellt unter *Einstellungen → Anwendungen → Zugriffstoken erzeugen*, mit Scopes `read:repository` + `write:repository` (idealerweise von einem dedizierten Service-User statt des Haupt-Accounts).
 
-## Testen
+Danach Claude Desktop **komplett beenden** (nicht nur das Fenster schließen) und neu starten. Die Gitea-Tools stehen dann automatisch in jedem neuen Chat zur Verfügung, ohne pro Chat neu verbunden werden zu müssen.
 
-Handshake ohne Header (sollte von Pangolin blockiert werden, sobald der Header aktiv ist):
+## Verfügbare Tools
-```bash
-curl -i https://gitea-mcp.vogt.de.com/mcp
-```
 
-Vollständiger MCP-Handshake mit korrekten Headern:
+Je nach Token-Gültigkeit/-Scope zeigt der Server unterschiedlich viele Tools:
-```bash
+
-curl -X POST https://gitea-mcp.vogt.de.com/mcp \
+- **Ohne gültigen Token / nur Lesezugriff:** nur öffentlich zugängliche Endpunkte – `search_repos`, `search_users`, `get_nodeinfo`, `get_server_version`
-  -H "Content-Type: application/json" \
+- **Mit gültigem Token inkl. Schreibrechten:** zusätzlich u. a. `create_file`, `update_file`, `get_file_contents`, `delete_file` sowie Issue-, PR- und weitere Repo-Management-Tools
-  -H "Accept: application/json, text/event-stream" \
+
-  -H "X-Api-Key: <secret>" \
+Falls nach dem Einrichten nur die vier Lese-Tools erscheinen, ist das ein starkes Indiz für einen ungültigen/fehlenden `FORGEJO_TOKEN` – Wert in der Config prüfen (kein Platzhalter wie `${FORGEJO_TOKEN}`, sondern der tatsächliche Token-String) und Claude Desktop neu starten.
-  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
-```
-Eine erfolgreiche Antwort enthält `serverInfo` mit `"name":"gitea"` (bzw. dem vom Server gemeldeten Namen).
 
 ## Sicherheitshinweise
 
-- Der `gitea-mcp`-Server selbst hat **keine eigene Authentifizierung** – wer die URL ohne den `X-Api-Key`-Schutz erreicht, hat vollen Zugriff auf alle Repos, die für `FORGEJOMCP_TOKEN` sichtbar sind (inkl. Schreibrechte, je nach Token-Scope).
+- Der Token liegt im Klartext in `claude_desktop_config.json` auf dem jeweiligen Client-Rechner. Zugriff auf diese Datei entspricht Zugriff auf das Gitea-Konto im Umfang des Token-Scopes.
-- Empfohlen: dedizierter Gitea-Service-User mit möglichst eng gefasstem Token-Scope statt eines Admin-Tokens für `FORGEJOMCP_TOKEN`.
+- Empfohlen: dedizierter Gitea-Service-User mit möglichst eng gefasstem Token-Scope statt eines Admin-Tokens.
-- Der Secret-Wert für `X-Api-Key` muss identisch in Pangolin und in der Claude-Desktop-Config gepflegt werden.
+- Tokens, die versehentlich in Chat-Verläufen, Logs oder Screenshots sichtbar wurden, sollten zeitnah in Gitea rotiert werden.
-- Da im Compose-File aktuell ein Klartext-Token vorkam: Token in Gitea rotieren/neu ausstellen, sobald der bisherige Wert irgendwo (z. B. Chat-Verlauf) sichtbar war, und stattdessen über `.env` einbinden (siehe oben).