v3.2.0 - Build-Only Mode

What's New

Build-Only Mode (--build-only / -b)

New CLI flag that loads only 11 build-focused tools instead of the full 30 tool set, reducing overhead for build-focused workflows.

Tools included:

• xcodebuild (6): build, test, clean, list, version, get-details
• simctl (1): simctl-list (for simulator discovery)
• system (4): rtfm, tool-search, cache, persistence

Usage:

{
  "mcpServers": {
    "xc-mcp": {
      "command": "npx",
      "args": ["-y", "xc-mcp", "--build-only"]
    }
  }
}

Combined with Minimal Mode:

{
  "args": ["-y", "xc-mcp", "--mini", "--build-only"]
}

This gives maximum token reduction for build-focused AI workflows.

---

Full Changelog: v3.1.0...v3.2.0

Published Package (v3.2.0)

• [email protected]

Installation

npm install -g [email protected]

MCP Server Usage

node node_modules/xc-mcp/dist/index.js

v3.1.0

What's New

--mini CLI flag for reduced token usage

Adds a --mini CLI argument that toggles between verbose (~18.7k tokens) and minimal (~540 tokens) tool descriptions, achieving ~97% token reduction.

This is useful for clients like Claude Code that don't support the MCP defer_loading property.

Usage

{
  "mcpServers": {
    "xc-mcp": {
      "command": "npx",
      "args": ["-y", "xc-mcp", "--mini"]
    }
  }
}

Changes

• Add src/config.ts for CLI argument parsing
• Add getDescription() helper to src/registry/types.ts
• Add *_DOCS_MINI exports to all 30 tool files
• Update all 6 registry files to use getDescription()
• Update README with Minimal Mode documentation

Use rtfm tool for full documentation on-demand when running in mini mode.

Full Changelog: v3.0.1...v3.1.0

Published Package (v3.1.0)

• [email protected]

Installation

npm install -g [email protected]

MCP Server Usage

node node_modules/xc-mcp/dist/index.js

v3.0.1: Modular Tool Registration Refactoring

🎯 Overview

Major refactoring of tool registration system for improved code organization and maintainability. No breaking changes - all tools work identically to 3.0.0.

✨ What's New

Modular Registry System

Split monolithic src/index.ts into organized, maintainable registry modules:

src/registry/
├── index.ts          # Orchestration
├── types.ts          # Shared types
├── xcodebuild.ts     # 6 xcodebuild tools
├── simctl.ts         # 11 simctl tools
├── idb.ts            # 9 IDB tools
├── cache.ts          # 2 cache tools
├── workflows.ts      # 2 workflow tools
└── system.ts         # 1 system tool

Documentation in Schema

• Moved full documentation into tool registration description fields
• Imported from existing *_DOCS constants (single source of truth, no duplication)
• Applied defer_loading: true for token efficiency
• Preserved ~1k startup footprint

📊 Code Improvements

Metric	Before	After	Change
src/index.ts	1,500+ lines	141 lines	-91%
Largest module	1,500 lines	309 lines	More maintainable
Registry modules	—	8 files	Organized by category
Tests passing	1,179/1,179	1,179/1,179	✅ 100%
Startup tokens	~1k	~1k	✅ Preserved

🔄 Compatibility

✅ Zero Breaking Changes

• All 30 tools work identically to v3.0.0
• Same tool signatures and parameters
• Same error handling and responses
• Direct upgrade from 3.0.0

🚀 Benefits

• Better Code Organization - Related tools grouped by category
• Improved Maintainability - Registry modules are 70-309 lines each
• Cleaner Architecture - Clear separation of concerns
• Easier Extensions - Add new tools to relevant category module
• Full Documentation - Docs in MCP schema via defer_loading
• Token Efficient - ~1k startup footprint unchanged

🛠️ Technical Details

Registry Modules

Each module registers its category's tools with full documentation:

export function registerSimctlTools(server: McpServer): void {
  server.registerTool(
    'simctl-list',
    {
      description: SIMCTL_LIST_DOCS,  // Full markdown documentation
      inputSchema: { /* ... */ },
      ...DEFER_LOADING_CONFIG,  // Deferred loading
    },
    async args => { /* handler */ }
  );
  // ... 10 more tools
}

Orchestration

Simple, clean initialization:

// src/index.ts
import { registerAllTools } from './registry/index.js';

private async registerTools() {
  registerAllTools(this.server);
}

📝 Commit

• PR: #78 (Merged ✅)
• Commits: 1
• Changed files: 10
• Insertions/Deletions: 946 insertions, 992 deletions (net -46)

🧪 Testing

• ✅ TypeScript: No errors
• ✅ ESLint: All issues resolved
• ✅ Tests: 1,179/1,179 passing
• ✅ Build: Success
• ✅ Server startup: Verified with defer_loading enabled

