apple-tools-mcp 1.0.1__tar.gz

apple_tools_mcp-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apple MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apple_tools_mcp-1.0.1/PKG-INFO

@@ -0,0 +1,376 @@
+Metadata-Version: 2.4
+Name: apple-tools-mcp
+Version: 1.0.1
+Summary: Unified Apple ecosystem MCP server for macOS
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Repository, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Changelog, https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/JonathanRReed/Apple-MCPs/issues
+Keywords: mcp,model-context-protocol,macos,apple,ai-agent,automation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: apple-mcp-common<2,>=1.0.0
+Requires-Dist: apple-calendar-mcp<2,>=1.0.0
+Requires-Dist: apple-contacts-mcp<2,>=1.0.0
+Requires-Dist: apple-files-mcp<2,>=1.0.0
+Requires-Dist: apple-mcp-mail<2,>=1.0.0
+Requires-Dist: apple-maps-mcp<2,>=1.0.0
+Requires-Dist: apple-messages-mcp<2,>=1.0.0
+Requires-Dist: apple-mcp-notes<2,>=1.0.0
+Requires-Dist: apple-mcp-reminders<2,>=1.0.0
+Requires-Dist: apple-shortcuts-mcp<2,>=1.0.0
+Requires-Dist: apple-system-mcp<2,>=1.0.0
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.jonathanrreed/apple-tools-mcp -->
+
+# Apple-Tools-MCP
+
+Unified MCP server for Apple apps on macOS.
+
+One entrypoint for Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps. This server wraps the standalone servers and exposes a unified MCP interface.
+
+## What It Does
+
+- Read context across multiple Apple apps
+- Unified actions across all apps
+- Prompts for day planning, communications triage, and meeting prep
+- Persistent defaults for mail, calendar, reminders, notes, and communication routing
+- Per-contact preferences for people who always route a specific way
+- Helper workflows for communication routing, archiving mail, capturing follow-ups, and collaboration summaries
+- Mail thread helpers and Contacts method editing in one place
+- Preview, audit, and undo for reversible actions
+- Files-aware attachment and document workflows within scoped roots
+- System-aware workflows using the frontmost app, clipboard, notifications, running apps, and assistant-relevant macOS settings
+- Truthful Focus context and combined system snapshots for briefing and routing
+- Explicit macOS settings writes for appearance, Finder, Dock, and key accessibility preferences
+- Bounded GUI fallback tools when a native app-domain MCP cannot complete a task directly
+- Finder-aware file workflows, Finder tags, recent locations, and iCloud Drive awareness through Apple Files
+- Travel-aware workflows using Apple Maps for place search and route estimates
+- Daily briefing, weekly briefing, and communications-triage tools
+- Prompt fallback via `apple_list_prompts` and `apple_get_prompt`
+- One install target instead of ten separate configurations
+
+## When to use
+
+- Personal assistant workflows across multiple Apple apps
+- Cross-app operations (e.g., Calendar and Reminders together)
+- Simpler setup without wiring each standalone MCP separately
+
+## Tool Discovery
+
+Apple-Tools-MCP exposes its full tool surface through `tools/list`, with `readOnlyHint`/`destructiveHint` annotations and structured output schemas — modern clients defer-load large tool surfaces themselves. For context-constrained clients:
+
+- `search_tools` finds tools by name, aliases, and domain tags
+- `get_tool_info` loads the full schema and examples for one tool on demand
+- generated code-mode wrappers are exported under `generated/tool_wrappers/python`
+
+## Install On This Mac
+
+<details>
+<summary>Quick start (uvx, from PyPI)</summary>
+
+With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+
+```bash
+uvx apple-tools-mcp
+```
+
+No clone, no venv management.
+
+</details>
+
+<details>
+<summary>From a clone</summary>
+
+```bash
+git clone https://github.com/JonathanRReed/Apple-MCPs.git
+cd Apple-MCPs
+uv sync --all-packages
+```
+
+This builds one uv workspace environment with the unified entrypoint at `.venv/bin/apple-tools-mcp` plus every standalone server's console script (`bash scripts/install_all.sh` does the same, with a venv fallback for machines without uv). You can also point an MCP client at `Apple-Tools-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+<details>
+<summary>Generic MCP client config</summary>
+
+```json
+{
+  "mcpServers": {
+    "apple-tools": {
+      "command": "uvx",
+      "args": ["apple-tools-mcp"],
+      "env": {
+        "APPLE_MAIL_MCP_SAFETY_PROFILE": "full_access",
+        "APPLE_CALENDAR_MCP_SAFETY_MODE": "safe_manage",
+        "APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage",
+        "APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs",
+        "APPLE_FILES_MCP_SAFETY_MODE": "safe_manage",
+        "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage",
+        "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage",
+        "APPLE_NOTES_MCP_SAFETY_MODE": "full_access",
+        "APPLE_MESSAGES_MCP_SAFETY_MODE": "full_access",
+        "APPLE_SHORTCUTS_MCP_SAFETY_MODE": "full_access"
+      }
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/Apple-Tools-MCP/start.sh` as the command with empty `args`.
+
+</details>
+
+<details>
+<summary>Claude Code example</summary>
+
+```bash
+claude mcp add --transport stdio --scope project apple-tools -- uvx apple-tools-mcp
+```
+
+</details>
+
+## What It Exposes
+
+- Health and overview tools across all apps
+- Cross-app prompts
+- Delegated tools from Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System, and Maps
+- Suggestions and permission guides
+- Files, System, and Maps resources and prompts
+- Unified wrappers for Focus, system context, Finder reveal, file open, and file tagging
+- Preference tools: get, detect, and update defaults and contact preferences
+- Communication tools: prepare, send, preview
+- Workflow tools: archive, create reminders and notes with defaults, preview those defaulted writes, capture follow-ups, preview follow-up capture, and summarize event collaboration
+- Launch-hardening tools: strict Maps wrappers, duplicate-contact detection, digest-folder helpers, and Shortcut bridge routing
+- Audit tools: list recent actions and undo
+- Briefing tools: daily, weekly, and communications triage
+- Prompt fallback: `apple_list_prompts` and `apple_get_prompt`
+- Mail thread tools: get, reply, archive
+- Contacts mutation: create, update, delete with labeled methods
+- Calendar and Messages permission diagnostics
+- Launch and recovery: `apple_health`, `apple_permission_guide`, `apple_recheck_permissions`
+
+## Assistant Defaults
+
+Apple-Tools-MCP can persist a lightweight assistant state file with defaults for:
+
+- default mail account
+- default archive mailbox
+- default calendar
+- default reminders list
+- default notes folder
+- preferred communication channel, `messages`, `mail`, or `auto`
+- preferred message target type, `phone`, `email`, or `auto`
+- per-contact preferred channel and target overrides for specific people
+
+Detect and persist sensible defaults with `apple_detect_defaults`, inspect them with `apple_get_preferences`, and override them with `apple_update_preferences`.
+
+By default the state file is stored at `~/.apple-tools-mcp/preferences.json`. Override it with `APPLE_AGENT_MCP_STATE_FILE`.
+
+Apple-Tools-MCP also stores recent assistant actions in `~/.apple-tools-mcp/actions.json` so the unified server can expose audit history and undo for reversible operations.
+
+## How to Work With It
+
+- Resolve people through Contacts first, then decide between Messages or Mail based on saved defaults.
+- Set per-contact preferences for people who always prefer a specific channel.
+- Preview risky actions and defaulted create flows when the client wants confirmation.
+- Use Mail thread helpers when the user refers to a conversation, not a single message.
+- Set defaults early (archive mailbox, calendar, reminders list, notes folder) so the assistant doesn't keep asking.
+- Keep contact info current so communication routing works reliably.
+- Use Files before Mail, Messages, Notes, or Shortcuts when the request involves local documents.
+- Check System context before interruptive actions, especially when the frontmost app, clipboard, or battery state matters.
+- Treat Focus support as truthful best-effort. Use it when available, and do not invent a current Focus mode if the MCP reports unsupported on the local setup.
+- Use `apple_update_system_setting` for macOS preference changes and `apple_control_frontmost_app` only when a native app-domain tool cannot complete the task.
+- Prefer explicit System settings tools over generic GUI automation when the request is really a macOS preference change.
+- Use GUI fallback tools only when the native domain MCP cannot complete the task and the client has granted Accessibility access.
+- Use native Maps MCP tools for maps search and directions. Do not substitute shell, web, or external map providers when validating supported Maps behavior.
+- Use Shortcuts as the explicit bridge when native domain support is missing, rather than ad hoc shell or GUI work.
+- Use the dedicated digest folder helpers before saving daily or weekly briefings into Notes.
+- Use Maps when routing or travel time affects scheduling or communication.
+- Use `apple_list_recent_actions` and `apple_undo_action` for reversible operations.
+- When Mail must use a specific sender identity, pass the exact sender email in `from_account`, not just an account nickname.
+
+## macOS Permissions
+
+- Mail needs Automation access to Mail
+- Calendar needs Calendar access
+- Reminders needs Reminders access
+- Messages needs Automation access to Messages, plus Full Disk Access for history
+- Contacts needs Contacts access
+- Notes needs Automation access to Notes
+- Shortcuts usually works without a separate privacy prompt
+- Files access is controlled by `APPLE_FILES_MCP_ALLOWED_ROOTS`, not by a macOS privacy prompt
+- System actions may trigger System Events, Accessibility, or automation prompts depending on the host app
+- Focus status is best-effort and truthful on unsigned local installs
+- Notification Center history is not claimed where macOS does not expose it cleanly
+- Maps does not need a privacy prompt, but search and directions require the local Swift helper to compile
+
+## Launch Checklist
+
+- Add `uvx apple-tools-mcp` (or a clone's `Apple-Tools-MCP/start.sh` / installed `.venv/bin/apple-tools-mcp` entrypoint) to your MCP client
+- Reload or reconnect the client so the Apple-Tools-MCP tool surface is loaded into context
+- Call `apple_health` first to verify every domain
+- If a domain is blocked, call `apple_permission_guide`
+- After changing macOS permissions, call `apple_recheck_permissions`
+
+## Transports and Protocol Verification
+
+`stdio` is the default and recommended transport. Set `APPLE_AGENT_MCP_TRANSPORT=streamable-http` (with optional `APPLE_AGENT_MCP_HOST` and `APPLE_AGENT_MCP_PORT`) to serve Streamable HTTP instead — used below for protocol validation.
+
+### Official MCP conformance
+
+Start Apple-Tools-MCP in conformance mode:
+
+```bash
+cd /path/to/Apple-MCPs/Apple-Tools-MCP
+APPLE_AGENT_MCP_TRANSPORT=streamable-http \
+APPLE_AGENT_MCP_PORT=8765 \
+APPLE_AGENT_MCP_CONFORMANCE_MODE=1 \
+./start.sh
+```
+
+Then run the official active suite:
+
+```bash
+npx -y @modelcontextprotocol/conformance server \
+  --url http://127.0.0.1:8765/mcp \
+  --suite active
+```
+
+`APPLE_AGENT_MCP_CONFORMANCE_MODE=1` adds an opt-in MCP conformance surface covering content types, resources, resource templates, prompts, progress, and completion (fixtures for features removed by spec 2026-07-28 are intentionally absent). It is intended for CI and protocol testing, not normal assistant use.
+
+The briefing and triage tools (`apple_generate_daily_briefing`, `apple_generate_weekly_briefing`, `apple_triage_communications_task`) are standard synchronous tools — the experimental MCP tasks API they previously used was removed from the spec (SEP-1686) and SDK, with the same tool names and results.
+
+## Launch Docs
+
+- [Golden Workflows](../docs/launch/golden-workflows.md)
+- [Failure Modes](../docs/launch/failure-modes.md)
+- [Compatibility and Version Pinning](../docs/launch/compatibility.md)
+- [Code Mode](../docs/code-mode.md)
+- [Demo Script](../docs/launch/demo-script.md)
+- [Checklist Template Prompt](../docs/launch/prompts/checklist-template.md)
+
+### Inspector CLI smoke check
+
+From this server directory:
+
+```bash
+npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method tools/list
+npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method prompts/list
+npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method resources/list
+```
+
+For the full repo-wide smoke pass, run:
+
+```bash
+cd /path/to/Apple-MCPs
+bash scripts/inspector_smoke.sh
+```
+
+## Agent Routing Prompt
+
+```xml
+<apple_tools>
+`tools/list` returns the full tool surface. If context is constrained, use `search_tools` first, then `get_tool_info` only for the tools you plan to call.
+
+<routing>
+  <imessage trigger="text, message, msg, iMessage">
+    Resolve recipient via Contacts first. Confirm if multiple matches.
+    Omit service_name parameter entirely.
+  </imessage>
+
+  <contacts trigger="lookup, phone number, email, contact">
+    Run before any iMessage or Mail action.
+  </contacts>
+
+  <mail trigger="email, mail, inbox, draft, reply">
+    Search requires a query string (sender, subject, or "*" as wildcard). No list-all endpoint.
+    If text vs. email is ambiguous, ask once.
+  </mail>
+
+  <calendar trigger="calendar, event, schedule, appointment, meeting, block time">
+    Confirm date, time, duration, and title before writing.
+  </calendar>
+
+  <reminders trigger="remind me, task, to-do, don't forget">
+    Reminders are organized into lists. Identify available lists on first use and set a default.
+    due_date requires timezone offset: yyyy-MM-ddTHH:mm:ss-HH:00
+  </reminders>
+
+  <notes trigger="note, jot down, write this down, save this">
+    Multiple accounts may have a "Notes" folder. Identify them on first use and set a default.
+    Use for reference only. Time-sensitive items go to Reminders or Calendar.
+  </notes>
+
+  <shortcuts trigger="shortcut, automation, run shortcut">
+    List available shortcuts before running if request is vague.
+  </shortcuts>
+
+  <files trigger="file, folder, attachment, document, download, desktop">
+    Use Files before Mail, Messages, Notes, or Shortcuts when the request references local paths or attachments.
+    Confirm the exact path before mutation or send actions.
+  </files>
+
+  <system trigger="clipboard, frontmost app, battery, notification, open app">
+    Use System when local desktop context affects the next action.
+    Keep writes scoped unless the user clearly asked for a notification, clipboard update, or app launch.
+  </system>
+
+  <maps trigger="map, directions, route, commute, eta, address, place">
+    Use Maps when place lookup or travel time affects scheduling or communication.
+    Confirm origin, destination, and transport mode for time-sensitive plans.
+  </maps>
+</routing>
+
+<disambiguation>
+  1. Has due date/time -> Reminders
+  2. Reference material, no action -> Notes
+  3. Involves another person -> iMessage or Mail (Contacts first)
+  4. Text vs. email unclear -> ask once
+</disambiguation>
+
+<known_gotchas>
+  - service_name on iMessage calls causes error (-1728). Omit it.
+  - Bare timestamps without timezone offset fail on Reminders.
+  - Mail has no "list recent" endpoint. Always pass a search query.
+  - Use `search_tools` plus `get_tool_info` to inspect tools without loading every schema into context.
+  - Multiple Notes folders exist across accounts. Pick one default.
+  - Files access is limited to APPLE_FILES_MCP_ALLOWED_ROOTS.
+  - Some System actions depend on host app automation approval.
+  - Maps search and directions depend on the local Swift helper and Xcode command line tools.
+</known_gotchas>
+</apple_tools>
+```
+
+## Related Servers
+
+- [Apple Files MCP](../AppleFiles-MCP/README.md)
+- [Apple System MCP](../AppleSystem-MCP/README.md)
+- [Apple Maps MCP](../AppleMaps-MCP/README.md)
+- [Apple Mail MCP](../AppleMail-MCP/README.md)
+- [Apple Calendar](../Apple-Calendar-MCP/README.md)
+- [Apple Reminders MCP](../AppleReminders-MCP/README.md)
+- [Apple Messages MCP](../AppleMessages-MCP/README.md)
+- [Apple Contacts MCP](../AppleContacts-MCP/README.md)
+- [Apple Notes MCP](../AppleNotes-MCP/README.md)
+- [Apple Shortcuts MCP](../AppleShortcuts-MCP/README.md)