Gitea MCP-Server

Ein produktionsbereiter Model Context Protocol (MCP)-Server für die nahtlose Integration mit selbst gehosteten Gitea-Plattformen. Dieser Server bietet Werkzeuge zum Erstellen von Repositories und zum Hochladen von Dateien unter Beibehaltung der Verzeichnisstruktur.

Installations- und Einrichtungsanleitung

Diese Anleitung bietet Schritt-für-Schritt-Anweisungen zur Installation und Konfiguration des Gitea MCP-Servers, einschließlich der Fehlerbehebung bei häufigen Problemen.

Related MCP server: Gitea MCP Tool

Funktionen

• Repository-Erstellung: Erstellen Sie neue Repositories auf jeder konfigurierten Gitea-Instanz

• Datei-Upload: Laden Sie Dateien und Ordner hoch, während die Verzeichnisstruktur erhalten bleibt

• Projekt-Synchronisierung: Synchronisieren Sie automatisch ganze Projekte für initiale Commits (nur neue Dateien)

• Erweiterte Dateiaktualisierungen: Intelligentes Update-Tool mit Konfliktlösung zum Ändern bestehender Dateien

• Multi-Instanz-Unterstützung: Verbinden Sie sich gleichzeitig mit mehreren Gitea-Instanzen

• Ratenbegrenzung: Respektiert API-Ratenbegrenzungen pro Instanz

• Stapelverarbeitung: Effizienter Datei-Upload mit konfigurierbaren Stapelgrößen

• Umfassende Protokollierung: Strukturierte Protokollierung mit sicherheitsrelevanter Ausgabe

• Fehlerbehandlung: Robuste Fehlerbehandlung mit Wiederholungslogik

• TypeScript: Volle Typsicherheit und moderne JavaScript-Funktionen

Schnellstart

Voraussetzungen

• Node.js 18.0.0 oder höher

• Zugriff auf eine oder mehrere Gitea-Instanzen

• Persönliche Zugriffstoken für die Authentifizierung

Installation

1. Klonen Sie das Repository:

git clone <repository-url>
cd gitea-mcp

2. Installieren Sie die Abhängigkeiten:

npm install

3. Konfigurieren Sie die Umgebungsvariablen:

cp .env.example .env
# Edit .env with your Gitea instance details

4. Erstellen Sie das Projekt:

npm run build

5. Starten Sie den Server:

npm run start:mcp

Fehlerbehebung bei häufigen Problemen

Windows-Kompatibilität

Wenn Sie Windows verwenden, könnten Probleme mit dem Build-Skript auftreten. Das Standard-Build-Skript verwendet den chmod-Befehl, der unter Windows nicht verfügbar ist. Die package.json wurde aktualisiert, um ein Windows-kompatibles Build-Skript zu verwenden.

Protokollierungskonfiguration

Wenn Sie Probleme mit der Protokollierungskonfiguration haben, stellen Sie sicher, dass das Paket pino-pretty installiert ist:

npm install --save-dev pino-pretty

Umgebungsvariablen

Die .env-Datei sollte die folgende Konfiguration enthalten:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=debug

# Gitea Configuration
# Replace with your Gitea instance URL and token
GITEA_INSTANCES=[{"id":"main","name":"Main Gitea Instance","baseUrl":"https://your-gitea-instance.com","token":"your-personal-access-token","timeout":30000,"rateLimit":{"requests":100,"windowMs":60000}}]

# Upload Configuration
MAX_FILE_SIZE=10485760
MAX_FILES=100
BATCH_SIZE=10

# Gitea API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

Ersetzen Sie "https://your-gitea-instance.com" durch Ihre tatsächliche Gitea-Instanz-URL und "your-personal-access-token" durch Ihr persönliches Gitea-Zugriffstoken.

Ausführen mit Debug-Protokollierung

Um den Server mit aktivierter Debug-Protokollierung auszuführen, verwenden Sie das start:mcp-Skript:

