Entwicklerdokumentation

Was die Werkzeuge tun

Was ein Assistent mit dem BookDinePlay-MCP-Server kann und nicht kann: Gast-Buchung, Betreiber-Werkzeuge, Bestätigungen und geführte Einrichtung einer Location.

Ein Werkzeug ist eine Aktion, die der Assistent ausführen darf. Jedes trägt vier Hinweise, die Clients Ihnen vor dem Lauf zeigen: ob es nur liest, ob es Daten zerstören kann, ob eine Wiederholung harmlos ist und ob es über BookDinePlay hinausreicht (es verschickt eine E-Mail oder spricht mit Stripe). Ihr Client fragt Sie unter Umständen, ob ein Aufruf, der nicht nur liest, erlaubt ist.

Gast-Werkzeuge

Jede angemeldete Person kann sie nutzen, mit oder ohne eigene Location. Sie lesen dieselben öffentlichen Daten, die auch die Website einer Location zeigt, und eines davon bucht.

Werkzeug Was es tut
guest_venues_search Findet Locations, die in der BookDinePlay-App gelistet sein wollen, nach Name oder Stadt, und liefert den Slug jeder Location
guest_venue_get Zeigt Beschreibung, Adresse, Kontaktdaten, was buchbar ist, wie lange Buchungen dauern und die Öffnungszeiten samt Feiertagen
guest_menus_get Listet die veröffentlichten Menüs mit Speisen, Getränken, Preisen und Kennzeichnungen
guest_resources_get Listet Tische, Billardtische, Dartscheiben, Bahnen und Eventflächen mit Kapazität und Preis
guest_availability Listet die freien Startzeiten für eine Gruppe an einem Datum, mit den jeweils freien Tischen; bei einer Location mit Öffnung über Mitternacht werden Zeiten nach Mitternacht gekennzeichnet (startsNextDay) und mit include_previous_night der noch buchbare Rest der Vornacht ergänzt (businessDate)
guest_specials Listet die Specials eines Tages oder von bis zu 14 Tagen
guest_events Listet die veröffentlichten Events
guest_voucher_offers Zeigt, welche Geschenkgutscheine die Location online verkauft
guest_create_booking Bucht einen Tisch oder ein Spiel und verschickt die Bestätigungs-E-Mail

Buchen

guest_create_booking legt eine echte Reservierung an, deshalb sollte der Assistent es erst aufrufen, nachdem der Gast Location, Datum, Uhrzeit, Personenzahl und Kontaktdaten bestätigt hat. Der Name des Gastes ist ein Argument; die E-Mail-Adresse ebenfalls, sie wird aus der Anmeldung übernommen, wenn das Konto eine hat und der Gast keine andere nennt.

Fragt die Location, wie viele Personen einer Gruppe Kinder sind, nimmt guest_create_booking eine optionale Zahl children entgegen. Die Personenzahl bleibt die Gesamtzahl der Personen, Erwachsene plus Kinder, und mindestens ein Erwachsener muss bleiben. Der Assistent sendet sie nur, wenn der Gast es gesagt hat; eine Location, die die Frage ausgeschaltet hat, lehnt eine Buchung mit Kindern ab.

Die Antwort enthält die Buchungsreferenz, den Status, den Zeitraum und die Preisschätzung. Sie enthält nicht den Link zum Verwalten oder Stornieren der Buchung: Der steht in der Bestätigungs-E-Mail, und der Assistent sollte dem Gast sagen, dass er diese E-Mail zum Ändern oder Stornieren nutzt. Verlangt die Location eine Anzahlung, bleibt die Buchung Pending, bis sie bezahlt ist, und der Assistent kann diese Zahlung nicht entgegennehmen: Sie wird auf der Buchungsseite der Location bezahlt.

Ein Gast kann höchstens 10 Buchungen pro Stunde machen. Um eine Buchung nach einem Fehler oder einer Zeitüberschreitung zu wiederholen, ohne eine zweite zu riskieren, gibt der Assistent dieselbe request_id erneut mit; die API liefert dann die ursprüngliche Buchung zurück. Eine request_id gehört der Person, die sie benutzt hat, sodass sich zwei Personen mit demselben Wert nie begegnen.

Was Gäste über einen Assistenten nicht tun können

  • Eine bestehende Buchung nachschlagen, ändern oder stornieren. Dafür dient der Link in der Bestätigungs-E-Mail.
  • Eine Anzahlung zahlen, sich für ein Event anmelden, Tickets oder einen Gutschein kaufen.
  • Etwas lesen, das nicht öffentlich ist: Buchungen anderer Gäste, die Gästeliste oder die Umsätze einer Location.

Betreiber-Werkzeuge

Die Werkzeuge eines Betreibers decken die Konsole Bereich für Bereich ab. Jedes ruft dieselbe API auf wie die Konsole, was die Konsole ablehnt, lehnt das Werkzeug also mit derselben Meldung ab.

