apple-notes-reminders-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.

What this is

An MCP server (macOS-only) that exposes Apple Notes and Apple Reminders as tools to MCP clients (e.g. Claude Desktop). TypeScript, ESM, compiled with tsc, run under Node via stdio transport.

Commands

npm run build         # tsc compile, src/ -> dist/
npm run build:swift   # swiftc swift/reminders-daemon.swift -o swift/reminders-daemon (also runs on npm install via postinstall)
npm start             # node dist/index.js (the MCP server, stdio transport)

There is no lint script and no npm test. Test suites are standalone scripts:

npm run build && node scripts/test-phase2.mjs             # protobuf/checklist decoder
npm run build && node scripts/test-markdown.mjs            # markdown -> Notes-HTML converter
npm run build && node scripts/test-schema-detection.mjs    # schema-detection sanity checks (live DB)

scripts/test-phase2.mjs is self-contained — it reimplements the protobuf varint/field decoder inline (mirroring notesStore.ts) rather than importing it, so unit-test sections (varint safety, checklist edge cases, and a set of pinned full-pipeline fixtures that gzip-compress a complete synthetic document and decode it end to end) run without touching the real Notes database. Its final section ("Real DB notes") does open the actual dist/notesStore.js and read specific note IDs (p9875, p9656, p9858) that only exist in the original author's own Notes.app — those cases will fail/error on any other machine and can be ignored when validating unrelated changes.

scripts/test-markdown.mjs imports dist/markdown.js directly and asserts exact HTML output for the markdown converter — fully deterministic, no Notes.app or SQLite access needed.

scripts/test-schema-detection.mjs imports dist/notesStore.js and asserts invariants (non-empty folder path/id/account, Recently Deleted excluded, valid date parsing, etc.) against whatever real Notes database is present — like test-phase2.mjs's "Real DB notes" section, this needs Full Disk Access and actual note/folder data, so failures on a fresh or empty library are expected rather than a regression signal.