xClaude Plugin

/plugin marketplace add conorluddy/xclaude-plugin

Modular iOS development automation for Claude Code

Build, test, and automate iOS apps through natural conversation with Claude. 8 workflow-specific MCP servers with 24 tools across Xcode, Simulator, and IDB.

Enable only what you need. Each MCP is purpose-built for specific workflows, keeping your context window lean. Plus, our tools intelligently encapsulate Xcode output (errors, test results, build logs) so Claude processes structured JSON instead of raw 50+ line logs—saving significant tokens and enabling faster feedback loops.

Features

🎯 Modular Architecture

• 8 workflow-specific MCP servers (600-3500 tokens each)
• Enable only what you need - Ultra-minimal to full-featured
• 23 shared tools across Xcode, Simulator, and IDB
• Single source of truth - tools defined once, imported by MCPs

🔥 Surgical MCPs (Ultra-Focused)

• xc-build (~600 tokens) - Build validation, errors, clean, list schemes
• xc-launch (~400 tokens) - Simulator app lifecycle: install and launch
• xc-interact (~900 tokens) - Pure UI interaction, no build

📦 Core Workflow MCPs

• xc-ai-assist (~1400 tokens) - Build + UI automation + screenshots
• xc-setup (~800 tokens) - Environment configuration and validation
• xc-testing (~1200 tokens) - Test execution + UI flows
• xc-meta (~700 tokens) - Project maintenance and housekeeping

🚀 Full Access

• xc-all (~3500 tokens) - All 24 tools for complex workflows

📚 8 Procedural Skills (Loaded On-Demand)

• xcode-workflows - Build system guidance and result analysis
• simulator-workflows - Device and app lifecycle patterns
• ui-automation-workflows - Accessibility-first automation
• accessibility-testing - WCAG compliance and quality checks
• ios-testing-patterns - Test execution and flaky test detection
• crash-debugging - Crash log analysis and symbolication
• performance-profiling - Instruments integration
• state-management - Cache and configuration management

Installation

From GitHub (Recommended)

/plugin marketplace add conorluddy/xclaude-plugin
/plugin install xclaude-plugin

From Local Development

/plugin marketplace add /path/to/xclaude-plugin
/plugin install xclaude-plugin

First 60 Seconds

Just installed? Enable xc-build and xc-launch for rapid development:

1. In Claude settings, enable "xc-build" and "xc-launch" MCPs
2. Ask Claude: "Build and run MyApp on iPhone 15"
3. Done! ✨

That's it. xc-build + xc-launch gives you a composable development loop: build with xc-build, then install & launch with xc-launch. Claude orchestrates the two-step workflow. If you need other workflows (testing, setup, UI automation), see Choosing the Right MCP below.

Requirements

• macOS 13.0+ or Linux
• Xcode 15.0+ (macOS only, for iOS development)
• Node.js 18+
• Optional: IDB (Facebook iOS Development Bridge) for advanced UI automation

Migration Guide (v0.4.0)

If you're upgrading from an earlier version, note these breaking changes:

Renamed Server: xc-build-and-launch → xc-launch

What changed: - Server renamed from xc-build-and-launch to xc-launch for clarity - Removed: xcode_build_and_launch monolithic tool (with skip_build flag), plus xcode_build, xcode_clean, xcode_list (moved to xc-build) - Now contains: Only simulator_install_app and simulator_launch_app - Philosophy: Use xc-build + xc-launch together for development loop

Why: The monolithic xcode_build_and_launch tool coupled build, install, and launch into a single operation. The new architecture separates build concerns (xc-build) from simulator lifecycle (xc-launch), enabling: - Better error recovery (retry individual steps) - Clearer mental model (build → install → launch) - No skip_build code smell - Follows Single Responsibility Principle

Action required: 1. Update your .mcp.json configuration: diff - "xc-build-and-launch": { - "command": "node", - "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-servers/xc-build-and-launch/dist/index.js"] + "xc-launch": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-servers/xc-launch/dist/index.js"] 2. In Claude settings, enable "xc-launch" instead of "xc-build-and-launch"

