mcp-apple-reminders AGENTS.md

AGENTS.md

1. Project snapshot

• What: macOS-only MCP server exposing Apple Reminders (EventKit + private ReminderKit) to Claude Code, Codex, and Claude Desktop.
• Runtime: Python 3.10+ (repo venv runs 3.13.5 from miniconda). MCP SDK 1.27+ (FastMCP) + PyObjC. Three-tier native layer at src/mcp_apple_reminders/_native/ (renamed from libs/pyremindkit/ in slice 0.2).
• Platform: macOS only — depends on EventKit / ReminderKit and a granted Reminders permission on the interpreter binary.
• Owner: @pierce (single-author repo as of 2026-05).
• Non-goals: cross-platform support, reminder UI (use Reminders.app), iCloud sync logic (macOS handles it).

2. Setup

./install.sh                          # creates ./venv, installs editable pkg + deps, builds native helpers
./venv/bin/python3 verify_setup.py    # preflight: interpreter, deps, perms, client configs

Grant Reminders permission on first launch — approve the macOS dialog when verify_setup.py runs, OR run ./shim_mcp.sh once and approve. Permission is per-binary; the conda Python interpreter must be the one approved.

3. Commands the agent MUST run before declaring done

• ruff check src/ tests/
• black --check src/ tests/
• ./venv/bin/python -m pytest tests/test_mcp_tools.py tests/test_workflow_tools.py tests/test_e2e.py — explicit paths (or make test-actual)
• make check-architecture (line-limit gate: hard cap 400 lines/file)
• make bump-patch (or minor/major) before commit — bump_required_per_commit: true

4. Repo layout

src/mcp_apple_reminders/        FastMCP server (server.py) + lifespan.py + models.py + formatting.py
src/mcp_apple_reminders/tools/  17 @mcp.tool modules: calendars, reminders, completion, queries,
                                workflow, groups, alarms, bulk, sections, smartlists, appearance,
                                templates, flags, attachments, grocery, agents, sampling (58 tools)
src/mcp_apple_reminders/resources/  @mcp.resource SQLite views (e.g. agents://current/{project})
src/mcp_apple_reminders/prompts/    @mcp.prompt canned workflows
src/mcp_apple_reminders/_native/    Three-tier native layer: sqlite.py (+ _sqlite_helpers) = reads;
                                eventkit.py = Swift EventKit helper; reminderkit.py +
                                reminderkit_actions.py = Obj-C ReminderKit (private) helper;
                                legacy PyObjC wrapper (core, _internal, calendars, models); bulk.py
src/mcp_apple_reminders/_native/bin/  Compiled rem_eventkit + rem_reminderkit (from _native/src/
                                *.swift / *.m; build with `make build-native`)
scripts/                        Gate scripts (bump_version, check_architecture, check_module_rules, …)
tests/                          Test suite (test_*.py) + tests/_support/ (TestResults harness, cleanup)
docs/                           MAP.md, TOOLS.md, SQLITE_SCHEMA.md, SECURITY-REVIEW.md, adr/, audits/
verify_setup.py                 Install + permission + client-config verification
install.sh, shim_mcp.sh         Bootstrap + first-run permission-prompt shim