init

docs/implementation-plan.md

@@ -0,0 +1,144 @@
+# 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: `https://mail.simon-franken.de/SOGo/dav`
+- 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