📦 Installation

# Upgrade existing installation
npm install [email protected]

# Or with Claude Code
/model haiku

⚠️ Notes

• Maintenance Release: Code organization improvements, no new features
• Backward Compatible: Safe to upgrade from v3.0.0
• Recommended: All users should upgrade for better maintainability
• Contributing: Easier codebase to extend with new tools going forward

---

Release Date: January 23, 2025
Type: Maintenance / Refactoring
Breaking Changes: None ✅

Published Package (v3.0.1)

• [email protected]

Installation

npm install -g [email protected]

MCP Server Usage

node node_modules/xc-mcp/dist/index.js

v3.0.0 - defer_loading support

Breaking Changes

• All 29 tools now use platform-native defer_loading — Claude discovers tools automatically on-demand
• Removed custom tool-search tool (platform handles discovery)

New Features

• Platform defer_loading — Zero baseline token overhead; tools loaded when needed
• Workflow tools — workflow-tap-element and workflow-fresh-install for multi-step operations

Changes

• Removed tool-search.ts and tool-registry.ts (platform replaces custom implementation)
• Environment variable XC_MCP_DEFER_LOADING=false disables defer_loading for debugging

Upgrade Notes

No code changes required. Platform tool search handles discovery automatically.

v2.0.2 - Critical Bug Fixes

v2.0.2 - Critical Bug Fixes

Three critical bugs fixed that prevented UI element detection and gesture execution in real-world iOS automation.

🐛 Bugs Fixed

1. JSON Parser Format Mismatch

Problem: IDB returns [{},{},{}] but parser expected {}\n{}\n{}

• Impact: 0 elements detected despite accessible UI
• Fix: Created parseFlexibleJson() utility handling both JSON array and NDJSON formats
• Files: src/utils/json-parser.ts (new), src/tools/idb/ui-describe.ts

2. Frame Object Type Mismatch

Problem: frame returned as object {x,y,width,height} but parser expected string "{{x,y},{w,h}}"

• Impact: frameStr.match is not a function errors
• Fix: Updated parseAXFrame() to handle both object and string formats
• Files: src/tools/idb/ui-describe.ts

3. Swipe Duration Units Confusion ⭐

Problem: Schema default 500 interpreted as 500ms by LLMs but treated as 500 seconds internally

• Impact: Velocity 0.8 pts/sec instead of 1333 pts/sec → iOS rejected swipes (<650 pts/sec threshold)
• Fix: Changed API to accept milliseconds, convert to seconds internally
• Breaking: Manual duration values need updating (rare - most use profile defaults)
  • Before: duration: 0.2 (seconds)
  • After: duration: 200 (milliseconds)

📊 Testing

• ✅ 77 tests passing (21 new json-parser + 56 ui-describe)
• ✅ Build successful
• ✅ Ready for production use

V2: Token Efficiency

Version 2.0.0

Consolidates the tool namespace from 51 to 28
tools through modular routing patterns, reducing MCP schema
token overhead by 75% from the v1.2.1 baseline. This release
introduces accessibility-first automation workflows and removes
7 tools with limited agent utility.

Token Efficiency

Version	Tools	Token Count	Key Optimization
v1.2.1	51	~7,850	Baseline (verbose
descriptions)
v1.3.2	51	~3,000	RTFM progressive disclosure
v2.0.0	28	~1,980	Operation enum consolidation

Total reduction: 75% fewer tokens, 45% fewer tools.

Breaking Changes

Tool Consolidation

21 individual tools have been consolidated into 6 routers using
operation enums. All consolidated tools now require an
operation parameter.

simctl-device (7 tools → 1 router)

Old Tool	New Syntax
simctl-boot	simctl-device({ operation: 'boot', ... })
simctl-shutdown	`simctl-device({ operation: 'shutdown',
... })`
simctl-create	`simctl-device({ operation: 'create', ...
})`
simctl-delete	`simctl-device({ operation: 'delete', ...
})`
simctl-erase	simctl-device({ operation: 'erase', ... })

|
| simctl-clone | simctl-device({ operation: 'clone', ... })
|
| simctl-rename | simctl-device({ operation: 'rename', ... }) |

simctl-app (4 tools → 1 router)

Old Tool	New Syntax
simctl-install	simctl-app({ operation: 'install', ... })

|

| simctl-uninstall | simctl-app({ operation: 'uninstall', ... }) |
| simctl-launch | simctl-app({ operation: 'launch', ... }) |
| simctl-terminate | simctl-app({ operation: 'terminate', ... }) |

idb-app (4 tools → 1 router)

