PrimeCal MCP-Tools und -Ressourcen

Diese Seite dokumentiert die kanonische, vom Server bereitgestellte PrimeCal-MCP-Oberfläche.

Tool-Familien

Organisationen, Ressourcen und Reservierungen

primecal_organisations_list
primecal_organisations_active_set
primecal_organisations_billing_status_get
primecal_organisations_billing_settings_update
primecal_organisations_stripe_onboardingLink_create
primecal_organisations_payments_debug_get
primecal_resourceTypes_list
primecal_resources_list
primecal_reservations_availability_list
primecal_reservations_list
primecal_reservations_get
primecal_reservations_create

Gemeinsame Eingabefelder:

organisationId nur zum Wechseln der aktiven Organisation
resourceTypeId
optional resourceId
date für die tagesgenaue Verfügbarkeit
startTime / endTime für die Erstellung von Reservierungen
optional status, startFrom und endTo für das Auflisten von Reservierungen

Wichtiges Verhalten:

Reservierungs- und Ressourcen-Tools lösen die aktive Organisation aus dem Agentenkontext auf, nicht aus beliebigen Client-Nutzlasten
Abrechnungs- und Payment-Debug-Tools verwenden ebenfalls die aktive Organisation, erfordern jedoch einen expliziten Organisationsbereich und einen Organisationsadministrator-Besitzkontext
Die Verfügbarkeit nutzt dieselbe Blockierungslogik wie die öffentliche Buchung
MCP legt keine Stripe-Schlüssel, Checkout-Sitzungen, Zahlungsabsichten oder Webhook-Verarbeitung offen
Das Erstellen von Reservierungen ist auf zahlungsfreie Abläufe beschränkt, es sei denn, der Besitzkontext agiert in einer administrativen Organisationsrolle

Abrechnungsspezifische Eingabefelder:

defaultCurrency für abrechnungssichere Aktualisierungen
optional reservationId / bookingId
optional paymentStatus
optional limit

Kalender und Ereignisse

primecal_calendars_list
primecal_calendars_get
primecal_calendars_events_list
primecal_calendars_events_search_v2
primecal_calendars_events_get_v2
primecal_calendars_events_create
primecal_calendars_events_update
primecal_calendars_events_delete
primecal_calendar_userGroups_list
primecal_calendar_userGroups_details
primecal_calendar_userGroups_createInvite
primecal_calendar_userGroups_acceptInvite
primecal_calendar_userGroups_attachCalendars
primecal_calendar_userGroups_detachCalendars

Gemeinsame Eingabefelder:

optional calendarId (Zahl)
optional calendarIds (Zahlen-Array)
from / to (ISO-8601-UTC-Zeitstempel)
optional fields, limit, cursor, expandRecurrences, includeFullDescription und userTimezone
eventId oder id für Aktualisierungen/Löschungen
event-Objekt für Erstellungs-/Aktualisierungsnutzlasten

Empfohlene Referenzen:

Eingabefelder für Personengruppen-Tools:

groupId (Zahl)
groupIds (Zahlen-Array) zur optionalen Filterung beim Auflisten
calendarIds (Zahlen-Array) für Anhänge-/Trenn-Operationen
permission (read, write oder admin) für Anhänge-Operationen
email und optional message für die Erstellung von Einladungen
token für die Annahme von Einladungen

Personengruppen-Tools werden durch calendar.userGroups.*-Aktionsschlüssel gesteuert. Anhängen- und Trennen-Tools erfordern sowohl Gruppen- als auch Kalenderbereich.

Aufgaben und Erinnerungen

primecal_tasks_list
primecal_tasks_create
primecal_tasks_update
primecal_tasks_delete
primecal_tasks_labels_list
primecal_tasks_labels_create
primecal_tasks_labels_update
primecal_tasks_labels_delete
primecal_tasks_focus_list
primecal_tasks_auto_schedule
primecal_tasks_accept_assignment
primecal_tasks_bounce_assignment
primecal_tasks_dependencies_add
primecal_tasks_dependencies_remove
primecal_tasks_checklist_list
primecal_tasks_checklist_add
primecal_tasks_checklist_update
primecal_tasks_checklist_remove
primecal_reminders_create
primecal_reminders_update

Erinnerungs-Tools basieren auf Aufgaben und bilden Erinnerungsfelder (remindAt, note) auf Aufgabenfelder (dueDate, body) ab.

