公理
- 作者仓库星标 0
- 作者更新于 2026年8月24日 18:29
- 作者仓库 Axiom
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @CharlesWiltgen · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
## 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
```dot
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
章节与文件索引
按说明文件中的顺序排列。
光标 MCP 工具边界
光标 UI 工具可用性
何时使用
1. 设置/连接 → xcode-mcp-setup
2. 使用工具和工作流程 → xcode-mcp-tools
文件/命令 -> xclog · xcsym · xcprof · xclog launch · axiom_xclog_launch · xcsym crash · axiom_xcsym_crash · xcprof record
内容校验值 -> ad5a571bdfba
当前原文的自动摘译,尚未人工审校。
光标 MCP 工具边界
下面的
xclog、xcsym和xcprof示例是参考语法,不是 Cursor 的可执行命令。将每个子命令映射到同名的 MCP 工具(例如,xclog launch到axiom_xclog_launch、xcsym crash到axiom_xcsym_crash、xcprof record到axiom_xcprof_record)并将其参数保留为结构化字段。不要运行裸助手二进制文件。如果所需的 MCP 工具不可用,请停止并报告 Axiom MCP 集成丢失;不要回退到同名的可执行文件。光标 UI 工具可用性
xcui是一个外部工具,不与 Cursor 插件捆绑在一起;它没有 Axiom MCP 包装器。 在 UI 自动化之前,请检查command -v xcui。何时使用
在以下情况下使用此技能: 首次设置 Xcode MCP 为任何 MCP 客户端配置
xcrun mcpbridge使用任何 Xcode MCP 工具(文件操作、构建、测试、预览) 通过 MCP 工具构建、测试或预览1. 设置/连接 → xcode-mcp-setup
触发因素: 首次 Xcode MCP 设置 客户端特定配置(Claude Code、Cursor、Codex、VS Code、Gemini CLI) 连接错误(“连接被拒绝”、“当前没有打开工作区。”) 权限对话框混乱
2. 使用工具和工作流程 → xcode-mcp-tools
触发器:如何通过 MCP 构建/测试/预览 工作流程模式(BuildFix 循环、TestFix 循环) 工具陷阱和反模式 工作区目标策略;无头引导程序(打开或创建工作区)