Previous versions: - v0.3.0: xc-run → xc-build-and-launch - v0.3.0: xc-compile → xc-build, xc-hybrid → xc-all

See .mcp.json.example for the current configuration.

Choosing the Right MCP

Enable the Right MCP for Your Task

IMPORTANT: Enable ONE MCP at a time for optimal token efficiency. Choose based on your current workflow:

☐ xc-build                # Build validation, errors, clean? (~600 tokens)
☐ xc-launch               # Simulator lifecycle: install + launch? (~400 tokens)
☐ xc-interact             # Testing UI with app already built? (~900 tokens)
☐ xc-ai-assist            # AI-driven UI iteration? (~1400 tokens)
☐ xc-setup                # First time setup? (~800 tokens)
☐ xc-testing              # Running test suites? (~1200 tokens)
☐ xc-meta                 # Maintenance tasks? (~700 tokens)
☐ xc-all                  # Complex workflow needing everything? (~3500 tokens)

💡 Tip: Enable xc-build + xc-launch together for development loop (~1000 tokens total)

Example Workflows

Scenario 1: Build and fix errors

Enable: xc-build (~600 tokens)

"Build the project and show me the errors"

→ Uses xcode_build with automatic error extraction
→ Returns up to 10 errors for quick fixes
→ 87% less tokens than old architecture!

Scenario 2: Rapid development - build and run

Enable: xc-build + xc-launch (~1000 tokens)

"Build and run MyApp on iPhone 15"

→ Claude orchestrates: build (xc-build) → install & launch (xc-launch)
→ Composable two-server workflow
→ Better error recovery (retry individual steps)
→ Perfect for iterative development

Scenario 3: Testing UI flows (app already built)

Enable: xc-interact (~900 tokens)

"Tap the Login button, then check if the profile screen appears"

→ Queries accessibility tree (3-4x faster than screenshots)
→ Taps elements by coordinates
→ Validates UI state without rebuilding

Scenario 4: AI-driven UI iteration

Enable: xc-ai-assist (~1400 tokens)

"Update the button color to blue, rebuild, and show me a screenshot"

→ Modifies code, builds, captures screenshot
→ Complete workflow in one MCP
→ Includes visual feedback (screenshots)

Architecture

Modular MCP Design

┌─────────────────────────────────────────────────────┐
│  Shared Tool Library (24 tools)                     │
│  ├─ Xcode (6): build, build+run, clean, test, list, version │
│  ├─ Simulator (12): boot, install, screenshot, etc.│
│  └─ IDB (6): describe, tap, input, gesture, etc.   │
└─────────────────────────────────────────────────────┘
         ↓ Tools imported by MCP servers ↓
┌─────────────────────────────────────────────────────┐
│  8 Workflow-Specific MCP Servers                    │
│  ├─ xc-build:            3 tools   (~600 tokens)   │
│  ├─ xc-launch:           2 tools   (~400 tokens)   │
│  ├─ xc-interact:         6 tools   (~900 tokens)   │
│  ├─ xc-ai-assist:        7 tools   (~1400 tokens)  │
│  ├─ xc-setup:            5 tools   (~800 tokens)   │
│  ├─ xc-testing:          6 tools   (~1200 tokens)  │
│  ├─ xc-meta:             6 tools   (~700 tokens)   │
│  └─ xc-all:              24 tools  (~3500 tokens)  │
└─────────────────────────────────────────────────────┘

Key Benefits

For Users:

• Enable only what you need (300-3500 tokens)
• Clear mental model (workflow-based naming)
• No tool duplication confusion
• Easy to toggle on/off in Claude settings

For Developers:

• Single source of truth (shared tools)
• Easy testing (isolated functions)
• Simple maintenance (update once)
• Type-safe throughout (zero any usage)

MCP Server Reference

🔥 Surgical MCPs

MCP	Tools	Token Cost	Use When
xc-build	3	~600	Build validation with clean/scheme discovery
xc-launch	2	~400	Simulator lifecycle: install and launch app
xc-interact	6	~900	Testing UI flows with app already built