primecal_tasks_create/primecal_tasks_update akzeptieren außerdem durationMinutes (1–1440, für die automatische Terminplanung verwendet), context (deep_work, errand, admin, kid_safe, low_energy), autoScheduled sowie preferredWindowStartHour/preferredWindowEndHour (0–23) – z. B. bildet „30 Minuten konzentrierte Arbeit für den Bericht blocken“ auf primecal_tasks_create mit durationMinutes: 30, context: 'deep_work' ab.

primecal_tasks_focus_list akzeptiert ein optionales date (YYYY-MM-DD, Standard heute UTC) und liefert dieselbe nach Zeitplan geordnete, abhängigkeitsgefilterte Liste wie GET /api/tasks/focus.

primecal_tasks_auto_schedule, primecal_tasks_accept_assignment und primecal_tasks_bounce_assignment akzeptieren jeweils taskId oder id; bounce akzeptiert zusätzlich ein optionales reason (max. 500 Zeichen). primecal_tasks_dependencies_add/_remove nehmen taskId und dependsOnTaskId entgegen.

primecal_tasks_checklist_list/_add/_update/_remove nehmen alle taskId entgegen, zusätzlich title (add), oder itemId/id mit optional title/isDone/order (update), oder itemId/id (remove) – z. B. bildet „füge 'Location buchen' zur Checkliste meiner Party-Planungs-Aufgabe hinzu“ auf primecal_tasks_checklist_add ab. Alle vier geben die vollständige aktualisierte Checkliste der Aufgabe zurück.

Routinen und Haushalt

primecal_routine_templates_list
primecal_routine_templates_clone
primecal_routine_templates_instantiate
primecal_routine_templates_streak
primecal_routine_templates_skip
primecal_household_items_list
primecal_household_items_create
primecal_household_items_mark_used_up
primecal_household_items_consume

primecal_routine_templates_clone akzeptiert templateId/id und optional groupId, um eine System-Vorlage in eine Personengruppe statt in die persönlichen Vorlagen des Aufrufers zu klonen. primecal_routine_templates_instantiate akzeptiert templateId/id und startet die Vorlage sofort – z. B. „starte meine Abendroutine“ – genau wie die Schaltfläche Start now, unabhängig vom Wiederholungsplan der Vorlage.

primecal_routine_templates_streak akzeptiert templateId/id und liefert { currentStreak, longestStreak, lastCompletedDate, totalInstantiations }. primecal_routine_templates_skip akzeptiert templateId/id und überspringt den heutigen Durchlauf, ohne Aufgaben zu erstellen – z. B. „überspringe das Putzen diese Woche, wir sind auf Reisen“ – ohne den Rotationsverlauf zu beeinträchtigen.

primecal_household_items_create akzeptiert name, category, quantity, groupId, expiryDate (YYYY-MM-DD), shelfLifeDays (1–3650) und lowStockThreshold (>= 0, ein unabhängiger mengenbasierter Nachschub-Auslöser). primecal_household_items_mark_used_up akzeptiert eine Artikel-ID und markiert sie so, dass der stündliche Nachschub-Scan dafür eine Aufgabe anlegt. primecal_household_items_consume akzeptiert itemId/id und ein optionales amount (Standard 1), um die Menge zu verringern – z. B. „2 Rollen Papierhandtücher verbraucht“.

Den zugrunde liegenden REST-Vertrag sowie das Rotations-/Nachschubverhalten dieser Tools finden Sie in der Routinenvorlagen API und der Haushaltsartikel API.

Automatisierung

primecal_automation_rules_list
primecal_automation_rules_get
primecal_automation_rules_trigger
primecal_automation_rules_audit_list

Gemeinsame Eingabefelder:

ruleId (Zahl)
optional status, fromDate, toDate
Paginierung (page, limit)

Profil und Kontext

primecal_profile_get
primecal_context_snapshot

Eingabe für den Kontext-Snapshot:

days (1–30)
tasksLimit (1–200)
eventsLimit (1–200)
includeCompletedTasks (boolescher Wert)

Ressourcen

