# Für Entwickler: Tool-Referenz

Der Kalender-Sync-MCP-Server (`https://app.kalender-sync.de/mcp`, Streamable HTTP) stellt bis zu **sieben Tools** bereit. Die Tool-Beschreibungen sind Englisch — sie sind primär für das Sprachmodell geschrieben; dein Assistent antwortet dir trotzdem in deiner Sprache.

Zwei Eigenschaften gelten für alle Tools:

- **Sichtbarkeits-Gating:** Jedes Tool sieht nur die Kalender, die du freigegeben hast, und je Kalender nur die erlaubte [Detailstufe](https://docs.kalender-sync.de/ki-assistent/sichtbarkeit/). Nicht freigegebene Kalender existieren für den Server nicht.
- **Dynamische Tool-Liste:** Die vier Schreib-Tools erscheinen nur, wenn dein Zugriff schreiben darf ([in jedem Tarif, pro Kalender freigegeben](https://docs.kalender-sync.de/ki-assistent/schreibzugriff/)). Ein Zugriff ohne Schreibrecht sieht 4 Tools — ein Tool, das immer ablehnen würde, gibt es bei uns nicht. Änderst du die Schreibrechte später, erscheinen die Tools erst, wenn der Client die Tool-Liste [neu lädt](https://docs.kalender-sync.de/ki-assistent/schreibzugriff/#schreibzugriff-nachträglich-aktivieren).

## Lese-Tools

### `list_calendars`

Listet die freigegebenen Kalender mit ihrer jeweiligen Detailstufe. `readable: false` markiert Kalender, die gerade nicht gelesen werden können (sie fehlen dann auch in allen anderen Antworten — und werden bewusst aufgeführt statt verschwiegen). `writable: true` markiert die Kalender, in die dieser Zugriff Termine schreiben darf — das ist die Quelle für die `calendar_id` von `create_event`. `sync_health` zeigt zusätzlich den Zustand der Kalender-Sync-eigenen Synchronisation, falls der Kalender an einer teilnimmt.

*Parameter: keine.*

### `get_availability`

Liefert die Termine in einem Zeitraum, über alle freigegebenen Kalender hinweg. Jeder Kalender wird **direkt beim Anbieter** gelesen (keine Kopie); Lesevorgänge werden bis zu 60 Sekunden wiederverwendet. Enthalten ist alles außer abgesagten Terminen — auch Ganztägiges und „mit Vorbehalt". Konnte ein Kalender nicht gelesen werden, steht das in `sources` und `warnings` — eine Antwort behauptet nie Vollständigkeit, die sie nicht hat.

Je Eintrag sagt `blocks_time`, ob er die Zeit tatsächlich belegt. `false` steht bei Einträgen, die dich nicht unverfügbar machen: Feiertage, Geburtstage und **alle ganztägigen Termine aus Apple/iCloud**, die dieser Anbieter grundsätzlich als „frei" markiert, ohne dass sich daran etwas einstellen ließe. Ein solcher Eintrag ist trotzdem ein echter Termin — ein ganztägiges „Baustelle Darmstadt" ist ein Arbeitstag, keine freie Zeit. Für „Bin ich frei?" zählt darum nur `blocks_time: true`, für „Was habe ich an dem Tag?" zählt alles.

| Parameter | Pflicht | Beschreibung |
| --- | --- | --- |
| `from` / `to` | ja | Zeitraum, ISO 8601. Max. 92 Tage Spanne, Rückblick max. 365 Tage. |

### `search_events`

Findet Termine per Text — case-insensitive Substring über Titel, Ort und Beschreibung. Die Suche ist bewusst **ein Filter über dieselben sichtbarkeits-gefilterten Daten wie `get_availability`**, kein zweiter Lesepfad: Kalender auf Stufe „Nur Geblockt" haben keine Titel und können darum nie matchen — das sagt die Antwort als Warnung dazu. „Kein Treffer" ist also nie ein Beweis, dass es den Termin nicht gibt.

| Parameter | Pflicht | Beschreibung |
| --- | --- | --- |
| `query` | ja | Suchtext (min. 2 Zeichen) |
| `from` / `to` | nein | Zeitraum wie bei `get_availability`; Standard: −7 bis +85 Tage |

Maximal 50 Treffer (chronologisch die frühesten), `truncated` zeigt an, wenn gekappt wurde.

### `send_feedback`

Schickt Feedback des Nutzers ans Kalender-Sync-Team — etwa wenn etwas gewünscht wurde, das die Tools noch nicht können. Der Assistent ist angewiesen, das Tool **nur auf ausdrückliche Bitte** zu nutzen. `contact_ok` (Standard: aus) erlaubt genau **eine** themenbezogene Rückmeldung von uns — kein Newsletter, kein Verteiler. Details zur Verarbeitung in der [Datenschutzerklärung, Ziffer 3.10](https://kalender-sync.de/datenschutz/).

| Parameter | Pflicht | Beschreibung |
| --- | --- | --- |
| `message` | ja | Das Feedback (10–2000 Zeichen) |
| `category` | ja | `missing_capability` · `bug` · `other` |
| `contact_ok` | nein | Nur wenn der Nutzer einer einmaligen Antwort ausdrücklich zugestimmt hat |

## Schreib-Tools (alle Tarife, pro Kalender freigegeben)

Zwei getrennte Freigaben pro Kalender: **Termine anlegen** und, darunter, **bestehende Termine ändern und löschen**. Ohne die zweite kann der Assistent nur anfassen, was er selbst angelegt hat — deine bestehenden Termine sind dann technisch nicht adressierbar. Mehr dazu unter [Schreibzugriff](https://docs.kalender-sync.de/ki-assistent/schreibzugriff/).

### `create_event`

Legt einen Termin in einem beschreibbaren Kalender an. Die Verfügbarkeit wird **im Moment des Schreibens live geprüft** (nicht aus dem Cache): Eine Überschneidung verhindert das Anlegen nicht, kommt aber als Warnung zurück — ob doppelt gebucht werden soll, entscheidet der Nutzer. Gezählt wird dabei nur, was die Zeit wirklich belegt (`blocks_time: true`). Feiertage, Geburtstage und ganztägige Termine aus Apple/iCloud lösen bewusst keine Warnung aus, sonst wäre jede Buchung an einem Feiertag ein vermeintlicher Konflikt. Keine Warnung heißt also nicht, dass der Tag leer ist. `start`/`end` verlangen ISO 8601 **mit Zeitzone**; `calendar_id` ist nur bei mehreren beschreibbaren Kalendern nötig — welche das sind, zeigt `list_calendars` über `writable: true`. Fehlt die Angabe bei mehreren, nennt die Fehlermeldung die zulässigen Kalender.

### `update_event` · `delete_event`

Ändern bzw. löschen einen Termin. Adressierbar sind zwei Arten:

1. **Termine, die dieser Zugriff selbst angelegt hat** (per `event_id` aus `create_event`) — immer.
2. **Bestehende Termine** in einem Kalender, für den du „ändern und löschen" freigegeben hast — per `event_id` aus `get_availability` oder `search_events`.

Für den zweiten Fall gelten vier Bedingungen, und jede Absage nennt den Weg: der Kalender ist freigegeben, mit **Alle Details** geteilt, der Termin ist **keine synchronisierte Kopie** (sonst überschreibt der nächste Sync die Änderung — die Absage nennt den Quellkalender), und **du bist Organisator**. Eine fremde Einladung lässt sich nicht umschreiben; dafür gibt es `respond_to_event`.

Nicht adressierbare Termine antworten `not_found`, nicht `forbidden` — um nicht einmal die Existenz zu bestätigen. Löschungen werden beim Anbieter ausgeführt und propagieren über den normalen Sync in gespiegelte Kalender. Beide Tools tragen die MCP-Annotation `destructiveHint: true`.

### `respond_to_event`

Beantwortet eine **fremde Einladung**: zusagen, absagen oder vorläufig zusagen. Der Organisator wird benachrichtigt — das ist der Zweck: eine Einladung nur zu löschen entfernt sie lokal und lässt ihn weiter mit dir rechnen.

Die Berechtigung ist dieselbe wie fürs Ändern, die Bedingung aber die **umgekehrte**: Ändern setzt voraus, dass du Organisator bist, Beantworten setzt voraus, dass du es nicht bist. Bei einem **wiederkehrenden** Termin ist `scope` nötig — `occurrence` beantwortet nur dieses Datum, `series` alle. Ohne Angabe fragt der Assistent nach, statt zu raten: Eine Absage an den Organisator lässt sich nicht zurücknehmen.

Verfügbar für **Google und Microsoft**. Andere Anbieter melden Antworten nicht an den Organisator weiter; dort verweist das Tool auf die Kalender-App, statt eine Antwort zu schicken, die niemand bekommt.

## Protokollierung

Jeder Tool-Aufruf landet als **Metadaten** im [Zugriffsprotokoll](https://docs.kalender-sync.de/ki-assistent/) — Zeitpunkt, Tool, betroffene Kalender, Ergebnis. Nie der Inhalt deiner Termine, nie der Suchtext, nie der Feedback-Wortlaut.

---

*Stand: Server-Version 1.3.0 (10.09.2026). Der Server ist im [offiziellen MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=de.kalender-sync) als `de.kalender-sync/kalender-sync` gelistet. Er stellt die Tool-Liste bei jeder Verbindung neu zusammen, Clients cachen sie aber — nach einer Rechte-Änderung musst du sie im Client [neu laden](https://docs.kalender-sync.de/ki-assistent/schreibzugriff/#schreibzugriff-nachträglich-aktivieren).*