axiom-xcode-mcp

AI Community

Repo stars 0
Author updated Aug 25, 2026, 02:29 AM
Author repo Axiom

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Use when connecting to Xcode via MCP, using xcrun mcpbridge or the headless mcp-server, or working with ANY Xcode MCP tool (Xcod…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Cursor MCP Tool Boundary”, “Cursor UI Tool Availability”, “When to Use”, “Routing Logic”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name axiom-xcode-mcp directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Cursor MCP Tool Boundary / Cursor UI Tool Availability / When to Use” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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 an external tool and is not bundled with the Cursor plugin; it has no Axiom MCP wrapper. Before UI automation, check command -v xcui. If it is absent, 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 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 external 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" gate, 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 start and open <path>. 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)
Delegate to the an subagent 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

Thought	Reality
"I'll just use xcodebuild directly"	MCP gives IDE state, filtered compiler diagnostics, and rendered previews that CLI doesn't expose
"I already know how to set up MCP"	Client configs differ. Permission dialog behavior is specific. Check setup skill.
"I can figure out the tool params"	Tool schemas have required fields and gotchas. Check ref skill.
"One workspace is open, so I can skip the identifier"	`workspaceIdentifier` is required anyway, despite being absent from every `required` list.
"This is just file reading, I'll use Read tool"	XcodeRead sees Xcode's project view including generated files and resolved packages

Conflict Resolution (vs Other Routers)

Domain	Owner	Why
MCP-specific interaction (mcpbridge, mcp-server, MCP tools, workspace identifiers)	axiom-xcode-mcp	MCP protocol and tool-specific
Xcode environment (Derived Data, zombie processes, simulators)	axiom-build	Environment diagnostics, not MCP
Apple's bundled documentation (for-LLM guides/diagnostics)	axiom-apple-docs	Bundled docs, not MCP tool
`DocumentationSearch` MCP tool usage specifically	axiom-xcode-mcp	MCP tool invocation
Build failures diagnosed via CLI	axiom-build	Traditional build debugging
Build failures diagnosed via MCP tools	axiom-xcode-mcp	MCP workflow patterns

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

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: AI
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @CharlesWiltgen · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview axiom-xcode-mcp-ccfe96c76a.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

## 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 an external tool and is not bundled with the Cursor plugin; it has no Axiom MCP wrapper. Before UI automation, check `command -v xcui`. If it is absent, 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 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 external 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.**

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Cursor MCP Tool Boundary → Cursor UI Tool Availability → When to Use → Routing Logic → 1. Setup/Connection → xcode-mcp-setup → 2. Using Tools & Workflows → xcode-mcp-tools
terms    -> On Xcode 26.x, mcpbridge requires a running Xcode with a project open. · That constraint is gone on Xcode 27. · capability, not uptime · xcode-mcp-setup · Triggers · Read · xcode-mcp-tools · xcode-mcp-ref
files/cmd -> xclog · xcsym · xcprof · xclog launch · axiomxcloglaunch · xcsym crash · axiomxcsymcrash · xcprof record
body sha256 -> ad5a571bdfba

Decide Fit First

Design Intent

How To Use It

Boundaries And Review

Cursor MCP Tool Boundary

Cursor UI Tool Availability

Xcode MCP

When to Use

Routing Logic

1. Setup/Connection → xcode-mcp-setup

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

3. Tool API Reference → xcode-mcp-ref

Decision Tree

Anti-Rationalization

Conflict Resolution (vs Other Routers)

Example Invocations

Resources

Discussion