Old Tool	New Syntax
idb-install	idb-app({ operation: 'install', ... })
idb-uninstall	idb-app({ operation: 'uninstall', ... })
idb-launch	idb-app({ operation: 'launch', ... })
idb-terminate	idb-app({ operation: 'terminate', ... })

idb-targets (extended with 2 operations)

Old Tool	New Syntax
idb-targets	idb-targets({ operation: 'list', ... })
idb-connect	idb-targets({ operation: 'connect', ... })
idb-disconnect	`idb-targets({ operation: 'disconnect', ...

})` |

New operations: describe, focus

cache (4 tools → 1 router)

Old Tool	New Syntax
cache-get-stats	cache({ operation: 'get-stats', ... })
cache-get-config	cache({ operation: 'get-config', ... })

|

| cache-set-config | cache({ operation: 'set-config', ... })
|
| cache-clear | cache({ operation: 'clear', ... }) |

persistence (3 tools → 1 router)

Old Tool	New Syntax
persistence-enable	`persistence({ operation: 'enable', ...

})` |

| persistence-disable | persistence({ operation: 'disable', ... }) |
| persistence-status | persistence({ operation: 'status', ... }) |

Removed Tools

The following tools have been removed:

• xcodebuild-showsdks - Static environment information, agents
  typically use default SDKs
• simctl-suggest - Agents have explicit device requirements,
  recommendation logic redundant
• simctl-addmedia - Niche use case for photo picker testing
• simctl-privacy - Permission testing rarely needed in
  CI/automated workflows
• simctl-pbcopy - Text input achievable via idb-ui-input
• simctl-status-bar - Cosmetic screenshot enhancement, not
  required for development
• list-cached-responses - Meta debugging tool, limited agent
  utility

New Features

Accessibility-First Automation

Three new tools enable semantic UI automation as the primary
interaction method, with screenshots as fallback:

accessibility-quality-check

Assesses UI accessibility tree richness and provides workflow
recommendations.

Returns:

• Quality classification: rich (>3 tappable elements),
  moderate (2-3), minimal (≤1)
• Recommendation: accessibility-ready or screenshot-needed
• Element counts by type
• Performance metrics

Cost: ~30 tokens, ~80ms

idb-ui-find-element

Searches accessibility tree by label or identifier text
(case-insensitive, partial matching).

Returns:

• Matched elements with tap coordinates (centerX, centerY)
• Element metadata (type, label, identifier, enabled state)
• Frame bounds for visual context

Cost: ~40 tokens, ~100ms

idb-ui-describe

Extended with progressive disclosure for large accessibility
trees.

Returns:

• Summary with element counts and statistics
• Full element list or cache ID for progressive access
• Tappable element highlighting

Cost: ~50 tokens, ~120ms

Performance Comparison

Approach	Token Cost	Response Time	Use Case
Accessibility tree query	~50	120ms	Primary automation
method (95% of cases)
Screenshot analysis	~170	2000ms	Fallback for custom UI
(5% of cases)

Result: 3.4x cheaper, 16x faster for accessibility-driven
workflows.

New Utilities

element-extraction.ts

Extracts accessibility elements from simulator using simctl
query commands.

Features:

• Queries 8 element types (Button, TextField, SecureTextField,
  Switch, Slider, StaticText, Link, PickerWheel)
• Parses bounds from AXFrame format
• Handles malformed output gracefully
• Returns coordinate-ready elements for tap operations

idb-device-detection.ts

Handles UDID resolution and device validation for IDB
operations.

Functions:

• resolveIdbUdid() - Auto-detects UDID when not provided,
  falls back to last-used target
• validateDeviceReady() - Validates IDB companion connection
  for physical devices
• validateTargetBooted() - Ensures target is in Booted state
  before operations

Test Coverage

Added 119 tests across 5 new test suites:

• idb-ui-find-element.test.ts - 22 tests for semantic element
  search
• idb-accessibility-quality-check.test.ts - 25 tests for
  quality assessment logic
• element-extraction.test.ts - 23 tests for accessibility
  element parsing
• idb-device-detection.test.ts - 21 tests for UDID resolution
  and validation
• idb-ui-describe.test.ts - 34 tests for UI tree querying with
  progressive disclosure

Total test count: 1,136 tests passing
Coverage: 52.77% → 60.28%

Documentation

README.md

Complete rewrite with:

• Token efficiency evolution table
• Accessibility-first philosophy explanation with performance
  data
• Progressive disclosure pattern examples
• RTFM on-demand documentation workflow
• Tool reference organized by category
• CLAUDE.md template for end users

CLAUDE.md

Targeted updates:

• Project overview with v2.0.0 metrics
• Accessibility-first workflow section with decision tree
• V2.0 migration notes with complete tool consolidation mapping
• Updated coverage requirements (80% → 60%)

RTFM Tool Documentation

All tool documentation updated with:

