Dokumentation / MCP-Tools

MCP-Tools Referenz

Der MCP-Server ist unter /mcp erreichbar und stellt folgende Tools bereit. Öffentliche Tools sind ohne Login nutzbar; authentifizierte Tools erfordern ein Bearer-Token (OAuth PKCE).

Öffentliche Tools

Keine Authentifizierung erforderlich.

list_items

Gibt alle aktiven Geräte zurück. Nur aufrufen wenn der Nutzer explizit die komplette Geräteübersicht möchte — für gezielte Suchen besser search_items verwenden.

Keine Parameter
Gibt zurück: Array mit id, name, pricePerDay, pricePerWeek, pricePerWeekend, deposit, description, itemUrl, thumbnailUrl

search_items

Hybrid-Suche (70% semantisch via Jina + 30% lexikal). Findet Geräte nach Stichwort, Konzept oder Tag. Standard-Limit: 5 Treffer.

ParameterTypPflichtBeschreibung
querystringjaSuchbegriff oder -konzept
tagsstring[]neinNur Geräte mit allen angegebenen Tags
limitnumberneinMaximale Trefferzahl (1–20, Standard: 5)
Gibt zurück: Array mit id, name, pricePerDay, pricePerWeekend, pricePerWeek, tags, score

list_sets

Gibt alle verfügbaren Gerätesets zurück. Sets sind Bündel aus mehreren Geräten zu einem gemeinsamen Tagespreis.

Keine Parameter
Gibt zurück: Array mit id, name, description, pricePerDay, deposit

get_item

Zeigt alle Details eines bestimmten Geräts inkl. Bilderliste.

ParameterTypPflichtBeschreibung
idstringjaGeräte-ID
Gibt zurück: id, name, pricePerDay, pricePerWeek, pricePerWeekend, deposit, description, thumbnailUrl, images[], itemUrl, productUrl

check_availability

Prüft, ob ein Gerät oder Set in einem bestimmten Zeitraum verfügbar ist.

ParameterTypPflichtBeschreibung
deviceIdstringbedingtGeräte-ID (oder setId)
setIdstringbedingtSet-ID (oder deviceId)
startDatestringjaStartdatum YYYY-MM-DD
endDatestringjaEnddatum YYYY-MM-DD
Gibt zurück: { available: boolean }

Authentifizierte Tools

Diese Tools erfordern ein gültiges Bearer-Token. Ohne Token wird { error: "Nicht angemeldet" } zurückgegeben.

Buchungsverwaltung

create_booking

Erstellt eine Buchungsanfrage. Der Owner erhält eine E-Mail mit Approve/Reject-Link. Genau eines von deviceId oder setId ist erforderlich.

ParameterTypPflichtBeschreibung
deviceIdstringbedingtGeräte-ID
setIdstringbedingtSet-ID
startDatestringjaStartdatum YYYY-MM-DD
endDatestringjaEnddatum YYYY-MM-DD
firstNamestringjaVorname des Mieters
lastNamestringjaNachname des Mieters
phonestringjaTelefonnummer des Mieters
notesstringneinHinweise zur Buchung
Gibt zurück: { bookingId: string, status: "pending" }

get_my_bookings

Zeigt alle Buchungen des eingeloggten Nutzers als Mieter. Bei genehmigten Buchungen werden Abholadresse und Telefon des Owners mitgeliefert.

Keine Parameter
Gibt zurück: Array mit id, deviceId, setId, startDate, endDate, status (+ pickupAddress, ownerPhone bei approved)

cancel_booking

Storniert eine Buchung. Mieter und Owner können jeweils stornieren. Beide Parteien werden per E-Mail benachrichtigt.

ParameterTypPflichtBeschreibung
bookingIdstringjaID der Buchung
Gibt zurück: { status: "cancelled" }

approve_booking nur Owner

Bestätigt eine ausstehende Buchungsanfrage. Nur der Owner des Geräts darf genehmigen.

ParameterTypPflichtBeschreibung
bookingIdstringjaID der Buchung
Gibt zurück: { status: "approved" }

reject_booking nur Owner

Lehnt eine ausstehende Buchungsanfrage ab. Nur der Owner des Geräts darf ablehnen.

ParameterTypPflichtBeschreibung
bookingIdstringjaID der Buchung
Gibt zurück: { status: "rejected" }

get_owner_bookings nur Owner

Zeigt alle Buchungen auf den eigenen Geräten (alle Status).

