pyapple-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.

Development Commands

Installation and Development Setup

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run the MCP server directly
python -m pyapple_mcp.server

# Run the CLI from the source tree, without installing the console script
python -m pyapple_mcp.cli --help
python -m pyapple_mcp.cli perms

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector pyapple-mcp

Code Quality Tools

# Format code with Black
black .

# Sort imports with isort
isort .

# Type checking with mypy
mypy .

# Run tests
pytest

Building and Distribution

# Build package
python -m build

# Install locally
pip install .

Architecture Overview

Two front ends over one set of Apple integrations:

• server.py — the MCP server, on FastMCP. Ten tools, 88 operations, each tool a single call whose operation argument selects what it does. The tools/list annotations are computed from the policy in force rather than hardcoded, so under PYAPPLE_READ_ONLY=1 a tool honestly reports readOnlyHint: true (_annotations).
• cli.py — pyapple, the same ten tools as shell subcommands.

Neither front end contains Apple logic. Every query, AppleScript and framework call lives in utils/, and both front ends call the same handler objects out of handlers.py — not two copies that can drift out of agreement.

• policy.py — the permission model, and the single source of truth for which operations exist. OPERATIONS maps tool → operation → class. It is imported by both front ends and imports neither, which is what lets one permission string mean the same thing in an MCP config and in a shell. An operation with no entry raises rather than defaulting, and tests/test_policy.py reads the operation list out of server.py and fails if the two disagree.
• consent.py — the two-phase send gate. Orthogonal to policy.py: the policy says whether a caller may send, this says how one particular send is reached. Off unless PYAPPLE_CONFIRM_SENDS=1. Read its module docstring before touching it; the reasoning is there and is not repeated here.
• setup_helper.py — writes the Claude Desktop config.
• utils/ — one module per app, plus applescript.py, timeparse.py, phrasing.py, pasteboard.py and truncation.py. Three of the modules are not an app at all: shortcuts.py (a subprocess), presence.py (sensing) and doctor.py (what macOS is granting).