• Operation enum specifications for consolidated routers
• Migration examples for v1.x → v2.0
• Accurate tool counts (fixed: 33 → 28 tools)

Architecture Changes

Router Pattern

Consolidated routers follow consistent architecture:

• Thin routing layer (~100-200 lines)
• Operation enum for type safety
• Delegates to original tool implementations
• Preserves modularity of individual tool files

Example router structure:

export async function simctlDeviceTool(args: SimctlDeviceArgs) {
  const { operation } = args;

  switch (operation) {
    case 'boot': return simctlBootTool(args);
    case 'shutdown': return simctlShutdownTool(args);
    // ... other operations
  }
}

Progressive Disclosure

RTFM tool provides on-demand documentation access:

• Minimal tool descriptions in MCP schema (~70 tokens each)
• Full documentation with examples available via rtfm({ toolName })
• Category browsing via rtfm({ categoryName })
• Suggestion system for typos/partial matches

Installation

npm

npm install [email protected]

MCP Configuration

Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "xc-mcp": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Local development configuration:

{
  "mcpServers": {
    "xc-mcp": {
      "command": "node",
      "args": ["/path/to/xc-mcp/dist/index.js"]
    }
  }
}

Migration Guide

For AI Agents

1. Update tool calls to include operation parameter for
   consolidated routers
2. Adopt accessibility-first workflow:
   • Call accessibility-quality-check before screenshot
   • Use idb-ui-find-element for semantic element search
   • Fall back to screenshot only when accessibility data is
     insufficient
3. Replace removed tools:
   • simctl-privacy → Manual permission configu...

XC-MCP v1.3.2: Token Optimization Release

XC-MCP v1.3.2: Token Optimization Release

Philosophy: Latent Knowledge Over Explicit Documentation

This release introduces a fundamental shift in how XC-MCP handles context efficiency. Rather than embedding comprehensive documentation in every tool schema, we leverage latent model knowledge and progressive disclosure to eliminate redundant token consumption.

What Changed

Token Reduction Strategy:

• Removed verbose parameter descriptions (47% reduction per parameter)
• Condensed tool descriptions to 1-2 sentences (74% reduction per tool)
• Eliminated redundant "use RTFM" references from parameter definitions
• Stripped emoji and formatting bloat from schemas

Real Numbers:

• Before: ~39.2k tokens for 51 tools and 188 parameters
• After: ~30k tokens (23% reduction)
• Freed: ~9.2k tokens available for actual work

The RTFM Pattern: Progressive Disclosure

Instead of bloating schemas with full documentation:

1. Tool Discovery - Agents see minimal descriptions (~30k tokens total)
   xcodebuild-build: "Build Xcode projects with caching."
2. On-Demand Details - When needed, agents call RTFM
   rtfm({ toolName: "xcodebuild-build" })
3. Full Documentation - Comprehensive specs, examples, best practices returned on demand

Result: Context budget preserved for actual problem-solving, not tool discovery overhead.

Latent Model Knowledge Assumption

This approach assumes Claude and other frontier models have strong latent knowledge of:

• Xcode command-line architecture and conventions
• iOS simulator lifecycle and management
• Standard build/test workflows
• Common parameter patterns (projectPath, scheme, destination, etc.)

We don't need to re-teach these fundamentals—agents already know them. We only need to clarify XC-MCP-specific details via RTFM when necessary.

Breaking Changes

None. This is a backward-compatible optimization. All functionality preserved, documentation remains available via RTFM.

Road to v2.0

The token savings from this release enable the next phase: tool consolidation. In v2.0, we'll merge related operations into single tools with operation enums:

• simctl-boot + simctl-shutdown + simctl-create + ... → simctl-device (7→1)
• simctl-install + simctl-uninstall + simctl-launch + simctl-terminate → simctl-app (4→1)
• Cache operations → cache (4→1)
• Persistence operations → persistence (3→1)
• IDB app operations → idb-app (4→1)

v2.0 goal: 51 tools → 38 tools, ~1,800 tokens (40% further reduction).

Why This Matters

For agents with 200k context budgets:

• v1.3.1: 39.2k tokens = 19.6% overhead
• v1.3.2: 30k tokens = 15% overhead
• v2.0 (planned): 18k tokens = 9% overhead
• Freed tokens: 10k+ available for code understanding and reasoning

Testing

✅ All 1,011 tests pass
✅ No breaking changes
✅ MCP protocol compliance maintained

v1.2.1 - xc-mcp-mini

xc-mcp-mini: Optimized for AI Agents

This release introduces a new mini variant of xc-mcp, purpose-built for AI agents and focused build/test workflows.

---

📦 Two Packages, One Codebase

Quick Comparison

	xc-mcp (Full)	xc-mcp-mini (Mini)
