{
  "markdown": "# xcforge\n\n<p align=\"center\"><img src=\"xcforge.png\" alt=\"xcforge\" width=\"100%\"></p>\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Platform](https://img.shields.io/badge/platform-macOS_13%2B-blue)](#requirements)\n[![Swift 6.0](https://img.shields.io/badge/Swift-6.0-orange)](https://swift.org)\n[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io)\n[![Homebrew](https://img.shields.io/badge/homebrew-tap-FBB040?logo=homebrew&logoColor=white)](https://github.com/justinthevoid/homebrew-tap)\n[![GitHub release](https://img.shields.io/github/v/release/justinthevoid/xcforge)](https://github.com/justinthevoid/xcforge/releases)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\nAn MCP server and CLI for iOS development — build, test, automate, and diagnose from any AI agent or terminal.\n\n**109 MCP tools. 19 CLI command groups. Single native binary (~8 MB stripped, ~18 MB with debug symbols). Zero external runtime dependencies.**\n\n---\n\n## Install\n\n### Homebrew (recommended)\n\n```bash\nbrew tap justinthevoid/tap && brew install xcforge\n```\n\n### Claude Code (one-liner)\n\n```bash\nclaude mcp add xcforge -- xcforge\n```\n\nThis registers xcforge as an MCP server in your current project. Run it after installing via Homebrew.\n\n### From source\n\n```bash\ngit clone https://github.com/justinthevoid/xcforge.git\ncd xcforge && swift build -c release\ncp .build/release/XCForgeCLI /usr/local/bin/xcforge\n```\n\n## Uninstall\n\n### Homebrew\n\n```bash\nbrew uninstall xcforge\nbrew untap justinthevoid/tap   # optional: remove the tap\n```\n\n### From source\n\n```bash\nrm /usr/local/bin/xcforge\n```\n\n### Remove MCP configuration\n\nAfter uninstalling the binary, remove the `\"xcforge\"` entry from your MCP client config file (see [Configure](#configure) for file locations).\n\nFor Claude Code:\n\n```bash\nclaude mcp remove xcforge\n```\n\n---\n\n## Configure\n\nAdd xcforge to your MCP client. Each client has a different config format and file location.\n\n### Claude Code\n\nThe fastest way is the CLI command shown above under [Install](#install). To configure manually, add to `.mcp.json` in your project root (or `~/.claude/.mcp.json` for global):\n\n```json\n{\n  \"mcpServers\": {\n    \"xcforge\": {\n      \"command\": \"xcforge\",\n      \"args\": [],\n      \"type\": \"stdio\"\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nFile: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"xcforge\": {\n      \"command\": \"/opt/homebrew/bin/xcforge\",\n      \"args\": []\n    }\n  }\n}\n```\n\n> **Note:** Claude Desktop does not inherit your shell PATH. Use the full Homebrew path — `/opt/homebrew/bin/xcforge` on Apple Silicon, `/usr/local/bin/xcforge` on Intel.\n\n### Cursor\n\nFile: `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global)\n\n```json\n{\n  \"mcpServers\": {\n    \"xcforge\": {\n      \"command\": \"/opt/homebrew/bin/xcforge\",\n      \"args\": []\n    }\n  }\n}\n```\n\n> **Note:** Same PATH caveat as Claude Desktop — use the absolute path. Restart Cursor after changes.\n\n### VS Code (GitHub Copilot)\n\nFile: `.vscode/mcp.json` in your project root\n\n```json\n{\n  \"servers\": {\n    \"xcforge\": {\n      \"command\": \"xcforge\",\n      \"args\": [],\n      \"type\": \"stdio\"\n    }\n  }\n}\n```\n\n> **Note:** VS Code uses `\"servers\"` not `\"mcpServers\"`. Requires the GitHub Copilot extension with agent mode enabled. VS Code typically resolves PATH from your shell, so the bare command works.\n\n### Windsurf\n\nFile: `~/.codeium/windsurf/mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"xcforge\": {\n      \"command\": \"/opt/homebrew/bin/xcforge\",\n      \"args\": []\n    }\n  }\n}\n```\n\n> **Note:** Full path recommended. Restart Windsurf after editing.\n\n### Zed\n\nFile: `~/.config/zed/settings.json` (or `.zed/settings.json` per-project)\n\n```json\n{\n  \"context_servers\": {\n    \"xcforge\": {\n      \"command\": {\n        \"path\": \"/opt/homebrew/bin/xcforge\",\n        \"args\": []\n      },\n      \"settings\": {}\n    }\n  }\n}\n```\n\n> **Note:** Zed uses `\"context_servers\"` with a nested `\"command.path\"` — different from every other client.\n\n### Config quick reference\n\n| Client         | Config key        | File location                                                     | Needs absolute path? |\n| -------------- | ----------------- | ----------------------------------------------------------------- | -------------------- |\n| Claude Code    | `mcpServers`      | `.mcp.json`                                                       | No                   |\n| Claude Desktop | `mcpServers`      | `~/Library/Application Support/Claude/claude_desktop_config.json` | Yes                  |\n| Cursor         | `mcpServers`      | `.cursor/mcp.json`                                                | Yes                  |\n| VS Code        | `servers`         | `.vscode/mcp.json`                                                | No                   |\n| Windsurf       | `mcpServers`      | `~/.codeium/windsurf/mcp_config.json`                             | Yes                  |\n| Zed            | `context_servers` | `~/.config/zed/settings.json`                                     | Yes                  |\n\n---\n\n## Claude Code Skill\n\nxcforge includes a Claude Code skill that loads the full tool reference into context when you're working on iOS tasks. Install it globally with:\n\n```bash\nnpx skills justinthevoid/xcforge\n```\n\nOnce installed, Claude will automatically load the right reference files when you use xcforge tools — exact parameters, return values, and usage patterns for each category (build, test, simulator, UI automation, logs, LLDB, diagnosis, and more).\n\n---\n\n## Two Modes, Same Tools\n\n```bash\nxcforge                          # MCP server (stdio JSON-RPC, 109 tools)\nxcforge build --scheme MyApp     # CLI mode (19 command groups)\n```\n\nEvery tool available over MCP has a matching CLI command. Every CLI command supports `--json`.\n\n---\n\n## Tools Overview\n\n| Category              | Count | Highlights                                                                                        |\n| --------------------- | ----- | ------------------------------------------------------------------------------------------------- |\n| **Build**             | 6     | `build_sim`, `build_compile` (fast compile-only), `build_run_sim`, `clean`, project/scheme discovery |\n| **Test**              | 7     | `test_sim` with xcresult parsing, `test_failures`, `test_coverage`, `list_tests`, `test_plan_inspect`, agent output mode, known-failures gating |\n| **Simulator**         | 18    | Full lifecycle + video recording, location simulation, dark mode toggle, status bar override, info |\n| **Physical Devices**  | 7     | Via `devicectl` — list, install, launch, screenshot, pair                                         |\n| **UI Automation**     | 20    | WebDriverAgent + native AX bridge — find, tap (point or pixel), swipe, drag, type, alerts        |\n| **Screenshots**       | 3     | Framebuffer capture (0.3s), point-space coordinate alignment, optional grid overlay              |\n| **Visual Regression** | 3     | Pixel-diff baselines, multi-device checks (Dark Mode, Landscape, iPad), `bless` workflow          |\n| **Logs**              | 4     | 4-layer filtered capture, 8 topic categories, regex wait                                          |\n| **Console**           | 3     | stdout/stderr capture for launched apps                                                           |\n| **SPM**               | 5     | Resolve, update, show deps, reset, clean                                                          |\n| **Accessibility**     | 5     | Audit labels, traits, VoiceOver order, contrast                                                   |\n| **Git**               | 5     | Status, diff, log, commit, branch                                                                 |\n| **LLDB Debugger**     | 8     | Attach, breakpoints, inspect variables, backtrace, step/continue, arbitrary commands              |\n| **Diagnosis**         | 10    | Multi-step workflows: build, run, inspect, capture evidence, compare, verify                      |\n| **Plan Execution**    | 2     | Scripted multi-step automation with assertions                                                    |\n| **Session**           | 3     | Persistent defaults, `.xcforge.yaml` repo config, session profiles                                |\n\n---\n\n## Key Capabilities\n\n### Structured Test Results\n\nTest output is parsed from `.xcresult` bundles — the structured format Xcode generates internally — not from raw xcodebuild stdout/stderr.\n\nA single `test_sim` call returns: pass/fail counts, failure messages with source location, exported failure screenshots, and the xcresult path for deeper inspection via `test_failures` or `test_coverage`.\n\n### Fast Screenshots\n\nThe `screenshot` tool reads the simulator framebuffer via CoreSimulator's IOSurface API, falling back to ScreenCaptureKit, then simctl. Typical latency is ~300ms.\n\n### UI Automation Without Appium\n\nxcforge communicates directly with WebDriverAgent over HTTP and supplements it with a native Accessibility API bridge (AXPBridge). This means:\n\n- `find_element` with `scroll: true` auto-scrolls using 3 fallback strategies\n- `handle_alert` searches across SpringBoard, ContactsUI, and the active app — `accept_all` clears multiple permission dialogs in one call\n- `drag_and_drop` works with element IDs, not just coordinates\n- `get_source` returns the full view hierarchy in ~20ms\n\n### Topic-Filtered Logs\n\n`start_log_capture` streams os_log through 4 filter layers:\n\n1. **Noise exclusion** — strips 15 known noisy processes at the stream level\n2. **Capture modes** — `smart` (broad + topic-ready), `app` (tight, auto-detected bundle), `verbose`\n3. **Topic filtering** — `read_logs` classifies lines into 8 topics (app, crashes, network, lifecycle, springboard, widgets, background, system) and shows only app + crashes by default\n4. **Deduplication** — collapses repeated lines\n\nThe response includes a topic menu with counts, so the agent can pull in specific topics on demand without re-querying.\n\n### Interactive LLDB Debugger\n\n8 tools for attaching LLDB to running simulator processes, setting breakpoints, inspecting variables, viewing stack traces, and stepping through code. Sessions persist for 30 minutes, so you can attach once and run multiple debugging operations. CLI commands are one-shot (attach → operation → detach). Includes:\n\n- Session management: `lldb_attach` (by bundle ID or PID), `lldb_detach`\n- Breakpoints: set by file+line or function name, remove by ID\n- Inspection: evaluate expressions at the current frame, view stack traces\n- Execution control: continue, step over, step into, step out (with 10-second timeout)\n- Raw passthrough: run arbitrary LLDB commands\n\nUse alongside logs and screenshots for systematic root-cause analysis.\n\n### Diagnosis Workflows\n\n10 tools that chain together into structured diagnostic pipelines — start a session, build, launch, capture runtime signals, collect evidence (screenshots, logs, accessibility state), compare against previous runs, and verify fixes. Designed for agents to systematically debug issues across multiple iterations.\n\n### Physical Device Support\n\n7 tools wrapping Apple's `devicectl` for real devices — list connected devices, install/launch/terminate apps, take screenshots, and manage pairing.\n\n---\n\n## CLI Examples\n\n```bash\nxcforge init                                     # Scaffold a committed .xcforge.yaml (repo defaults)\nxcforge build                                    # Build (auto-detects project, scheme, sim)\nxcforge build compile --scheme MyApp             # Fast compile-only check (~5s)\nxcforge build --scheme MyApp --simulator \"iPhone 16 Pro\"\nxcforge test --scheme MyApp --json               # Run tests, JSON output\nxcforge test --for agent                         # Agent-optimized slim JSON\nxcforge test --gate                              # Subtract known-failures.yaml\nxcforge test rerun-failed                        # Replay last run's failures\nxcforge test plan inspect --plan AllTests        # Inspect .xctestplan\nxcforge build-test --env BLESS_BASELINE=1        # Inject env var into test process\nxcforge test failures --xcresult /path/to.xcresult\nxcforge test coverage --min-coverage 80\nxcforge bless --baseline login --tests \"UITests/LoginTests\"  # Baseline+test+diff in one call\nxcforge sim list                                 # List simulators\nxcforge sim boot \"iPhone 16 Pro\"\nxcforge sim info                                 # Booted simulator screen size and scale\nxcforge ui find --aid \"loginButton\"              # Find by accessibility ID\nxcforge ui tap --element el-0                    # Tap element at point coordinates\nxcforge ui tap-pixel --x 750 --y 1334            # Tap at pixel coordinates\nxcforge screenshot                               # Screenshot to stdout\nxcforge screenshot --grid --output /tmp/x.png    # Screenshot with point-coordinate grid\nxcforge pose Settings                            # Build, install, launch to a screen\nxcforge log start                                # Start log capture\nxcforge log read --include network               # Read with topic filter\nxcforge spm resolve                              # Resolve packages\nxcforge device list                              # Connected physical devices\nxcforge debug attach --bundle-id com.example.App    # Attach debugger\nxcforge debug breakpoint set --bundle-id com.example.App --file ViewController.swift --line 42\nxcforge debug inspect --bundle-id com.example.App --expression \"self.count\"\nxcforge debug backtrace --bundle-id com.example.App # Show stack trace\nxcforge debug continue --bundle-id com.example.App --mode step-over\nxcforge diagnose start --scheme MyApp            # Start diagnosis session\n```\n\n---\n\n## Alternatives\n\nThere are several iOS-focused MCP servers worth knowing about:\n\n| Server                                                               | Stars | Scope     | Build   | Test | UI Automation | Screenshots | Visual Regression | Accessibility | Physical Devices | SPM | Git | Logs |\n| -------------------------------------------------------------------- | ----- | --------- | ------- | ---- | ------------- | ----------- | ----------------- | ------------- | ---------------- | --- | --- | ---- |\n| **xcforge**                                                          | —     | 109 tools | Yes     | Yes  | Yes           | Yes         | Yes               | Yes           | Yes              | Yes | Yes | Yes  |\n| [XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP)          | ~5k   | ~15 tools | Yes     | Yes  | Partial       | No          | No                | No            | No               | No  | No  | No   |\n| [ios-simulator-mcp](https://github.com/joshuayoes/ios-simulator-mcp) | ~1.8k | ~10 tools | No      | No   | Yes           | Yes         | No                | No            | No               | No  | No  | No   |\n| [xcode-mcp-server](https://github.com/r-huijts/xcode-mcp-server)     | ~370  | ~8 tools  | Partial | No   | No            | No          | No                | No            | No               | No  | No  | No   |\n| [iosef](https://github.com/riwsky/iosef)                             | <10   | ~5 tools  | No      | No   | Yes           | No          | No                | No            | No               | No  | No  | No   |\n| [Appium MCP](https://github.com/nicholasgcoles/appium-mcp-server)    | <50   | ~10 tools | No      | No   | Yes           | Yes         | No                | No            | Partial          | No  | No  | No   |\n\n- **[XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP)** — The most popular iOS MCP server. Backed by Sentry. Covers build, test, and simulator management well. If you only need build/run workflows, it's a solid choice.\n- **[ios-simulator-mcp](https://github.com/joshuayoes/ios-simulator-mcp)** — Focused on simulator UI interaction — screenshots, taps, swipes, accessibility tree. Good if you only need simulator automation.\n- **[xcode-mcp-server](https://github.com/r-huijts/xcode-mcp-server)** — Early MCP server for Xcode project management. Basic integration — no simulator automation, testing, or device support.\n- **[iosef](https://github.com/riwsky/iosef)** — Agent-optimized simulator CLI with clean ergonomics. Narrow scope but thoughtful design. Swift native.\n- **[Appium MCP](https://github.com/nicholasgcoles/appium-mcp-server)** — Cross-platform (iOS + Android) via the Appium ecosystem. Requires Node.js + Java + Appium server — heavier dependency chain.\n\n**Where xcforge fits:** It combines fast compile checks, build, test, pixel-accurate UI automation, screenshot grids, screen-targeted launch, log analysis, visual regression, device support, SPM, accessibility auditing, and multi-step diagnosis in a single zero-dependency binary. The trade-off is iOS-only — no Android, watchOS, or visionOS.\n\n---\n\n## UI Automation Setup\n\nUI automation tools require a WebDriverAgent (WDA) backend running on the simulator. xcforge manages the WDA connection automatically — you just need to point it at a WDA project.\n\nxcforge tries two backends in order:\n\n1. **xcforgeWDA** (preferred) — xcforge's own WDA fork (`com.xcforge.wda.runner`). Auto-built and deployed when `XCFORGE_WDA_DIR` is set.\n2. **Original WebDriverAgent** (fallback) — Facebook/Appium's WDA. Picked up automatically if WDA is already running on port 8100.\n\n### Quick setup\n\nClone [appium/WebDriverAgent](https://github.com/appium/WebDriverAgent), rename the project and scheme for xcforge, then set `XCFORGE_WDA_DIR`:\n\n```bash\ngit clone https://github.com/appium/WebDriverAgent.git xcforgeWDA\n\n# Copy project with xcforge name and remap bundle ID\ncp -r xcforgeWDA/WebDriverAgent.xcodeproj xcforgeWDA/xcforgeWDA.xcodeproj\nsed -i '' 's/com\\.facebook\\.WebDriverAgentRunner/com.xcforge.wda.runner/g' \\\n  xcforgeWDA/xcforgeWDA.xcodeproj/project.pbxproj\n\n# Add xcforgeWDARunner scheme\ncp xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/WebDriverAgentRunner.xcscheme \\\n   xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcscheme\nsed -i '' 's/WebDriverAgent\\.xcodeproj/xcforgeWDA.xcodeproj/g' \\\n  xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcscheme\n```\n\nThen add `XCFORGE_WDA_DIR` to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"xcforge\": {\n      \"command\": \"xcforge\",\n      \"env\": {\n        \"XCFORGE_WDA_DIR\": \"/path/to/xcforgeWDA\"\n      }\n    }\n  }\n}\n```\n\nxcforge builds and deploys WDA automatically on the first UI tool call (~30–60s on first run, instant thereafter). See the [full UI Automation Setup guide](https://xcforge.dev/docs/guides/ui-automation-setup) for alternative configurations, custom ports, and troubleshooting.\n\n---\n\n## Requirements\n\n- macOS 13+\n- Xcode 15+\n- Swift 6.0+ (source builds only)\n- WebDriverAgent (UI automation only — see [UI Automation Setup](#ui-automation-setup))\n\n---\n\n## Web Baseline (Story 1.1)\n\nThe Web workspace is isolated under `Web/` and uses Astro Starlight plus Svelte with Bun-only package/script usage and Biome-only lint/format checks.\n\n```bash\ncd Web\nbun install\nbun run typecheck\nbun run lint\nbun run validate\n```\n\nLocal route assumptions after `bun run dev`:\n\n- Marketing route: `http://localhost:4321/`\n- Docs route: `http://localhost:4321/docs`\n- Docs depth route: `http://localhost:4321/docs/getting-started`\n\nIf setup fails, run:\n\n```bash\ncd Web\nbun run doctor\n```\n\nRemediation steps are documented in `Web/README.md`.\n\n---\n\n## Support\n\nIf xcforge saves you time, consider supporting development:\n\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/justinthevoid)\n[![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=flat&logo=ko-fi&logoColor=white)](https://ko-fi.com/joltik)\n[![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-ea4aaa?style=flat&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/justinthevoid)\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Contributing\n\nIssues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n",
  "bytes": 20237,
  "sha": "bee18f18f557ab1f2cd6e9439ef7ca813409f64aa37310fb10e8633bd4e08899",
  "repo_slug": "justinthevoid/xcforge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_justinthevoid_xcforge_5e01e28b/readme"
}