hoocal

An AI-agent-managed calendar service with bidirectional Google Calendar + Apple iCloud sync.

An AI agent connects over MCP (Model Context Protocol) and fully manages calendars and events — create / read / update / delete, reschedule, search, query availability. The agent reads and writes a local canonical store; a background sync engine reconciles that store with the user's real Google and iCloud calendars in both directions.

Architecture

Three logical layers, four runtime processes (one Docker image, APP env selects the entrypoint):

Layer	Package / App	Responsibility
Agent interface	apps/mcp-server	MCP Streamable-HTTP server; 12 calendar tools; local store only (never imports providers/sync — enforced by dependency-cruiser)
Core	packages/core	Canonical PostgreSQL store, local↔remote mapping, RLS multi-tenancy, availability compute
Sync engine	packages/sync-engine + apps/sync-worker	BullMQ bidirectional reconciliation; Google + iCloud adapters behind one CalendarProvider interface
	apps/webhook-receiver	Google events.watch push receiver
	apps/onboarding-web	User-driven Google OAuth + iCloud app-password capture (credentials never touch the agent)

Supporting packages: @hoocal/shared (pure types/errors/utils), @hoocal/ical-codec (RFC 5545 ↔ canonical), @hoocal/providers (adapters), @hoocal/auth-server (inbound MCP OAuth 2.1 resource server), @hoocal/credentials (outbound provider secrets), @hoocal/contracts (Zod tool schemas).

See the implementation plan for the full design and milestone roadmap.

Status — M0–M5 implemented ✅

All milestones are built and tested (73 unit tests + integration tests against real Postgres & Redis; full build / typecheck / module-boundary / lint gate green):

• M0 Scaffold — monorepo, full Drizzle schema (9 tables, enums, indexes, RLS), docker-compose, migration runner.
• M1 Google pull — CalendarProvider interface, GoogleAdapter (incremental syncToken + 410 full-resync), DST-correct recurrence codec, envelope-encrypted credentials, pull pipeline (idempotent, watermark-in-tx).
• M2 MCP + auth + reads — multi-tenant Streamable-HTTP MCP server, OAuth 2.1 resource server + PRM, session→user binding, 5 read tools, RLS tenant isolation (proven via a real MCP client).
• M3 Writes + push — 7 write tools (is_writable gating, two-phase confirm), agent-write store methods, idempotent push pipeline, Google OAuth onboarding with encrypted credential storage.
• M4 Bidirectional + webhooks — 3-stage echo suppression, LWW + SEQUENCE conflict resolution + journal, 412 handling, BullMQ scheduler/worker + per-unit advisory lock (Redis-tested), Google events.watch webhook receiver, fallback poll.
• M5 iCloud + hardening — ICloudAdapter (tsdav, full-PUT, capability errors), RFC 5545 ics codec (round-trip incl. TZID + master/override), iCloud onboarding, a shared adapter contract suite proving Google + iCloud satisfy one spec, and a live Radicale CalDAV integration test of the real transport.

Recurrence + sync edge cases (all implemented):

• Per-instance recurring edits — delete scope: this (EXDATE), update scope: this (detach the occurrence into a standalone event + EXDATE), and thisAndFuture (split the series, preserving a COUNT-bounded remainder). All sync cleanly to both providers.
• iCloud RECURRENCE-ID overrides — a resource's master + override VEVENTs pull as distinct events; writes use read-merge-write so editing one VEVENT never clobbers the others.
• iCloud delete-detection — an href/etag snapshot (carried in the watermark) detects server-side deletions; an unchanged CTag is a cheap no-op.
• Google events.watch — the sync-worker registers and renews push channels before the 7-day TTL when WEBHOOK_PUBLIC_URL is configured; otherwise the fallback poll runs.

Representation note: an agent-modified single occurrence is stored as a detached standalone event (master EXDATE + new event) rather than a provider-native exception — functionally equivalent and round-trips cleanly through both providers.

Develop

Requires Node ≥ 20, pnpm 11, Docker.

pnpm install
cp .env.example .env            # fill in secrets as needed

# Bring up infra + all 4 services (runs migrations first)
pnpm compose:up

# Or run the toolchain locally
pnpm build
pnpm typecheck
pnpm depcruise                  # architectural boundary checks
pnpm test

# Database
pnpm db:generate                # regenerate SQL migrations from the schema
pnpm db:migrate:dev             # apply migrations (tsx, no build needed) + FORCE RLS

Health endpoints: mcp-server :8080/health, sync-worker :8081/health, webhook-receiver :8082/health, onboarding-web :8083/health.

Testing philosophy

Sync is tested without hammering real providers: a local Radicale CalDAV server is the iCloud mock, Google is mocked at the HTTP layer (nock/msw) with recorded fixtures, and one shared adapter contract suite runs against both providers to prove provider-agnosticism. A live Google sandbox smoke runs only behind RUN_LIVE_GOOGLE=1 (nightly), never in the default suite.