Tools	51 tools	3 core tools
Use Case	Complete iOS development tooling	Focused build/test workflows
Agent Context	~15K tokens (tool discovery)	~800 tokens (94% reduction)
Simulator Management	Manual control (boot, list, suggest, etc.)	Auto-managed internally
UI Automation	✅ IDB integration (tap, input, gestures)	❌ Not included
Screenshots/Video	✅ Full capture & semantic naming	❌ Not included
Advanced Testing	✅ Permissions, push notifications, status bar	❌ Not included
Build & Test	✅ Full featured	✅ Full featured
Progressive Disclosure	✅ Yes	✅ Yes
Caching & Learning	✅ Yes	✅ Yes

---

🚀 When to Use Each Package

Use xc-mcp-mini when:

• Building and testing iOS apps is your primary workflow
• You want minimal agent context overhead
• You don't need manual simulator management
• You don't need UI automation or screenshot capabilities
• You're optimizing for agent performance and token efficiency

Use xc-mcp (full) when:

• You need UI automation (tap coordinates, input text, gestures)
• You want manual simulator lifecycle control
• You need screenshot/video capture with semantic naming
• You're testing push notifications, permissions, or deep links
• You need the complete iOS development toolset

---

🛠️ What's in xc-mcp-mini?

The mini variant includes exactly 3 tools that cover 95% of build/test workflows:

1. xcodebuild-build

Build Xcode projects with intelligent defaults and caching.

Key Features:

• Auto-selects simulator via internal cache queries
• Auto-boots simulator if needed
• Learns from successful builds
• Returns buildId for progressive disclosure
• Tracks build performance metrics

Example:

{
  "projectPath": "./MyApp.xcworkspace",
  "scheme": "MyApp",
  "configuration": "Debug"
  // destination auto-selected based on project history
}

2. xcodebuild-test

Run tests with smart defaults and structured results.

Key Features:

• Reuses learned configs from build tool
• Shares cached simulator selection
• Supports test filtering and test plans
• Returns testId for progressive disclosure
• Detailed test metrics (pass/fail counts, duration)

Example:

{
  "projectPath": "./MyApp.xcworkspace",
  "scheme": "MyApp",
  "onlyTesting": ["MyAppTests/testLogin"]
}

3. xcodebuild-get-details

Progressive disclosure for build/test logs.

Key Features:

• Retrieves full logs only when needed
• Filters: full-log, errors-only, warnings-only, summary
• Prevents token overflow on large outputs
• Configurable line limits

Example:

{
  "buildId": "build_abc123",
  "detailType": "errors-only",
  "maxLines": 50
}

---

💡 How It Works: Zero Manual Setup

The mini variant achieves 95% workflow coverage with just 3 tools because simulator management is handled internally:

Agent Request: Build MyApp
        ↓
xcodebuild-build (mini)
        ↓
   [Internal Steps - No Agent Action Needed]
   1. Query simulator cache
   2. Select best simulator (learned from history)
   3. Check if simulator is booted
   4. Boot if needed
   5. Execute build
        ↓
Return: buildId + summary (concise)

No need for agents to:

• Call simctl-list to discover simulators
• Call simctl-suggest to pick a simulator
• Call simctl-boot to start simulator
• Manage cache configuration

Result: Agents stay focused on building and testing, not simulator orchestration.

---

📊 Context Budget Comparison

When an AI agent loads MCP tools, it consumes tokens learning about available tools. Here's the impact:

Package	Tool Count	Approx. Context Tokens	% of Typical Context Budget (200K)
xc-mcp (full)	51 tools	~15,000 tokens	7.5%
xc-mcp-mini	3 tools	~800 tokens	0.4%

Savings: 94% reduction in tool discovery overhead

---

📦 Installation

Install Full Variant

npm install -g xc-mcp
# or
npx xc-mcp

Install Mini Variant

npm install -g xc-mcp-mini
# or
npx xc-mcp-mini

---

⚙️ Configuration

Claude Desktop Config (Full Variant)

{
  "mcpServers": {
    "xc-mcp": {
      "command": "npx",
      "args": ["xc-mcp"]
    }
  }
}

Claude Desktop Config (Mini Variant)

{
  "mcpServers": {
    "xc-mcp-mini": {
      "command": "npx",
      "args": ["xc-mcp-mini"]
    }
  }
}

---

🔄 Migration Guide

Already using xc-mcp and want to try mini?

Just install alongside it:

{
  "mcpServers": {
    "xc-mcp": {
      "command": "npx",
      "args": ["xc-mcp"]
    },
    "xc-mcp-mini": {
      "command": "npx",
      "args": ["xc-mcp-mini"]
    }
  }
}

Both packages share the same caches and learned configurations, so switching between them is seamless.

---

