# cameroncooke/xcodebuildmcp architecture

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

- Interactive diagram: https://gitdiagram.com/cameroncooke/xcodebuildmcp
- Repository: https://github.com/cameroncooke/xcodebuildmcp

## Overview

MobileBuildMCP is a macOS developer-tool server and CLI for agents working on iOS and macOS projects. The main workflow is an agent or engineer invokes a CLI command or MCP tool, which runs project operations through Xcode and related executors and returns structured results. Its documented capabilities include builds and tests, simulator/device operations, UI automation, debugging, coverage, project discovery and scaffolding, Swift Package Manager, and Xcode IDE tool bridging. The graph combines documented capabilities with source-index relationships; several subsystem internals were not sampled.

Main entry points: [`src/server/server.ts`](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/server/server.ts) (MCP Server), [`src/runtime/tool-invoker.ts`](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/runtime/tool-invoker.ts) (Tool Invoker), [`src/mcp/tools/coverage`](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/coverage) (Coverage), [`src/utils/xcodebuild-pipeline.ts`](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/xcodebuild-pipeline.ts) (Xcodebuild Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry Points"]
  node_cli["CLI<br/>[cli.ts]"]
  node_mcp["MCP Server<br/>[server.ts]"]
end

subgraph group_runtime["Tool Runtime"]
  node_catalog["Tool Catalog<br/>[tool-catalog.ts]"]
  node_invoker["Tool Invoker<br/>[tool-invoker.ts]"]
  node_typed["Typed Tool Factory"]
  node_executor["Command and File Executors<br/>[command.ts]"]
end

subgraph group_project["Project Operations"]
  node_build["Build and Test"]
  node_device["Device and Simulator"]
  node_ui["UI Automation"]
  node_debug["Debugging"]
  node_coverage["Coverage"]
  node_discovery["Discovery and Scaffolding"]
  node_swiftpm["Swift Package Tools"]
  node_xcodebuild["Xcodebuild Pipeline"]
end

subgraph group_state["State and Integrations"]
  node_config[("Configuration Store<br/>[config-store.ts]")]
  node_session[("Session Defaults Store<br/>[session-store.ts]")]
  node_bridge["Xcode Tools Bridge<br/>[manager.ts]"]
end

subgraph group_results["Results and Support"]
  node_domain["Domain Results and Fragments<br/>[domain-results.ts]"]
  node_render["Rendering<br/>[render.ts]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.ts]"]
  node_logger["Logging<br/>[logger.ts]"]
end

node_engineer(("Engineer or Agent"))
node_xcode["Xcode Toolchain"]

node_engineer -->|"runs commands"| node_cli
node_engineer -->|"sends requests"| node_mcp
node_cli -.->|"lists tools"| node_catalog
node_mcp -->|"exposes tools"| node_catalog
node_catalog -.->|"dispatches calls"| node_invoker
node_invoker -.->|"invokes handlers"| node_typed
node_typed -->|"reads defaults"| node_session
node_mcp -->|"offers build tools"| node_build
node_mcp -->|"offers device tools"| node_device
node_mcp -->|"offers automation"| node_ui
node_mcp -->|"offers debugging"| node_debug
node_mcp -->|"offers coverage"| node_coverage
node_mcp -->|"offers project tools"| node_discovery
node_mcp -->|"offers package tools"| node_swiftpm
node_build -.->|"runs builds"| node_xcodebuild
node_coverage -->|"executes commands"| node_executor
node_xcodebuild -.->|"runs operations"| node_xcode
node_xcodebuild -->|"emits fragments"| node_domain
node_invoker -.->|"returns results"| node_domain
node_domain -->|"renders output"| node_render
node_coverage -->|"creates diagnostics"| node_diagnostics
node_bridge -.->|"proxies tools"| node_xcode
node_bridge -->|"logs failures"| node_logger
node_config -->|"uses defaults"| node_session

click node_cli "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/cli.ts"
click node_mcp "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/server/server.ts"
click node_catalog "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/runtime/tool-catalog.ts"
click node_invoker "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/runtime/tool-invoker.ts"
click node_typed "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/typed-tool-factory.ts"
click node_build "https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools"
click node_device "https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools"
click node_ui "https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/ui-automation"
click node_debug "https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/debugging"
click node_coverage "https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/coverage"
click node_discovery "https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools"
click node_swiftpm "https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/swift-package"
click node_xcodebuild "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/xcodebuild-pipeline.ts"
click node_executor "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/command.ts"
click node_config "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/config-store.ts"
click node_session "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/session-store.ts"
click node_bridge "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/integrations/xcode-tools-bridge/manager.ts"
click node_domain "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/types/domain-results.ts"
click node_render "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/rendering/render.ts"
click node_diagnostics "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/diagnostics.ts"
click node_logger "https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/logger.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_cli,node_mcp toneBlue
class node_catalog,node_invoker,node_typed,node_executor toneAmber
class node_build,node_device,node_ui,node_debug,node_coverage,node_discovery,node_swiftpm,node_xcodebuild toneMint
class node_config,node_session,node_bridge toneRose
class node_domain,node_render,node_diagnostics,node_logger,node_engineer,node_xcode toneIndigo
```

## Components

### User Entry Points

- [CLI](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/cli.ts): `src/cli.ts`
- [MCP Server](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/server/server.ts): `src/server/server.ts`

### Tool Runtime

- [Tool Catalog](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/runtime/tool-catalog.ts): `src/runtime/tool-catalog.ts`
- [Tool Invoker](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/runtime/tool-invoker.ts): `src/runtime/tool-invoker.ts`
- [Typed Tool Factory](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/typed-tool-factory.ts): `src/utils/typed-tool-factory.ts`
- [Command and File Executors](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/command.ts): `src/utils/command.ts`

### Project Operations

- [Build and Test](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools): `src/mcp/tools`
- [Device and Simulator](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools): `src/mcp/tools`
- [UI Automation](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/ui-automation): `src/mcp/tools/ui-automation`
- [Debugging](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/debugging): `src/mcp/tools/debugging`
- [Coverage](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/coverage): `src/mcp/tools/coverage`
- [Discovery and Scaffolding](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools): `src/mcp/tools`
- [Swift Package Tools](https://github.com/cameroncooke/xcodebuildmcp/tree/main/src/mcp/tools/swift-package): `src/mcp/tools/swift-package`
- [Xcodebuild Pipeline](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/xcodebuild-pipeline.ts): `src/utils/xcodebuild-pipeline.ts`

### State and Integrations

- [Configuration Store](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/config-store.ts): `src/utils/config-store.ts`
- [Session Defaults Store](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/session-store.ts): `src/utils/session-store.ts`
- [Xcode Tools Bridge](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/integrations/xcode-tools-bridge/manager.ts): `src/integrations/xcode-tools-bridge/manager.ts`

### Results and Support

- [Domain Results and Fragments](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/types/domain-results.ts): `src/types/domain-results.ts`
- [Rendering](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/rendering/render.ts): `src/rendering/render.ts`
- [Diagnostics](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/diagnostics.ts): `src/utils/diagnostics.ts`
- [Logging](https://github.com/cameroncooke/xcodebuildmcp/blob/main/src/utils/logger.ts): `src/utils/logger.ts`

### Other components

- **Engineer or Agent**
- **Xcode Toolchain**

## Connections

- Engineer or Agent → CLI: runs commands (evidence: `README.md`)
- Engineer or Agent → MCP Server: sends requests (evidence: `README.md`)
- CLI → Tool Catalog: lists tools
- MCP Server → Tool Catalog: exposes tools (evidence: `README.md`)
- Tool Catalog → Tool Invoker: dispatches calls
- Tool Invoker → Typed Tool Factory: invokes handlers
- Typed Tool Factory → Session Defaults Store: reads defaults (evidence: `src/utils/typed-tool-factory.ts`)
- MCP Server → Build and Test: offers build tools (evidence: `README.md`)
- MCP Server → Device and Simulator: offers device tools (evidence: `README.md`)
- MCP Server → UI Automation: offers automation (evidence: `README.md`)
- MCP Server → Debugging: offers debugging (evidence: `README.md`)
- MCP Server → Coverage: offers coverage (evidence: `README.md`)
- MCP Server → Discovery and Scaffolding: offers project tools (evidence: `README.md`)
- MCP Server → Swift Package Tools: offers package tools (evidence: `README.md`)
- Build and Test → Xcodebuild Pipeline: runs builds
- Coverage → Command and File Executors: executes commands (evidence: `src/mcp/tools/coverage/get_file_coverage.ts`)
- Xcodebuild Pipeline → Xcode Toolchain: runs operations
- Xcodebuild Pipeline → Domain Results and Fragments: emits fragments (evidence: `src/utils/xcodebuild-pipeline.ts`)
- Tool Invoker → Domain Results and Fragments: returns results
- Domain Results and Fragments → Rendering: renders output
- Coverage → Diagnostics: creates diagnostics (evidence: `src/mcp/tools/coverage/get_file_coverage.ts`)
- Xcode Tools Bridge → Xcode Toolchain: proxies tools
- Xcode Tools Bridge → Logging: logs failures (evidence: `src/integrations/xcode-tools-bridge/manager.ts`)
- Configuration Store → Session Defaults Store: uses defaults (evidence: `src/utils/config-store.ts`)
