Xcode MCP

🚀 Xcode MCP Server

A comprehensive Model Context Protocol (MCP) server for Xcode development automation. It offers over 115 tools for project management, building, testing, simulator control, crash reporting, asset management, localization, and AI - powered workflows.

🚀 Quick Start

Prerequisites

• macOS (for Xcode tools)
• Python 3.11+
• Conda (recommended) or pip
• Xcode Command Line Tools

Installation

# Clone the repository
git clone <repository-url>
cd xcode-mcp

# Create conda environment
conda env create -f environment.yml
conda activate xcode-mcp

# Or use pip
pip install -r requirements.txt

Cursor Configuration

Add the following to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "xcode-mcp": {
      "command": "/path/to/miniconda3/envs/xcode-mcp/bin/python",
      "args": [
        "/path/to/xcode-mcp/run_unified_mcp.py"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Cursor to load the MCP server.

✨ Features

• 112 Direct Xcode Tools: Fast, single - step operations for common tasks.
• 3 LangGraph Subagentic Tools: Multi - step workflows with reasoning and state management.
• 21 New Tools: Include crash reporting, asset management, localization, and simulator enhancements.
• Unified Server: A single MCP server that combines all capabilities.
• Token Optimized: Achieve a 30 - 40% token reduction through caching and compression.
• Hyper - Specific Schemas: Comprehensive JSON schemas with examples and validation.
• Persona System: Configurable agent personas for different use cases.

📦 Installation

Method 1: Automated Setup Script

./setup.sh

This script will:

• Create a conda environment.
• Install dependencies.
• Verify the installation.
• Test the server.

Method 2: Manual Installation

# Create conda environment
conda env create -f environment.yml
conda activate xcode-mcp

# Verify installation
python -c "from src.unified_mcp_server import UnifiedMCPServer; print('✅ Installation successful')"

Dependencies

Core dependencies:

• fastapi - HTTP server (optional)
• pydantic - Data validation
• langgraph - Subagentic workflows (optional)
• langchain - LLM integration (optional)

See environment.yml for the complete list.

⚙️ Configuration

Environment Variables

# LLM Provider API Keys
export DEEPSEEK_API_KEY="your-deepseek-key"
export OPENAI_API_KEY="your-openai-key"  # Optional

# Model Selection
export DEFAULT_MODEL="ollama:qwen3-coder:30b"  # or "deepseek:deepseek-coder"

MCP Configuration

The server is configured via ~/.cursor/mcp.json. Use absolute paths for reliability:

{
  "mcpServers": {
    "xcode-mcp": {
      "command": "/Users/username/miniconda3/envs/xcode-mcp/bin/python",
      "args": ["/Users/username/Projects/xcode-mcp/run_unified_mcp.py"],
      "env": {
        "DEEPSEEK_API_KEY": "your-key"
      }
    }
  }
}

💻 Usage Examples

Basic Usage

Direct Tools

Use direct tools for simple, single - step operations:

Use the list_projects tool
Use the build_project tool with scheme "MyApp"
Use the run_tests tool

LangGraph Subagentic Tools

Use LangGraph tools for complex, multi - step workflows:

Use langgraph_agent with prompt "Set up my development environment"
Use langgraph_workflow with workflow "Build, test, and generate report"

With Personas

Apply personas for specialized behavior:

{
  "name": "langgraph_agent",
  "arguments": {
    "prompt": "Help me optimize my build",
    "persona": {
      "id": "build-optimizer",
      "role": "optimizer"
    }
  }
}

Advanced Usage

More complex scenarios can be achieved by combining different tools and personas according to specific requirements.

📚 Documentation

🛠️ Tools Reference

Direct Tools (112 tools)

New in v2.1.0

• Crash Reporting (4 tools): symbolicate_crash_log, analyze_crash_log, get_crash_reports, export_crash_log
• Asset Management (5 tools): optimize_images, generate_app_icons, validate_asset_catalog, check_asset_sizes, manage_color_assets
• Simulator Enhancements (5 tools): set_simulator_location, get_simulator_logs, list_simulator_apps, simulate_network_conditions, clone_simulator
• Localization (4 tools): extract_strings, validate_localizations, check_localization_coverage, list_localizations
• Build Enhancements (3 tools): set_build_number, set_version, analyze_build_time

Original Tools (94 tools)

Project Management

• list_projects - List all Xcode projects
• create_project - Create a new Xcode project
• open_project - Open a project in Xcode
• list_schemes - List available build schemes
• switch_scheme - Change the active scheme

Building

• build_project - Build a project
• build_workspace - Build a workspace
• clean_build - Clean build artifacts
• archive_project - Create an archive
• analyze_build - Analyze build performance

Testing

• run_tests - Run unit tests
• run_ui_tests - Run UI tests
• generate_test_report - Generate a test report
• code_coverage_report - Get a coverage report

Simulator & Devices

• list_devices - List available simulators
• boot_simulator - Boot a simulator
• install_app - Install an app on a device
• launch_app - Launch an app

LLM Integration

• get_llm_status - Check LLM service status
• configure_llm - Configure the LLM provider

See schemas/xcode-mcp-tools.json for the complete list.

LangGraph Tools (3 tools)

langgraph_agent

A subagentic agent for complex workflows with reasoning and state management. Parameters:

• prompt (required) - Natural language task description
• model (optional) - Model override (e.g., "ollama:qwen3-coder:30b")
• persona (optional) - Persona configuration

Example:

Use langgraph_agent with prompt "Verify my development environment and list all projects"

langgraph_workflow

Execute multi - step workflows with automatic tool orchestration. Parameters:

• workflow (required) - Workflow description
• context (optional) - Additional context
• persona (optional) - Persona configuration

Example:

Use langgraph_workflow with workflow "1. Clean build 2. Build project 3. Run tests 4. Generate report"

langgraph_status

Get the status of the LangGraph agent and available capabilities.

🏗️ Architecture

Unified Server

The project uses a unified MCP server (src/unified_mcp_server.py) that combines:

• Direct Tools: 94 tools from src/xcode_tools/
• LangGraph Tools: 3 subagentic tools using LangGraph
• Optimization Layer: Caching, compression, and schema optimization

Project Structure

xcode-mcp/
├── src/
│   ├── unified_mcp_server.py    # Main unified server
│   ├── tool_registry.py          # Tool registration system
│   ├── langgraph_agent.py        # LangGraph agent implementation
│   ├── llm_service.py            # LLM provider abstraction
│   └── xcode_tools/              # Tool implementations
│       ├── project.py            # Project management
│       ├── build.py              # Build operations
│       ├── testing.py            # Testing tools
│       ├── simulator.py          # Simulator control
│       └── ...
├── schemas/
│   ├── xcode-mcp-tools.json      # Tool schema definitions
│   ├── persona_schemas.json      # Persona schema
│   └── persona_examples.json     # Pre-configured personas
├── tests/
│   └── test_unified_server.py    # Comprehensive test suite
├── docs/                         # Additional documentation
├── examples/                     # Usage examples
├── run_unified_mcp.py            # Server entry point
└── environment.yml               # Conda dependencies

Tool Registration

Tools are automatically registered from:

1. JSON schema (schemas/xcode-mcp-tools.json)
2. Python implementations (src/xcode_tools/)
3. Dynamic discovery and mapping

LangGraph Integration

LangGraph tools use the direct tools internally:

• The agent receives a natural language prompt.
• Breaks it down into steps.
• Calls the appropriate direct tools.
• Maintains state across steps.
• Returns a comprehensive result.

👤 Personas

Personas provide specialized agent behavior for different use cases.

Available Personas

• senior-ios-architect
  • Role: Architect
  • Expertise: Swift, Xcode, Architecture, iOS, Performance
  • Style: Professional, Detailed, Expert - level
  • Use for: Architecture decisions, best practices, design patterns
• swift-mentor
  • Role: Mentor
  • Expertise: Swift, Xcode, iOS, SwiftUI
  • Style: Friendly, Comprehensive, Intermediate - level
  • Use for: Learning, education, step - by - step guidance
• build-optimizer
  • Role: Optimizer
  • Expertise: Xcode, Performance, CI/CD
  • Style: Concise, Moderate, Advanced - level
  • Use for: Build performance, optimization, CI/CD
• test-specialist
  • Role: Tester
  • Expertise: Testing, Xcode, Swift, CI/CD
  • Style: Professional, Detailed, Advanced - level
  • Use for: Test strategies, coverage, quality

Using Personas

{
  "persona": {
    "id": "build-optimizer",
    "role": "optimizer",
    "expertise": ["xcode", "performance"],
    "communication_style": {
      "tone": "concise",
      "verbosity": "moderate",
      "technical_level": "advanced"
    }
  }
}

See schemas/persona_examples.json for complete examples.

🔧 Technical Details

Performance Optimizations

• Schema Caching: 5 - minute TTL
• Response Caching: Successful responses are cached
• Compact JSON: Reduced token usage
• Lazy Loading: LangGraph is loaded only when needed

Performance Metrics

• Token Reduction: 30 - 40% through optimization
• Memory Usage: 50% reduction (unified server)
• Response Time: 50% faster (cached responses)
• Schema Loading: 80% faster (cached)

🧪 Testing

Run Test Suite

# Comprehensive tests
python tests/test_unified_server.py

# Connection test
python test_mcp_connection.py

Expected Results

• ✅ 8/8 tests passing
• ✅ 97 tools available
• ✅ All protocols working
• ✅ Server responds correctly

🚀 Development

Adding New Tools

1. Add to Schema (schemas/xcode-mcp-tools.json):

{
  "name": "my_new_tool",
  "description": "Tool description",
  "parameters": [...]
}

2. Implement Function (src/xcode_tools/):

def my_new_tool(param1: str, param2: int) -> dict:
    # Implementation
    return {"result": "..."}

3. Test:

python -c "from src.tool_registry import get_registry; r = get_registry(); print(r.execute_tool('my_new_tool', param1='test', param2=1))"

Project Organization

• Core Server: src/unified_mcp_server.py
• Tool Registry: src/tool_registry.py
• Tool Implementations: src/xcode_tools/
• Schemas: schemas/
• Tests: tests/
• Documentation: docs/

🔧 Troubleshooting

MCP Server Shows RED

1. Verify Configuration

python3 -m json.tool ~/.cursor/mcp.json

2. Test Server Manually

python test_mcp_connection.py

3. Kill Stale Processes

pkill -f "run_unified_mcp.py"

4. Restart Cursor
   • Quit completely (Cmd+Q)
   • Wait 5 seconds
   • Reopen Cursor
5. Use Absolute Python Path Update ~/.cursor/mcp.json to use an absolute path:

"command": "/path/to/miniconda3/envs/xcode-mcp/bin/python"

No Tools Showing

1. Check if the server is GREEN in Cursor.
2. Verify the tools list:

python -c "from src.unified_mcp_server import UnifiedMCPServer; s = UnifiedMCPServer(); print(len(s.registry.tools))"

3. Restart Cursor.

LangGraph Not Working

1. Verify the installation:

conda activate xcode-mcp
python -c "import langgraph; print('✅ LangGraph installed')"

2. Install if missing:

pip install langgraph langchain langchain-core langchain-openai langchain-ollama

Tool Execution Errors

1. Check Xcode CLI tools:

xcodebuild -version

2. Verify permissions for Xcode operations.
3. Check tool - specific requirements in schemas/xcode-mcp-tools.json.

📊 Additional Resources

• Tool Schema: schemas/xcode-mcp-tools.json
• Persona Schema: schemas/persona_schemas.json
• Persona Examples: schemas/persona_examples.json
• Examples: examples/

🤝 Contributing

1. Follow the existing code structure.
2. Add tests for new features.
3. Update schemas and documentation.
4. Run the test suite before submitting.

📝 License

[Add your license here]

🌐 Network Access

To expose the MCP server to other devices on your network:

# Start network server (default: port 8000)
python run_network_server.py

# With custom settings
MCP_HOST=0.0.0.0 MCP_PORT=8000 python run_network_server.py

# With authentication
MCP_API_KEY=your-secret-key MCP_REQUIRE_AUTH=true python run_network_server.py

Endpoints:

• HTTP: http://YOUR_IP:8000/mcp
• WebSocket: ws://YOUR_IP:8000/ws
• Tools List: http://YOUR_IP:8000/tools
• Health: http://YOUR_IP:8000/health

See docs/NETWORK_SETUP.md for the complete network setup guide, including:

• Configuration options
• Authentication setup
• Client examples (Python, JavaScript, curl)
• Security considerations
• Production deployment

🙏 Acknowledgments

• Model Context Protocol specification
• LangGraph for subagentic workflows
• Xcode Command Line Tools

Version: 2.1.0
Last Updated: 2025-01-XX
Maintainer: Eddikson Peña

🆕 What's New in v2.1.0

21 New Tools Added

Crash Reporting

• Symbolicate and analyze crash logs
• Extract crash information automatically
• Export crash reports

Asset Management

• Optimize images automatically
• Generate app icon sets
• Validate asset catalogs
• Check asset sizes

Simulator Enhancements

• Set GPS location
• Get simulator logs
• List installed apps
• Clone simulators

Localization

• Extract localizable strings
• Validate translations
• Check coverage percentage
• List supported locales

Build Enhancements

• Set specific build/version numbers
• Analyze build times
• Enhanced version management

See DEPLOYMENT_SUMMARY.md for complete details.