# antondkg/mcp-imessage architecture

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

- Interactive diagram: https://gitdiagram.com/antondkg/mcp-imessage
- Repository: https://github.com/antondkg/mcp-imessage

## Overview

mcp-imessage is a macOS MCP server for browsing and searching local Messages history, looking up Contacts.app entries, and optionally sending or drafting messages. The main workflow runs from an MCP client through the Rust tool server to local data or Messages.app; draft results can open in the embedded React UI for review and approval. README capabilities fill in unsampled tool behavior. Source excerpts show selected calls and UI rendering, but not every route or UI handoff.

Main entry points: [`src/main.rs`](https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs) (MCP tool server), [`ui/src/main.tsx`](https://github.com/antondkg/mcp-imessage/blob/main/ui/src/main.tsx) (Embedded UI app), [`src/messages.rs`](https://github.com/antondkg/mcp-imessage/blob/main/src/messages.rs) (Thread and message queries), [`src/contacts.rs`](https://github.com/antondkg/mcp-imessage/blob/main/src/contacts.rs) (Contact lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_server["MCP tool server<br/>[main.rs]"]
  node_thread_tools["Thread tools<br/>[main.rs]"]
  node_search_tool["Message search tool<br/>[main.rs]"]
  node_contact_tools["Contact tools<br/>[main.rs]"]
end

subgraph group_data["Local data"]
  node_message_queries["Thread and message queries<br/>[messages.rs]"]
  node_message_db[("Messages database")]
  node_contact_lookup["Contact lookup<br/>[contacts.rs]"]
  node_contacts_app["Contacts.app"]
end

subgraph group_messaging["Send and draft"]
  node_send_tool["Send and draft tools<br/>[main.rs]"]
  node_send_logic["Send validation and delivery<br/>[send.rs]"]
  node_messages_app["Messages.app"]
end

subgraph group_ui["Embedded UI"]
  node_ui_app["Embedded UI app<br/>[main.tsx]"]
  node_ui_components["Conversation and contact views"]
  node_ui_catalog["Composable UI catalog<br/>[catalog.ts]"]
end

node_client(("MCP client"))

node_client -->|"calls tools"| node_server
node_server -->|"registers routes"| node_thread_tools
node_server -->|"registers routes"| node_search_tool
node_server -.->|"registers routes"| node_contact_tools
node_server -->|"registers routes"| node_send_tool
node_thread_tools -->|"calls queries"| node_message_queries
node_search_tool -->|"calls search"| node_message_queries
node_contact_tools -.->|"searches contacts"| node_contact_lookup
node_message_queries -->|"reads history"| node_message_db
node_message_queries -->|"resolves names"| node_contact_lookup
node_contact_lookup -.->|"looks up contacts"| node_contacts_app
node_send_tool -->|"validates requests"| node_send_logic
node_send_logic -->|"sends messages"| node_messages_app
node_send_tool -.->|"returns draft view"| node_ui_app
node_ui_app -.->|"receives tool results"| node_client
node_ui_app -->|"renders views"| node_ui_components
node_ui_app -->|"registers components"| node_ui_catalog
node_ui_components -.->|"requests draft approval send"| node_send_tool

click node_server "https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs"
click node_thread_tools "https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs"
click node_search_tool "https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs"
click node_contact_tools "https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs"
click node_message_queries "https://github.com/antondkg/mcp-imessage/blob/main/src/messages.rs"
click node_contact_lookup "https://github.com/antondkg/mcp-imessage/blob/main/src/contacts.rs"
click node_send_tool "https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs"
click node_send_logic "https://github.com/antondkg/mcp-imessage/blob/main/src/send.rs"
click node_ui_app "https://github.com/antondkg/mcp-imessage/blob/main/ui/src/main.tsx"
click node_ui_components "https://github.com/antondkg/mcp-imessage/blob/main/ui/src/imessage-components.tsx"
click node_ui_catalog "https://github.com/antondkg/mcp-imessage/blob/main/ui/src/catalog.ts"

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,node_thread_tools,node_search_tool,node_contact_tools,node_client toneBlue
class node_message_queries,node_message_db,node_contact_lookup,node_contacts_app toneAmber
class node_send_tool,node_send_logic,node_messages_app toneMint
class node_ui_app,node_ui_components,node_ui_catalog toneRose
```

## Components

### MCP server

- [MCP tool server](https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs): `src/main.rs`
- [Thread tools](https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs): `src/main.rs`
- [Message search tool](https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs): `src/main.rs`
- [Contact tools](https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs): `src/main.rs`

### Local data

- [Thread and message queries](https://github.com/antondkg/mcp-imessage/blob/main/src/messages.rs): `src/messages.rs`
- **Messages database**
- [Contact lookup](https://github.com/antondkg/mcp-imessage/blob/main/src/contacts.rs): `src/contacts.rs`
- **Contacts.app**

### Send and draft

- [Send and draft tools](https://github.com/antondkg/mcp-imessage/blob/main/src/main.rs): `src/main.rs`
- [Send validation and delivery](https://github.com/antondkg/mcp-imessage/blob/main/src/send.rs): `src/send.rs`
- **Messages.app**

### Embedded UI

- [Embedded UI app](https://github.com/antondkg/mcp-imessage/blob/main/ui/src/main.tsx): `ui/src/main.tsx`
- [Conversation and contact views](https://github.com/antondkg/mcp-imessage/blob/main/ui/src/imessage-components.tsx): `ui/src/imessage-components.tsx`
- [Composable UI catalog](https://github.com/antondkg/mcp-imessage/blob/main/ui/src/catalog.ts): `ui/src/catalog.ts`

### Other components

- **MCP client**

## Connections

- MCP client → MCP tool server: calls tools (evidence: `README.md`)
- MCP tool server → Thread tools: registers routes (evidence: `src/main.rs`)
- MCP tool server → Message search tool: registers routes (evidence: `src/main.rs`)
- MCP tool server → Contact tools: registers routes (evidence: `src/main.rs`)
- MCP tool server → Send and draft tools: registers routes (evidence: `src/main.rs`)
- Thread tools → Thread and message queries: calls queries (evidence: `src/main.rs`)
- Message search tool → Thread and message queries: calls search (evidence: `src/main.rs`)
- Contact tools → Contact lookup: searches contacts (evidence: `src/main.rs`)
- Thread and message queries → Messages database: reads history (evidence: `README.md`)
- Thread and message queries → Contact lookup: resolves names (evidence: `src/messages.rs`)
- Contact lookup → Contacts.app: looks up contacts
- Send and draft tools → Send validation and delivery: validates requests (evidence: `src/main.rs`)
- Send validation and delivery → Messages.app: sends messages (evidence: `README.md`)
- Send and draft tools → Embedded UI app: returns draft view
- Embedded UI app → MCP client: receives tool results
- Embedded UI app → Conversation and contact views: renders views (evidence: `ui/src/main.tsx`)
- Embedded UI app → Composable UI catalog: registers components (evidence: `ui/src/main.tsx`)
- Conversation and contact views → Send and draft tools: requests draft approval send