Keine Parameter
Gibt zurück: Array mit id, deviceId, deviceName, startDate, endDate, firstName, lastName, phone, status

Geräteverwaltung

create_item Uploader-Berechtigung

Legt ein neues Gerät an. Erfordert den lender-Status (kann über request_lender_status beantragt werden).

ParameterTypPflichtBeschreibung
namestringjaName des Geräts
pricePerDaynumberjaTagespreis in Euro
pricePerWeeknumberneinWochenpreis in Euro
pricePerWeekendnumberneinWochenendpreis in Euro
depositnumberneinKaution in Euro
productUrlstringneinLink zum Produkt
descriptionstringneinBeschreibung
tagsstring[]neinSchlagwörter (werden klein geschrieben)
Gibt zurück: { itemId: string }

update_item nur Owner des Geräts

Aktualisiert ein eigenes Gerät. Alle Parameter außer id sind optional.

ParameterTypPflichtBeschreibung
idstringjaGeräte-ID
namestringneinNeuer Name
pricePerDaynumberneinNeuer Tagespreis
pricePerWeeknumberneinNeuer Wochenpreis
pricePerWeekendnumberneinNeuer Wochenendpreis
depositnumberneinNeue Kaution
descriptionstringneinNeue Beschreibung
activebooleanneinAktiv/Inaktiv schalten
tagsstring[]neinNeue Schlagwörter
thumbnailPathstringneinNeuer Thumbnail-Pfad
Gibt zurück: { success: true, item: ... }

list_my_items nur Owner

Zeigt alle eigenen Geräte (auch inaktive).

Keine Parameter
Gibt zurück: Array mit id, name, pricePerDay, active, thumbnailUrl u.a.

attach_image_to_item Uploader-Berechtigung

Verknüpft ein hochgeladenes Bild (via POST /images/upload) mit einem Gerät und setzt es optional als Thumbnail.

ParameterTypPflichtBeschreibung
itemIdstringjaGeräte-ID
imageIdstringjaBild-ID (vom Upload zurückgegeben)
setAsThumbnailbooleanneinAls Thumbnail setzen
Gibt zurück: { success: true, imageId, path, url?, thumbnailSet }

Profilverwaltung

get_profile

Gibt das eigene Profil zurück, inklusive Vermieter-Status. Nutze dieses Tool, um zu prüfen, ob der Nutzer Vermieter ist (lender) oder eine Vermieter-Anfrage offen hat (lenderStatus: "pending").

Keine Parameter
Gibt zurück: name, email, phone, addressStreet, addressZip, addressCity, lender (boolean), admin (boolean), lenderStatus ("approved" | "pending" | "none"), lenderRequestedAt, profileComplete, missingProfileFields

update_profile

Aktualisiert das eigene Profil. Alle Parameter sind optional.

ParameterTypPflichtBeschreibung
namestringneinAnzeigename
phonestringneinTelefonnummer
addressStreetstringneinStraße + Hausnummer
addressZipstringneinPostleitzahl
addressCitystringneinStadt
Gibt zurück: Aktualisiertes Profil-Objekt

Vermieter-Flow

request_lender_status

Beantragt die Freischaltung als Vermieter. Voraussetzung: vollständiges Profil (Telefon und Adresse). Alle Admins werden per E-Mail informiert, und entscheiden über Freischaltung unter /admin/lender-requests/:userId. Cooldown: 1 Stunde zwischen zwei Anfragen.

Keine Parameter
Gibt zurück: { ok: true, message, notifiedAdmins } oder Fehler bei unvollständigem Profil bzw. aktivem Cooldown.

Admin-Tools

admin_approve_uploader nur Admin

Gibt einen Nutzer als Vermieter frei (setzt lender = true).

ParameterTypPflichtBeschreibung
userIdOrEmailstringjaUser-ID oder E-Mail-Adresse
Gibt zurück: { ok: true, userId, email, lender: true }

admin_revoke_uploader nur Admin

Entzieht einem Nutzer die Vermieter-Berechtigung.

ParameterTypPflichtBeschreibung
userIdOrEmailstringjaUser-ID oder E-Mail-Adresse
reasonstringneinBegründung (optional)
Gibt zurück: { ok: true, userId, email, lender: false }

admin_list_users nur Admin

Listet alle Nutzer auf. Optionaler Filter: all | pending (kein Vermieter) | approved (Vermieter).

ParameterTypPflichtBeschreibung
filterstringneinall | pending | approved
Gibt zurück: Array mit id, email, name, lender, admin, approvedAt