🔧 Technical Changes in v1.2.1

Added

• New Package: xc-mcp-mini with 3 core build/test tools
• Dual Publishing: Automated GitHub Actions workflow for parallel package publishing
• Build Config: tsconfig.mini.json for dedicated mini variant compilation
• Publishing Script: scripts/publish-mini.sh for manual mini package publishing
• Documentation: docs/PUBLISHING.md with comprehensive dual-package publishing guide

Changed

• Package Name: Renamed mini variant from xc-mini-mcp to xc-mcp-mini
  • Better npm discoverability (groups alphabetically with xc-mcp)
  • Follows npm conventions (base-variant naming pattern)
• Build Script: Updated build:mini to use dedicated TypeScript config

Fixed

• TypeScript Compilation: Fixed mini variant build issues with Map iteration

---

📈 Performance Benefits

Build/Test Workflow Comparison

Traditional Approach (manual simulator management):

1. simctl-list → 2K tokens (response)
2. simctl-suggest → 1K tokens (response)
3. simctl-boot → 500 tokens (response)
4. xcodebuild-build → 1K tokens (response)
───────────────────────────────────────
Total: 4.5K tokens + 4 tool calls

xc-mcp-mini Approach:

1. xcodebuild-build → 1K tokens (response)
   (simulator selection + boot handled internally)
───────────────────────────────────────
Total: 1K tokens + 1 tool call

Result: 77% token reduction, 75% fewer tool calls

---

🎯 Example Agent Workflows

Workflow 1: Build and Fix Errors

Agent: Build MyApp in Debug configuration
→ xcodebuild-build(projectPath, scheme, configuration: "Debug")
← buildId: "build_xyz", success: false, errorCount: 3

Agent: Show me the errors
→ xcodebuild-get-details(buildId: "build_xyz", detailType: "errors-only")
← [Full error details with line numbers]

Agent: (Analyzes errors, suggests fixes)

Workflow 2: Run Specific Tests

Agent: Run only the login tests
→ xcodebuild-test(projectPath, scheme, onlyTesting: ["MyAppTests/testLogin"])
← testId: "test_abc", passed: 5, failed: 1, duration: 12.3s

Agent: Show me the test failures
→ xcodebuild-get-details(testId: "test_abc", detailType: "errors-only")
← [Failed test details with stack traces]

---

🔗 Links

• Documentation: https://github.com/conorluddy/xc-mcp#readme
• Full Package: https://www.npmjs.com/package/xc-mcp
• Mini Package: https://www.npmjs.com/package/xc-mcp-mini
• Publishing Guide: https://github.com/conorluddy/xc-mcp/blob/main/docs/PUBLISHING.md
• Issues: https://github.com/conorluddy/xc-mcp/issues

---

🙏 Feedback Welcome

This is the first release of the mini variant. We'd love to hear:

• Does the 3-tool approach cover your workflows?
• What use cases require the full variant?
• Should we offer additional mini variants (e.g., UI automation only)?

Open an issue: https://github.com/conorluddy/xc-mcp/issues/new

---

Happy Building! 🚀

Published Package (v1.2.1)

• [email protected]

Installation

npm install -g [email protected]

MCP Server Usage

node node_modules/xc-mcp/dist/index.js

v1.2.0: Massive tool additions. IOS Simulator etc.

All notable changes to XC-MCP are documented in this file. This project adheres to Semantic Versioning.

[1.2.0] - 2025-10-25

🚀 Major Features

IDB Integration (11 new tools)

Complete iOS Development Bridge integration enabling UI automation on simulators and physical devices:

Target Management

• idb-targets: List and describe iOS targets (simulators + devices)
• idb-connect: Manage persistent IDB companion connections

App Management

• idb-list-apps: List installed apps with running status and architecture info
• idb-install: Deploy .app bundles or .ipa archives to targets
• idb-launch: Start apps with stdout/stderr streaming support
• idb-terminate: Force-quit running applications
• idb-uninstall: Remove apps and clean up data/preferences

UI Automation

• idb-ui-tap: Tap interactions with auto-retry on nearby coordinates (±5px fallback)
• idb-ui-input: Type text and keyboard commands with sensitive data handling
• idb-ui-gesture: Complex gestures (swipe with auto-direction→coordinate conversion, pinch, rotate)
• idb-ui-describe: Query accessibility tree to find UI elements programmatically

Key IDB Features

• Auto-UDID detection: Automatically finds booted simulator or optimal device
• Coordinate transform: Converts screen percentages to pixel coordinates automatically
• Screen dimension fetching: Auto-fetches dimensions from idb describe when missing
• NDJSON parsing: Correctly handles IDB's line-delimited JSON output format
• Intelligent caching: 5-second TTL balances freshness with performance
• Works with physical devices via idb_companion

