apple-system-mcp 1.0.1__tar.gz

apple_system_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_system_mcp-1.0.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: apple-system-mcp
+Version: 1.0.1
+Summary: Local Apple System 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: 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-system-mcp -->
+
+# Apple System MCP
+
+Local MCP server for macOS system context, truthful Focus support metadata, assistant-relevant settings reads, explicit settings writes, and bounded GUI fallback automation.
+
+## Capabilities
+
+- battery status
+- frontmost app
+- running applications
+- clipboard read and write
+- local notifications
+- open an application
+- appearance settings
+- accessibility settings
+- Dock settings
+- Finder settings
+- truthful Focus support metadata
+- combined system context snapshots
+- appearance mode write
+- Finder visibility and bar writes
+- Dock write controls for autohide and recent apps
+- accessibility writes for reduce motion, increase contrast, and reduce transparency
+- GUI fallback tools for menu clicks, key presses, text entry, button clicks, and pop-up selection
+- preference-domain inspection via `defaults export`
+- resources: `system://status`, `system://applications`, `system://settings`, `system://context`
+- prompt: `system_capture_context`
+- tool discovery helpers `search_tools` and `get_tool_info` for context-constrained clients
+
+## 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-system-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 workspace environment with every server's entry point in `.venv/bin` (for example `.venv/bin/apple-system-mcp`). You can also point an MCP client at `AppleSystem-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+```json
+{
+  "mcpServers": {
+    "apple-system": {
+      "command": "uvx",
+      "args": ["apple-system-mcp"],
+      "env": {
+        "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage"
+      }
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/AppleSystem-MCP/start.sh` as the command with empty `args`.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --scope project apple-system -- uvx apple-system-mcp
+```
+
+## Transport
+
+`stdio` is the default and recommended transport. Set `APPLE_SYSTEM_MCP_TRANSPORT=streamable-http` (with optional `APPLE_SYSTEM_MCP_HOST` and `APPLE_SYSTEM_MCP_PORT`) to serve Streamable HTTP instead.
+
+## Prompting Notes
+
+- `tools/list` returns the full System tool surface. Context-constrained clients can use `search_tools` first, then `get_tool_info` for the System tool they need.
+- Use this server when the user’s current desktop context matters.
+- Read battery state and the frontmost app before interruptive actions.
+- Use the settings tools before falling back to raw `defaults read` in prompts or E2E checks.
+- Use `APPLE_SYSTEM_MCP_SAFETY_MODE=safe_manage` for assistant-grade operation.
+- Keep `safe_readonly` only for audit-only or context-only deployments.
+- Keep GUI fallback narrow. Prefer native app-domain MCPs first, then explicit System tools, then GUI tools only when native support is missing.
+- Focus reporting is best-effort and truthful. This server does not claim Notification Center history support when macOS does not expose it cleanly on an unsigned local install.
+
+## Health And Recovery
+
+- `system_health`
+- `system_permission_guide`
+- `system_get_settings_snapshot`
+- `system_get_focus_status`
+- `system_get_context_snapshot`
+- `system_read_preference_domain`
+
+## Assistant-Grade Control Surface
+
+The launch System write surface is explicit, not generic:
+
+- `system_set_appearance_mode`
+- `system_set_show_all_extensions`
+- `system_set_show_hidden_files`
+- `system_set_finder_path_bar`
+- `system_set_finder_status_bar`
+- `system_set_dock_autohide`
+- `system_set_dock_show_recents`
+- `system_set_reduce_motion`
+- `system_set_increase_contrast`
+- `system_set_reduce_transparency`
+
+The bounded GUI fallback surface is:
+
+- `system_gui_list_menu_bar_items`
+- `system_gui_click_menu_path`
+- `system_gui_press_keys`
+- `system_gui_type_text`
+- `system_gui_click_button`
+- `system_gui_choose_popup_value`
+
+## Launch Checklist
+
+- Add `uvx apple-system-mcp` (or a clone's `AppleSystem-MCP/start.sh`) to your MCP client
+- Reload or reconnect the client so the System tool surface is loaded into context
+- Call `system_health` first
+- If a scoped system action is blocked, call `system_permission_guide`
+- Call `system_status` to verify the full context surface is available

apple_system_mcp-1.0.1/README.md

@@ -0,0 +1,137 @@
+<!-- mcp-name: io.github.jonathanrreed/apple-system-mcp -->
+
+# Apple System MCP
+
+Local MCP server for macOS system context, truthful Focus support metadata, assistant-relevant settings reads, explicit settings writes, and bounded GUI fallback automation.
+
+## Capabilities
+
+- battery status
+- frontmost app
+- running applications
+- clipboard read and write
+- local notifications
+- open an application
+- appearance settings
+- accessibility settings
+- Dock settings
+- Finder settings
+- truthful Focus support metadata
+- combined system context snapshots
+- appearance mode write
+- Finder visibility and bar writes
+- Dock write controls for autohide and recent apps
+- accessibility writes for reduce motion, increase contrast, and reduce transparency
+- GUI fallback tools for menu clicks, key presses, text entry, button clicks, and pop-up selection
+- preference-domain inspection via `defaults export`
+- resources: `system://status`, `system://applications`, `system://settings`, `system://context`
+- prompt: `system_capture_context`
+- tool discovery helpers `search_tools` and `get_tool_info` for context-constrained clients
+
+## 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-system-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 workspace environment with every server's entry point in `.venv/bin` (for example `.venv/bin/apple-system-mcp`). You can also point an MCP client at `AppleSystem-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+```json
+{
+  "mcpServers": {
+    "apple-system": {
+      "command": "uvx",
+      "args": ["apple-system-mcp"],
+      "env": {
+        "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage"
+      }
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/AppleSystem-MCP/start.sh` as the command with empty `args`.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --scope project apple-system -- uvx apple-system-mcp
+```
+
+## Transport
+
+`stdio` is the default and recommended transport. Set `APPLE_SYSTEM_MCP_TRANSPORT=streamable-http` (with optional `APPLE_SYSTEM_MCP_HOST` and `APPLE_SYSTEM_MCP_PORT`) to serve Streamable HTTP instead.
+
+## Prompting Notes
+
+- `tools/list` returns the full System tool surface. Context-constrained clients can use `search_tools` first, then `get_tool_info` for the System tool they need.
+- Use this server when the user’s current desktop context matters.
+- Read battery state and the frontmost app before interruptive actions.
+- Use the settings tools before falling back to raw `defaults read` in prompts or E2E checks.
+- Use `APPLE_SYSTEM_MCP_SAFETY_MODE=safe_manage` for assistant-grade operation.
+- Keep `safe_readonly` only for audit-only or context-only deployments.
+- Keep GUI fallback narrow. Prefer native app-domain MCPs first, then explicit System tools, then GUI tools only when native support is missing.
+- Focus reporting is best-effort and truthful. This server does not claim Notification Center history support when macOS does not expose it cleanly on an unsigned local install.
+
+## Health And Recovery
+
+- `system_health`
+- `system_permission_guide`
+- `system_get_settings_snapshot`
+- `system_get_focus_status`
+- `system_get_context_snapshot`
+- `system_read_preference_domain`
+
+## Assistant-Grade Control Surface
+
+The launch System write surface is explicit, not generic:
+
+- `system_set_appearance_mode`
+- `system_set_show_all_extensions`
+- `system_set_show_hidden_files`
+- `system_set_finder_path_bar`
+- `system_set_finder_status_bar`
+- `system_set_dock_autohide`
+- `system_set_dock_show_recents`
+- `system_set_reduce_motion`
+- `system_set_increase_contrast`
+- `system_set_reduce_transparency`
+
+The bounded GUI fallback surface is:
+
+- `system_gui_list_menu_bar_items`
+- `system_gui_click_menu_path`
+- `system_gui_press_keys`
+- `system_gui_type_text`
+- `system_gui_click_button`
+- `system_gui_choose_popup_value`
+
+## Launch Checklist
+
+- Add `uvx apple-system-mcp` (or a clone's `AppleSystem-MCP/start.sh`) to your MCP client
+- Reload or reconnect the client so the System tool surface is loaded into context
+- Call `system_health` first
+- If a scoped system action is blocked, call `system_permission_guide`
+- Call `system_status` to verify the full context surface is available

apple_system_mcp-1.0.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apple-system-mcp"
+version = "1.0.1"
+description = "Local Apple System MCP server for macOS"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["mcp", "model-context-protocol", "macos", "apple", "ai-agent", "automation"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: MacOS X",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "apple-mcp-common>=1.0.0,<2",
+  "mcp>=2.0.0,<3",
+  "pydantic>=2.12.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/JonathanRReed/Apple-MCPs"
+Repository = "https://github.com/JonathanRReed/Apple-MCPs"
+Changelog = "https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md"
+Issues = "https://github.com/JonathanRReed/Apple-MCPs/issues"
+
+[project.scripts]
+apple-system-mcp = "apple_system_mcp.tools:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<10",
+  "ruff>=0.12,<1",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.uv.sources]
+apple-mcp-common = { workspace = true }

apple_system_mcp-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

apple_system_mcp-1.0.1/src/apple_system_mcp/__init__.py

@@ -0,0 +1 @@
+"""Apple System MCP package."""

apple_system_mcp-1.0.1/src/apple_system_mcp/config.py

@@ -0,0 +1,36 @@
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+
+
+@dataclass(frozen=True)
+class Settings:
+    server_name: str
+    version: str
+    safety_mode: str
+    transport: str
+    host: str
+    port: int
+    log_level: str
+
+
+def _parse_int(value: str | None, default: int) -> int:
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        return default
+
+
+@lru_cache(maxsize=1)
+def load_settings() -> Settings:
+    return Settings(
+        server_name="Apple System MCP",
+        version="1.0.1",
+        safety_mode=os.environ.get("APPLE_SYSTEM_MCP_SAFETY_MODE", "safe_manage").strip().lower() or "safe_manage",
+        transport=os.environ.get("APPLE_SYSTEM_MCP_TRANSPORT", "stdio").strip().lower() or "stdio",
+        host=os.environ.get("APPLE_SYSTEM_MCP_HOST", "127.0.0.1"),
+        port=_parse_int(os.environ.get("APPLE_SYSTEM_MCP_PORT"), 8000),
+        log_level=os.environ.get("APPLE_SYSTEM_MCP_LOG_LEVEL", "INFO").strip().upper() or "INFO",
+    )

apple_system_mcp-1.0.1/src/apple_system_mcp/models.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ToolError(BaseModel):
+    error_code: str = Field(description="Stable machine-readable error code")
+    message: str = Field(description="Human-readable error message")
+    suggestion: str | None = Field(default=None, description="Suggested next step")
+
+
+class ErrorResponse(BaseModel):
+    ok: bool = False
+    error: ToolError
+
+
+class HealthResponse(BaseModel):
+    ok: bool = True
+    server_name: str
+    version: str
+    safety_mode: str
+    transport: str
+    capabilities: list[str]
+    supports: list[str]
+
+
+class BatteryStatus(BaseModel):
+    percentage: int | None = None
+    power_source: str | None = None
+    charging: bool | None = None
+    raw: str
+
+
+class AppRecord(BaseModel):
+    name: str
+    bundle_id: str | None = None
+    process_id: int | None = None
+
+
+class ClipboardResponse(BaseModel):
+    ok: bool = True
+    text: str
+
+
+class NotificationResponse(BaseModel):
+    ok: bool = True
+    delivered: bool
+    title: str
+
+
+class OpenAppResponse(BaseModel):
+    ok: bool = True
+    opened: bool
+    application: str
+    bundle_id: str | None = None
+
+
+class RunningAppsResponse(BaseModel):
+    ok: bool = True
+    apps: list[AppRecord]
+    count: int
+
+
+class StatusResponse(BaseModel):
+    ok: bool = True
+    battery: BatteryStatus | None = None
+    frontmost_app: str | None = None
+    frontmost_application: AppRecord | None = None
+    running_apps_count: int | None = None
+
+
+class SettingsDomainsResponse(BaseModel):
+    ok: bool = True
+    domains: list[dict[str, str]]
+    count: int
+
+
+class SettingsSectionResponse(BaseModel):
+    ok: bool = True
+    section: str
+    values: dict[str, object]
+
+
+class SettingsSnapshotResponse(BaseModel):
+    ok: bool = True
+    appearance: dict[str, object]
+    accessibility: dict[str, object]
+    dock: dict[str, object]
+    finder: dict[str, object]
+
+
+class FocusStatusResponse(BaseModel):
+    ok: bool = True
+    focus_supported: bool
+    focus_active: bool | None = None
+    focus_name: str | None = None
+    observed_at: str
+    source: str
+    confidence: float | None = None
+    notes: list[str] = Field(default_factory=list)
+
+
+class SystemContextResponse(BaseModel):
+    ok: bool = True
+    observed_at: str
+    battery: BatteryStatus | None = None
+    frontmost_app: str | None = None
+    frontmost_application: AppRecord | None = None
+    running_apps_count: int | None = None
+    focus: FocusStatusResponse
+    notification_history_supported: bool = False
+    notification_history_notes: list[str] = Field(default_factory=list)
+
+
+class PreferenceDomainResponse(BaseModel):
+    ok: bool = True
+    domain: str
+    current_host: bool = False
+    values: dict[str, object]
+
+
+class SettingMutationResponse(BaseModel):
+    ok: bool = True
+    section: str
+    setting: str
+    requested_value: bool | str
+    observed_value: bool | str | None = None
+    restarted_processes: list[str] = Field(default_factory=list)
+    used_gui_fallback: bool = False
+
+
+class GuiMenuItemsResponse(BaseModel):
+    ok: bool = True
+    application: str
+    bundle_id: str | None = None
+    process_id: int | None = None
+    menu_bar_items: list[str]
+    count: int
+    used_gui_fallback: bool = True
+
+
+class GuiActionResponse(BaseModel):
+    ok: bool = True
+    action: str
+    application: str | None = None
+    bundle_id: str | None = None
+    process_id: int | None = None
+    target: str | None = None
+    selector_type: str | None = None
+    value: bool | str | list[str] | None = None
+    used_gui_fallback: bool = True

apple_system_mcp-1.0.1/src/apple_system_mcp/permissions.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from apple_system_mcp.config import load_settings
+
+
+@dataclass(frozen=True)
+class SafetyError(Exception):
+    error_code: str
+    message: str
+    suggestion: str | None = None
+
+
+READ_ONLY_ACTIONS = {
+    "system_health",
+    "system_status",
+    "system_get_battery",
+    "system_get_frontmost_app",
+    "system_list_running_apps",
+    "system_get_clipboard",
+    "system_list_settings_domains",
+    "system_get_appearance_settings",
+    "system_get_accessibility_settings",
+    "system_get_dock_settings",
+    "system_get_finder_settings",
+    "system_get_settings_snapshot",
+    "system_get_focus_status",
+    "system_get_context_snapshot",
+    "system_read_preference_domain",
+}
+
+MANAGE_ACTIONS = {
+    "system_set_clipboard",
+    "system_show_notification",
+    "system_open_application",
+    "system_set_appearance_mode",
+    "system_set_show_all_extensions",
+    "system_set_show_hidden_files",
+    "system_set_finder_path_bar",
+    "system_set_finder_status_bar",
+    "system_set_dock_autohide",
+    "system_set_dock_show_recents",
+    "system_set_reduce_motion",
+    "system_set_increase_contrast",
+    "system_set_reduce_transparency",
+    "system_gui_list_menu_bar_items",
+    "system_gui_click_menu_path",
+    "system_gui_press_keys",
+    "system_gui_type_text",
+    "system_gui_click_button",
+    "system_gui_choose_popup_value",
+}
+
+
+def ensure_action_allowed(action: str) -> None:
+    safety_mode = load_settings().safety_mode
+    if action in READ_ONLY_ACTIONS:
+        return
+    if action in MANAGE_ACTIONS and safety_mode in {"safe_manage", "full_access"}:
+        return
+    raise SafetyError(
+        error_code="SAFETY_RESTRICTION",
+        message=f"{action} is not allowed while APPLE_SYSTEM_MCP_SAFETY_MODE={safety_mode}.",
+        suggestion="Use safe_manage or full_access for system mutation tools.",
+    )