MCP Waifu Queue

Dieses Projekt implementiert einen MCP-Server (Model Context Protocol) für einen KI-„Waifu“-Charakter für Konversationen, der die OpenRouter-API über eine Redis-Warteschlange für die asynchrone Verarbeitung nutzt. Es verwendet die FastMCP-Bibliothek für eine vereinfachte Server-Einrichtung und -Verwaltung.

Inhaltsverzeichnis

• Funktionen

• Architektur

• Voraussetzungen

• Installation

• Konfiguration

• Ausführen des Dienstes

• MCP-API

• Testen

• Fehlerbehebung

• Mitwirken

• Lizenz

Related MCP server: local-agent-context

Funktionen

• Textgenerierung über OpenRouter unter Verwendung des Modells aus ~/.model-openrouter oder openrouter/free.

• Anfragen-Warteschlange mittels Redis zur asynchronen Verarbeitung gleichzeitiger Anfragen.

• MCP-konforme API unter Verwendung von FastMCP.

• Nachverfolgung des Auftragsstatus über MCP-Ressourcen.

• Konfiguration über Umgebungsvariablen (.env-Datei).

• Laden von API-Schlüsseln:

  • OpenRouter: OPENROUTER_API_KEY oder ~/.api-openrouter

• Modellauswahl-Dateien im Home-Verzeichnis:

  • ~/.model-openrouter für den Namen des OpenRouter-Modells

Architektur

Das Projekt besteht aus mehreren Schlüsselkomponenten:

• main.py: Der Haupteinstiegspunkt, der die FastMCP-Anwendung initialisiert und MCP-Tools/Ressourcen definiert.

• respond.py: Enthält die Kernlogik zur Textgenerierung unter Verwendung der OpenRouter-API.

• task_queue.py: Verwaltet die Interaktionen mit der Redis-Warteschlange (unter Verwendung von python-rq) und stellt Generierungsanfragen in die Warteschlange.

• utils.py: Enthält Hilfsfunktionen, insbesondere call_predict_response, die vom Worker ausgeführt wird, um die Generierungslogik in respond.py aufzurufen.

• worker.py: Ein Redis-Worker (python-rq), der Aufträge aus der Warteschlange verarbeitet und call_predict_response aufruft.

• config.py: Verwaltet die Konfiguration unter Verwendung von pydantic-settings.

• models.py: Definiert Pydantic-Modelle für die Validierung von MCP-Anfragen und -Antworten.

Der Ablauf einer Anfrage ist wie folgt:

1. Ein Client sendet eine Anfrage an das generate_text MCP-Tool (definiert in main.py).

2. Das Tool stellt die Anfrage (Prompt) in eine Redis-Warteschlange (verwaltet durch task_queue.py).

3. Ein worker.py-Prozess nimmt den Auftrag aus der Warteschlange auf.

4. Der Worker führt die Funktion call_predict_response (aus utils.py) aus.

5. call_predict_response ruft die Funktion predict_response (in respond.py) auf, die mit der OpenRouter-API interagiert.

6. Der generierte Text (oder eine Fehlermeldung) wird von predict_response zurückgegeben und von RQ als Auftragsergebnis gespeichert.

7. Der Client kann den Auftragsstatus und das Ergebnis über die job://{job_id} MCP-Ressource (definiert in main.py) abrufen.

graph LR
    subgraph Client
        A[User/Client] -->|1. Send Prompt via MCP Tool| B(mcp-waifu-queue: main.py)
    end
    subgraph mcp-waifu-queue Server
        B -->|2. Enqueue Job (prompt)| C[Redis Queue]
        B -->|7. Return Job ID| A
        D[RQ Worker (worker.py)] --|>| C
        D -->|3. Dequeue Job & Execute| E(utils.call_predict_response)
        E -->|4. Call Generation Logic| F(respond.predict_response)
        F -->|5. Call OpenRouter API| G[OpenRouter API]
        G -->|6. Return Response| F
        F --> E
        E -->|Update Job Result in Redis| C
        A -->|8. Check Status via MCP Resource| B
        B -->|9. Fetch Job Status/Result| C
        B -->|10. Return Status/Result| A
    end

Voraussetzungen

• Python 3.7+

• pip oder uv (Python-Paket-Installer)

• Redis-Server (installiert und laufend)

• Ein OpenRouter-API-Schlüssel

Anleitungen zur Installation von Redis auf Ihrem System finden Sie auf der offiziellen Redis-Website: https://redis.io/docs/getting-started/ Einen OpenRouter-API-Schlüssel erhalten Sie unter: https://openrouter.ai/

Installation

1. Klonen Sie das Repository:

   git clone <YOUR_REPOSITORY_URL>
   cd mcp-waifu-queue

2. Erstellen und aktivieren Sie eine virtuelle Umgebung mit uv:

   python -m uv venv .venv
   .venv/Scripts/python.exe -m ensurepip
   .venv/Scripts/python.exe -m pip install uv

3. Installieren Sie die Abhängigkeiten:

   .venv/Scripts/python.exe -m uv pip install -r requirements.txt
   .venv/Scripts/python.exe -m uv pip install -r requirements-dev.txt

Konfiguration

1. Modellnamen über Dateien im $HOME-Verzeichnis:

   • OpenRouter-Modelldatei:

     echo "openrouter/free" > ~/.model-openrouter

2. API-Schlüssel: Bevorzugt über Umgebungsvariablen mit Datei-Fallback:

   • OpenRouter: OPENROUTER_API_KEY oder ~/.api-openrouter GXP6

   (Ersetzen Sie YOUR_API_KEY_HERE durch Ihren tatsächlichen Schlüssel)

