How r-huijts/xcode-mcp-server works
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.