xcode-build-mcp

jontolof/xcode-build-mcp

3.2

If you are the rightful owner of xcode-build-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Xcode Build Server MCP is a highly optimized server designed to streamline Xcode operations, significantly reducing token usage while maintaining full functionality for iOS/macOS development workflows.

Tools
14
Resources
0
Prompts
0

Xcode Build Server MCP

A highly optimized Model Context Protocol (MCP) server for Xcode operations that reduces token usage by 83% while maintaining full functionality for iOS/macOS development workflows.

๐ŸŽฏ Key Features

  • 83% Token Reduction: From ~47,000 to ~8,000 tokens (14 tools vs 83)
  • 90%+ Output Filtering: Intelligent filtering of verbose xcodebuild output
  • Smart Auto-Detection: Automatically detects project types and selects appropriate simulators
  • Unified Interface: Single tools for multiple scenarios instead of variant proliferation
  • Zero Dependencies: Built with Go standard library for maximum reliability
  • Real-time Streaming: Progressive output for long-running operations
  • Intelligent Caching: LRU cache for frequently accessed project data

๐Ÿ“Š Why This Project?

Popular xcode-build MCP implementation suffers from severe tool proliferation:

  • 83 redundant tools consuming ~47,000 tokens
  • Separate tools for project vs workspace (2x duplication)
  • Separate tools for simulator name vs ID (2x duplication)
  • Separate tools for each platform (4x multiplication)
  • Most developers use <10% of available tools

Our solution consolidates everything into 14 essential tools that cover 100% of common workflows.

๐Ÿš€ Quick Start

Prerequisites

  • Go 1.21 or higher
  • Xcode 14.0 or higher
  • macOS 12.0 or higher

Installation

# Clone the repository
git clone https://github.com/jontolof/xcode-build-mcp.git
cd xcode-build-mcp

# Build the server
go build -o xcode-build-mcp cmd/server/main.go

# Install to PATH (optional)
sudo cp xcode-build-mcp /usr/local/bin/

Basic Usage

# Run the MCP server
xcode-build-mcp

# Run with debug logging
MCP_LOG_LEVEL=debug xcode-build-mcp

# Run with custom output filtering
MCP_OUTPUT_MODE=minimal xcode-build-mcp

Integration with MCP Clients

Add to your MCP client configuration:

{
  "mcpServers": {
    "xcode-build": {
      "command": "xcode-build-mcp",
      "args": ["stdio"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "MCP_OUTPUT_MODE": "standard"
      }
    }
  }
}

๐Ÿ› ๏ธ The 14 Essential Tools

Build & Test Tools

1. xcode_build

Universal build command that auto-detects project type and simulator.

{
  "tool": "xcode_build",
  "parameters": {
    "path": "MyApp.xcodeproj",
    "scheme": "MyApp",
    "configuration": "Debug"
  }
}
2. xcode_test

Universal test execution with parsed results.

{
  "tool": "xcode_test",
  "parameters": {
    "path": "MyApp.xcodeproj",
    "scheme": "MyAppTests",
    "filter": "testLogin*"
  }
}
3. xcode_clean

Clean build artifacts and derived data.

{
  "tool": "xcode_clean",
  "parameters": {
    "path": "MyApp.xcodeproj",
    "derivedData": true
  }
}

Discovery Tools

4. discover_projects

Find all Xcode projects in directory tree.

{
  "tool": "discover_projects",
  "parameters": {
    "root": ".",
    "maxDepth": 3
  }
}
5. list_schemes

List available build schemes.

{
  "tool": "list_schemes",
  "parameters": {
    "path": "MyApp.xcodeproj"
  }
}
6. list_simulators

List available iOS/macOS simulators.

{
  "tool": "list_simulators",
  "parameters": {
    "platform": "iOS",
    "available": true
  }
}

Runtime Tools

7. simulator_control

Boot, shutdown, or reset simulators.

{
  "tool": "simulator_control",
  "parameters": {
    "action": "boot",
    "identifier": "iPhone 15 Pro"
  }
}
8. install_app

Install apps to simulators or devices.

{
  "tool": "install_app",
  "parameters": {
    "appPath": "build/MyApp.app",
    "destination": "iPhone 15 Pro"
  }
}
9. launch_app

Launch installed apps with optional arguments.

{
  "tool": "launch_app",
  "parameters": {
    "bundleId": "com.example.myapp",
    "destination": "iPhone 15 Pro",
    "arguments": ["--debug", "--mock-data"]
  }
}

Debug Tools

10. capture_logs

Capture and filter device/simulator logs.

{
  "tool": "capture_logs",
  "parameters": {
    "action": "start",
    "destination": "iPhone 15 Pro",
    "filter": "MyApp"
  }
}
11. screenshot

Capture simulator screenshots.

{
  "tool": "screenshot",
  "parameters": {
    "destination": "iPhone 15 Pro",
    "outputPath": "screenshots/login.png"
  }
}
12. describe_ui

