# r-huijts/xcode-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/r-huijts/xcode-mcp-server
- Repository: https://github.com/r-huijts/xcode-mcp-server

## Overview

##### Project type and purpose
- This is a backend server application built in Node.js/TypeScript.
- It implements the Model Context Protocol (MCP) to expose Xcode‑related tools over HTTP to AI assistants (e.g., Claude Desktop).
- Its goal is to provide a secure, modular, and extensible API for managing Xcode projects, simulators, builds, CocoaPods, SPM, and general file operations.

##### File structure
- Top‑level files
- package.json, tsconfig.json, .env.example, setup.sh: configuration, build, and installation scripts
- src/index.ts: application entry point
- src/server.ts: MCP server bootstrap and HTTP listener
- src/tools (module boundary)
- build/, cocoapods/, file/, project/, simulator/, spm/, xcode/: each folder exports a set of handlers for a tool group
- index.ts inside each category registers tools with the central registry
- src/utils
- error handling, file and path management, project directory state, safe file operations
- src/types
- shared data models and Zod schemas for request validation
- test/
- unit tests (e.g., project-path-test.ts)
- docs/ & assets/
- user guides, tool overviews, workflows, and test plans

##### README for additional insights
- Lists high‑level features (project mgmt, file ops, build/test, CocoaPods, SPM, simulators, Xcode utilities)
- Describes setup script steps, environment variables, and integration with Claude Desktop
- Outlines the “Core Components” and “Request Flow” in prose
- Emphasizes security: path validation, Zod schemas, process management

A. External Actors
- AI Assistant / Claude Desktop client
- Developer (via CLI or HTTP tool)
B. HTTP/MCP Layer
- HTTP Server (Express or built‑in)
- MCP Request Dispatcher & Tool Registry
C. Tool Modules (grouped by category)
- Project Management
- File Operations
- Build & Testing
- CocoaPods Integration
- Swift Package Manager
- iOS Simulator
- Xcode Utilities
D. Shared Services / Utilities
- Path Management & Validation
- File System Abstraction & Safe Operations
- Project Directory State Management
- Error Handling & Logging
- Zod Schema Validation (Types)
E. External Dependencies
- Xcode Command‑Line Tools (xcodebuild, xcrun)
- CocoaPods (pod CLI)
- Swift Package Manager (swift CLI)
- iOS Simulator Control (simctl)
- File System & OS Shell

##### Relationships and interactions
- Client → HTTP/MCP Layer: JSON‑RPC or REST calls
- HTTP/MCP Layer → Tool Registry: look up handler by tool name
- Selected Tool Module → Utilities: validate inputs (Zod), manage paths, handle errors
- Tool Module → External Dependencies: spawn processes (xcodebuild, pod, swift, simctl), read/write files
- Tool Module → Shared State: update/consult projectDirectoryState for context
- Results flow back up: External Dependency output → Tool Module adapts → MCP Layer serializes → Client