Build Settings Cache

New intelligent caching layer that auto-discovers Xcode project metadata:

• Auto-discovers bundle IDs from Xcode build settings
• Extracts deployment targets (iOS, macOS minimum versions)
• Identifies supported device families (iPhone, iPad, Mac Catalyst)
• Extracts app capabilities from build configuration
• 1-hour TTL prevents repeated expensive xcodebuild operations
• Graceful degradation with fallback handling

Screenshot Enhancements

Vision-optimized screenshots with interactive element metadata:

• Base64-encoded inline screenshots (no file I/O required)
• Automatic element extraction from accessibility tree
• Interactive element coordinates in response (x, y, width, height)
• Element types and labels for context
• Screen dimensions included for coordinate validation
• Semantic naming support: {appName}_{screenName}_{state}_{timestamp}.png
• Graceful degradation if elements unavailable

View Coordinate Cache Foundation

Intelligent view caching system for repeated interactions:

• Element structure hashing via SHA256 fingerprinting
• Confidence tracking with age decay algorithm
• Auto-disables on low hit rate (<60%)
• LRU eviction (50 views, 5 coordinates per view)
• Opt-in via enableCoordinateCaching parameter
• Integration with persistence system for cross-session caching

✨ Enhancements

Tool Improvements

• Auto-UDID Detection: 7 core tools now auto-detect booted simulators when UDID not specified
• Tool Aliases: Shorter invocation names for better agent ergonomics:
  • query → simctl-query-ui
  • tap → simctl-tap
  • type → simctl-type-text
  • scroll → simctl-scroll
  • swipe, pinch, rotate → simctl-gesture
  • screenshot → simctl-io / idb-ui-describe
  • screenshot-save → file-based variant

Simulator Tooling

• Guidance warnings for 9 tools when simulators shutdown or unavailable
• Input validation for enum parameters (dataNetwork, wifiMode, batteryState)
• Enhanced error messages with troubleshooting steps
• Coordinate retry mechanism: Automatic ±5px fallback on tap failures
• Fixed empty response handling in simctl-get-app-container

LLM Optimization Patterns

Comprehensive patterns for AI-agent optimization:

• Semantic metadata: appName, screenName, state for context understanding
• Structured test context: testName, expectedBehavior, actualBehavior tracking
• Permission audit trails: scenario, step, timestamp for test validation
• Interaction sequence tracking: actionName for workflow reconstruction
• Progressive disclosure: Large outputs cached with IDs instead of inline

Documentation System

• 53 documentation sidecar files (.md) for all tools
• Tool-specific examples and usage patterns
• Parameter descriptions with type information
• Common error scenarios and solutions
• Progressive disclosure pattern enables detailed help

Error Messages

• Enhanced tap error guidance: 4 common failure reasons with solutions
• Improved query-ui guidance: Predicate syntax help and troubleshooting
• Better coordinate feedback: Recommends query-ui → tap workflow
• Actionable error messages: Clear next steps instead of opaque codes

Code Quality

• Refactored build.ts and xcodebuild-test.ts for clarity
• Removed emoji from responses (token efficiency)
• Unified response structure across similar tools
• 25-35% more efficient responses (size reduction)
• Clear section markers for AI-friendly navigation

🐛 Fixes

Critical Fixes

• IDB Cache TTL: Reduced from 60s to 5s to prevent stale boot state
• Float Precision: Implemented IntCoordinate type system to prevent CLI parsing errors
• Swipe Direction: Auto-converts direction strings to screen-relative coordinates
• NDJSON Parsing: Fixed line-by-line parsing for IDB multi-object output
• Screen Dimensions: Auto-fetches dimensions when missing from idb list-targets

Test Fixes

• Fixed 140+ failing tests across simulator tooling
• Updated error handling patterns to match McpError behavior
• Removed path module mock that broke file operations
• Fixed tmpdir initialization for proper test isolation

📊 Project Metrics

Tooling Expansion

• Total tools: 52 (up from ~28 in v1.1.0)
• Tool categories: 9 (Xcode, Simulator, IDB, Simulator Control, App Management, UI Automation, I/O, Advanced Testing, Cache Management)
• Tool aliases: 8 shorter names for better agent ergonomics

Test Coverage

• Total tests: 1000+ across 44 test suites
• Coverage threshold: 80% minimum (maintained)
• Test suite categories:
  • State management (cache, config, build settings)
  • Utility functions (command execution, validation)
  • Tool tests (all 52 tools fully tested)
  • Integration patterns (MCP protocol compliance)

Code Quality

• TypeScript: 0 compilation errors
• ESLint: Pre-existing warnings only (unrelated to features)
• Code style: Prettier formatting enforced
• Architecture: Progressive disclosure throughout