Bereich Werkzeuge
Konto und Bedingungen server_info, whoami, legal_status, legal_accept, setup_progress, media_upload
Registrierung (ohne Location) onboarding_status, onboarding_check_slug, onboarding_legal_documents, onboarding_sign_up
Locations venues_list, venues_create, venue_create, venue_get, venue_update
Buchungen reservations_today_overview, reservations_list, reservations_get, availability_check, reservations_create, reservations_update, reservations_set_status, reservations_refund_deposit, reservations_assign_table, reservation_requests_list, reservation_requests_approve, reservation_requests_decline
Öffnungszeiten hours_get, hours_replace, hours_add_closure, hours_set_special_day
Einstellungen der Location booking_durations_get, booking_durations_update, cancellation_policy_get, cancellation_policy_update, app_listing_get, app_listing_set, extras_get, extras_replace, booking_rules_get, booking_rules_update, children_settings_get, children_settings_set, allocation_settings_get, allocation_settings_update, child_rules_get, child_rules_update, high_chairs_get, high_chairs_set, unassigned_bookings_get, unassigned_bookings_set, request_settings_get, request_settings_set
Ressourcen resources_list, resources_create, resources_update, resources_delete, resources_assign_group, resource_groups_list, resource_groups_create, resource_groups_update, resource_groups_delete, floor_plan_get, floor_plan_save, zones_create, zones_update, zones_delete, table_merges_list, table_merges_create, table_merges_update, table_merges_delete, resource_blocks_list, resource_blocks_create, resource_blocks_update, resource_blocks_delete
Menüs und Specials menus_get, menus_replace, menus_upsert_item, menus_remove_item, specials_list, specials_get, specials_days, specials_create, specials_update, specials_delete, specials_preview, specials_settings_get, specials_settings_update
Website-Highlights highlights_list, highlights_get, highlights_create, highlights_update, highlights_delete
Events events_list, events_get, events_create, events_update, events_publish, events_cancel, events_delete, events_preview, event_registrations_list, event_registrations_cancel, event_registrations_refund, event_checkin, event_undo_checkin
Gutscheine voucher_settings_get, voucher_settings_update, vouchers_list, vouchers_get, vouchers_issue, vouchers_resend, vouchers_void, vouchers_change_expiry, vouchers_refund_sale, voucher_lookup, voucher_redeem, voucher_reverse_redemption
Bestellungen, QR-Codes, Nachrichten orders_list, qr_codes_list, qr_codes_generate, qr_codes_regenerate, qr_codes_delete, messages_list, messages_reply
Stationen und Push-Benachrichtigungen stations_list, stations_create, stations_update, stations_delete, station_routes_set, notification_preferences_get, notification_preferences_set
Team und API-Schlüssel employees_list, employees_create, employees_set_active, employees_assign_resource, employees_unassign_resource, api_keys_list, api_keys_create, api_keys_revoke
Mitarbeiter-Zugänge und Schichten staff_list, staff_invite, staff_set_role, staff_link_employee, staff_remove, shifts_list, shifts_create, shifts_update, shifts_delete, staff_access_policy_get, staff_access_policy_set, staff_access_grants_list, staff_access_open, staff_access_revoke
No-Show-Schutz guest_blocks_list, guest_blocks_block, guest_blocks_unblock, guest_blocks_update_settings
Auszahlungen und Abrechnung payouts_status, payouts_refresh, payouts_onboarding_link, billing_summary, billing_checkout_link, billing_portal_link, billing_update_company

Werkzeuge, die eine ganze Liste ersetzen, zum Beispiel die Menüs oder die Wochen-Öffnungszeiten, sagen das in ihrer Beschreibung, und der Assistent liest vorher den aktuellen Stand, damit nichts verloren geht, was Sie nicht erwähnt haben. Für eine kleine Änderung ist ein Werkzeug vorzuziehen, das eine einzelne Sache ändert, etwa eine Schließung hinzuzufügen.

Konten mit mehreren Locations

Bei einem Premium-Konto mit mehr als einer Location zeigt venues_list die Locations mit dem Slug jeder einzelnen. Jedes Location-Werkzeug nimmt diesen Slug als Argument venue, und der Server schickt ihn genau wie die Konsole an die API. Ohne venue bei einem Konto mit mehreren lehnt das Werkzeug ab und nennt die Locations zur Auswahl; ein Konto mit einer Location braucht das Argument nie. Ob Sie eine Location nutzen dürfen, entscheidet die API: Ein auf eine Location beschränkter Betreiber bekommt für eine andere dieselbe Meldung wie in der Konsole. venues_create legt eine weitere Location im Rahmen des Tariflimits an (Premium, bis zu 25) und ist Betreibern des ganzen Kontos vorbehalten; venue_create legt die erste an.

Plattform-Admins

Ein Plattform-Admin bekommt außerdem Werkzeuge, um Mandanten aufzulisten, anzulegen und zu ändern (admin_tenants_list, admin_tenants_get, admin_tenants_create, admin_tenants_update), die Betreiber eines Mandanten aufzulisten, hinzuzufügen und zu korrigieren (admin_tenant_operators_list, admin_tenant_operators_create, admin_tenant_operators_update), einen Betreiber per E-Mail einzuladen (admin_tenants_operators_invite), die Abrechnung neu abzugleichen (admin_billing_resync), die Demo-Location zurückzusetzen (admin_demo_venue_reset) sowie Buchungen mandantenübergreifend aufzulisten und ihren Status zu setzen (admin_reservations_list, admin_reservations_set_status). Jedes Location-Werkzeug nimmt außerdem act_as_tenant für einen Admin, der innerhalb eines Mandanten arbeitet. Sie erscheinen nur für einen Admin, und ein Aufruf durch jemand anderen wird von der API selbst abgelehnt.

