YOURLS-MCP

YOURLS-MCP

Ein Model Control Protocol (MCP)-Server zur Integration der YOURLS-URL-Verkürzung in Claude Desktop.

Autor: Martin Kessler

Überblick

YOURLS-MCP bildet eine Brücke zwischen Claude Desktop und Ihrer selbst gehosteten YOURLS -URL-Shortener-Instanz. Nach der Konfiguration ermöglicht es Claude, URLs mithilfe Ihrer persönlichen YOURLS-Installation automatisch zu kürzen.

Merkmale

• Kürzen Sie URLs mit Ihrer YOURLS-Instanz
• Erstellen Sie benutzerdefinierte Kurz-URLs mit bestimmten Schlüsselwörtern
• Umgang mit doppelten URLs: Erstellen Sie mehrere Kurz-URLs für dieselbe Ziel-URL (eindeutig für YOURLS-MCP).
• Erweiterte URL-Informationen und Statistiken
• Datenbankstatistiken
• Intelligente Fallbacks für Plugins
• Umfassende Dokumentation und Testtools

Schnellstart

Installation

Konfiguration

Erstellen Sie eine Claude Desktop-Konfigurationsdatei, die auf Ihre YOURLS-MCP-Installation verweist:

Speichern Sie diese Datei in Ihrem Claude Desktop-Konfigurationsverzeichnis. Normalerweise lautet das Verzeichnis:

• macOS: ~/Library/Application Support/Claude/config.json
• Windows: %APPDATA%\Claude\config.json
• Linux: ~/.config/Claude/config.json

Merkmale

• Nahtlose Integration mit Claude Desktop über MCP
• URLs direkt über Claude kürzen
• Erweitern Sie verkürzte URLs, um ihr Ziel anzuzeigen
• Abrufen von Klickstatistiken für Ihre Links
• Unterstützung benutzerdefinierter Schlüsselwörter
• Sichere signaturbasierte Authentifizierung
• Konfiguration der Umgebungsvariablen

Konfigurationsoptionen

Die folgenden Umgebungsvariablen können in der Claude Desktop-Konfiguration festgelegt werden:

Verfügbare MCP-Tools

YOURLS-MCP stellt Claude die folgenden Tools zur Verfügung:

Kernwerkzeuge

1. URL verkürzen

Verkürzt eine lange URL mithilfe Ihrer YOURLS-Instanz.

Parameter:

• url (erforderlich): Die lange URL, die gekürzt werden soll
• keyword (optional): Benutzerdefiniertes Schlüsselwort für die Kurz-URL
• title (optional): Titel für die URL

2. expand_url

Erweitert eine kurze URL, um die ursprüngliche lange URL zu erhalten.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort zum Erweitern

3. url_stats

Ruft Statistiken für eine verkürzte URL ab.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort, für das Statistiken abgerufen werden sollen

4. db_stats

Ruft globale Statistiken für Ihre YOURLS-Instanz ab.

Parameter: Keine

5. benutzerdefinierte URL erstellen

Erstellt eine benutzerdefinierte Kurz-URL mit einem bestimmten Schlüsselwort, auch für URLs, die bereits in der Datenbank vorhanden sind.

Parameter:

• url (erforderlich): Die zu kürzende Ziel-URL
• keyword (erforderlich): Das benutzerdefinierte Schlüsselwort für die Kurz-URL (z. B. „Web“ für bysha.pe/web)
• title (optional): Titel für die URL
• bypass_shortshort (optional): Ob das ShortShort-Plugin umgangen werden soll, das das Kürzen bereits gekürzter URLs verhindert (Standard: false)
• force_url_modification (optional): Ob die Verwendung der URL-Änderungsmethode zum Erstellen mehrerer Kurz-URLs für dasselbe Ziel erzwungen werden soll (Standard: „false“)

6. Verkürzen mit Analytics

Verkürzt eine lange URL mit Google Analytics UTM-Parametern.

Parameter:

• url (erforderlich): Die zu kürzende URL
• source (erforderlich): UTM-Quellparameter – identifiziert die Quelle des Datenverkehrs (z. B. „Google“, „Newsletter“, „Twitter“)
• medium (erforderlich): UTM-Mediumparameter – identifiziert das Marketingmedium (z. B. „CPC“, „Soziales“, „E-Mail“)
• campaign (erforderlich): UTM-Kampagnenparameter – identifiziert die spezifische Kampagne (z. B. „summer_sale“, „product_launch“)
• term (optional): UTM-Term-Parameter – identifiziert bezahlte Suchbegriffe
• content (optional): UTM-Inhaltsparameter - unterscheidet Anzeigen oder Links, die auf dieselbe URL verweisen
• keyword (optional): Benutzerdefiniertes Schlüsselwort für die Kurz-URL
• title (optional): Titel für die URL

Plugin-basierte Tools

7. url_analytics

Ruft detaillierte Klickanalysen für eine Kurz-URL innerhalb eines bestimmten Zeitraums ab. Erfordert die Installation des API ShortURL Analytics-Plugins.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort, für das Analysen abgerufen werden sollen
• date (erforderlich): Startdatum für die Analyse im Format JJJJ-MM-TT
• date_end (optional): Enddatum für die Analyse im Format JJJJ-MM-TT (standardmäßig das Startdatum, falls nicht angegeben)

8. Vertrags-URL

Prüft, ob eine URL bereits gekürzt wurde, ohne eine neue Kurz-URL zu erstellen. Erfordert die Installation des API Contract-Plugins.

Parameter:

• url (erforderlich): Die URL, um zu überprüfen, ob sie gekürzt wurde

9. URL aktualisieren

Aktualisieren Sie eine vorhandene Kurz-URL, sodass sie auf eine andere Ziel-URL verweist. Dazu muss das API-Plugin „URL bearbeiten“ installiert sein.

Parameter:

• shorturl (erforderlich): Die zu aktualisierende Kurz-URL oder das Schlüsselwort
• url (erforderlich): Die neue Ziel-URL
• title (optional): Optionaler neuer Titel („behalten“, um den vorhandenen beizubehalten, „auto“, um ihn von der URL abzurufen)

10. Schlüsselwort ändern

Ändern Sie das Schlüsselwort einer bestehenden Kurz-URL. Dazu muss das API-Plugin „URL bearbeiten“ installiert sein.

Parameter:

• oldshorturl (erforderlich): Die vorhandene Kurz-URL oder das Schlüsselwort
• newshorturl (erforderlich): Das neue zu verwendende Schlüsselwort
• url (optional): Optionale URL (falls nicht angegeben, wird die URL von oldshorturl verwendet)
• title (optional): Optionaler neuer Titel („behalten“, um den vorhandenen beizubehalten, „auto“, um ihn von der URL abzurufen)

11. URL-Schlüsselwort abrufen

Holen Sie sich die Schlüsselwörter für eine lange URL. Dazu muss das API Edit URL-Plugin installiert sein.

Parameter:

• url (erforderlich): Die lange URL zum Nachschlagen
• exactly_one (optional): Wenn false, werden alle Schlüsselwörter für diese URL zurückgegeben (Standard: true)

12. URL löschen

Löscht eine Kurz-URL. Dazu muss das Plugin „API Delete“ installiert sein.

Parameter:

• shorturl (erforderlich): Die zu löschende Kurz-URL oder das Schlüsselwort

13. list_urls

Erhalten Sie eine Liste von URLs mit Sortier-, Paginierungs- und Filteroptionen. Erfordert die Installation des Plugins „API List Extended“.

Parameter:

• sortby (optional): Feld zum Sortieren nach (Schlüsselwort, URL, Titel, IP, Zeitstempel, Klicks) (Standard: Zeitstempel)
• sortorder (optional): Sortierreihenfolge (ASC oder DESC) (Standard: DESC)
• offset (optional): Paginierungsoffset (Standard: 0)
• perpage (optional): Anzahl der Ergebnisse pro Seite (Standard: 50)
• query (optional): Optionale Suchabfrage zum Filtern nach Schlüsselwörtern
• fields (optional): Zurückzugebende Felder (Schlüsselwort, URL, Titel, Zeitstempel, IP, Klicks) (Standard: alle Felder)

14. QR-Code generieren

Generieren Sie einen QR-Code für eine verkürzte URL. Erfordert die Installation des Plugins YOURLS-IQRCodes.