npm run start:mcp

Dieses Skript setzt NODE_ENV auf development und LOG_LEVEL auf debug, bevor der Server gestartet wird.

Entwicklungseinrichtung

Für die Entwicklung mit Hot-Reloading:

npm run dev

Konfiguration

Umgebungsvariablen

Erstellen Sie eine .env-Datei basierend auf .env.example:

# Server Configuration
NODE_ENV=development
LOG_LEVEL=info

# Gitea Configuration
GITEA_INSTANCES='[
  {
    "id": "main",
    "name": "Main Gitea Instance", 
    "baseUrl": "https://gitea.example.com",
    "token": "your-personal-access-token",
    "timeout": 30000,
    "rateLimit": {
      "requests": 100,
      "windowMs": 60000
    }
  }
]'

# Upload Configuration
MAX_FILE_SIZE=10485760  # 10MB
MAX_FILES=100
BATCH_SIZE=10

# API Configuration
GITEA_TIMEOUT=30000
GITEA_MAX_RETRIES=3

Gitea-Instanzkonfiguration

Jede Gitea-Instanz erfordert:

• id: Eindeutige Kennung für die Instanz

• name: Menschenlesbarer Name für die Protokollierung

• baseUrl: Basis-URL Ihrer Gitea-Instanz

• token: Persönliches Zugriffstoken mit entsprechenden Berechtigungen

• timeout: Anforderungs-Timeout in Millisekunden (optional)

• rateLimit: Konfiguration der Ratenbegrenzung (optional)

Einrichtung des persönlichen Zugriffstokens

1. Melden Sie sich bei Ihrer Gitea-Instanz an

2. Gehen Sie zu Einstellungen → Anwendungen → Persönliche Zugriffstoken

3. Erstellen Sie ein neues Token mit diesen Berechtigungen:

   • repo: Voller Repository-Zugriff

   • write:repository: Repositories erstellen

   • read:user: Benutzerinformationen lesen

MCP-Client-Konfiguration

Claude Desktop

Fügen Sie dies zu Ihrer Claude Desktop-Konfiguration hinzu:

