axiom-xcode-mcp

name: axiom-xcode-mcpdescription: "Use when connecting to Xcode via MCP, using xcrun mcpbridge or the headless mcp-server, or working with ANY Xcode MCP tool (XcodeRead, BuildProject, RunSomeTests, RenderPreview). Covers setup, tool reference, workflows, troubleshooting."

Cursor MCP Tool Boundary

The xclog, xcsym, and xcprof examples below are reference syntax, not executable commands for Cursor. Map each subcommand to the same-named MCP tool—for example, xclog launch to axiom_xclog_launch, xcsym crash to axiom_xcsym_crash, and xcprof record to axiom_xcprof_record—and preserve its arguments as structured fields. Do not run a bare helper binary. If a required MCP tool is unavailable, stop and report that the Axiom MCP integration is missing; do not fall back to a same-named executable.

Cursor UI Tool Availability

xcui is Axiom's own tool, distributed separately from the Cursor plugin; it has no Axiom MCP wrapper. Before UI automation, check command -v xcui. If absent, use a stable Axiom repository checkout and locate <axiom-checkout>/.claude-plugin/plugins/axiom/tools/xcui, where <axiom-checkout> is that checkout's absolute root. Before using either discovered executable, verify it is executable and run --help; substitute that verified absolute path for every xcui command, then run doctor. Do not use the cached axiom-cursor/ plugin directory as the checkout root. If xcui remains unavailable, AXe fallback is limited to compatible input verbs: tap, slider, type, swipe, drag, touch, gesture, button, key, key-sequence, key-combo, and screenshot. Then check command -v axe before that fallback; add --tap-style physical to every axe tap and handle DEVELOPER_DIR explicitly if AXe reports a SimulatorKit loading error. AXe cannot replace wait, assert, a11y, dialog, voiceover, resize, or doctor. If neither tool is available, stop UI automation, explain the checkout setup requirement, and continue only with non-UI simulator and log checks. If AXe exists but the requested workflow requires an xcui-only capability, stop that UI workflow and report the limitation.

Xcode MCP

You MUST use this skill for ANY Xcode MCP interaction — setup, tool usage, workflow patterns, or troubleshooting.

Xcode ships an MCP server exposing IDE tools to external AI clients. xcrun mcpbridge is the stdio transport clients register, available since Xcode 26.3. Xcode 27 adds an explicit "Allow External Agents to Use Xcode Tools" setting, the run-agent launch path, an agent-extension model (custom MCP servers, skills, plug-ins), and a headless server. This skill suite covers setup, tool reference, workflow patterns, and troubleshooting.

On Xcode 26.x, mcpbridge requires a running Xcode with a project open. If that's a liability, the device/simulator half of these operations has a fully Xcode-independent CLI path: devicectl + simctl + Axiom's xcui/xclog/xcsym/xcprof. See axiom-tools (skills/device-control-ref.md).

That constraint is gone on Xcode 27. xcrun mcp-server runs the tool service with Xcode.app closed — sudo xcrun mcp-server enable, then xcrun mcp-server open <project-or-workspace-path>, which launches the service if needed. Clients still register xcrun mcpbridge; the bridge is the transport, mcp-server is the service. Apple's tool schemas describe workspaceIdentifier as "used in headless mode", so headless is a supported model rather than a workaround.

Choose between MCP and the CLI tools (devicectl, simctl, and Axiom's xcui/xclog/xcsym/xcprof) on capability, not uptime. xcui asserts, waits, toggles accessibility settings, and computes VoiceOver announcements, and none of them need sudo — which still matters in CI, where the headless server's sudo opt-in may not be available. The IDE-authoring tools (build state, render previews) remain MCP-only; xcodebuild builds and tests but does not render previews.

When to Use

Use this skill when:

• Setting up Xcode MCP for the first time
• Configuring xcrun mcpbridge for any MCP client
• Using any Xcode MCP tool (file ops, build, test, preview)
• Building, testing, or previewing via MCP tools
• Troubleshooting mcpbridge connection issues
• Workspace targeting questions
• Permission dialog confusion
• Driving simulator input with AXe (tap/type/swipe) -> read skills/axe-ref.md

Routing Logic

1. Setup/Connection → xcode-mcp-setup

Triggers:

• First-time Xcode MCP setup
• Client-specific config (Claude Code, Cursor, Codex, VS Code, Gemini CLI)
• Connection errors ("Connection refused", "No workspaces are currently open.")
• Permission dialog confusion
• Multi-Xcode targeting (MCP_XCODE_PID)
• Schema compliance issues with strict clients
• Giving external agents access to Xcode (Intelligence settings gate)
• Launching an agent via Xcode config (xcrun mcpbridge run-agent)
• Exporting Xcode's skill bundles (xcrun agent skills export)
• Extending Xcode's agent (per-agent config files, MCP servers, plug-ins)

Read: skills/xcode-mcp-setup.md

---

2. Using Tools & Workflows → xcode-mcp-tools

Triggers:

• How to build/test/preview via MCP
• Workflow patterns (BuildFix loop, TestFix loop)
• Tool gotchas and anti-patterns
• Workspace targeting strategy; headless bootstrap (open or create a workspace)
• When to use MCP tools vs CLI (xcodebuild)
• Destructive operation safety (XcodeRM, XcodeMV)

Read: skills/xcode-mcp-tools.md

---

3. Tool API Reference → xcode-mcp-ref

Triggers:

• Specific tool parameters and schemas
• Input/output format for a tool
• "How does XcodeGrep work?"
• "What params does BuildProject take?"
• Tool category listing

Read: skills/xcode-mcp-ref.md

---

Decision Tree

digraph xcode_mcp_router {
    rankdir=TB;
    "User has Xcode MCP question" [shape=ellipse];
    "Setup or connection?" [shape=diamond];
    "Using tools or workflows?" [shape=diamond];
    "Need specific tool params?" [shape=diamond];

    "xcode-mcp-setup" [shape=box];
    "xcode-mcp-tools" [shape=box];
    "xcode-mcp-ref" [shape=box];

    "User has Xcode MCP question" -> "Setup or connection?";
    "Setup or connection?" -> "xcode-mcp-setup" [label="yes"];
    "Setup or connection?" -> "Using tools or workflows?" [label="no"];
    "Using tools or workflows?" -> "xcode-mcp-tools" [label="yes"];
    "Using tools or workflows?" -> "Need specific tool params?" [label="no"];
    "Need specific tool params?" -> "xcode-mcp-ref" [label="yes"];
    "Need specific tool params?" -> "xcode-mcp-tools" [label="general question"];
}

Anti-Rationalization

Conflict Resolution (vs Other Routers)

Example Invocations

User: "How do I set up Xcode MCP with Claude Code?" -> Read: skills/xcode-mcp-setup.md

User: "How do I build my project using MCP tools?" -> Read: skills/xcode-mcp-tools.md

User: "What parameters does BuildProject take?" -> Read: skills/xcode-mcp-ref.md

User: "My mcpbridge connection keeps failing" -> Read: skills/xcode-mcp-setup.md

User: "How do I target a specific workspace?" / "How do I run this without Xcode open?" -> Read: skills/xcode-mcp-tools.md

User: "Can I render SwiftUI previews via MCP?" -> Read: skills/xcode-mcp-tools.md (workflow), then skills/xcode-mcp-ref.md (params)

User: "Cursor can't parse Xcode's MCP responses" -> Read: skills/xcode-mcp-setup.md (schema compliance section)

Resources

Skills: skills/xcode-mcp-setup.md, skills/xcode-mcp-tools.md, skills/xcode-mcp-ref.md, skills/axe-ref.md