# mattt/imcp architecture

> Architecture diagram of the GitHub repository mattt/imcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mattt/imcp
- Repository: https://github.com/mattt/imcp

## Overview

iMCP exposes personal-data and device capabilities as MCP tools through a macOS menu-bar app. An MCP client launches the bundled stdio server; it discovers the app over Bonjour and proxies the client connection to the app’s MCP server. The app requests approval, dispatches enabled tool calls to service implementations, and returns results to the client. Users enable services and tools in the app, which also supports configuring Claude Desktop. Service capabilities are taken from the README; unsampled service implementations are represented by their listed source paths, without inferring their internal API wiring.

Main entry points: [`App/Models/Service.swift`](https://github.com/mattt/imcp/blob/main/App/Models/Service.swift) (Service tools), [`App/Controllers/ServerController.swift`](https://github.com/mattt/imcp/blob/main/App/Controllers/ServerController.swift) (Server controller), [`CLI/MCPService.swift`](https://github.com/mattt/imcp/blob/main/CLI/MCPService.swift) (MCP service), [`CLI/StdioProxy.swift`](https://github.com/mattt/imcp/blob/main/CLI/StdioProxy.swift) (Stdio proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_bridge["Client bridge"]
  node_server_entry["Server entry<br/>[main.swift]"]
  node_mcp_service["MCP service<br/>[MCPService.swift]"]
  node_bonjour_discovery["Bonjour discovery"]
  node_stdio_proxy["Stdio proxy<br/>[StdioProxy.swift]"]
end

subgraph group_app_server["App server"]
  node_server_controller["Server controller"]
  node_mcp_server["MCP server"]
  node_service_protocol["Service tools<br/>[Service.swift]"]
  node_tool_model["Tool model<br/>[Tool.swift]"]
  node_value_model["Tool values<br/>[Value.swift]"]
end

subgraph group_personal_services["Personal services"]
  node_calendar["Calendar events<br/>[Calendar.swift]"]
  node_contacts["Contacts<br/>[Contacts.swift]"]
  node_location["Location<br/>[Location.swift]"]
  node_maps["Maps and routes<br/>[Maps.swift]"]
  node_messages["Messages<br/>[Messages.swift]"]
  node_phone["Call history<br/>[Phone.swift]"]
  node_reminders["Reminders<br/>[Reminders.swift]"]
  node_shortcuts["Shortcuts<br/>[Shortcuts.swift]"]
  node_utilities["Utilities<br/>[Utilities.swift]"]
  node_weather["Weather<br/>[Weather.swift]"]
  node_capture["Screen capture<br/>[Capture.swift]"]
end

subgraph group_app_controls["App controls"]
  node_app["iMCP app<br/>[App.swift]"]
  node_content_view["Menu controls<br/>[ContentView.swift]"]
  node_service_toggles["Service toggles"]
  node_settings["Service settings"]
  node_approval_view["Connection approval"]
  node_claude_config["Claude configuration"]
end

node_mcp_client(("MCP client"))
node_apple_frameworks["Apple services"]
node_claude_desktop["Claude Desktop"]

node_mcp_client -->|"launches stdio"| node_server_entry
node_server_entry -->|"runs"| node_mcp_service
node_mcp_service -->|"discovers app"| node_bonjour_discovery
node_mcp_service -->|"starts proxy"| node_stdio_proxy
node_stdio_proxy -->|"bridges stdio"| node_mcp_client
node_stdio_proxy -->|"forwards MCP"| node_mcp_server
node_app -->|"creates"| node_server_controller
node_server_controller -->|"manages"| node_mcp_server
node_mcp_server -->|"requests approval"| node_approval_view
node_content_view -->|"controls"| node_server_controller
node_service_toggles -->|"enables services"| node_server_controller
node_settings -->|"updates tools"| node_server_controller
node_server_controller -->|"dispatches tools"| node_service_protocol
node_service_protocol -->|"defines tools"| node_tool_model
node_mcp_server -->|"handles arguments"| node_value_model
node_service_protocol -->|"calls tools"| node_calendar
node_service_protocol -->|"calls tools"| node_contacts
node_service_protocol -->|"calls tools"| node_location
node_service_protocol -->|"calls tools"| node_maps
node_service_protocol -->|"calls tools"| node_messages
node_service_protocol -->|"calls tools"| node_phone
node_service_protocol -->|"calls tools"| node_reminders
node_service_protocol -->|"calls tools"| node_shortcuts
node_service_protocol -->|"calls tools"| node_utilities
node_service_protocol -->|"calls tools"| node_weather
node_service_protocol -->|"calls tools"| node_capture
node_calendar -->|"uses system APIs"| node_apple_frameworks
node_claude_config -->|"updates config"| node_claude_desktop

click node_server_entry "https://github.com/mattt/imcp/blob/main/CLI/main.swift"
click node_mcp_service "https://github.com/mattt/imcp/blob/main/CLI/MCPService.swift"
click node_bonjour_discovery "https://github.com/mattt/imcp/blob/main/CLI/BonjourDiscovery.swift"
click node_stdio_proxy "https://github.com/mattt/imcp/blob/main/CLI/StdioProxy.swift"
click node_server_controller "https://github.com/mattt/imcp/blob/main/App/Controllers/ServerController.swift"
click node_mcp_server "https://github.com/mattt/imcp/blob/main/App/Controllers/ServerController.swift"
click node_service_protocol "https://github.com/mattt/imcp/blob/main/App/Models/Service.swift"
click node_tool_model "https://github.com/mattt/imcp/blob/main/App/Models/Tool.swift"
click node_value_model "https://github.com/mattt/imcp/blob/main/App/Models/Value.swift"
click node_calendar "https://github.com/mattt/imcp/blob/main/App/Services/Calendar.swift"
click node_contacts "https://github.com/mattt/imcp/blob/main/App/Services/Contacts.swift"
click node_location "https://github.com/mattt/imcp/blob/main/App/Services/Location.swift"
click node_maps "https://github.com/mattt/imcp/blob/main/App/Services/Maps.swift"
click node_messages "https://github.com/mattt/imcp/blob/main/App/Services/Messages.swift"
click node_phone "https://github.com/mattt/imcp/blob/main/App/Services/Phone.swift"
click node_reminders "https://github.com/mattt/imcp/blob/main/App/Services/Reminders.swift"
click node_shortcuts "https://github.com/mattt/imcp/blob/main/App/Services/Shortcuts.swift"
click node_utilities "https://github.com/mattt/imcp/blob/main/App/Services/Utilities.swift"
click node_weather "https://github.com/mattt/imcp/blob/main/App/Services/Weather.swift"
click node_capture "https://github.com/mattt/imcp/blob/main/App/Services/Capture.swift"
click node_app "https://github.com/mattt/imcp/blob/main/App/App.swift"
click node_content_view "https://github.com/mattt/imcp/blob/main/App/Views/ContentView.swift"
click node_service_toggles "https://github.com/mattt/imcp/blob/main/App/Views/ServiceToggleView.swift"
click node_settings "https://github.com/mattt/imcp/blob/main/App/Views/ServicesSettingsView.swift"
click node_approval_view "https://github.com/mattt/imcp/blob/main/App/Views/ConnectionApprovalView.swift"
click node_claude_config "https://github.com/mattt/imcp/blob/main/App/Integrations/ClaudeDesktop.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_mcp_service,node_bonjour_discovery,node_stdio_proxy,node_mcp_client toneBlue
class node_server_controller,node_mcp_server,node_service_protocol,node_tool_model,node_value_model toneAmber
class node_calendar,node_contacts,node_location,node_maps,node_messages,node_phone,node_reminders,node_shortcuts,node_utilities,node_weather,node_capture toneMint
class node_app,node_content_view,node_service_toggles,node_settings,node_approval_view,node_claude_config toneRose
class node_apple_frameworks,node_claude_desktop toneIndigo
```

## Components

### Client bridge

- [Server entry](https://github.com/mattt/imcp/blob/main/CLI/main.swift): `CLI/main.swift`
- [MCP service](https://github.com/mattt/imcp/blob/main/CLI/MCPService.swift): `CLI/MCPService.swift`
- [Bonjour discovery](https://github.com/mattt/imcp/blob/main/CLI/BonjourDiscovery.swift): `CLI/BonjourDiscovery.swift`
- [Stdio proxy](https://github.com/mattt/imcp/blob/main/CLI/StdioProxy.swift): `CLI/StdioProxy.swift`

### App server

- [Server controller](https://github.com/mattt/imcp/blob/main/App/Controllers/ServerController.swift): `App/Controllers/ServerController.swift`
- [MCP server](https://github.com/mattt/imcp/blob/main/App/Controllers/ServerController.swift): `App/Controllers/ServerController.swift`
- [Service tools](https://github.com/mattt/imcp/blob/main/App/Models/Service.swift): `App/Models/Service.swift`
- [Tool model](https://github.com/mattt/imcp/blob/main/App/Models/Tool.swift): `App/Models/Tool.swift`
- [Tool values](https://github.com/mattt/imcp/blob/main/App/Models/Value.swift): `App/Models/Value.swift`

### Personal services

- [Calendar events](https://github.com/mattt/imcp/blob/main/App/Services/Calendar.swift): `App/Services/Calendar.swift`
- [Contacts](https://github.com/mattt/imcp/blob/main/App/Services/Contacts.swift): `App/Services/Contacts.swift`
- [Location](https://github.com/mattt/imcp/blob/main/App/Services/Location.swift): `App/Services/Location.swift`
- [Maps and routes](https://github.com/mattt/imcp/blob/main/App/Services/Maps.swift): `App/Services/Maps.swift`
- [Messages](https://github.com/mattt/imcp/blob/main/App/Services/Messages.swift): `App/Services/Messages.swift`
- [Call history](https://github.com/mattt/imcp/blob/main/App/Services/Phone.swift): `App/Services/Phone.swift`
- [Reminders](https://github.com/mattt/imcp/blob/main/App/Services/Reminders.swift): `App/Services/Reminders.swift`
- [Shortcuts](https://github.com/mattt/imcp/blob/main/App/Services/Shortcuts.swift): `App/Services/Shortcuts.swift`
- [Utilities](https://github.com/mattt/imcp/blob/main/App/Services/Utilities.swift): `App/Services/Utilities.swift`
- [Weather](https://github.com/mattt/imcp/blob/main/App/Services/Weather.swift): `App/Services/Weather.swift`
- [Screen capture](https://github.com/mattt/imcp/blob/main/App/Services/Capture.swift): `App/Services/Capture.swift`

### App controls

- [iMCP app](https://github.com/mattt/imcp/blob/main/App/App.swift): `App/App.swift`
- [Menu controls](https://github.com/mattt/imcp/blob/main/App/Views/ContentView.swift): `App/Views/ContentView.swift`
- [Service toggles](https://github.com/mattt/imcp/blob/main/App/Views/ServiceToggleView.swift): `App/Views/ServiceToggleView.swift`
- [Service settings](https://github.com/mattt/imcp/blob/main/App/Views/ServicesSettingsView.swift): `App/Views/ServicesSettingsView.swift`
- [Connection approval](https://github.com/mattt/imcp/blob/main/App/Views/ConnectionApprovalView.swift): `App/Views/ConnectionApprovalView.swift`
- [Claude configuration](https://github.com/mattt/imcp/blob/main/App/Integrations/ClaudeDesktop.swift): `App/Integrations/ClaudeDesktop.swift`

### Other components

- **MCP client**
- **Apple services**
- **Claude Desktop**

## Connections

- MCP client → Server entry: launches stdio
- Server entry → MCP service: runs
- MCP service → Bonjour discovery: discovers app
- MCP service → Stdio proxy: starts proxy
- Stdio proxy → MCP client: bridges stdio
- Stdio proxy → MCP server: forwards MCP
- iMCP app → Server controller: creates
- Server controller → MCP server: manages
- MCP server → Connection approval: requests approval
- Menu controls → Server controller: controls
- Service toggles → Server controller: enables services
- Service settings → Server controller: updates tools
- Server controller → Service tools: dispatches tools
- Service tools → Tool model: defines tools
- MCP server → Tool values: handles arguments
- Service tools → Calendar events: calls tools
- Service tools → Contacts: calls tools
- Service tools → Location: calls tools
- Service tools → Maps and routes: calls tools
- Service tools → Messages: calls tools
- Service tools → Call history: calls tools
- Service tools → Reminders: calls tools
- Service tools → Shortcuts: calls tools
- Service tools → Utilities: calls tools
- Service tools → Weather: calls tools
- Service tools → Screen capture: calls tools
- Calendar events → Apple services: uses system APIs
- Claude configuration → Claude Desktop: updates config