admin_tenants_operators_invite legt den Zugang der Person an, verknüpft ihn mit einem Betreiber des Mandanten und schickt ihr eine E-Mail mit einem Link, um das Passwort zu setzen. Ein erneuter Aufruf für dieselbe Adresse verschickt die Einladung noch einmal; er legt nie einen zweiten Betreiber an. Gehört die Adresse schon einem Betreiber oder meldet sie sich schon mit Google, Apple oder Microsoft an, wird nichts gesendet, und das Werkzeug sagt, was stattdessen zu tun ist (admin_tenant_operators_create mit dem Auth0-Subject der Person). Bei der ersten Anmeldung muss die Person die Nutzungsbedingungen und den Auftragsverarbeitungsvertrag akzeptieren, bevor sonst etwas funktioniert.

Änderungen bestätigen

Werkzeuge, die sich schwer rückgängig machen lassen, etwa eine Buchung stornieren, eine Anzahlung erstatten, eine Ressource löschen, einen Gutschein entwerten oder einen QR-Code neu erzeugen, arbeiten in zwei Schritten. Der erste Aufruf ändert nichts: Er antwortet mit einer Vorschau, was genau passieren würde, und einer Bestätigung. Der Assistent zeigt Ihnen die Vorschau. Nur wenn Sie zustimmen, ruft er das Werkzeug ein zweites Mal mit der Bestätigung auf, und erst dann geschieht die Änderung.

Die Bestätigung gilt fünf Minuten, für Sie, für dieses Werkzeug und für genau diese Argumente. Ändert der Assistent etwas am Aufruf, etwa die Buchung oder den Betrag, passt die Bestätigung nicht mehr und er beginnt mit einer neuen Vorschau von vorn.

Was Betreiber-Werkzeuge nie zurückgeben

Ein geheimer API-Schlüssel wird nie im Chat gezeigt: Er wird einmal auf einer eigenen Seite außerhalb der Unterhaltung angezeigt. Gutscheincodes, Ticketcodes, QR-Token-Werte und der Stornolink eines Gastes sind ebenfalls nie Teil einer Antwort.

Eine neue Location einrichten

Wer noch keine Location hat, kann beim Assistenten beginnen. Die Werkzeuge prüfen, wo Sie stehen, ob die gewünschte Webadresse frei ist, zeigen die AGB und den Auftragsverarbeitungsvertrag und melden Sie dann an.

  • Die AGB akzeptieren Sie selbst. Der Assistent akzeptiert nie in Ihrem Namen. Ihr Client zeigt ein Formular, und die Zustimmung wird nur aus Ihrer Antwort auf dieses Formular festgehalten. Ein Client, der ein solches Formular nicht zeigen kann, verweist Sie stattdessen auf die Web-Anmeldung unter app.bookdineplay.com.
  • Sie zahlen auf der Seite von Stripe. Braucht ein Tarif eine Zahlung, gibt der Assistent Ihnen einen Link, den Sie selbst öffnen. Einrichtungsschritte, die einen aktiven Tarif brauchen, werden abgelehnt, bis die Zahlung eingegangen ist.
  • Danach führt er durch die Einrichtung, Schritt für Schritt: Profil und Adresse, Öffnungszeiten, Tische und Spiel-Ressourcen, Menü, Buchungsregeln und Veröffentlichen. Der Prompt set_up_my_venue startet das, und der Assistent kann zeigen, was schon erledigt ist und was noch fehlt.

Prompts

Ein Prompt ist eine vorgefertigte Anfrage, die Ihr Client in einem Menü anbieten kann. Er ändert von sich aus nichts; die Werkzeuge, die er nennt, funktionieren weiter wie oben beschrieben.

Prompt Was er den Assistenten tun lässt
daily_briefing Heute in Ihrer Location zusammenfassen: Buchungen, offene Anzahlungen und Ankünfte in den nächsten Stunden, nur lesend
set_holiday_hours „Am 24. Dezember geschlossen“ in genaue Daten übersetzen, die betroffenen Buchungen zeigen und es nach Ihrer Bestätigung umsetzen
set_up_my_venue Die geführte Einrichtung von oben durchlaufen, ein bestätigter Schritt nach dem anderen
admin_onboard_venue Plattform-Admins: einen Mandanten für einen neuen Kunden anlegen, dessen ersten Betreiber per E-Mail einladen und die erste Anmeldung erklären

Grenzen

Jede Person darf 120 Werkzeugaufrufe pro Minute machen, davon 30, die Daten ändern, und 10 Gast-Buchungen pro Stunde. Ein Aufruf über dem Limit liefert einen Fehler, der sagt, wie lange zu warten ist.