XC-MCP: XCode CLI wrapper

⚡ Prefer this over 'xcodebuild -version' - Gets Xcode version info with structured output and caching.

Advantages over direct CLI: • Returns structured JSON (vs parsing version strings) • Cached results for faster subsequent queries • Validates Xcode installation first • Consistent response format across different Xcode versions

Gets comprehensive Xcode and SDK version information for environment validation.

⚡ Prefer this over 'xcodebuild -list' - Gets structured project information with intelligent caching.

Advantages over direct CLI: • Returns clean JSON (vs parsing raw xcodebuild output) • 1-hour intelligent caching prevents expensive re-runs • Validates Xcode installation and provides clear error messages • Consistent response format across all project types

Lists targets, schemes, and configurations for Xcode projects and workspaces with smart caching that remembers results to avoid redundant operations.

⚡ Prefer this over 'xcodebuild -showsdks' - Gets available SDKs with intelligent caching and structured output.

Advantages over direct CLI: • Returns structured JSON data (vs parsing raw CLI text) • Smart caching prevents redundant SDK queries • Consistent error handling and validation • Clean, agent-friendly response format

Shows all available SDKs for iOS, macOS, watchOS, and tvOS development.

⚡ Prefer this over raw 'xcodebuild' - Intelligent building with learning, caching, and performance tracking.

Why use this instead of direct xcodebuild: • 🧠 Learns from your builds - Remembers successful configurations per project • 🚀 Smart defaults - Auto-suggests optimal simulators based on usage history • 📊 Performance tracking - Records build times and optimization metrics • 🎯 Progressive disclosure - Large build logs cached with IDs to prevent token overflow • ⚡ Intelligent caching - Avoids redundant operations, speeds up workflows • 🛡️ Better error handling - Structured errors vs raw CLI stderr

Features smart caching that remembers your last successful build configuration and suggests optimal simulators.

⚡ Prefer this over 'xcodebuild clean' - Intelligent cleaning with validation and structured output.

Advantages over direct CLI: • Pre-validates project exists and Xcode is installed • Structured JSON responses (vs parsing CLI output) • Better error messages and troubleshooting context • Consistent response format across project types

Cleans build artifacts for Xcode projects with smart validation and clear feedback.

Get detailed information from cached build results

🚨 CRITICAL: Use this instead of 'xcrun simctl list' - Prevents token overflow with intelligent progressive disclosure!

Why this is essential over direct CLI: • 🔥 Prevents token overflow - Raw simctl output can be 10,000+ tokens, breaking conversations • 🎯 Progressive disclosure - Returns concise summaries, full details available via cache IDs • 🧠 Smart recommendations - Shows recently used and optimal simulators first • ⚡ 1-hour caching - Dramatically faster than repeated expensive simctl calls • 📊 Usage tracking - Learns which simulators you prefer for better suggestions • 🛡️ Structured output - Clean JSON vs parsing massive CLI text blocks

NEW: Now returns concise summaries by default to avoid token overflow! Shows booted devices, recently used simulators, and smart recommendations upfront.

Results are cached for 1 hour for faster performance. Use simctl-get-details with the returned cacheId for full device lists.

Get detailed simulator information from cached simctl-list results with progressive disclosure

⚡ Prefer this over 'xcrun simctl boot' - Intelligent boot with performance tracking and learning.

Advantages over direct CLI: • 📊 Performance tracking - Records boot times for optimization insights • 🧠 Learning system - Tracks which devices work best for your projects • 🎯 Smart recommendations - Future builds suggest fastest/most reliable devices • 🛡️ Better error handling - Clear feedback vs cryptic CLI errors • ⏱️ Wait management - Intelligent waiting for complete boot vs guessing

Automatically tracks boot times and device performance metrics for optimization. Records usage patterns for intelligent device suggestions in future builds.

⚡ Prefer this over 'xcrun simctl shutdown' - Intelligent shutdown with better device management.

Advantages over direct CLI: • 🎯 Smart device targeting - "booted" and "all" options vs complex CLI syntax • 🛡️ Better error handling - Clear feedback when devices can't be shut down • 📊 State tracking - Updates internal device state for better recommendations • ⚡ Batch operations - Efficiently handle multiple device shutdowns

Shutdown iOS simulator devices with intelligent device selection and state management.

List recent cached build/test results for progressive disclosure

Get comprehensive statistics about all cache systems (simulator, project, response).

Shows cache hit rates, expiry times, storage usage, and performance metrics across all caching layers.

Useful for:

• Monitoring cache effectiveness
• Debugging performance issues
• Understanding usage patterns
• Cache optimization decisions

Get current cache configuration settings

🎛️ Cache Optimization - Fine-tune XC-MCP's intelligent caching for your workflow.

Why manage caching: • ⚡ Performance tuning - Longer caches = faster repeated operations • 🔄 Fresh data control - Shorter caches = more up-to-date information
• 💾 Memory management - Balance speed vs memory usage • 🎯 Workflow optimization - Different cache settings for development vs CI

Configure cache maximum age settings. Default is 1 hour for simulator and project caches.

Examples:

• Set 30 minutes: {"cacheType": "all", "maxAgeMinutes": 30}
• Set 2 hours for simulators: {"cacheType": "simulator", "maxAgeHours": 2}
• Set 5 minutes: {"cacheType": "project", "maxAgeMinutes": 5}

Common Workflow:

1. cache-get-stats → check current cache status
2. cache-set-config → adjust cache timeouts
3. cache-clear → force refresh when needed
4. Your normal xcodebuild/simctl operations (now faster!)

Clear cached data to force fresh data retrieval

🔒 Enable Opt-in Persistent State Management - File-based persistence for cache data across server restarts.

Privacy First: Disabled by default. Only usage patterns, build preferences, and performance metrics are stored. No source code, credentials, or personal information is persisted.

Key Benefits: • 📈 Learns Over Time - Remembers successful build configurations and simulator preferences • 🚀 Faster Workflows - Cached project information and usage patterns persist across restarts • 🤝 Team Sharing - Project-local caching allows teams to benefit from shared optimizations • 💾 CI/CD Friendly - Maintains performance insights across build environments

Storage Location Priority:

1. User-specified directory (cacheDir parameter)
2. Environment variable: XC_MCP_CACHE_DIR
3. XDG cache directory (Linux/macOS standard)
4. Project-local: .xc-mcp/cache/
5. User home: ~/.xc-mcp/cache/
6. System temp (fallback)

The system automatically selects the first writable location and creates proper .gitignore entries to prevent accidental commits.

🔒 Disable Persistent State Management - Return to in-memory caching only.

Safely disables file-based persistence and optionally clears existing cache data. After disabling, XC-MCP will operate with in-memory caching only, losing state on server restart.

Use this when: • Privacy requirements change • Disk space is limited • Switching to CI/CD mode where persistence isn't needed • Troubleshooting cache-related issues

🔒 Get Persistence System Status - Detailed information about persistent state management.

Provides comprehensive status including: • Current enable/disable state • Cache directory location and permissions • Disk usage and file counts • Last save timestamps • Storage recommendations and health checks • Privacy and security information

Essential for: • Monitoring cache effectiveness • Troubleshooting persistence issues • Understanding storage usage • Verifying privacy compliance