RomM MCP

romm-mcp ist ein von der Community gepflegter Model-Context-Protocol-Server (MCP) für die begrenzte Verwaltung von RomM über die authentifizierte API von RomM. Er ist nicht mit dem RomM-Projekt verbunden, wird nicht von ihm unterstützt und nicht von ihm gewartet.

Der Server ist bewusst enger gefasst als die vollständige RomM-API: Er bietet explizite typisierte Lese-/Schreib-Tools für gängige Bibliotheksverwaltungsaufgaben, ohne einen generischen HTTP-Durchgriff oder eine breite administrative Hintertür.

Status und Kompatibilität

• Erste Release-Linie: 0.1.x.

• Getestet gegen die API-Verträge von RomM 5.1.0.

• Erfordert Python 3.12 oder neuer.

• Verwendet RomM-Client-API-Tokens (rmm_...) als Bearer-Anmeldedaten.

Spätere RomM-Versionen sind möglicherweise weiterhin kompatibel, gelten aber erst als getestet, wenn dies verifiziert wurde.

Grenzen des Funktionsumfangs

In v0.1 enthalten:

• Plattform- und ROM-Erkennung.

• Begrenzte Aktualisierungen der ROM-Textmetadaten (name, name_sort_key, summary).

• Persönliche ROM-Status-, Bewertungs- und Abschluss-Eigenschaften.

• ROM-Notizen.

• Reguläre Sammlungen und Sammlungszugehörigkeit.

• Smarte Sammlungen mit einem expliziten RomM-5.1-Filterschema.

• Benutzersichtbarkeit und das Lesen von Spielsitzungen.

In v0.1 bewusst ausgeschlossen:

• Generischer API/HTTP-Durchgriff.

• Löschung von ROMs oder ROM-Dateien.

• Hochladen oder Ersetzen von ROMs/Dateien.

• Remote-Abruf von Covern/Handbüchern und Asset-Änderungen.

• Bibliotheksscans, Hintergrundaufgaben und Massenaktualisierung von Metadaten.

• Änderung der Plattform-/Systemkonfiguration.

• Client-Token-Verwaltung.

• Änderung von Benutzern, Berechtigungsgruppen oder Autorisierungen.

• Änderung von Geräten/Synchronisierung.

Das Entfernen von ROMs aus einer Sammlung ändert nur die Sammlungszugehörigkeit. Das Löschen einer regulären Sammlung erfordert confirm=true; RomM entfernt dabei auch das eigene verwaltete Artwork-/Ressourcenverzeichnis dieser Sammlung, aber ROM-Dateien werden von diesem MCP nie gelöscht.

Siehe docs/tools.md für die vollständige Oberfläche mit 26 Tools und die Nebenwirkungen pro Tool.

Installation

Releases werden als unveränderliche GitHub-Release-Wheels verteilt. romm-mcp ist derzeit nicht auf PyPI veröffentlicht.

Für v0.1.0:

uvx --python 3.12 \
  --from https://github.com/X1pheR/romm-mcp/releases/download/v0.1.0/romm_mcp-0.1.0-py3-none-any.whl \
  romm-mcp

Jedes Release enthält SHA256SUMS. Für festgepinnte oder Produktionsnutzung verifizieren Sie den Wheel-Digest vor der Bereitstellung und pinnen Sie, wo unterstützt, die Artefakt-URL mit ihrem SHA-256-Hash.

Konfiguration

Der Server erfordert ein dediziertes RomM-Client-API-Token, das in einer Datei gespeichert ist. Token-Werte werden niemals als MCP-Tool-Argumente akzeptiert.

ROMM_BASE_URL=https://romm.example.com
ROMM_API_TOKEN_FILE=/path/to/romm-api-token
ROMM_TIMEOUT_SECONDS=15

ROMM_BASE_URL muss eine absolute http://- oder https://-URL sein. ROMM_TIMEOUT_SECONDS muss größer als 0 und höchstens 300 Sekunden betragen.

Für das vollständige v0.1-Toolset ist der vorgesehene RomM-Scope-Satz:

me.read
platforms.read
roms.read
roms.write
roms.user.read
roms.user.write
collections.read
collections.write
users.read

Die Scopes users.write, Aufgabenausführung, Plattform-Schreiben, Geräte-Schreiben und Asset-Schreiben sind für v0.1 nicht erforderlich.

MCP-Client-Beispiel

{
  "command": "uvx",
  "args": [
    "--python",
    "3.12",
    "--from",
    "https://github.com/X1pheR/romm-mcp/releases/download/v0.1.0/romm_mcp-0.1.0-py3-none-any.whl",
    "romm-mcp"
  ],
  "env": {
    "ROMM_BASE_URL": "https://romm.example.com",
    "ROMM_API_TOKEN_FILE": "/path/to/romm-api-token",
    "ROMM_TIMEOUT_SECONDS": "15"
  }
}

Sicherheitsmodell

Das RomM-Client-API-Token und seine vorgelagerten Scopes bilden die harte Autorisierungsgrenze. Verwenden Sie ein dediziertes Token und gewähren Sie nur die Scopes, die für die Tools erforderlich sind, die Sie bereitstellen möchten.

Die MCP-Schicht fügt eine zweite Grenze hinzu:

• Anmeldedaten werden dateibasiert gespeichert und sind in den Tool-Schemas nicht enthalten.

• Es gibt kein generisches Anfrage-Tool.

• Remote-URLs für Cover/Handbücher werden nicht akzeptiert, wodurch serverseitiges Abrufen/Schreiben von Assets über dieses MCP vermieden wird.

• Das Löschen von Notizen, regulären Sammlungen und smarten Sammlungen erfordert explizit confirm=true.

• ROM-/Dateilöschung, Uploads, Aufgabenausführung und Autorisierungsverwaltung fehlen in der Tool-Registrierung.

Siehe SECURITY.md für Hinweise zur Meldung von Schwachstellen und zum Umgang mit Anmeldedaten.

Entwicklung

uv.lock ist die kanonische exakte Abhängigkeitsauflösung, die von CI und Release-Verifizierung verwendet wird, während das veröffentlichte Paket kompatible Abhängigkeitsbereiche in pyproject.toml beibehält.

bash ./scripts/verify.sh

Das Verifizierungsskript erstellt eine isolierte Python-3.12-Umgebung, synchronisiert die eingefrorene uv.lock-Auflösung, kompiliert das Paket, führt die Testsuite aus und baut das Release-Wheel.

Upstream und Lizenz

Dieses Repository ist eine unabhängige Community-Integration für RomM. RomM ist ein separates Upstream-Projekt, das unter seiner eigenen Lizenz und seinen eigenen Projektrichtlinien steht.

romm-mcp ist unter der MIT-Lizenz lizenziert.