3. Weitere Einstellungen: Kopieren Sie die .env.example-Datei nach .env:

   cp .env.example .env

4. Ändern Sie die .env-Datei, um die restlichen Konfigurationswerte festzulegen:

   • MAX_NEW_TOKENS: Maximale Anzahl an Token für die Antwort (Standard: 2048).

   • REDIS_URL: Die URL Ihres Redis-Servers (Standard: redis://localhost:6379).

   • FLASK_ENV, FLASK_APP: Optional, bezogen auf Flask, falls anderswo verwendet, nicht wesentlich für den Betrieb des MCP-Servers/Workers.

Ausführen des Dienstes

1. Stellen Sie sicher, dass Redis läuft. Wenn Sie es lokal installiert haben, müssen Sie möglicherweise den Redis-Server-Prozess starten (z. B. Befehl redis-server oder über einen Dienstmanager).

2. Starten Sie den RQ-Worker: Öffnen Sie ein Terminal, aktivieren Sie Ihre virtuelle Umgebung (source .venv/bin/activate oder ähnlich) und führen Sie aus:

   python -m mcp_waifu_queue.worker

   Dieser Befehl startet den Worker-Prozess, der auf Aufträge in der in Ihrer .env-Datei definierten Redis-Warteschlange wartet. Lassen Sie dieses Terminal geöffnet.

3. Starten Sie den MCP-Server: Öffnen Sie ein weiteres Terminal, aktivieren Sie die virtuelle Umgebung und führen Sie den MCP-Server mit einem Tool wie uvicorn aus (Sie müssen es möglicherweise installieren: pip install uvicorn oder uv pip install uvicorn):

   uvicorn mcp_waifu_queue.main:app --reload --port 8000 # Example port

   Ersetzen Sie 8000 durch Ihren gewünschten Port. Das --reload-Flag ist nützlich für die Entwicklung.

   Alternativ können Sie das Skript start-services.sh verwenden (hauptsächlich für Linux/macOS-Umgebungen konzipiert), das versucht, Redis (falls nicht laufend) und den Worker im Hintergrund zu starten:

   # Ensure the script is executable: chmod +x ./scripts/start-services.sh
   ./scripts/start-services.sh
   # Then start the MCP server manually as shown above.

MCP-API

Der Server stellt die folgenden MCP-konformen Endpunkte bereit:

Tools

• generate_text

  • Beschreibung: Sendet eine Textgenerierungsanfrage über die Hintergrund-Warteschlange an die OpenRouter-API.

  • Eingabe: {"prompt": "Ihr Text-Prompt hier"} (Typ: GenerateTextRequest)

  • Ausgabe: {"job_id": "rq:job:..."} (Eine eindeutige ID für den in die Warteschlange eingereihten Auftrag)

Ressourcen

• job://{job_id}

  • Beschreibung: Ruft den Status und das Ergebnis eines zuvor übermittelten Auftrags ab.

  • URI-Parameter: job_id (Die vom generate_text-Tool zurückgegebene ID).

  • Ausgabe: {"status": "...", "result": "..."} (Typ: JobStatusResponse)

    • status: Der aktuelle Zustand des Auftrags (z. B. "queued", "started", "finished", "failed"). RQ verwendet intern leicht abweichende Begriffe ("started" vs. "processing", "finished" vs. "completed"). Die Ressource bildet diese ab.

    • result: Der generierte Text, wenn der Auftragsstatus "completed" ist, andernfalls null. Wenn der Auftrag fehlgeschlagen ist, kann das Ergebnis null sein oder Fehlerinformationen enthalten, abhängig von der Handhabung durch RQ.

Testen

Das Projekt enthält Tests. Stellen Sie sicher, dass Sie die Testabhängigkeiten installiert haben (pip install -e .[test] oder uv pip install -e .[test]).

Führen Sie Tests mit pytest aus:

pytest tests

Hinweis: Tests erfordern möglicherweise das Mocking von Redis (fakeredis) und potenziell der OpenRouter-API-Aufrufe, abhängig von deren Implementierung.

Fehlerbehebung

• Fehler: OpenRouter API key not available: Stellen Sie sicher, dass OPENROUTER_API_KEY gesetzt ist oder ~/.api-openrouter mit Ihrem Schlüssel in einer einzigen Zeile (ohne Leerzeichen) existiert.

• Aufträge bleiben in "queued" hängen: Überprüfen Sie, ob der RQ-Worker (python -m mcp_waifu_queue.worker) in einem separaten Terminal läuft und mit derselben Redis-Instanz verbunden ist, die in .env angegeben ist. Überprüfen Sie die Worker-Protokolle auf Fehler.

• ConnectionRefusedError (Redis): Stellen Sie sicher, dass Ihr Redis-Server läuft und unter der in .env angegebenen REDIS_URL erreichbar ist.

• Verbindungsprobleme zum MCP-Server: Stellen Sie sicher, dass der MCP-Server (uvicorn ...) läuft und Sie sich mit dem richtigen Host/Port verbinden.

Mitwirken

1. Forken Sie das Repository.

2. Erstellen Sie einen neuen Branch für Ihr Feature oder Ihren Bugfix (git checkout -b feature/your-feature-name).

3. Nehmen Sie Ihre Änderungen vor und committen Sie diese (git commit -am 'Add some feature').

4. Pushen Sie Ihren Branch auf Ihr geforktes Repository (git push origin feature/your-feature-name).

5. Erstellen Sie einen Pull Request für das ursprüngliche Repository.

Bitte halten Sie sich an die Codierungsstandards und Linting-Regeln (ruff) des Projekts.

Lizenz

Dieses Projekt ist unter der MIT-0-Lizenz lizenziert - siehe die Datei LICENSE für Details.