Baomihua Formatter MCP Server

Ein eigenständiger Node.js-MCP-Server zum Prüfen und Bearbeiten von Mediendateien in OpenList und CloudDrive2 sowie zum Abfragen von TMDB-Film- und Serienmetadaten. Der Server kommuniziert über MCP stdio und speichert Speicher-/TMDB-Anmeldeinformationen in der lokalen Umgebungskonfiguration und nicht in Tool-Beschreibungen oder eingecheckter Dokumentation.

Anforderungen

• Node.js 20 oder neuer (package.json deklariert engines.node >=20.0.0).

• Netzwerkzugriff auf den konfigurierten OpenList- und/oder CloudDrive2-Endpunkt, wenn diese Backends verwendet werden.

• TMDB-Anmeldeinformationen bei Verwendung der TMDB-Tools.

Installation

Führen Sie im Server-Projektverzeichnis Folgendes aus:

Set-Location C:\path\to\baomihua-formatter-mcp-server
Copy-Item .env.example .env
npm install

Bearbeiten Sie die lokale .env-Datei mit den für Ihre Umgebung benötigten Endpunkten und Anmeldeinformationen. .env wird von Git ignoriert; committen Sie sie niemals, fügen Sie keine Geheimnisse in diese README ein und nehmen Sie keine echten Anmeldeinformationen in eine in der Versionsverwaltung eingecheckte MCP-Client-Konfiguration auf.

Die unterstützten Konfigurationsschlüssel werden in .env.example dokumentiert, einschließlich:

• OPENLIST_URL, OPENLIST_USERNAME, OPENLIST_PASSWORD und optional OPENLIST_OTP_CODE;

• CLOUDDRIVE2_URL, CLOUDDRIVE2_TOKEN und CLOUDDRIVE2_TLS;

• TMDB_API_KEY oder TMDB_TOKEN sowie optional TMDB_LANGUAGE und TMDB_PROXY;

• STORAGE_CONCURRENCY, UPLOAD_CONCURRENCY und STORAGE_MAX_CONCURRENCY;

MCP-Server ausführen

Das npm-Skript startet den stdio-Server:

npm run mcp

Der Prozess soll von einem MCP-Client gestartet werden, sodass der normale Protokollverkehr über stdin/stdout läuft. Halten Sie Diagnoseausgaben von stdout fern, wenn Sie den Server einbetten.

Generischer MCP-Client-Eintrag

Verwenden Sie eine absolute Node-Ausführungsdatei und einen absoluten Serverpfad. Ersetzen Sie nur die Beispielpfade und konfigurieren Sie Geheimnisse über die lokale .env-Datei des Servers; dieser Eintrag enthält absichtlich keine Anmeldeinformationen:

{
  "mcpServers": {
    "baomihua-formatter": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\baomihua-formatter-mcp-server\\server.js"
      ]
    }
  }
}

Der MCP-Client sollte den Eintrag aus einem Kontext heraus starten, in dem das Serverprojekt seine .env-Datei hat. Ein äquivalenter Shell-Befehl ist:

& 'C:\Program Files\nodejs\node.exe' 'C:\path\to\baomihua-formatter-mcp-server\server.js'

Tool-Gruppen und Semantik

Speichernavigation

Beide Speicher-Backends bieten eine direkte Auflistung und einen rekursiven Scan an:

• openlist_list / clouddrive2_list listen nur direkte Unterelemente auf.

• openlist_scan / clouddrive2_scan sammeln rekursiv Nachfolgeelemente und akzeptieren begrenzte concurrency- und continue_on_error-Optionen.

• openlist_stat / clouddrive2_stat prüfen einen genauen Pfad.

• openlist_search / clouddrive2_search durchsuchen Einträge unterhalb eines Pfads.

Scan- und Upload-Verzeichnisoperationen verwenden begrenzte Parallelität. Halten Sie die Parallelität innerhalb des konfigurierten Maximums des Servers und lassen Sie continue_on_error auf false, sofern nicht absichtlich eine teilweise Fertigstellung akzeptiert wird.

Dateioperationen

OpenList und CloudDrive2 stellen jeweils Werkzeuge zum Erstellen von Verzeichnissen, Umbenennen, Löschen von Dateien/Verzeichnissen, Verschieben, Kopieren und Hochladen von Dateien/Verzeichnissen bereit. CloudDrive2 bietet außerdem clouddrive2_get_download_url an.

Jedes verändernde Tool erfordert confirm: true. Der Agent oder MCP-Client muss dem Benutzer zuerst die genauen vorgeschlagenen Pfade, Namen, Ziele, Konfliktrichtlinie und zerstörerischen Auswirkungen präsentieren. Der Server lehnt unbestätigte Änderungen ab. continue_on_error ist kein Bestätigungsmechanismus; es steuert nur, ob ein begrenzter Stapel nach einem Fehler bei einem Element fortgesetzt wird.

TMDB

Der Server stellt tmdb_search_movie, tmdb_search_tv, tmdb_get_movie_details, tmdb_get_tv_details und tmdb_get_season_details bereit. Diese Tools geben Kandidaten oder Metadaten zurück; sie benennen keine Dateien um.

Die Extraktion von Dateinamen-Titel/Jahr/Staffel/Episode/Qualität liegt bewusst in der Verantwortung des Agents. Untersuchen Sie bei Medienformatierungs-Workflows den vollständigen Speicherpfad, extrahieren Sie diese Felder unabhängig, fragen Sie TMDB-Kandidaten ab, validieren Sie das ausgewählte Ergebnis mit Details und bitten Sie den Benutzer, mehrdeutige Namensgleichheitskandidaten aufzulösen, bevor Sie eine Änderung vorschlagen.

Empfohlener Arbeitsablauf

1. Verwenden Sie einen Backend-*_list-Aufruf zur direkten Navigation oder *_scan zur rekursiven Erfassung.

2. Behalten Sie die ursprünglichen Pfade bei und parsen Sie Titel, Jahr, Staffel, Episode, Qualität und Untertitelmarkierungen unabhängig.

3. Durchsuchen Sie TMDB, vergleichen Sie Kandidaten mit den geparsten Belegen und rufen Sie Details für die gewählte ID ab.

4. Zeigen Sie einen vollständigen Umbenennungs-/Verschiebe-/Kopier-/Lösch-/Upload-Vorschlag an und warten Sie auf eine ausdrückliche Bestätigung.

5. Führen Sie die bestätigte Änderung mit confirm: true aus.

6. Verifizieren Sie mit einer Folgeauflistung, einem Stat- oder Scan-Aufruf und melden Sie Erfolge, Übersprungenes und Fehler.

Entwicklung

Führen Sie die Testsuite aus diesem Verzeichnis aus:

npm test

Das Projekt ist privat, verwendet ESM und hat keine Laufzeitabhängigkeit von der älteren Formatter-CLI. Halten Sie Anmeldeinformationen und generierte Protokolle aus Commits heraus.