primecal.current-context (primecal://current-context)
primecal.automation-summary (primecal://automation-summary)
primecal.calendar.user-groups (primecal://calendar/user-groups)
primecal.calendar.user-group-detail (primecal://calendar/user-groups/{id})

Beide Ressourcen liefern in resources/read-Antworten von MCP textuellen Inhalt vom Typ application/json.

Personengruppen-Ressourcen sind schreibgeschützt und enthalten nur Gruppen und Kalender, die der Bereich des Agenten erlaubt.

Enterprise-Reservierungs-JSON-RPC-Beispiele

Die aktive Organisation wechseln

{
  "jsonrpc": "2.0",
  "id": 30,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_active_set",
    "arguments": {
      "organisationId": 12
    }
  }
}

Verfügbarkeit für einen Dienst auslesen

{
  "jsonrpc": "2.0",
  "id": 31,
  "method": "tools/call",
  "params": {
    "name": "primecal_reservations_availability_list",
    "arguments": {
      "date": "2026-05-20",
      "resourceTypeId": 8
    }
  }
}

Eine zahlungsfreie Reservierung erstellen

{
  "jsonrpc": "2.0",
  "id": 32,
  "method": "tools/call",
  "params": {
    "name": "primecal_reservations_create",
    "arguments": {
      "resourceTypeId": 8,
      "resourceIds": [41, 42],
      "startTime": "2026-05-20T10:00:00Z",
      "endTime": "2026-05-20T11:00:00Z",
      "notes": "Agent-assisted booking"
    }
  }
}

Abrechnungsstatus der aktiven Organisation auslesen

{
  "jsonrpc": "2.0",
  "id": 33,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_billing_status_get",
    "arguments": {}
  }
}

Die Standard-Abrechnungswährung aktualisieren

{
  "jsonrpc": "2.0",
  "id": 34,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_billing_settings_update",
    "arguments": {
      "defaultCurrency": "eur"
    }
  }
}

Stripe-Onboarding vorbereiten

{
  "jsonrpc": "2.0",
  "id": 35,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_stripe_onboardingLink_create",
    "arguments": {}
  }
}

Payment-Debug-Status prüfen

{
  "jsonrpc": "2.0",
  "id": 36,
  "method": "tools/call",
  "params": {
    "name": "primecal_organisations_payments_debug_get",
    "arguments": {
      "paymentStatus": "pending",
      "limit": 10
    }
  }
}

Personengruppen-JSON-RPC-Beispiele

Zugängliche Gruppen und Kalender auflisten

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "primecal_calendar_userGroups_list",
    "arguments": {
      "includeCalendars": true
    }
  }
}

Eine Gruppeneinladung erstellen

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "primecal_calendar_userGroups_createInvite",
    "arguments": {
      "groupId": 9,
      "email": "teammate@example.com",
      "message": "Join the shared planning calendars."
    }
  }
}

Das Ergebnis ist absichtlich generisch gehalten und verrät nicht, ob die E-Mail-Adresse einem bestehenden PrimeCal-Benutzer zugeordnet ist.

Einen Kalender an eine Gruppe anhängen

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "primecal_calendar_userGroups_attachCalendars",
    "arguments": {
      "groupId": 9,
      "calendarIds": [5],
      "permission": "write"
    }
  }
}

Die Gruppenübersichts-Ressource auslesen

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "resources/read",
  "params": {
    "uri": "primecal://calendar/user-groups"
  }
}

Schema- und Ergebnismodell

Alle Tools werden über MCP tools/list aufgelistet und veröffentlichen JSON-Schema-kompatible inputSchema-Objekte.

Die Ergebnisform folgt den MCP-Konventionen, mit folgenden wichtigen Unterscheidungen:

Tools, die Arrays liefern

Tools, die Sammlungen zurückgeben (listOrganisations, listResources, listReservations, primecal_calendars_events_list usw.), setzen kein structuredContent. Aufrufer müssen den JSON-String in content[0].text parsen, um das Array zu erhalten.

{
  "content": [
    {
      "type": "text",
      "text": "[{\"id\":41,\"name\":\"Pool lane A\"},{\"id\":42,\"name\":\"Pool lane B\"}]"
    }
  ]
}

Tools, die Objekte liefern

Tools, die ein einzelnes Objekt zurückgeben, setzen structuredContent direkt auf das Objekt (nicht in ein weiteres Objekt verpackt).

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":42,\"title\":\"Project review\"}"
    }
  ],
  "structuredContent": {
    "id": 42,
    "title": "Project review"
  }
}

Fehler-Umschlag

Alle Fehler setzen isError: true, enthalten eine menschenlesbare Beschreibung in content[0].text und setzen structuredContent immer auf das Fehlerobjekt:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Agent does not have access to this tool or scope."
    }
  ],
  "structuredContent": {
    "error": {
      "type": "forbidden",
      "message": "Agent does not have access to this tool or scope.",
      "statusCode": 403,
      "retriable": false
    }
  }
}

Werte für type:

`type`	HTTP-Status	Bedeutung
`validation_error`	400	Fehlerhafte Eingabe oder DTO-Validierungsfehler.
`unauthorized`	401	Fehlender oder ungültiger Agent-Schlüssel.
`forbidden`	403	Gültiger Schlüssel, aber unzureichender Berechtigungsbereich.
`not_found`	404	Angeforderte Ressource existiert nicht.
`conflict`	409	Statuskonflikt (z. B. Buchungsüberschneidung).
`rate_limited`	429	Ratenlimit überschritten; nach Backoff erneut versuchen.
`http_error`	5xx	Upstream- oder serverseitiger Fehler.
`internal_error`	—	Unerwarteter interner Fehler.

