apple-calendar-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.

An MCP server exposing Apple Calendar on macOS to any client that speaks the protocol. Two halves: a Swift CLI wrapping EventKit, and a TypeScript MCP layer that drives it.

Commands

npm test                                  # full vitest suite
npx vitest run tests/freeTime.test.ts     # one file
npx vitest run -t "ignoriert abgesagte"   # one test by name
npm run typecheck                         # tsc --noEmit (covers src/ and tests/)
npm run build                             # tsc -> dist/ (src/ only)
./swift/build.sh                          # compile + sign bin/calendar-helper (universal)

build.sh builds both arm64 and x86_64 against a macOS 14 deployment target and joins them with lipo. The binary ships inside the npm package, so an arm64-only build would be broken on Intel Macs — and only at the user's end, never at build time. Signing happens on the finished fat binary; lipo would invalidate per-slice signatures anyway.

After changing swift/main.swift, run ./swift/build.sh and restart the client. There is no service to reinstall — the helper is a child process of the MCP server, so the next server start picks up the new binary.

After changing src/, run npm run build and restart the client; it loads dist/index.js once at startup.

vitest.config.ts pins TZ=Europe/Berlin. Several tests assert literal +02:00 timestamps. Do not make those assertions timezone-agnostic — the offset is part of what they verify.

The architecture constraint that explains everything

macOS attributes calendar (TCC) permission to the responsible parent process, not to the binary being executed. A GUI client like Claude Desktop declares no calendar usage description anywhere in its bundle, so any process it spawns is denied — silently, with no dialog and no entry in System Settings.

The helper escapes this by disclaiming that responsibility at startup. reexecDisclaimed() in swift/main.swift re-execs the process via posix_spawn(POSIX_SPAWN_SETEXEC) with responsibility_spawnattrs_setdisclaim, making the binary its own TCC-responsible process. macOS then reads the usage description from its embedded Info.plist and prompts under the name calendar-helper. This is the same private libSystem call Chromium uses for its helper processes; it is resolved through dlsym, so a future macOS dropping the symbol degrades to the old behaviour instead of failing to load.