{
  "mcpServers": {
    "gitea-mcp": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/gitea-mcp",
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Andere MCP-Clients

Der Server kommuniziert über stdio und folgt der MCP-Protokollspezifikation. Informationen zur Konfiguration finden Sie in der Dokumentation Ihres Clients.

Verfügbare Werkzeuge

create_repository

Erstellen Sie ein neues Repository auf einer angegebenen Gitea-Instanz.

Parameter:

• instanceId (Zeichenfolge, erforderlich): Gitea-Instanzkennung

• name (Zeichenfolge, erforderlich): Repository-Name

• description (Zeichenfolge, optional): Repository-Beschreibung

• private (Boolesch, Standard: true): Repository privat machen

• autoInit (Boolesch, Standard: true): Mit README initialisieren

• defaultBranch (Zeichenfolge, Standard: "main"): Standard-Branch-Name

Beispiel:

{
  "instanceId": "main",
  "name": "my-new-repo",
  "description": "A test repository",
  "private": true,
  "autoInit": true,
  "defaultBranch": "main"
}

upload_files

Laden Sie mehrere Dateien in ein Repository hoch, während die Verzeichnisstruktur erhalten bleibt.

Parameter:

• instanceId (Zeichenfolge, erforderlich): Gitea-Instanzkennung

• owner (Zeichenfolge, erforderlich): Benutzername des Repository-Besitzers

• repository (Zeichenfolge, erforderlich): Repository-Name

• files (Array, erforderlich): Array von Datei-Objekten mit path und content

• message (Zeichenfolge, erforderlich): Commit-Nachricht

• branch (Zeichenfolge, Standard: "main"): Ziel-Branch

• batchSize (Zahl, Standard: 10): Dateien pro Stapel

Beispiel:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-repo",
  "files": [
    {
      "path": "README.md",
      "content": "# My Project\n\nProject description here."
    },
    {
      "path": "src/index.js", 
      "content": "console.log('Hello, World!');"
    }
  ],
  "message": "Initial commit",
  "branch": "main",
  "batchSize": 5
}

sync_project ⚠️ Nur initiale Commits

Entdecken und synchronisieren Sie automatisch ein gesamtes Projektverzeichnis mit einem Gitea-Repository unter Einhaltung der .gitignore-Regeln.

Wichtig: Dieses Werkzeug ist für initiale Projekt-Uploads konzipiert und kann nur neue Dateien erstellen. Es kann keine Dateien aktualisieren, die bereits im Repository vorhanden sind. Verwenden Sie zum Aktualisieren bestehender Dateien stattdessen das sync_update-Werkzeug.

Parameter:

• instanceId (Zeichenfolge, erforderlich): Gitea-Instanzkennung

• owner (Zeichenfolge, erforderlich): Benutzername des Repository-Besitzers

• repository (Zeichenfolge, erforderlich): Repository-Name

• message (Zeichenfolge, erforderlich): Commit-Nachricht für die Synchronisierung

• branch (Zeichenfolge, Standard: "main"): Ziel-Branch

• projectPath (Zeichenfolge, Standard: "."): Pfad zum zu synchronisierenden Projektverzeichnis

• dryRun (Boolesch, Standard: false): Vorschau dessen, was hochgeladen würde, ohne tatsächlich hochzuladen

• includeHidden (Boolesch, Standard: false): Versteckte Dateien einbeziehen (beginnend mit .)

• maxFileSize (Zahl, Standard: 1048576): Maximale Dateigröße in Bytes (1MB)

• textOnly (Boolesch, Standard: true): Nur Textdateien hochladen (Binärdateien überspringen)

Funktionen:

• Liest und wendet automatisch .gitignore-Regeln an

• Enthält sinnvolle Standardwerte für gängige Ignorier-Muster (node_modules/, .git/, etc.)

• Scannt rekursiv das Projektverzeichnis nach geeigneten Dateien

• Einfache Heuristik zum Erkennen und optionalen Überspringen von Binärdateien

• Größenfilterung für große Dateien

• Dry-Run-Modus zur Vorschau von Änderungen

• Detaillierte Berichterstattung über gefundene, gefilterte, hochgeladene und fehlgeschlagene Dateien

Anwendungsfälle:

• Initiale Projekteinrichtung und erster Commit

• Hochladen neuer Projekte in leere Repositories

• Massen-Upload von Dateien in neue Repositories

Beispiel:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "message": "Initial project sync",
  "branch": "main",
  "projectPath": "./my-app",
  "dryRun": false,
  "includeHidden": false,
  "maxFileSize": 2097152,
  "textOnly": true
}

sync_update ✨ Erweiterte Dateiaktualisierungen

Erweitertes Werkzeug zum Aktualisieren bestehender Dateien in einem Gitea-Repository mit intelligenter Konfliktlösung und Änderungserkennung.

Parameter:

• instanceId (Zeichenfolge, erforderlich): Gitea-Instanzkennung

• owner (Zeichenfolge, erforderlich): Benutzername des Repository-Besitzers

• repository (Zeichenfolge, erforderlich): Repository-Name

• files (Array, erforderlich): Array von Dateioperations-Objekten

• files[].path (Zeichenfolge, erforderlich): Dateipfad im Repository (Schrägstriche)

• files[].content (Zeichenfolge, bedingt): Dateiinhalt (erforderlich für Hinzufügen/Ändern-Operationen)

• files[].operation (Zeichenfolge, erforderlich): Operationstyp: 'add', 'modify' oder 'delete'

• files[].sha (Zeichenfolge, optional): Aktueller Datei-SHA (wird automatisch erkannt, falls nicht angegeben)