📦 Core Workflow MCPs

MCP	Tools	Token Cost	Use When
xc-ai-assist	7	~1400	AI UI iteration with visual feedback
xc-setup	5	~800	Initial setup, environment validation
xc-testing	6	~1200	Running test suites + UI automation
xc-meta	6	~700	Maintenance, housekeeping, environment checks

🚀 Full Access

MCP	Tools	Token Cost	Use When
xc-all	23	~3500	Complex workflows needing everything

Pro tip: Don't enable multiple MCPs simultaneously - tool duplication will increase token usage! Use xc-all instead for multi-workflow sessions.

Cheat Sheet - Which Tools Are in Which MCP?

Quick reference to find which MCP has the tools you need:

Xcode Tools

Tool	xc-build	xc-launch	xc-interact	xc-ai-assist	xc-setup	xc-testing	xc-meta	xc-all
xcode_build	✅			✅				✅
xcode_build_and_launch								✅
xcode_clean	✅						✅	✅
xcode_test						✅		✅
xcode_list	✅						✅	✅
xcode_version					✅		✅	✅

Simulator Tools

Tool	xc-build	xc-launch	xc-interact	xc-ai-assist	xc-setup	xc-testing	xc-meta	xc-all
simulator_list					✅			✅
simulator_boot					✅			✅
simulator_shutdown							✅	✅
simulator_create					✅			✅
simulator_delete							✅	✅
simulator_install_app		✅						✅
simulator_launch_app		✅						✅
simulator_terminate_app								✅
simulator_screenshot				✅		✅		✅
simulator_openurl								✅
simulator_get_app_container								✅
simulator_health_check					✅		✅	✅

IDB Tools

Tool	xc-build	xc-launch	xc-interact	xc-ai-assist	xc-setup	xc-testing	xc-meta	xc-all
idb_describe			✅	✅		✅		✅
idb_tap			✅	✅		✅		✅
idb_input			✅	✅		✅		✅
idb_gesture			✅			✅		✅
idb_find_element			✅	✅				✅
idb_check_quality			✅	✅				✅

Tool Library (24 Total)

Xcode Tools (6)

• xcode_build - Build with automatic error extraction
• xcode_build_and_launch - Build, install, and launch on simulator
• xcode_clean - Clean build artifacts
• xcode_test - Run XCTest suites
• xcode_list - List schemes/targets
• xcode_version - Check Xcode installation

Simulator Tools (12)

• simulator_list - Enumerate simulators
• simulator_boot - Boot device
• simulator_shutdown - Shutdown device
• simulator_create - Create new simulator
• simulator_delete - Delete simulator
• simulator_install_app - Install app
• simulator_launch_app - Launch app
• simulator_terminate_app - Terminate app
• simulator_screenshot - Capture screenshot
• simulator_openurl - Open URL/deep link
• simulator_get_app_container - Get app container path
• simulator_health_check - Validate environment

IDB Tools (6)

• idb_describe - Query accessibility tree (accessibility-first!)
• idb_tap - Tap coordinates
• idb_input - Type text or press keys
• idb_gesture - Swipes and hardware buttons
• idb_find_element - Search by label (semantic)
• idb_check_quality - Assess accessibility data richness

Configuring Your Project

Add this section to your project's .claude/CLAUDE.md file. This guides Claude on when and why to use the xclaude-plugin tools instead of directly calling Xcode or shell commands:

```markdown

xclaude-plugin: Why and When to Use These Tools

The xclaude-plugin provides 8 modular MCPs with 24 specialized iOS tools. Always prefer these over raw xcodebuild or shell commands for iOS development tasks. Here's why:

Why These Tools Trump Raw Commands

Task	Direct Bash	xclaude-plugin	Why Plugin Wins
Build + get errors	xcodebuild -scheme Foo 2>&1 (50+ lines of parsing)	xcode_build tool	Auto-extracts up to 10 errors, structured JSON, 87% fewer tokens
Test suite execution	xcodebuild test + manual parsing	xcode_test tool	Parses resu