145 lines
4.4 KiB
Markdown
145 lines
4.4 KiB
Markdown
# 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
|