apple-contacts-mcp

Use BEFORE adding any new tool, parameter, or endpoint to the Apple Contacts MCP server. Also use when considering API changes, evaluating feature requests, or when tempted to create a specialized operation. Contains the decision tree that prevents tool sprawl and the anti-pattern catalog.

Use BEFORE writing any code that touches Contacts.app data. Covers the Contacts.framework / PyObjC primary surface, the AppleScript fallback path for note + modification-date access, the TCC authorization flow, and the gotchas that aren't obvious from Apple's docs (entitlement-gated keys, raw label tokens, vCard 3.0-only export). Read together with `docs/research/contacts-api-gap-analysis.md` for the empirical basis.

Use when designing list/search/batch operations or chasing a slow tool. Establishes the empirical baselines from Phase 0 plus the patterns that hold for Contacts.framework specifically — most importantly the absence of subprocess overhead that makes mail-style perf advice misleading.

Use when setting up, running, or debugging integration tests against real Apple Contacts. Also use when unit tests pass but behavior seems wrong, when adding new AppleScript operations, or when you need to understand why mocked tests are insufficient for this project.

Use when the user wants to release a new version. Orchestrates the full release workflow including milestone check, version bump, changelog generation, validation, tagging, and PR creation. Also use when discussing release planning or version management.