Parameter:

• shorturl (erforderlich): Die kurze URL oder das Schlüsselwort zum Generieren eines QR-Codes für
• size (optional): QR-Code-Größe in Pixeln
• border (optional): Rahmenbreite um den QR-Code
• ecc (optional): Fehlerkorrekturstufe: L (niedrig), M (mittel), Q (Quartil) oder H (hoch)
• format (optional): Bildformat (png, jpg, svg usw.)

Anwendungsbeispiele

Nach der Konfiguration kann Claude die YOURLS-Tools mit Eingabeaufforderungen wie den folgenden verwenden:

Beispiele für Kernfunktionen

• „Kürzen Sie diese URL für mich: https://example.com/sehr-lange-url-die-gekürzt-werden-muss “
• „Erstellen Sie eine kurze URL mit dem Schlüsselwort ‚docs‘ für https://example.com/documentation “
• „Richten Sie eine benutzerdefinierte URL bysha.pe/web ein, die auf shapescale.com verweist.“
• „Erstellen Sie eine benutzerdefinierte Kurz-URL für unsere Dokumentation mit dem Schlüsselwort ‚docs‘.“
• „Erstellen Sie mehrere Schlüsselwörter (docs, docs2, docs3) für dieselbe Dokumentations-URL.“
• „Erstellen Sie eine kurze URL für unsere Kampagne mit UTM-Tracking-Parametern“
• „Kürzen Sie diese Marketing-URL mit Google Analytics-Tracking: Quelle=Newsletter, Medium=E-Mail, Kampagne=Sommerstart“
• "Erweitern Sie diese kurze URL: https://IhreDomain.com/abc "
• „Wie viele Klicks hat meine Kurz-URL https://yourdomain.com/abc ?“
• „Zeigen Sie mir die Statistiken für meine YOURLS-Instanz“

Beispiele für Plugin-basierte Funktionen

• „Geben Sie mir detaillierte Analysen für die Kurz-URL ‚abc‘ für Januar 2025.“
• „Zeigen Sie mir die Klickstatistiken für bysha.pe/abc vom 01.01.2025 bis zum 31.01.2025“
• „Wie hoch war der tägliche Datenverkehr für meine Kurz-URL ‚Web‘ im letzten Monat?“
• „Überprüfen Sie, ob diese URL bereits gekürzt wurde: https://example.com/page “
• „Hat jemand bereits eine Kurz-URL für https://example.com/page erstellt?“
• „Aktualisieren Sie das Ziel der Kurz-URL ‚docs‘, sodass es auf https://example.com/new-documentation verweist.“
• „Ändern Sie, wohin das Schlüsselwort ‚docs‘ verweist.“
• „Benennen Sie die Kurz-URL ‚docs‘ in ‚documentation‘ um.“
• „Ändern Sie das Schlüsselwort meiner Kurz-URL von ‚docs‘ in ‚documentation‘.“
• „Was ist das Schlüsselwort für diese lange URL: https://example.com/page ?“
• "Liste alle Kurz-URLs für https://example.com/page auf"
• „Löschen Sie die Kurz-URL ‚docs‘“
• „Entfernen Sie das Schlüsselwort ‚docs‘ aus meiner YOURLS-Instanz.“
• „Zeigen Sie mir die aktuellsten 10 Kurz-URLs in meiner YOURLS-Datenbank“
• "Liste alle Kurz-URLs sortiert nach der Anzahl der Klicks auf"
• „Suchen Sie nach kurzen URLs, die ‚Produkt‘ enthalten.“
• „Generieren Sie einen QR-Code für meine Kurz-URL ‚docs‘“
• „Erstellen Sie einen QR-Code für bysha.pe/web“
• „Geben Sie mir einen QR-Code für meine Produktseite mit hoher Fehlerkorrektur“
• „Ich brauche einen größeren QR-Code für die ‚Landing‘-Kurz-URL, also 300 Pixel.“
• „Generieren Sie einen SVG-QR-Code für unseren Dokumentationslink.“

Entwicklung

Wie es funktioniert

YOURLS-MCP fungiert als Brücke zwischen Claude Desktop und Ihrer YOURLS-Instanz:

1. Claude Desktop startet den YOURLS-MCP-Server bei Bedarf
2. Der Server liest die Konfiguration aus Umgebungsvariablen
3. Wenn Claude ein Tool aufruft, führt der Server die entsprechenden API-Aufrufe an Ihre YOURLS-Instanz durch
4. Die Ergebnisse werden Claude in einem strukturierten Format zurückgegeben

Der Server verwendet den Model Context Protocol (MCP)-Standard zur Kommunikation mit Claude Desktop und ermöglicht so eine nahtlose Integration und natürliche Sprachinteraktion mit Ihrem URL-Shortener.

Umgang mit doppelten URLs

YOURLS-MCP bietet die einzigartige Möglichkeit, mehrere Kurz-URLs für dieselbe Ziel-URL zu erstellen. Diese Funktion wird von YOURLS nicht nativ unterstützt. Ausführliche Informationen zu dieser Funktion finden Sie in der Dokumentation zur Handhabung doppelter URLs .

Es werden zwei Ansätze unterstützt:

1. Plugin-Ansatz (empfohlen): Verwendet das enthaltene Plugin „Force Allow Duplicates“, um echte doppelte URLs zu erstellen
2. URL-Modifikationsansatz (Fallback): Fügt Zeitstempelparameter hinzu, um jede URL technisch eindeutig zu machen und gleichzeitig die Funktionalität zu erhalten

Das System wählt automatisch den geeigneten Ansatz basierend auf Ihrem YOURLS-Setup.

Kompatibilität mit YOURLS-Plugins

YOURLS-MCP ist so konzipiert, dass es sowohl mit Standard-YOURLS-Installationen als auch mit verschiedenen Plugins funktioniert, mit integrierten Fallbacks, wenn Plugins nicht verfügbar sind:

Unterstützte Plugins mit Fallbacks

YOURLS-MCP enthält intelligente Fallbacks für erweiterte Funktionen, wenn keine Plugins installiert sind:

• API ShortURL Analytics : Für detaillierte Klickstatistiken mit Datumsbereichen
  • Fallback-Verhalten : Bietet grundlegende Klickstatistiken über die YOURLS-Kern-API, wenn das Plugin nicht verfügbar ist
• API-Vertrag : Um zu prüfen, ob URLs vorhanden sind, ohne sie zu erstellen
  • Fallback-Verhalten : Verwendet die Kern-API von YOURLS Stats, um mit Filterung nach vorhandenen URLs zu suchen
• API-URL bearbeiten : Zum Aktualisieren kurzer URLs und Ändern von Schlüsselwörtern
  • Fallback-Verhalten :
    • Zum Aktualisieren von URLs: Versuche, die URL mit demselben Schlüsselwort neu zu erstellen
    • Zum Ändern von Schlüsselwörtern: Erstellt eine neue Kurz-URL mit dem neuen Schlüsselwort (die alte bleibt erhalten, da zum Löschen das API Delete-Plugin erforderlich ist)
    • Zum Abrufen von URL-Schlüsselwörtern: Verwendet die Kern-API YOURLS-Statistiken mit Filterung
• API Delete : Zum Entfernen kurzer URLs
  • Fallback-Verhalten : Eingeschränkt – bietet Informationen darüber, dass zum Löschen das Plugin erforderlich ist, da die Kern-API von YOURLS das Löschen nicht unterstützt
• API-Liste erweitert : Für eine erweiterte URL-Auflistung mit Sortierung und Filterung
  • Fallback-Verhalten : Verwendet die Kern-API von YOURLS-Statistiken mit clientseitiger Sortierung und Paginierung
• YOURLS-IQRCodes : Zum Generieren von QR-Codes aus Kurz-URLs
  • Fallback-Verhalten : Keines – erfordert die Installation des Plugins
• ShortShort : Behandelt den Fehler ordnungsgemäß, wenn versucht wird, eine bereits gekürzte URL zu kürzen
  • Kompatibilität : Die Fehlerbehandlung funktioniert unabhängig davon, ob das Plugin installiert ist
