keeper.sh

Aggregates calendar events from heterogeneous sources (Google Calendar, Outlook, Office 365, iCloud, CalDAV, ICS) into a single normalized event schema through provider-specific adapters. Each provider implements a standardized interface that translates proprietary event formats (Google's calendar API response structure, Microsoft Graph event objects, iCalendar RFC 5545 format) into a unified internal representation, enabling downstream tools to operate on events without provider-specific branching logic.

Exposes aggregated calendar operations as MCP (Model Context Protocol) tools that Claude and other LLM clients can invoke directly. Implements the MCP tool schema specification with JSON-RPC 2.0 transport, allowing LLMs to call calendar functions (list events, create event, update event, delete event) with structured arguments and receive typed responses. The MCP server runs as a standalone process that Claude Desktop or Cline can discover and communicate with via stdio or HTTP transport.

Exposes webhook endpoints that receive real-time event change notifications from calendar providers (Google Calendar push notifications, Microsoft Graph change notifications) and processes them to update the aggregated calendar state. Implements webhook signature verification to ensure authenticity, handles webhook retries and exponential backoff for failed deliveries, and maintains a webhook delivery log. Supports filtering notifications by event type (created, updated, deleted) and calendar source.

Exports aggregated calendar events to multiple formats (ICS/iCalendar, JSON, CSV) with configurable filtering and field selection. Implements RFC 5545 compliant ICS generation with proper VEVENT component structure, timezone definitions, and recurrence rules. Supports exporting to file or HTTP response stream. Handles large exports (>100MB) with streaming to avoid memory exhaustion.

Manages OAuth2 authorization flows for Google Calendar and Microsoft Graph (Outlook/Office 365) with automatic token refresh and secure credential persistence. Implements the OAuth2 authorization code flow with PKCE (Proof Key for Code Exchange) for public clients, stores refresh tokens in encrypted local storage or environment variables, and automatically refreshes access tokens before expiration to maintain uninterrupted calendar access. Handles token revocation and re-authorization on credential invalidation.

Implements the CalDAV protocol (RFC 4791) for reading and writing calendar events to CalDAV servers (e.g., Nextcloud, Radicale, Fruux). Supports automatic server discovery via DNS SRV records and well-known URIs (.well-known/caldav), handles WebDAV PROPFIND and REPORT operations to enumerate calendars and fetch events, and implements iCalendar serialization/deserialization for event data. Supports both Basic and Digest HTTP authentication for CalDAV server access.

Parses iCalendar (ICS) files from local paths or HTTP URLs using RFC 5545 compliant parsing, extracting VEVENT components and normalizing them into the unified event schema. Supports recurring events (RRULE), timezone definitions (VTIMEZONE), and attendee lists (ATTENDEE). Implements periodic polling to detect changes in remote ICS files and sync new/updated events into the aggregated calendar. Handles ICS file encoding variations (UTF-8, ISO-8859-1) and malformed iCalendar data gracefully.

Provides create, read, update, and delete operations for calendar events across all aggregated providers through a unified API. Implements conflict detection by checking for overlapping events before creation/update, validates event properties (required fields, time ranges), and routes operations to the appropriate provider backend. Handles provider-specific constraints (e.g., Google Calendar's 5000 event limit per calendar, Microsoft's attendee limits) and returns detailed error messages for failed operations.

Expands recurring events (defined via iCalendar RRULE) into individual event instances across a specified date range, handling complex recurrence patterns (daily, weekly, monthly, yearly with exceptions via EXDATE). Applies timezone-aware scheduling to ensure recurring events respect daylight saving time transitions and user timezone preferences. Caches expanded instances to avoid recomputation on repeated queries. Supports RRULE parameters like BYDAY, BYMONTH, BYSETPOS for complex scheduling patterns.

Provides full-text search and structured filtering across aggregated calendar events using in-memory indexing or external search backends. Supports filtering by date range, calendar source, attendees, event title/description, and custom properties. Implements efficient query execution by pre-filtering events before full-text search to reduce search space. Returns ranked results with relevance scoring for text queries.

Analyzes aggregated calendar events to compute free time slots, busy periods, and availability patterns. Generates scheduling suggestions by finding common available time slots across multiple attendees' calendars. Implements working hours configuration (e.g., 9-5 Monday-Friday) to filter availability to business hours. Computes metrics like calendar utilization percentage, average meeting duration, and fragmentation (number of meetings per day).

Implements bidirectional event synchronization across multiple calendar providers with conflict resolution when the same event is modified in multiple sources. Uses event UID (unique identifier) and modification timestamps to detect conflicts, applies configurable conflict resolution strategies (last-write-wins, provider-priority, manual review). Maintains a sync log to track which events have been synced and detect orphaned events. Supports incremental sync to avoid re-processing unchanged events.