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.

Commands

# Install dependencies (initializes vendor/event submodule + builds bin/event)
pnpm install

# Build TypeScript and the vendored `event` CLI (required before running)
pnpm build

# Run all tests
pnpm test

# Run a single test file
pnpm test -- src/path/to/file.test.ts

# Run tests matching a pattern
pnpm test -- --testNamePattern="pattern"

# Lint and format with Biome
pnpm lint

# Combined lint + typecheck
pnpm check

Architecture

This is an MCP (Model Context Protocol) server providing native macOS integration with Apple Reminders and Calendar via EventKit.

Layer Structure

src/
├── index.ts              # Entry point: loads config, starts server
├── server/
│   ├── server.ts         # MCP server setup with stdio transport
│   ├── handlers.ts       # Request handler registration (tools, prompts)
│   ├── prompts.ts        # Prompt template definitions and builders
│   └── promptAbstractions.ts
├── tools/
│   ├── definitions.ts    # MCP tool schemas
│   ├── index.ts          # Tool routing: dispatches to handlers
│   └── handlers/         # Domain-specific CRUD handlers
│       ├── reminderHandlers.ts
│       ├── subtaskHandlers.ts
│       ├── listHandlers.ts
│       ├── calendarHandlers.ts
│       └── shared.ts     # Common formatting utilities (extractAndValidateArgs, formatListMarkdown)
├── utils/
│   ├── eventCli.ts       # Executes the vendored `event` Swift CLI, parses raw JSON
│   ├── reminderRepository.ts  # Repository pattern for reminders
│   ├── calendarRepository.ts  # Repository pattern for calendar events
│   ├── binaryValidator.ts     # Secure binary path validation
│   ├── errorHandling.ts       # Centralized async error wrapper (CliUserError / CliPermissionError)
│   ├── helpers.ts             # CLI argument builders (addOptionalArg, nullToUndefined)
│   ├── tagUtils.ts            # TS-side tag parsing/writing in the reminder notes field
│   └── subtaskUtils.ts        # TS-side subtask parsing/writing in the reminder notes field
├── validation/
│   └── schemas.ts        # Zod schemas for input validation
└── types/
    └── index.ts          # TypeScript interfaces and type constants