# Cozi for ChatGPT

An unofficial, read-only MCP server that lets ChatGPT query a live Cozi family calendar through Cozi's published iCalendar (ICS) feed.

The private MVP is deployed on Cloudflare Workers and connected to ChatGPT as a developer plugin named **Cozi**.

## What it does

The MCP server exposes seven read-only tools:

- `list_family_members` — list family members inferred from Cozi event prefixes.
- `list_events` — return events in a date range, optionally filtered by person.
- `get_next_event` — return the next upcoming event, optionally for one person.
- `search_events` — search titles, locations, descriptions, and participant prefixes.
- `find_conflicts` — return overlapping events in a date range.
- `find_free_time` — find open windows for one or more people.
- `availability_summary` — compare busy versus free calendar time across people without double-counting overlapping events.

The calendar layer handles:

- timed and all-day events
- `RRULE` recurrence expansion
- `EXDATE` exclusions
- Cozi participant prefixes such as `Michael/Jackson:` or `All:`
- America/Los_Angeles and other IANA timezone-aware output
- whitespace cleanup and normalization
- overlapping-event union for availability calculations

## Example prompts

```text
@Cozi What's on the family calendar today?
@Cozi What is Jackson's next event?
@Cozi What is Hannah doing today?
@Cozi Are there any calendar conflicts this weekend?
@Cozi Find a 90-minute free block for Michael and Jackson this Saturday between 9 AM and 8 PM.
@Cozi Who has the most free time this week?
```

## Architecture

```text
Cozi calendar
    |
    | private published ICS URL
    v
Cloudflare Worker
    |
    | validate + fetch + parse
    v
Calendar engine
    |
    | deterministic structured MCP tools
    v
ChatGPT
```

The Worker is stateless. It fetches the configured Cozi ICS URL on demand and exposes structured, read-only MCP actions to ChatGPT.

See [`docs/architecture.md`](docs/architecture.md) for more detail.

## Security model

The Cozi feed URL is effectively a read credential to the family calendar. **Never commit it.**

Production expects it as a Cloudflare Worker runtime secret named:

```text
COZI_CALENDAR_URL
```

For local development, copy `.dev.vars.example` to `.dev.vars` and replace the placeholder with a private test feed URL. `.dev.vars` is gitignored.

The Worker accepts only HTTPS URLs on the exact `rest.cozi.com` host with a Cozi iCalendar-feed path. Redirects are handled manually and are not automatically followed to another host. The configured feed URL is never returned by an MCP tool.

## Local development

Requirements:

- Node.js 20+
- npm
- a private Cozi calendar feed URL for live testing

```bash
npm install
npm test
npm run check
```

Run locally:

```bash
cp .dev.vars.example .dev.vars
# edit .dev.vars with your private Cozi URL
npm run dev
```

Local MCP endpoint:

```text
http://localhost:8787/mcp
```

## Cloudflare deployment

The repository is connected to Cloudflare Workers Builds. Pushes to `main` automatically deploy using:

```text
npx wrangler deploy
```

The Worker configuration lives in `wrangler.jsonc` and the production secret is managed in Cloudflare, not GitHub.

Health endpoint:

```text
https://<worker>.<account>.workers.dev/health
```

MCP endpoint:

```text
https://<worker>.<account>.workers.dev/mcp
```

## ChatGPT connection

The private developer connection uses the HTTPS `/mcp` endpoint with **no MCP authentication** because the single private Cozi feed URL is stored server-side as a Cloudflare secret.

That is appropriate only for the private MVP. A public release must add per-user connection/authentication and secure per-user storage so every user supplies only their own Cozi calendar feed.

## Validation

The private MVP passed live end-to-end tests on August 11, 2026, including:

- today's family schedule
- next event for a family member
- person-specific daily schedule
- weekend conflict detection
- multi-person free-time search
- family availability comparison

See [`docs/live-validation-2026-08-11.md`](docs/live-validation-2026-08-11.md) and [`docs/test-prompts.md`](docs/test-prompts.md).

No real family calendar data or real Cozi subscription URL is committed to this repository. Tests use a synthetic Cozi-style ICS fixture.

## Status

**v0.2.0 private MVP:** functional and deployed.

Next public-release gate: per-user onboarding/authentication, privacy-policy completion, plugin icon/metadata polish, and submission review.

## Disclaimer

This is an independent, unofficial integration and is not affiliated with, endorsed by, or sponsored by Cozi Group Inc.