stdio-based mcp server initialization with caldav authentication
Initializes a Model Context Protocol server that communicates with AI assistants via StdioServerTransport over stdin/stdout, authenticating to CalDAV servers using environment variable credentials. The server registers tool handlers using @modelcontextprotocol/sdk and validates all incoming requests through Zod schemas before delegating to the underlying CalDAVClient, ensuring type-safe message serialization/deserialization across the MCP protocol boundary.
Unique: Uses @modelcontextprotocol/sdk's StdioServerTransport for direct stdin/stdout communication with AI assistants, avoiding HTTP overhead and enabling tight integration with Claude's native MCP support. Validates all tool inputs with Zod schemas before CalDAV delegation, providing type safety at the protocol boundary.
vs alternatives: Simpler deployment than REST-based calendar APIs because it eliminates HTTP server setup and uses MCP's standardized protocol, enabling direct integration with Claude without custom client code.
calendar enumeration with metadata extraction
Exposes a list-calendars tool that queries the CalDAV server via ts-caldav's getCalendars() method, returning structured metadata for each calendar including display name, color, and calendar-specific properties. The tool validates no input parameters and returns a JSON array of calendar objects, enabling AI assistants to discover available calendars before performing event operations.
Unique: Directly wraps ts-caldav's getCalendars() method without caching or filtering, providing real-time calendar discovery. Zod schema validation ensures consistent output structure across CalDAV server implementations.
vs alternatives: More reliable than parsing calendar URLs manually because it uses the CalDAV protocol's standard PROPFIND discovery mechanism, handling server-specific variations automatically.
event querying with date range filtering
Implements a list-events tool that queries the CalDAV server for events within a specified date range using ts-caldav's getEvents() method. Accepts startDate and endDate parameters (ISO 8601 format), validates them with Zod schemas, and returns a structured JSON array of event objects including title, start/end times, description, and recurrence rules. Enables AI assistants to check calendar availability and retrieve event details for scheduling decisions.
Unique: Uses ts-caldav's getEvents() with CalDAV REPORT requests for server-side date filtering, reducing payload size compared to fetching all events and filtering client-side. Zod validates ISO 8601 date strings before passing to CalDAV client.
vs alternatives: More efficient than REST APIs that require fetching all events because CalDAV's REPORT method performs server-side filtering, reducing bandwidth and latency for large calendars.
event creation with recurrence and validation
Exposes a create-event tool that constructs new calendar events with title, start/end times, description, and optional recurrence rules (RRULE format). Validates all inputs using Zod schemas (date format, string length, RRULE syntax), then delegates to ts-caldav's createEvent() method which generates iCalendar (ICS) format and POSTs to the CalDAV server. Returns the created event's unique identifier (UID) and confirmation details, enabling AI assistants to schedule events with full iCalendar feature support.
Unique: Leverages ts-caldav's iCalendar (ICS) generation to support full RFC 5545 features including RRULE recurrence, avoiding custom event serialization. Zod schemas validate RRULE syntax and date ordering before CalDAV delegation, catching invalid inputs early.
vs alternatives: More feature-rich than simple REST event creation because it supports iCalendar's native recurrence rules (RRULE), enabling complex scheduling patterns without custom logic.
event deletion with uid-based targeting
Implements a delete-event tool that removes calendar events by their unique identifier (UID). Accepts a single UID parameter, validates it with Zod schemas, and delegates to ts-caldav's deleteEvent() method which sends a DELETE request to the CalDAV server. Returns confirmation of deletion, enabling AI assistants to cancel or remove events from calendars with precise targeting.
Unique: Uses CalDAV's DELETE method with UID targeting, providing atomic event removal without requiring event re-fetching. Zod validates UID format before delegation, preventing malformed requests.
vs alternatives: More reliable than REST APIs that require event re-fetching before deletion because CalDAV's UID-based DELETE is idempotent and doesn't require state synchronization.
zod-based input validation at mcp protocol boundary
Implements runtime validation of all tool inputs using Zod schemas before delegating to CalDAVClient methods. Each tool (list-calendars, list-events, create-event, delete-event) has a corresponding Zod schema that validates parameter types, string lengths, date formats (ISO 8601), and RRULE syntax. Validation errors are caught and returned as structured MCP error responses, preventing invalid requests from reaching the CalDAV server and providing clear error messages to AI assistants.
Unique: Centralizes input validation at the MCP protocol boundary using Zod schemas, catching errors before CalDAV delegation. Provides structured validation errors that MCP clients can parse and present to users.
vs alternatives: More maintainable than ad-hoc validation because Zod schemas are declarative and reusable, reducing validation code duplication across tools.
caldav protocol abstraction via ts-caldav client
Abstracts CalDAV protocol complexity by delegating all calendar operations to the ts-caldav library, which handles HTTP/CalDAV request construction, XML parsing, and iCalendar serialization. The MCP server registers tool handlers that call ts-caldav methods (getCalendars, getEvents, createEvent, deleteEvent), which internally manage PROPFIND/REPORT/PUT/DELETE requests, authentication headers, and response parsing. This abstraction eliminates the need for the MCP server to understand CalDAV protocol details.
Unique: Delegates all CalDAV protocol handling to ts-caldav, eliminating custom HTTP/XML code. The MCP server focuses purely on tool registration and input validation, keeping concerns separated.
vs alternatives: Simpler than implementing CalDAV protocol directly because ts-caldav handles PROPFIND/REPORT/PUT/DELETE request construction, XML parsing, and iCalendar serialization automatically.
environment variable-based credential management
Loads CalDAV server credentials (URL, username, password) from environment variables at server startup, avoiding hardcoded secrets in source code. The server reads CALDAV_URL, CALDAV_USERNAME, and CALDAV_PASSWORD from the process environment and passes them to the ts-caldav client initialization. This pattern enables secure deployment in containerized environments (Docker, Kubernetes) where secrets are injected at runtime.
Unique: Uses environment variables for credential injection, enabling secure deployment patterns in containerized environments without code changes. Credentials are loaded at startup and passed to ts-caldav client.
vs alternatives: More secure than hardcoded credentials and simpler than OAuth2 flows, making it ideal for internal automation and containerized deployments.
+2 more capabilities