内容
<div align="center">
<img src="https://github.com/XcodeBazelMCP/XcodeBazelMCP/blob/HEAD/assets/LOGO.png?raw=true" alt="XcodeBazelMCP" width="200">
<h1>XcodeBazelMCP</h1>
<p>
一个适用于基于Bazel的苹果平台开发的模型上下文协议（MCP）服务器和命令行界面（CLI）。
提供了21个工作流类别中的125种工具，涵盖iOS、macOS、tvOS、watchOS、visionOS和Swift Package Manager。
</p>
[](https://github.com/XcodeBazelMCP/XcodeBazelMCP/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/xcodebazelmcp)
[](https://github.com/XcodeBazelMCP/XcodeBazelMCP/blob/main/LICENSE)
[](https://nodejs.org/)
[](https://developer.apple.com/xcode/)
[](https://github.com/XcodeBazelMCP/XcodeBazelMCP)
[](https://modelcontextprotocol.io)
[](https://codecov.io/gh/XcodeBazelMCP/XcodeBazelMCP)
[](https://badge.socket.dev/npm/package/xcodebazelmcp/0.1.0)
[](https://deepwiki.com/XcodeBazelMCP/XcodeBazelMCP)
</div>
<br>
## 提供的内容
- **构建和运行** — 在模拟器和物理设备上构建、安装、启动和停止iOS/macOS应用程序。
- **测试和覆盖率** — 运行单元/UI/构建测试，支持过滤、流式输出和代码覆盖率。
- **模拟器管理** — 启动、关闭、擦除、配置位置/外观/状态栏。
- **物理设备** — 通过`xcrun devicectl`进行完整的设备生命周期管理：列出、配对、安装、启动、终止、截图、日志捕获。
- **LLDB调试** — 附加到模拟器或设备进程，设置断点，检查变量，步进代码。
- **UI自动化** — 在模拟器上（通过IDB或CGEvent fallback）点击、滑动、输入、拖拽、缩放和检查可访问性树。
- **多平台** — tvOS、watchOS、visionOS目标的构建、运行、测试和发现。
- **Swift Package Manager** — 构建、测试、运行、清理、解析、转储和初始化Swift包。
- **项目发现** — 查询Bazel构建图，发现目标，检查依赖关系。
- **脚手架** — 从模板（ios_app、macos_app等）生成新的Bazel项目。
- **会话和配置** — 工作区管理、构建配置文件、默认值、健康检查。
- **后台守护进程** — 用于状态操作的每个工作区守护进程。
- **自我更新** — 检查和安装更新。
## 要求
- 安装了Xcode的macOS
- Node.js 18+
- `PATH`上的Bazel或Bazelisk
- Bazel工作区（通过`BAZEL_IOS_WORKSPACE`、配置文件或`set_workspace`工具设置）
### 可选（适用于iOS 17+的设备截图和日志）
- `pymobiledevice3` — `pip3 install pymobiledevice3`
- 用于截图：`sudo pymobiledevice3 remote tunneld`在后台运行
- 用于日志：首先尝试使用`pymobiledevice3`，否则回退到`idevicesyslog`
## 安装
### npm
```sh
npm install -g xcodebazelmcp
```
然后使用已安装的CLI：
```sh
xcodebazelmcp mcp
```
### Homebrew
```sh
brew install XcodeBazelMCP/tap/xcodebazelmcp
```
然后使用已安装的CLI：
```sh
xcodebazelmcp mcp
```
或者直接通过npx运行（无需安装）：
```sh
npx -y xcodebazelmcp mcp
```
### 快速入门（交互式）
```sh
npx -y xcodebazelmcp setup
```
### 安装代理技能（Cursor / Codex）
```sh
npx -y xcodebazelmcp init
```
## MCP 配置
```json
{
"mcpServers": {
"XcodeBazelMCP": {
"command": "npx",
"args": ["-y", "xcodebazelmcp", "mcp"],
"env": {
"BAZEL_IOS_WORKSPACE": "/path/to/your/ios-workspace"
}
}
}
}
```
如果您使用npm或Homebrew全局安装了CLI：
```json
{
"mcpServers": {
"XcodeBazelMCP": {
"command": "xcodebazelmcp",
"args": ["mcp"],
"env": {
"BAZEL_IOS_WORKSPACE": "/path/to/your/ios-workspace"
}
}
}
}
```
或使用工作区标志：
```sh
npx -y xcodebazelmcp mcp --workspace /path/to/your/ios-workspace
```
### 从源代码构建
```sh
git clone https://github.com/XcodeBazelMCP/XcodeBazelMCP.git
cd XcodeBazelMCP
npm install
npm run build
```
## 使用工作区
XcodeBazelMCP需要知道要操作的Bazel工作区。有几种方法可以设置它，按优先级顺序排列：
1. **MCP工具在运行时** — `bazel_ios_set_workspace`（为后续工具调用设置工作区）
2. **CLI标志** — `xcodebazelmcp mcp --workspace /path/to/workspace`
3. **环境变量** — `BAZEL_IOS_WORKSPACE=/path/to/workspace`
4. **配置文件** — 工作区根目录中的`.xcodebazelmcp/config.yaml`（支持配置文件）
5. **回退** — `process.cwd()`
对于多工作区设置，请在`config.yaml`中使用**配置文件**：
```yaml
profiles:
app:
defaultTarget: '//app:app'
defaultPlatform: simulator
defaultBuildMode: debug
mac:
defaultTarget: '//mac:mac'
defaultPlatform: macos
```
然后在运行时切换：`xcodebazelmcp set-defaults --profile app`
## 环境变量
| 变量 | 用途 |
| --- | --- |
| `BAZEL_IOS_WORKSPACE` | Bazel工作区根目录（最高优先级工作区源） |
| `BAZEL_PATH` / `MCP_BAZEL_PATH` | Bazel/Bazelisk二进制文件的路径（默认为`PATH`上的`bazel`） |
| `BAZEL_IOS_STARTUP_ARGS` | 在每个调用中预先添加的Bazel启动参数（引用感知） |
| `BAZEL_IOS_MCP_MAX_OUTPUT` | 命令输出的最大捕获字符数（默认200000） |
| `BAZEL_IOS_SIMULATOR_CPU` | 覆盖iOS模拟器CPU（`sim_arm64` / `x86_64`; 默认：主机） |
| `BAZEL_IOS_DISCOVER_SCOPE` | 非单体仓库的默认`discover`查询范围（例如`//...`） |
| `BAZEL_IOS_COMMAND_LOG` | 持久的NDJSON命令日志的路径 |
| `BAZEL_IOS_COMMAND_LOG_MAX_BYTES` | 旋转命令日志的最大大小（默认5 MiB） |
| `BAZEL_IOS_COMMAND_LOG_DISABLE` | 设置为`1`以禁用命令日志记录 |
| `IDB_PATH` | 用于UI自动化的`idb`二进制文件的路径（否则在`PATH`上发现） |
| `BITRISE_BUILD_CACHE_AUTH_TOKEN` | **不需要。**本地构建/测试是默认的。只有在您故意想要Bitrise RBE（`--config=bitrise` / `--config=remote_linux`）时才设置此令牌。没有它，这些配置将自动被丢弃。 |
### 默认本地执行
DoorDash的`ios`仓库定义了`--config=bitrise`和`--config=remote_linux`以启用可选的Bitrise远程执行。 **您不需要`BITRISE_BUILD_CACHE_AUTH_TOKEN`来进行XcodeBazelMCP。** 默认情况下，代理和工具在您的Mac上本地运行。
如果调用传递`--config=bitrise`或`--config=remote_linux`而没有令牌，XcodeBazelMCP会静默丢弃这些标志并本地运行。仅当您明确想要RBE卸载（例如在Bitrise执行器上进行重编译）时才设置令牌。
## CLI示例
```sh
# 健康检查
xcodebazelmcp doctor
# 发现和查询
xcodebazelmcp discover --scope //Apps/... --kind apps
xcodebazelmcp query 'deps(//app:app)'
# 构建和运行（模拟器）
xcodebazelmcp build //app:app --debug --simulator
xcodebazelmcp run //app:app --simulator-name "iPhone 16 Pro"
# 构建和运行（设备）
xcodebazelmcp device-run //app:app --device-name "iPhone"
xcodebazelmcp device-screenshot output.png --device-name "iPhone"
xcodebazelmcp device-log-start --device-name "iPhone"
# 测试
xcodebazelmcp test //tests:UnitTests --filter "SomeTest/testCase" --stream
# macOS
xcodebazelmcp macos-build //mac:mac --debug
xcodebazelmcp macos-run //mac:mac
# Swift Package Manager
xcodebazelmcp spm-build --path ./MyPackage
xcodebazelmcp spm-test --filter "MyTests/testExample"
# 脚手架
xcodebazelmcp new ios_app MyNewApp --bundle-id com.example.MyNewApp
# 配置
xcodebazelmcp defaults
xcodebazelmcp set-defaults --target //app:app --simulator-name "iPhone 16 Pro"
xcodebazelmcp workflows
```
## 工作流类别（125种工具）
工作流控制哪些工具被宣传给MCP客户端。智能默认值启用最常见的工作流；使用`toggle-workflow`进行自定义。
| 类别 | 工具 | 描述 |
| --- | --- | --- |
| **构建** | 2 | 为模拟器或设备构建iOS目标 |
| **测试** | 2 | 运行iOS测试，可选覆盖 |
| **模拟器** | 12 | 管理模拟器生命周期、设置、媒体和容器 |
| **应用程序生命周期** | 6 | 在模拟器上安装、启动、停止、卸载应用程序 |
| **捕获** | 5 | 截图、视频录制、日志捕获（模拟器） |
| **代理调试** | 4 | NDJSON代理调试日志（Cursor DEBUG MODE） |
| **UI自动化** | 9 | 点击、滑动、输入、拖拽、可访问性快照 |
| **深层链接** | 2 | 打开URL和发送推送通知 |
| **设备** | 16 | 物理设备构建、部署、测试、截图、日志、卸载、应用程序列表 |
| **LLDB** | 10 | LLDB调试器：断点、变量、步进 |
| **macOS** | 13 | macOS构建、运行、测试、发现 |
| **tvOS** | 4 | tvOS构建、运行、测试、发现 |
| **watchOS** | 4 | watchOS构建、运行、测试、发现 |
| **visionOS** | 4 | visionOS构建、运行、测试、发现 |
| **SPM** | 7 | Swift Package Manager操作 |
| **项目** | 6 | 目标发现、查询、依赖关系、反向依赖关系 |
| **脚手架** | 2 | 生成新的Bazel项目 |
| **会话** | 7 | 工作区、默认值、配置文件、健康检查 |
| **守护进程** | 3 | 后台守护进程管理 |
| **更新** | 2 | 自我更新和版本检查 |
| **Xcode** | 3 | Apple-native Xcode MCP检测、DeviceHub、技能（[docs](docs/xcode-native-mcp.md)） |
## iOS 17+ 设备说明
苹果公司在iOS 17 / macOS 15中用CoreDevice（`remoted`）替换了`lockdownd`/`usbmuxd`。这意味着：
- **`xcrun devicectl`** 是设备操作的唯一可靠CLI（列表、安装、启动、终止）。
- **截图** 需要`pymobiledevice3`和`tunneld`运行 - 没有`devicectl`截图子命令。
- **日志** 使用`pymobiledevice3 syslog live`（自动回退到旧设备的`idevicesyslog`）。
- **进程终止** 使用两步PID查找，因为`devicectl`在进程列表中不公开`bundleIdentifier`。
有关详细信息，请参阅[docs/device-support.md](docs/device-support.md)。
## 开发
```sh
git clone https://github.com/XcodeBazelMCP/XcodeBazelMCP.git
cd XcodeBazelMCP
npm install
npm run build # 构建dist/
npm test # 运行测试（vitest）
npm run lint # ESLint
```
## 说明
服务器使用`spawn`启动Bazel，而不是shell。额外的标志作为argv条目传递，以便命令可重现并避免shell插值。
