# shaneholloman/mcp-apple-server architecture

> Architecture diagram of the GitHub repository shaneholloman/mcp-apple-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shaneholloman/mcp-apple-server
- Repository: https://github.com/shaneholloman/mcp-apple-server

## Overview

##### Main Components
- Entry Point: Represent the “index.ts” as the main entry to the system. This is where command processing likely begins.
- Command Handlers / Tool Coordinator: “tools.ts” appears to coordinate or provide common logic for invoking the specific utilities.
- External Interface: Since the tool works within the MCP protocol and integrates with local Apple applications (Messages, Calendar, Notes, etc.), include components to represent:
- The MCP protocol interface (which is also configured via the JSON snippet in the README).
- The external Apple apps themselves. You could denote these as “Apple Messages”, “Apple Mail”, “Apple Notes”, etc.
- Configuration / Build Tools: Mention that the project uses Bun (bun.lockb, CLI commands) and a typical TypeScript setup (tsconfig.json, package.json), which though not central to runtime, are important to deployment and local development.

##### Relationships & Data Flow
- That each utility module communicates with the corresponding Apple native service. For instance, “mail.ts” will call the Apple Mail API, “calendar.ts” makes calls to the Calendar app, etc.
- By linking MCP protocol configuration (as detailed by the JSON snippet) to the connection between Claude Desktop or cursor (installation commands) and the tool, emphasize that this project serves as an MCP server for Apple devices.

##### Architectural Patterns & Technologies
- Modularity: The segregation into different “utils” modules suggests a pattern where each utility is self-contained. Indicate modular design or separation of concerns with clear boundaries between features.
- Command Pattern: Since user commands are processed and routed to various functional modules, this hints at a command-dispatching pattern.
- Technology Stack: Mark TypeScript (index.ts, tsconfig.json), Bun runtime (bun.lockb, package.json scripts, bun commands), and the MCP protocol integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Command Processing Layer
    UC["User Command"]:::internal
    EP["Entry Point: index.ts"]:::internal
    CC["Command Coordinator: tools.ts"]:::internal

    UC -->|"starts"| EP
    EP -->|"dispatches to"| CC

    %% Utility Modules Container
    subgraph "Utility Modules"
        CAL["Calendar Module"]:::internal
        CON["Contacts Module"]:::internal
        MAIL["Mail Module"]:::internal
        MAPS["Maps Module"]:::internal
        MSG["Message Module"]:::internal
        NOTES["Notes Module"]:::internal
        REM["Reminders Module"]:::internal
        WS["WebSearch Module"]:::internal
    end

    %% Link from Command Coordinator to each Utility Module
    CC -->|"routes to"| CAL
    CC -->|"routes to"| CON
    CC -->|"routes to"| MAIL
    CC -->|"routes to"| MAPS
    CC -->|"routes to"| MSG
    CC -->|"routes to"| NOTES
    CC -->|"routes to"| REM
    CC -->|"routes to"| WS

    %% External Apple Applications
    subgraph "External Apple Applications"
        ACAL["Apple Calendar"]:::external
        ACON["Apple Contacts"]:::external
        AMAIL["Apple Mail"]:::external
        AMAPS["Apple Maps"]:::external
        AMSG["Apple Messages"]:::external
        ANOTES["Apple Notes"]:::external
        AREM["Apple Reminders"]:::external
        SEARCH["External Search API"]:::external
    end

    %% Connections from Utility Modules to External Services
    CAL -->|"calls"| ACAL
    CON -->|"calls"| ACON
    MAIL -->|"calls"| AMAIL
    MAPS -->|"calls"| AMAPS
    MSG -->|"calls"| AMSG
    NOTES -->|"calls"| ANOTES
    REM -->|"calls"| AREM
    WS  -->|"calls"| SEARCH

    %% Configuration & Build Tools
    subgraph "Configuration & Build Tools"
        JP["package.json"]:::configuration
        TS["tsconfig.json"]:::configuration
        BL["bun.lockb"]:::configuration
        RD["README.md"]:::configuration
    end

    %% Dashed arrow to represent configuration influence on the system entry point
    RD ---|"configures"| EP

    %% Click Events for Components
    click EP "https://github.com/shaneholloman/mcp-apple-server/blob/main/index.ts"
    click CC "https://github.com/shaneholloman/mcp-apple-server/blob/main/tools.ts"
    click CAL "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/calendar.ts"
    click CON "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/contacts.ts"
    click MAIL "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/mail.ts"
    click MAPS "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/maps.ts"
    click MSG "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/message.ts"
    click NOTES "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/notes.ts"
    click REM "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/reminders.ts"
    click WS "https://github.com/shaneholloman/mcp-apple-server/blob/main/utils/webSearch.ts"
    click JP "https://github.com/shaneholloman/mcp-apple-server/blob/main/package.json"
    click TS "https://github.com/shaneholloman/mcp-apple-server/blob/main/tsconfig.json"
    click BL "https://github.com/shaneholloman/mcp-apple-server/blob/main/bun.lockb"
    click RD "https://github.com/shaneholloman/mcp-apple-server/blob/main/README.md"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#1E5A8A,stroke-width:2px;
    classDef external fill:#FFE4B5,stroke:#A65A00,stroke-width:2px;
    classDef configuration fill:#E6F9E6,stroke:#2F8F2F,stroke-width:2px;
```