retriable ist true bei vorübergehenden Fehlern (rate_limited, manche http_error-Varianten) und false bei dauerhaften Fehlern.

Migrationshinweis: Frühere Dokumentationen zeigten "type": "permission_denied" im Fehler-Umschlag. Dieser Typ existiert nicht mehr – verwenden Sie stattdessen "forbidden" (HTTP 403). Aufrufer, die auf "permission_denied" geprüft haben, müssen auf "forbidden" umstellen.

Erwartungen an die Nutzlast-Reichhaltigkeit

PrimeCal-Tools sollten reichhaltige Daten zurückgeben, damit KI-Hosts mit minimalen zusätzlichen Roundtrips argumentieren können.

Ereignisobjekte enthalten Zeitleiste, Wiederholung, Status, Farbe und Metadaten.
Personengruppenobjekte enthalten Rolle, minimale Mitgliederübersichten, einladungssichere Metadaten und vereinfachte Kalenderverweise bei entsprechendem Bereich.
Aufgabenobjekte enthalten Beschriftungen und Metadaten zur Aufgaben-Kalender-Spiegelung.
Automatisierungsantworten enthalten Regeldefinitionen, Zähler und Audit-Einträge.
Reservierungsobjekte enthalten zugewiesene Ressourcen, Ressourcentyp, Angebots-Snapshot, Kunden-Nutzlast, Status und Zahlungsstatus.

Schneller Protokolltest

initialize gegen /api/mcp
tools/list
resources/list
tools/call mit primecal_profile_get
resources/read für primecal://current-context

Erwartung der May.B.Late-Demo:

primecal_calendars_list sollte Work, Personal und Side projects enthalten.
primecal_calendar_userGroups_list sollte nur Gruppen zurückgeben, die der Personengruppen-Bereich des Agenten erlaubt.
primecal_organisations_list sollte nur Organisationen zurückgeben, die durch das Agentenprofil und den zugrunde liegenden Besitzerzugriff erlaubt sind.

Tool-Familien​

Organisationen, Ressourcen und Reservierungen​

Kalender und Ereignisse​

Aufgaben und Erinnerungen​

Routinen und Haushalt​

Automatisierung​

Profil und Kontext​

Ressourcen​

Enterprise-Reservierungs-JSON-RPC-Beispiele​

Die aktive Organisation wechseln​

Verfügbarkeit für einen Dienst auslesen​

Eine zahlungsfreie Reservierung erstellen​

Abrechnungsstatus der aktiven Organisation auslesen​

Die Standard-Abrechnungswährung aktualisieren​

Stripe-Onboarding vorbereiten​

Payment-Debug-Status prüfen​

Personengruppen-JSON-RPC-Beispiele​

Zugängliche Gruppen und Kalender auflisten​

Eine Gruppeneinladung erstellen​

Einen Kalender an eine Gruppe anhängen​

Die Gruppenübersichts-Ressource auslesen​

Schema- und Ergebnismodell​

Tools, die Arrays liefern​

Tools, die Objekte liefern​

Fehler-Umschlag​

Erwartungen an die Nutzlast-Reichhaltigkeit​

Schneller Protokolltest​

Tool-Familien

Organisationen, Ressourcen und Reservierungen

Kalender und Ereignisse

Aufgaben und Erinnerungen

Routinen und Haushalt

Automatisierung

Profil und Kontext

Ressourcen

Enterprise-Reservierungs-JSON-RPC-Beispiele

Die aktive Organisation wechseln

Verfügbarkeit für einen Dienst auslesen

Eine zahlungsfreie Reservierung erstellen

Abrechnungsstatus der aktiven Organisation auslesen

Die Standard-Abrechnungswährung aktualisieren

Stripe-Onboarding vorbereiten

Payment-Debug-Status prüfen

Personengruppen-JSON-RPC-Beispiele

Zugängliche Gruppen und Kalender auflisten

Eine Gruppeneinladung erstellen

Einen Kalender an eine Gruppe anhängen

Die Gruppenübersichts-Ressource auslesen

Schema- und Ergebnismodell

Tools, die Arrays liefern

Tools, die Objekte liefern

Fehler-Umschlag

Erwartungen an die Nutzlast-Reichhaltigkeit

Schneller Protokolltest