• Vorhandene URLs zulassen : Ändert, wie YOURLS mit doppelten URLs umgeht
  • Plugin-URL : https://github.com/elder-oss/yourls-allow-existing-urls
  • Hinweis : Dieses Plugin ändert Fehlerantworten in Erfolgsantworten, erstellt aber keine neuen Kurz-URLs für bestehende Ziel-URLs.
  • Unsere Lösung : YOURLS-MCP implementiert einen URL-Modifikationsansatz, der einen Zeitstempelparameter hinzufügt, um URLs in der Datenbank eindeutig zu machen und gleichzeitig die Benutzererfahrung zu erhalten
  • Installation : Optional – unser Ansatz zur URL-Änderung funktioniert mit oder ohne installiertes Plugin
• Duplikate zulassen erzwingen : Ermöglicht das Erstellen mehrerer kurzer URLs für dieselbe Ziel-URL.
  • Plugin-Repository : https://github.com/kesslerio/yourls-force-allow-duplicates (in Kürze verfügbar)
  • Beschreibung : Benutzerdefiniertes Plugin, das die eindeutige URL-Einschränkung von YOURLS umgeht
  • Verwendung : Fügen Sie force=1 zu Ihren API-Anfragen hinzu oder verwenden Sie force_url_modification=false mit dem Tool create_custom_url
  • Installation :
    1. Download aus dem Plugin-Repository
    2. Kopieren Sie den Ordner force-allow-duplicates in Ihr Verzeichnis YOURLS/user/plugins/
    3. Aktivieren Sie das Plugin in Ihrer YOURLS-Admin-Oberfläche

Fallback-Mechanismus

Wenn eine Plugin-abhängige Funktion verwendet wird, das Plugin aber nicht installiert ist, führt YOURLS-MCP Folgendes aus:

1. Erkennt automatisch fehlende Plugins
2. Bietet, soweit möglich, entsprechende Fallback-Funktionen
3. Enthält ein fallback_used: true Attribut in Antworten, wenn Fallbacks aktiviert sind
4. Fügt fallback_limitations -Informationen hinzu, wenn die Fallback-Funktionalität eingeschränkt ist
5. Gibt bei vollständig nicht unterstützten Vorgängen informative Fehlermeldungen zurück

Dieser Ansatz stellt sicher, dass YOURLS-MCP mit möglichst vielen YOURLS-Installationen funktioniert und gleichzeitig klare Informationen über die mit Plugins verfügbaren erweiterten Funktionen bereitstellt.

Entwicklung und Tests

Testskripte

Das Projekt enthält verschiedene Testskripte im Verzeichnis tests/integration/ :

• URL-Verkürzungstests :
  • test-custom-url.js : Tests zum Erstellen benutzerdefinierter URLs mit bestimmten Schlüsselwörtern
  • test-url-modification.js : Testet den URL-Änderungsansatz für den Umgang mit doppelten URLs
  • test-plugin-behavior.js : Testet das Verhalten des Plugins „Vorhandene URLs zulassen“
• Plugin-Tests :
  • test-duplicate-urls.js : Testet das Erstellen doppelter URLs mit unterschiedlichen Schlüsselwörtern
  • test-plugin-approach.js : Testet den direkten Plugin-Ansatz zur Handhabung von Duplikaten
• Laufende Tests :
  # Run a specific test node tests/integration/test-custom-url.js

Hilfsskripte

Das Verzeichnis scripts/ enthält Dienstprogrammskripte für allgemeine Vorgänge:

• create-random.js : Erstellt eine zufällige Kurz-URL für ein angegebenes Ziel
• Andere Skripte für bestimmte Aufgaben zur URL-Erstellung

Lizenz

MIT

Um

YOURLS-MCP wurde von Martin Kessler entwickelt, um YOURLS über das Model Context Protocol (MCP) mit Claude Desktop und anderen Claude-Angeboten zu integrieren.

Das Plugin „Force Allow Duplicates“ wurde entwickelt, um das Problem der Erstellung mehrerer Kurz-URLs für dasselbe Ziel zu lösen, was in YOURLS nicht nativ unterstützt wird.

Für Support, Probleme oder Funktionsanfragen:

• YOURLS-MCP: https://github.com/kesslerio/yourls-mcp/issues
• Plugin „Force Allow Duplicates“: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (sobald das Repository erstellt ist)