• message (Zeichenfolge, erforderlich): Commit-Nachricht für alle Operationen

• branch (Zeichenfolge, Standard: "main"): Ziel-Branch

• strategy (Zeichenfolge, Standard: "auto"): Update-Strategie: 'auto', 'batch' oder 'individual'

• conflictResolution (Zeichenfolge, Standard: "fail"): Konfliktbehandlung: 'fail', 'overwrite' oder 'skip'

• detectChanges (Boolesch, Standard: true): Vergleich mit Remote-Dateien, um unnötige Updates zu vermeiden

• dryRun (Boolesch, Standard: false): Vorschau der Operationen ohne Änderungen vorzunehmen

Hauptfunktionen:

• Intelligente API-Nutzung: Verwendet PUT für Updates, POST für Erstellungen, DELETE für Entfernungen

• Änderungserkennung: Vergleicht lokale mit Remote-Inhalten, um unnötige Updates zu überspringen

• Automatische SHA-Auflösung: Ruft automatisch erforderliche SHA-Werte für Update-Operationen ab

• Mehrere Strategien: Auto, Batch (einzelner Commit) oder individuell (separate Commits)

• Konfliktlösung: Behandelt Fälle, in denen sich Remote-Dateien seit der letzten Synchronisierung geändert haben

• Gemischte Operationen: Kann Erstellungs-, Update- und Löschvorgänge in einem einzigen Aufruf verarbeiten

• Dry-Run-Modus: Vorschau der Operationen, die durchgeführt würden, ohne Änderungen vorzunehmen

Operationstypen:

• add: Neue Dateien erstellen (entspricht POST-API)

• modify: Bestehende Dateien aktualisieren (verwendet PUT-API mit SHA zur Konfliktlösung)

• delete: Bestehende Dateien entfernen (verwendet DELETE-API mit SHA)

Strategieoptionen:

• auto: Wählt intelligent den besten Ansatz basierend auf Dateianzahl und Operationstypen

• batch: Führt alle Operationen in einem einzigen Commit unter Verwendung der Gitea-Batch-API aus

• individual: Führt jede Operation als separaten Commit aus

Anwendungsfälle:

• Aktualisieren bestehender Projektdateien

• Selektive Dateiänderungen

• Massen-Dateioperationen (Erstellen, Aktualisieren, Löschen)

• Inkrementelle Projektaktualisierungen

• Automatisierte Dateiwartung

Beispiel:

{
  "instanceId": "main",
  "owner": "username",
  "repository": "my-project",
  "files": [
    {
      "path": "README.md",
      "content": "# Updated Project\n\nThis is an updated version of the project.",
      "operation": "modify"
    },
    {
      "path": "src/new-feature.js",
      "content": "// New feature implementation\nfunction newFeature() {\n  return 'Hello, World!';\n}",
      "operation": "add"
    },
    {
      "path": "old-file.txt",
      "operation": "delete"
    }
  ],
  "message": "Update documentation and add new feature",
  "branch": "main",
  "strategy": "auto",
  "detectChanges": true,
  "dryRun": false
}

Dry-Run-Beispielantwort:

{
  "dryRun": true,
  "strategy": "individual",
  "summary": {
    "discovered": 3,
    "analyzed": 3,
    "needsUpdate": 2,
    "processed": 0,
    "succeeded": 0,
    "failed": 0,
    "skipped": 0
  },
  "filesNeedingUpdate": [
    {
      "path": "README.md",
      "operation": "modify",
      "hasRemoteSha": true
    },
    {
      "path": "src/new-feature.js",
      "operation": "add",
      "hasRemoteSha": false
    }
  ]
}

Leitfaden zur Werkzeugauswahl

Wann welches Werkzeug zu verwenden ist:

1. create_repository: Neue Repositories erstellen

2. sync_project: Initialer Projekt-Upload in leere/neue Repositories