🔄 Changes & Migration

API Changes

• simctl-io now returns screenshotInfo object instead of flat response
• Screenshots include interactiveElements metadata when available
• All coordinate responses now use IntCoordinate type system
• IDB tools return targetInfo, appInfo, interactionInfo consistently

Breaking Changes

• None for stable APIs
• Internal response structures simplified but backward compatible at MCP level

Configuration Changes

• New cache configuration for BuildSettingsCache (1-hour default TTL)
• New coordinate cache configuration (opt-in via enableCoordinateCaching)
• Persistence system supports new cache types automatically

📚 Documentation

New Documentation

• docs/LLM_OPTIMIZATION.md: Comprehensive LLM optimization patterns guide
• Updated CLAUDE.md: Tool categories and architecture documentation
• Updated README.md: 52 tools, workflows, comprehensive examples
• Generated 53 tool documentation sidecar files
• CODESTYLE.md: Code style guide from v1.1.0 (applicable to v1.2.0)

Documentation Examples

• IDB workflow examples: app install → launch → tap interactions
• Build settings usage: permission validation, auto-configuration
• Screenshot + query-ui workflow: deterministic UI element discovery
• Coordinate caching: usage patterns and performance implications

🎯 Use Cases Enabled

Complete iOS Testing Workflows

1. Build & Deploy: Build app, extract bundle ID from settings cache, install via IDB
2. UI Automation: Launch app, take screenshot with elements, tap discovered coordinates
3. Permission Testing: Verify permissions from build cache, grant via simctl-privacy, test behavior
4. State Validation: Take screenshots, verify expected UI state, repeat workflow steps

Multi-Device Testing

• Device recommendations based on build settings (device families)
• Parallel testing on multiple simulators with performance tracking
• Automatic device selection based on app capabilities

Debugging & Diagnostics

• Health checks across Xcode, simulators, runtimes, disk space
• Build settings discovery for configuration validation
• Cache statistics for performance optimization

🙏 Acknowledgments

Key Contributions

• IDB integration: Solves physical device testing limitation
• Build settings cache: Enables permission validation and auto-configuration
• UI coordinate system: Makes UI automation reliable instead of trial-and-error
• Element extraction: Bridges screenshot vision and programmatic interaction

Special Thanks

• Claude Code for MCP server scaffolding and tool generation
• Xcode command-line team for stable APIs
• iOS Development Bridge developers for powerful automation capabilities

---

[1.1.0] - 2025-10-21

Added

• xcodebuild-test tool with progressive disclosure and smart defaults
• Test plan execution support with test filtering
• Test-without-building for faster iteration
• Comprehensive code style guide (CODESTYLE.md)
• Support for test result retrieval via xcodebuild-get-details

Changed

• Refactor...

v1.1.0: Added Xcode test tool

Release Notes - Version 1.1.0

New Features

🧪 xcodebuild-test Tool - Run Tests with Smart Defaults

• New xcodebuild-test tool enables intelligent test execution with progressive disclosure
• Smart defaults: Automatically applies cached build configurations and simulator preferences
• Test filtering: Support for onlyTesting and skipTesting patterns for granular test control
• Test plans: Built-in support for named test plans
• Test-without-building: Execute pre-built tests with testWithoutBuilding flag
• Detailed metrics: Automatic parsing of test results with pass/fail counts and failed test
  identification
• Performance tracking: Records test execution patterns for optimization insights
• Progressive disclosure: Returns summary via testId with full logs accessible on demand

Improvements

📋 Code Style Guide (CODESTYLE.md)

• New comprehensive guide for human-AI code collaboration
• Establishes best practices for context engineering and token efficiency
• Documents patterns for progressive disclosure and intelligent caching
• Provides examples for sustainable long-term development

🔧 Build Tool Enhancement

• Minor refactoring to align with new code style standards

📖 Documentation Updates

• Updated README with new test operations in tool reference table
• Added xcodebuild-test to tool inventory with progressive disclosure support

Testing

• Comprehensive test suite (388+ lines) covering:
  • Test configuration assembly and smart defaults
  • Command building and execution
  • Test result parsing and metric extraction
  • Error handling and edge cases
  • Cache integration and response formatting

Technical Details

• Version bump: 1.0.5 → 1.1.0
• ~1500 lines of new functionality and documentation
• 80% test coverage maintained
• All code quality checks passed (ESLint, Prettier, pre-commit hooks)

---

Key Achievement: Extends XC-MCP's intelligent wrapper pattern to test operations, maintaining the
progressive disclosure model that eliminates token overflow while preserving full Xcode CLI
functionality.

Published Package (v1.1.0)

• [email protected]

Installation

npm install -g [email protected]

MCP Server Usage

node node_modules/xc-mcp/dist/index.js