Get UI element hierarchy for testing.

{
  "tool": "describe_ui",
  "parameters": {
    "destination": "iPhone 15 Pro",
    "format": "tree"
  }
}

Automation Tools

13. ui_interact

Perform UI interactions (tap, swipe, type).

{
  "tool": "ui_interact",
  "parameters": {
    "destination": "iPhone 15 Pro",
    "action": "tap",
    "parameters": {
      "x": 100,
      "y": 200
    }
  }
}
14. get_app_info

Extract app metadata and information.

{
  "tool": "get_app_info",
  "parameters": {
    "appPath": "build/MyApp.app",
    "info": "all"
  }
}

๐Ÿ“ˆ Performance

Token Usage Comparison

MetricCurrent ImplementationOur ImplementationImprovement
Tool Count83 tools14 tools83% reduction
Token Usage~47,000~8,00083% reduction
Output Verbosity100%<10%90%+ filtering
Response TimeVariable<100ms (cached)Consistent

Output Filtering Example

Before (Raw xcodebuild output):

CompileSwift normal x86_64 /Users/dev/MyApp/Sources/ViewControllers/LoginViewController.swift (in target 'MyApp' from project 'MyApp')
    cd /Users/dev/MyApp
    /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift -frontend -c -primary-file...
[500+ more lines of compilation details]

After (Filtered output):

Building MyApp (Debug)...
โœ“ Compiled LoginViewController.swift
โœ“ Compiled AppDelegate.swift
โœ“ Linking MyApp.app
Build succeeded in 12.3s
Output: build/Debug-iphonesimulator/MyApp.app

๐Ÿ”ง Configuration

Environment Variables

VariableDefaultDescription
MCP_LOG_LEVELinfoLogging level: debug, info, warn, error
MCP_OUTPUT_MODEstandardOutput verbosity: minimal, standard, verbose
MCP_CACHE_TTL300Cache TTL in seconds
MCP_TIMEOUT300Command timeout in seconds
XCODE_PATHAuto-detectPath to Xcode.app

Configuration File

Create ~/.xcode-build-mcp/config.json:

{
  "outputMode": "standard",
  "caching": {
    "enabled": true,
    "ttl": 300
  },
  "filtering": {
    "rules": "default",
    "customPatterns": []
  }
}

๐Ÿงช Development

Building from Source

# Clone repository
git clone https://github.com/[username]/xcode-build-mcp.git
cd xcode-build-mcp

# Install dependencies (minimal)
go mod download

# Build
go build -o xcode-build-mcp cmd/server/main.go

# Run tests
go test ./...

# Run with race detection
go test -race ./...

# Generate coverage report
go test -cover ./...

Project Structure

xcode-build-mcp/
โ”œโ”€โ”€ cmd/server/          # Server entry point
โ”œโ”€โ”€ internal/
โ”‚   โ”œโ”€โ”€ mcp/            # MCP protocol implementation
โ”‚   โ”œโ”€โ”€ xcode/          # Xcode integration
โ”‚   โ”œโ”€โ”€ filter/         # Output filtering
โ”‚   โ”œโ”€โ”€ cache/          # Caching system
โ”‚   โ””โ”€โ”€ tools/          # Tool implementations
โ”œโ”€โ”€ pkg/types/          # Shared types
โ”œโ”€โ”€ tests/              # Test suites
โ””โ”€โ”€ docs/               # Documentation

Testing

# Run all tests
make test

# Run integration tests
make test-integration

# Run benchmarks
make bench

# Check coverage
make coverage

๐Ÿ“š Documentation

  • - Detailed design rationale
  • - Implementation roadmap and milestones
  • - Complete tool API documentation

๐Ÿ“Š Benchmarks

# Token usage benchmark
Original implementation: 46,950 tokens
Optimized implementation: 7,910 tokens
Reduction: 83.15%

# Output filtering benchmark
Input: 10,000 lines of xcodebuild output
Filtered output: 847 lines
Reduction: 91.53%
Processing time: 8.2ms

# Response time (cached operations)
discover_projects: 12ms
list_schemes: 8ms
list_simulators: 23ms
xcode_build (cached): 94ms

๐Ÿ”’ Security

  • No sensitive data is logged or cached
  • All user paths are validated
  • Command injection protection
  • Secure handling of build artifacts

๐Ÿ“ License

This project is licensed under the MIT License - see the file for details.

๐Ÿ™ Acknowledgments

  • Inspired by the need for efficient MCP servers
  • Built for the iOS/macOS development community
  • Optimized for AI-assisted development workflows

๐Ÿ“ž Support

๐Ÿšฆ Project Status

Current Phase: Production Ready โœ…

  • Design specification
  • Implementation plan
  • Core MCP server
  • Tool implementation (14 essential tools)
  • Testing & optimization
  • Output filtering (90%+ reduction)
  • Production release

Built with โค๏ธ for the iOS/macOS development community