3. upload_files: Spezifische Dateien mit voller Kontrolle über den Prozess hochladen

4. sync_update: Bestehende Dateien aktualisieren, neue Dateien erstellen oder Dateien in bestehenden Repositories löschen

Workflow-Beispiel:

# 1. Create a new repository
create_repository → "my-new-project"

# 2. Initial upload of all project files
sync_project → Upload entire project structure

# 3. Later updates to specific files
sync_update → Modify README.md, add new features, delete old files

Entwicklung

Skripte

• npm run build - Für Produktion bauen

• npm run dev - Entwicklung mit Hot-Reloading

• npm start - Produktionsserver starten

• npm test - Tests ausführen

• npm run lint - Code linten

• npm run format - Code formatieren

• npm run type-check - TypeScript-Typüberprüfung

Projektstruktur

gitea-mcp/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── config/               # Configuration management
│   ├── gitea/                # Gitea API client
│   ├── tools/                # MCP tool implementations
│   ├── services/             # Business logic services
│   ├── utils/                # Utilities (logging, errors, etc.)
│   └── types/                # TypeScript type definitions
├── build/                    # Compiled JavaScript
├── docs/                     # Documentation
└── package.json

Hinzufügen neuer Werkzeuge

1. Werkzeugimplementierung in src/tools/ erstellen

2. Schema-Validierung in src/tools/schemas.ts hinzufügen

3. Werkzeug in src/tools/index.ts registrieren

4. Tests in tests/unit/tools/ hinzufügen

Bereitstellung

Docker

Bauen und ausführen mit Docker:

# Build image
docker build -t gitea-mcp .

# Run container
docker run -d \
  --name gitea-mcp \
  --env-file .env \
  gitea-mcp

Überlegungen zur Produktion

• Verwenden Sie Umgebungsvariablen oder Secrets-Management für Token

• Konfigurieren Sie geeignete Protokollierungsebenen

• Richten Sie Überwachung und Gesundheitsprüfungen ein

• Verwenden Sie Prozessmanager wie PM2 für Node.js-Anwendungen

• Erwägen Sie die Verwendung von Docker oder Kubernetes für die Orchestrierung

Sicherheit

Best Practices

• Speichern Sie Token sicher mithilfe von Umgebungsvariablen oder Secrets-Management

• Verwenden Sie minimal erforderliche Berechtigungen für Zugriffstoken

• Validieren Sie alle Eingabeparameter

• Protokollieren Sie Sicherheitsereignisse, ohne sensible Daten preiszugeben

• Verwenden Sie HTTPS für alle Gitea-API-Kommunikationen

• Rotieren Sie regelmäßig Zugriffstoken

Ratenbegrenzung

Der Server implementiert eine Ratenbegrenzung pro Gitea-Instanz, um API-Limits zu respektieren:

• Standard: 100 Anfragen pro Minute pro Instanz

• Konfigurierbar über rateLimit in der Instanzkonfiguration

• Automatischer Wiederholungsversuch mit exponentiellem Backoff

Fehlerbehebung

Häufige Probleme

Authentifizierung fehlgeschlagen

• Überprüfen Sie, ob das Zugriffstoken korrekt ist und die erforderlichen Berechtigungen besitzt

• Prüfen Sie, ob das Token abgelaufen ist

• Stellen Sie sicher, dass die Basis-URL korrekt ist

Ratenbegrenzung erreicht

• Reduzieren Sie die Stapelgröße für Datei-Uploads

• Passen Sie die Konfiguration der Ratenbegrenzung an

• Warten Sie, bevor Sie Anfragen wiederholen

Datei-Upload fehlgeschlagen

• Überprüfen Sie, ob der Dateiinhalt gültig ist

• Stellen Sie sicher, dass Dateipfade keine illegalen Zeichen enthalten

• Stellen Sie sicher, dass das Repository existiert und Sie Schreibberechtigungen