caldav-mcp/docs/implementation-plan.md

CalDAV MCP Server - Final Implementation Plan (v2)

1) Objectives

• Provide an MCP server (Streamable HTTP) for one configured CalDAV host.
• Use pass-through authentication from MCP client to CalDAV upstream.
• Resolve principal dynamically per authenticated caller.
• Support calendar and event CRUD against SOGo-compatible CalDAV.
• Handle multiple calendars visible under a principal (including shared/read-only calendars).

2) Scope (v1)

In

• Principal discovery (current-user-principal, calendar-home-set)
• Calendar CRUD (list/create/update/delete; update/create gated by server capability)
• Event CRUD (VEVENT): list/get/create/update/delete
• Conditional requests with ETag
• Structured error mapping from HTTP/WebDAV to MCP errors
• Streamable HTTP support

Out (v1)

• Scheduling workflow (iTIP)
• Full incremental sync (sync-token) unless server capability is confirmed
• Advanced recurrence expansion server-side
• Multi-host routing

3) Principal and Auth Strategy

• Configure host: <your-caldav-base-url>
• Do not hardcode principal identity; resolve dynamically for each authenticated request.
• Per request:
  1. Forward allowlisted auth headers (Authorization; optional Cookie behind config)
  2. Resolve principal dynamically using PROPFIND current-user-principal
  3. Resolve calendar-home-set from principal
• Security:
  • Never persist credentials
  • Redact auth in logs
  • Reject upstream host override
  • TLS verification on by default

4) Transport and Runtime

• TypeScript + Node.js MCP SDK
• Streamable HTTP endpoint: POST /mcp
• Health endpoint: GET /healthz
• Request correlation ID across MCP + CalDAV calls
• Request-scoped auth context only (no cross-request leakage)

5) MCP Tools (v1)

1. caldav_discover_principal
2. caldav_list_calendars
3. caldav_create_calendar (if supported)
4. caldav_update_calendar (if supported)
5. caldav_delete_calendar
6. caldav_list_events (time-range bounded)
7. caldav_get_event
8. caldav_create_event
9. caldav_update_event
10. caldav_delete_event

Tool outputs include href, etag, and normalized identifiers.

6) Protocol Mapping

• Discovery/list: PROPFIND (Depth: 0/1)
• Event query: REPORT calendar-query with time-range
• Read object: GET
• Create/update object: PUT text/calendar
• Delete object/calendar: DELETE
• Create calendar: MKCALENDAR
• Update calendar props: PROPPATCH

Implementation rules:

• Parse 207 Multi-Status per-resource
• Normalize hrefs to absolute canonical URLs
• Use If-Match for updates/deletes where possible

7) Data and Validation Rules

• Support raw ICS input/output for fidelity
• Optional structured event input converted to ICS
• Validate:
  • UID presence (generate if absent on create)
  • DTSTART/DTEND consistency
  • Timezone references (VTIMEZONE preservation)
• Deterministic event href strategy from UID (configurable)

8) Error Model

Map to MCP errors with safe diagnostics:

• 400 invalid input
• 401 unauthenticated
• 403 forbidden
• 404 not found
• 409/412 conflict/precondition
• 422 unprocessable calendar data
• 423 locked
• 424 failed dependency
• 507 insufficient storage
• 5xx upstream unavailable

9) Configuration

• CALDAV_BASE_URL
• MCP_HTTP_PORT
• LOG_LEVEL
• ALLOW_COOKIE_PASSTHROUGH=false
• CALDAV_TIMEOUT_MS
• CALDAV_RETRY_COUNT (idempotent ops only)

10) Delivery Phases

1. Bootstrap server + config + logging + health
2. WebDAV core client + XML parser/builder + capability probe
3. Principal discovery + calendar listing
4. Calendar CRUD (capability-gated)
5. Event CRUD + ETag conflict controls
6. Hardening: error mapping, redaction, timeout/retry, large-query handling
7. Tests + docs + runbook

11) Testing

• Unit: XML parsing, URL normalization, ETag logic, error mapping
• Integration:
  • Auth pass-through success/failure
  • Multi-calendar discovery from principal
  • Event CRUD roundtrip with conflict test
  • Read-only/shared calendar write rejection
• Contract: MCP tool schemas/responses
• Smoke: discover -> list calendars -> create/update/delete event

12) Definition of Done

• Streamable MCP endpoint stable
• Pass-through auth verified against target SOGo host
• Multiple calendars discoverable and usable
• Calendar + VEVENT CRUD works with conflict handling
• Errors/logging secure and actionable
• Documentation sufficient for deploy and troubleshooting