##### Architectural patterns and principles
- Modular architecture: each tool category is a pluggable module registered at startup
- Layered design: Presentation (HTTP), Application (MCP dispatcher), Domain (tools), Infrastructure (utils, OS)
- Single Responsibility: utils folder isolates cross‑cutting concerns (errors, file, path)
- Secure and robust: path validation, parameter validation via Zod, safe file operations
- Plugin/Registry pattern: new tools added by registering in src/tools/*/index.ts
- CI/CD readiness: tests in test/, setup.sh for automation, .env for configuration

- Project, File, Build, CocoaPods, SPM, Simulator, Xcode Utilities
- xcodebuild / xcrun
- simctl
- pod CLI
- swift CLI
- File System
g. At the bottom or top, show “.env / setup.sh” feeding into the MCP Server as configuration injection.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    AI_Assistant["AI Assistant / CLI"]:::actor

    %% Configuration Bootstrap
    Config[".env / setup.sh"]:::config

    %% HTTP/MCP Layer
    subgraph "HTTP / MCP Layer"
        direction TB
        HTTP_Server["HTTP/MCP Server"]:::layer
        Dispatcher["Request Dispatcher"]:::layer
        Registry["Tool Registry"]:::layer
    end

    %% Tool Modules
    subgraph "Tool Modules"
        direction TB
        ProjectTool["Project Management Module"]:::tools
        FileTool["File Operations Module"]:::tools
        BuildTool["Build & Testing Module"]:::tools
        CocoaPodsTool["CocoaPods Integration Module"]:::tools
        SPMTool["Swift Package Manager Module"]:::tools
        SimulatorTool["iOS Simulator Module"]:::tools
        XcodeUtils["Xcode Utilities Module"]:::tools
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        direction TB
        PathMgr["Path Management & Validation"]:::utils
        FileSysAbst["File System Abstraction"]:::utils
        SafeFS["Safe File Operations"]:::utils
        DirState["Project Directory State"]:::utils
        ErrorHandler["Error Handling & Logging"]:::utils
        ZodValidation["Zod Schema Validation"]:::utils
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        XcodeCLI["xcodebuild / xcrun"]:::external
        Simctl["simctl"]:::external
        PodCLI["pod CLI"]:::external
        SwiftCLI["swift CLI"]:::external
        FileSystem["OS File System"]:::external
    end

    %% Connections
    AI_Assistant -->|calls HTTP API| HTTP_Server
    Config --> HTTP_Server
    HTTP_Server --> Dispatcher
    Dispatcher --> Registry

    Registry --> ProjectTool
    Registry --> FileTool
    Registry --> BuildTool
    Registry --> CocoaPodsTool
    Registry --> SPMTool
    Registry --> SimulatorTool
    Registry --> XcodeUtils

    %% Tools to Utilities
    ProjectTool --> PathMgr
    ProjectTool --> FileSysAbst
    ProjectTool --> SafeFS
    ProjectTool --> DirState
    ProjectTool --> ErrorHandler
    ProjectTool --> ZodValidation

    FileTool --> PathMgr
    FileTool --> FileSysAbst
    FileTool --> SafeFS
    FileTool --> DirState
    FileTool --> ErrorHandler
    FileTool --> ZodValidation

    BuildTool --> PathMgr
    BuildTool --> FileSysAbst
    BuildTool --> SafeFS
    BuildTool --> DirState
    BuildTool --> ErrorHandler
    BuildTool --> ZodValidation

    CocoaPodsTool --> PathMgr
    CocoaPodsTool --> FileSysAbst
    CocoaPodsTool --> SafeFS
    CocoaPodsTool --> DirState
    CocoaPodsTool --> ErrorHandler
    CocoaPodsTool --> ZodValidation

    SPMTool --> PathMgr
    SPMTool --> FileSysAbst
    SPMTool --> SafeFS
    SPMTool --> DirState
    SPMTool --> ErrorHandler
    SPMTool --> ZodValidation

    SimulatorTool --> PathMgr
    SimulatorTool --> FileSysAbst
    SimulatorTool --> SafeFS
    SimulatorTool --> DirState
    SimulatorTool --> ErrorHandler
    SimulatorTool --> ZodValidation

    XcodeUtils --> PathMgr
    XcodeUtils --> FileSysAbst
    XcodeUtils --> SafeFS
    XcodeUtils --> DirState
    XcodeUtils --> ErrorHandler
    XcodeUtils --> ZodValidation

    %% Tools to External Dependencies
    ProjectTool --> XcodeCLI
    BuildTool --> XcodeCLI
    CocoaPodsTool --> PodCLI
    SPMTool --> SwiftCLI
    SimulatorTool --> Simctl
    FileTool --> FileSystem
    XcodeUtils --> XcodeCLI

    %% Click Events
    click HTTP_Server "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/index.ts"
    click HTTP_Server "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/server.ts"
    click ProjectTool "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/tools/project/index.ts"
    click FileTool "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/tools/file/index.ts"
    click BuildTool "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/tools/build/index.ts"
    click CocoaPodsTool "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/tools/cocoapods/index.ts"
    click SPMTool "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/tools/spm/index.ts"
    click SimulatorTool "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/tools/simulator/index.ts"
    click XcodeUtils "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/tools/xcode/index.ts"
    click PathMgr "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/utils/pathManager.ts"
    click FileSysAbst "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/utils/file.ts"
    click SafeFS "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/utils/safeFileOperations.ts"
    click DirState "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/utils/projectDirectoryState.ts"
    click ErrorHandler "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/utils/errors.ts"
    click ZodValidation "https://github.com/r-huijts/xcode-mcp-server/blob/master/src/types/index.ts"
    click Config "https://github.com/r-huijts/xcode-mcp-server/blob/master/.env.example"
    click Config "https://github.com/r-huijts/xcode-mcp-server/blob/master/setup.sh"

    %% Styles
    classDef actor fill:#D6E9FE,stroke:#4990E2,color:#000
    classDef config fill:#FDF2D6,stroke:#E2A749,color:#000
    classDef layer fill:#E8F6EF,stroke:#35A37D,color:#000
    classDef tools fill:#F0F0F0,stroke:#888888,color:#000
    classDef utils fill:#FFF5F5,stroke:#E25353,color:#000
    classDef external fill:#F5F5FF,stroke:#6E6EB4,color:#000
```
