cozi_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Node 20+/TypeScript MCP server that exposes Cozi Family Organizer (lists + calendar) to AI assistants. Distributed two ways: MCPB bundle (drag-and-drop into Claude Desktop) and npx @mjucius/cozi-mcp for any other MCP client. Smithery distribution was dropped in 2.2.3 (zero installs, and its stale listings leaked into the official MCP Registry — #14); don't re-add a registry without a reason to expect users there.

v2.0 (2026-05) is a ground-up Node/TypeScript rewrite of the prior Python v1. The runtime changed AND the tool surface was consolidated (14 → 12 tools, slim projections). See README.md for the v1→v2 migration table. Legacy Python source is preserved at git tag v1.0.0.

Development Commands

• npm install — install dependencies
• npm test — vitest (214 tests, mocks CoziClient at the boundary; no creds needed)
• npm run test:live — live conformance suite against the real Cozi API (tests/live/; reads creds.env or COZI_USERNAME/COZI_PASSWORD, skips without them). ~43 tests, ~2.5 min, self-cleaning. Required before every release — see Testing.
• npm run typecheck — tsc --noEmit
• npm run build — tsup → dist/server.js + dist/bin.js
• npm run dev — local stdio dev (needs COZI_USERNAME + COZI_PASSWORD env vars)
• npm run bundle:mcpb — produces cozi-mcp.mcpb at repo root

Architecture

Core components

• src/server.ts — createServer({ config }) factory, called by bin.ts. Per-credentials Map<string, CoziClient> cache so concurrent sessions stay isolated.
• src/bin.ts — npx + MCPB stdio entry point (#!/usr/bin/env node). Reads COZI_USERNAME/COZI_PASSWORD env vars, instantiates createServer, pipes to StdioServerTransport.
• src/instructions.ts — SERVER_INSTRUCTIONS constant injected into the MCP server.
• src/cozi/ — Inlined Cozi HTTP client. No separate npm package. Cozi API access lives here.
  • client.ts — CoziClient class (auth with cookie refresh + list/item/calendar CRUD, calendar search). Every request carries the apikey.
  • http.ts — fetch wrapper with per-client cookie jar, 100ms rate-limit gate, 3-attempt retry/backoff, 401-once-then-reauth.
  • models.ts — Zod schemas with .transform() for camelCase↔snake_case wire mapping.
  • appointment-payloads.ts — toApiCreate/Edit/DeleteFormat() builders for the three Cozi appointment payload shapes.
  • errors.ts — CoziError hierarchy.
• src/tools/ — 15 MCP tools. Each tool has a *Handler function (directly testable) and a register*Tool(server, getClient) registrar.
  • projections.ts — slimPerson / slimListSummary / slimItem / slimAppt. Wire keys are exact strings (type, item_count, all_day — not listType, itemCount, allDay).
  • parsers.ts — parseIsoDateTime, parseListType.
  • untrusted.ts — toolResult returns two text blocks: content[0] is the boundary-fenced Cozi data, content[1] a local-time stamp from localNow() (host clock; TZ overrides) so assistants with a UTC clock resolve "tomorrow" correctly.