使用说明

Lightweight visionOS Build MCP for AI Coding Agents

Seiro MCP是一个轻量级的MCP服务器，专注于AI编码代理的visionOS开发工作流程。它使Codex CLI和其他MCP客户端能够通过一组专用的MCP工具安全地构建、验证和检查visionOS项目。

Seiro MCP的目标不是公开Xcode的所有功能。相反，它有意关注AI编码代理在日常开发中最频繁执行的开发人员工作流程。如今，它提供了visionOS构建工具以及捆绑的Codex技能指导，随着时间的推移，它将扩展更多以开发人员为中心的空间计算实用程序，同时仍然专注于开发而不是发布管理。

特性

专注于AI编码代理的visionOS开发工作流程
通过明确的项目约束实现安全的构建自动化
AI友好的MCP界面，用于构建、诊断和工件
Codex技能集成，用于首选的visionOS构建操作
可预测的本地开发工作流程
用Rust编写

为什么选择Seiro MCP？

通用Xcode自动化功能强大，但AI编码代理通常需要一个集中的开发操作子集：验证环境、构建项目、检查故障和检索工件。

Seiro MCP有意保持该接口较小。较小的MCP工具表面更容易让代理推理，更容易让人类审查，在本地开发环境中运行更安全。该项目优先考虑可预测的开发人员工作流程，而不是发布自动化、签名编排或完整的Xcode替换。

轻量级并不意味着功能更少。这意味着为人工智能辅助开发提供正确的功能，同时有意将面向发布的工作流、签名编排和广泛的Xcode自动化排除在项目范围之外。

快速开始

cargo install seiro-mcp --locked
seiro-mcp config mcp
seiro-mcp config project

粘贴输出 seiro-mcp config mcp 进入Codex CLI配置(~/.codex/config.toml).
跑 seiro-mcp config project 从目标项目根目录开始。
编辑 seiro-mcp.toml 以允许目标项目路径和方案。
重新启动MCP客户端并使用visionOS工具。

现在，您可以要求Codex使用Seiro MCP构建您的visionOS项目。

可选的Codex技能设置：

seiro-mcp skill install

安装

先决条件

Rust 1.91.1（推荐 rustup override set 1.91.1)
货物（ cargo 命令必须可用）
Codex CLI
任何MCP客户端（例如，官方MCP CLI/Inspector）
git, bash/zsh

如果DevToolsSecurity已禁用，请先启用它：

$ DevToolsSecurity -status
Developer mode is currently disabled.

$ sudo DevToolsSecurity -enable

1.从crates.io安装

cargo install seiro-mcp --locked

升级到v0.5.1

如果您已经安装了早期版本，请升级到 v0.5.1 与：

cargo install seiro-mcp --locked --force --version 0.5.1
seiro-mcp --version

发布历史和升级说明发布在 GitHub发布.

升级后刷新捆绑技能指南：

seiro-mcp skill remove seiro-mcp-visionos-build-operator
seiro-mcp skill install

2.准备Codex和项目配置

（参见 docs/config.md 详情）

生成Codex端MCP代码段：

seiro-mcp config mcp

将输出粘贴到Codex配置中(~/.codex/config.toml):

[mcp_servers.seiro_mcp]
command = "/Users/<user>/.cargo/bin/seiro-mcp"

然后从目标项目根创建项目本地Seiro MCP配置：

seiro-mcp config project

这创造了 seiro-mcp.toml:

[visionos]
allowed_paths = []
allowed_schemes = []
xcode_path = "/Applications/Xcode.app/Contents/Developer"

MCP_CONFIG_PATH 和 --config 仍然可用于非默认配置位置。当两者均未设置时，Seiro MCP读取 seiro-mcp.toml 从进程当前目录。

3.可选：安装并运行捆绑技能

seiro-mcp skill install --dry-run
seiro-mcp skill install

捆绑技能名称使用 seiro-mcp- 前缀以避免冲突。
捆绑的技能规范源代码是 .agents/skills/seiro-mcp-visionos-build-operator/，包括 SKILL.md, agents/openai.yaml，以及图标资产 .agents/skills/seiro-mcp-visionos-build-operator/assets/.
使用 seiro-mcp skill remove seiro-mcp-visionos-build-operator 回滚。
skill remove 回报 not_found 当技能已经不存在时，不会失败。
验证与的兼容性 seiro-mcp --version 在技能操作之前。
对于该释放线， seiro-mcp skill install 默认为 seiro-mcp-visionos-build-operator。仍然支持显式传递该技能名称。
seiro-mcp skill install 将捆绑的技能安装到本地Codex技能目录中，不安装Seiro MCP服务器二进制文件或配置MCP设置。
使用 seiro-mcp --help, seiro-mcp skill --help，以及 seiro-mcp --version 用于自我检查。
```
seiro-mcp --help
seiro-mcp skill --help
seiro-mcp skill install --help
```

Codex的替代GitHub安装路径 skill-installer:

使用Codex skill-installer 当您想直接从公共GitHub存储库安装技能时，请使用以下参数：
- --repo karad/seiro-mcp
- --path .agents/skills/seiro-mcp-visionos-build-operator
这只安装Codex技能文件。你仍然需要 seiro-mcp 二进制加MCP服务器配置(seiro-mcp config mcp 和 seiro-mcp config project).

用法

使用Codex CLI

在Codex CLI配置中添加以下条目(~/.codex/config.toml)调用visionOS工具：

[mcp_servers.seiro_mcp]
command = "/Users/<your-username>/.cargo/bin/seiro-mcp"

Codex CLI不扩展 ${HOME}，因此使用绝对路径并替换 <your-username>.
更喜欢 seiro-mcp config mcp 使用实际安装的二进制路径打印此代码段。
默认情况下，Seiro MCP读取 seiro-mcp.toml 从项目当前目录。
重新启动Codex CLI并确认 mcp list 显示了visionOS工具。

运作原理

1.通过MCP客户端启动服务器

MCP客户端必须将服务器作为子进程生成，并通过stdio执行RMCP握手。跑步 cargo run 直接没有客户端将立即失败。

检查员示例：

npx @modelcontextprotocol/inspector seiro-mcp

如果需要非默认配置路径，请传递 MCP_CONFIG_PATH=/absolute/path/to/seiro-mcp.toml.
如果您是从源代码开发的，请构建二进制文件并通过MCP客户端启动它。

2.在构建之前验证沙盒策略

mcp call validate_sandbox_policy '{
    "project_path": "/Users/<user>/codex/workspaces/vision-app",
    "required_sdks": ["visionOS", "visionOS Simulator"],
    "xcode_path": "/Applications/Xcode.app/Contents/Developer"
}'

如果 status: "ok"，继续 build_visionos_app.
如果 status: "error" 或MCP错误，根据代码修复：
- path_not_allowed：将项目父目录添加到 visionos.allowed_paths.
- sdk_missing：第一次检查 details.diagnostics (probe_mode, effective_required_sdks, detected_sdks_raw, detected_sdks_normalized)，然后从Xcode>设置>平台安装visionOS SDK。
- devtools_security_disabled：run DevToolsSecurity -enable.
- xcode_unlicensed：run sudo xcodebuild -license.
- disk_insufficient：确保20GB+的可用空间用于构建。

构建前可选的飞行前准备：

mcp call inspect_xcode_sdks '{
    "required_sdks": ["visionOS", "visionOS Simulator"],
    "xcode_path": "/Applications/Xcode.app/Contents/Developer"
}'

此只读工具返回 missing_required_sdks 以及用于沙盒验证的相同SDK探测上下文。
建议的故障排除顺序： validate_sandbox_policy 诊断-> inspect_xcode_sdks （可选）->重试验证/构建。

构建前可选方案发现：

mcp call inspect_xcode_schemes '{
    "project_path": "/Users/<user>/codex/workspaces/VisionApp/VisionApp.xcodeproj",
    "xcode_path": "/Applications/Xcode.app/Contents/Developer"
}'

在以下情况下使用此功能 project_path 或 scheme 未知。
如果 project_path 省略，解析顺序为：
1. .xcodeproj 在当前工作目录中发现
2. visionos.default_project_path 在 seiro-mcp.toml

3.开始构建 `build_visionos_app`

mcp call build_visionos_app '{
    "project_path": "/Users/<user>/codex/workspaces/VisionApp/VisionApp.xcodeproj",
    "scheme": "VisionApp",
    "destination": "platform=visionOS Simulator,name=Apple Vision Pro",
    "configuration": "debug",
    "extra_args": ["-quiet"],
    "env_overrides": {"MOCK_XCODEBUILD_BEHAVIOR": "success"}
}'

project_path / workspace 必须是内的绝对路径 visionos.allowed_paths.
scheme 必须列在 visionos.allowed_schemes.
configuration 应使用小写规范值： debug 或 release为了兼容性， Debug / Release 也被接受。
允许 extra_args: -quiet, -UseModernBuildSystem=YES, -skipPackagePluginValidation, -allowProvisioningUpdates.
MOCK_XCODEBUILD_BEHAVIOR 切换测试夹具(tests/fixtures/visionos/mock-xcodebuild.sh)在 success / fail / timeout.
成功，回报 job_id, artifact_path, artifact_sha256, log_excerpt, duration_ms；失败时，返回错误，例如 build_failed 或 timeout.
如果多个模拟器与目的地名称匹配， build_visionos_app 回报 destination_ambiguous 与 matched_devices, available_destinations，并准备重试 suggested_destination.

如果构建失败，请在不运行手动shell命令的情况下检查诊断：

mcp call inspect_build_diagnostics '{
    "job_id": "<UUID returned in build error context>",
    "include_log_excerpt": true,
    "prefer_typecheck": true
}'

availability: "available" 回报 primary_location (file, line, column)来自类型检查诊断。
availability: "unavailable" 回落到a xcodebuild_log 带注释的总结。

4.下载工件 `fetch_build_output`

mcp call fetch_build_output '{
    "job_id": "<UUID returned by build_visionos_app>",
    "include_logs": true
}'

artifact_zip 指向 target/visionos-builds/<job_id>/artifact.zip；复制之前 download_ttl_seconds 到期。
集 include_logs: false 省略 log_excerpt 并降低客户端的噪声。

技能支持

Seiro MCP仅保持MCP流量不变。您可以选择以下任一模式：

MCP专用模式：呼叫 validate_sandbox_policy / build_visionos_app / inspect_build_diagnostics （失败时）/ fetch_build_output 直接。
技能辅助模式：使用 seiro-mcp-visionos-build-operator 熟练掌握Xcode/visionOS项目工作流程，因此Codex更喜欢Seiro MCP而不是直接 xcodebuild / swiftc.
如果 project_path 或 scheme 在技能辅助模式下缺失，请运行 inspect_xcode_schemes 首先作为可选的飞行前准备。
在本地发现项目时，请记住 .xcodeproj 和 .xcworkspace 是目录包。不要依赖仅文件搜索，例如 rg --files 决定他们缺席。

此存储库中的技能路径：

.agents/skills/seiro-mcp-visionos-build-operator/SKILL.md

从CLI安装：

seiro-mcp skill install --dry-run
seiro-mcp skill install

使用Codex从GitHub安装 skill-installer:

--repo karad/seiro-mcp
--path .agents/skills/seiro-mcp-visionos-build-operator

提示示例：

Use seiro-mcp-visionos-build-operator for this visionOS build task.
Please run this using the seiro-mcp-visionos-build-operator skill.
Use Seiro MCP for this Xcode project instead of direct xcodebuild.

重要提示：

技能提供编排指导。
MCP提供执行能力。
在技能辅助模式下，实际执行仍然是MCP工具调用，合同不变。
从GitHub安装技能或 seiro-mcp skill install 不安装Seiro MCP服务器二进制文件或配置MCP客户端连接。
对于Xcode/visionOS项目任务，直接使用shell xcodebuild / swiftc 应将其视为回退路径，而不是默认路径。

跑步

服务器必须由MCP客户端作为子进程启动；跑步 cargo run 直接失败 MCP_CLIENT_REQUIRED （出口44）。
Seiro MCP目前支持本地stdio MCP启动。TCP模式不是支持的本地工作流的一部分。
看 docs/runbook.md 了解完整的创业秘诀。

启动模式

--config / MCP_CONFIG_PATH: --config 胜利；否则 MCP_CONFIG_PATH -> ./seiro-mcp.toml （相对路径解析为绝对路径）。
默认的本地Codex工作流不需要设置令牌。
退出代码：
- 44: MCP_CLIENT_REQUIRED （stdin/stdout是一个TTY；必须通过MCP客户端启动）
有关详细信息，请参阅Runbook部分“关机程序和退出代码”。

故障排除

未找到配置文件：run seiro-mcp config project 在项目根目录或设置绝对值 MCP_CONFIG_PATH.
MCP_CLIENT_REQUIRED：运行时发生 cargo run 直接；始终通过MCP客户端（检查器/Codex等）启动。
seiro-mcp: command not found：验证安装和使用 seiro-mcp config mcp 打印Codex MCP代码段。
path_not_allowed：将项目父级添加到 visionos.allowed_paths 并重新启动。
scheme_not_allowed：将方案添加到 visionos.allowed_schemes 并重新启动。
sdk_missing：检查 details.diagnostics 第一；如果 probe_mode 是 env，验证 VISIONOS_SANDBOX_SDKS。然后跑 inspect_xcode_sdks 并在SDK/config修复后重试。
build_failed：使用 job_id 从结构化错误和调用 inspect_build_diagnostics 在重试之前识别文件/行。

参考文献

visionOS快速入门： docs/quickstart.md
runbook： docs/runbook.md
配置详细信息： docs/config.md

动机

随着AI编码代理的能力越来越强，它们也需要可靠的方式与本地开发环境进行交互。现有的解决方案通常旨在公开广泛的Xcode功能，但许多自主开发任务只需要这些功能中一小部分定义良好的子集。

Seiro MCP从一个简单的想法开始：只提供人工智能辅助visionOS开发实际需要的工具，并使这些工具可靠、安全、易于人工智能代理使用。Seiro MCP不是一个功能齐全的Xcode自动化服务器，而是一个专注的开发伙伴，帮助AI代理构建、验证、检查诊断并支持空间计算项目。

长期愿景是将Seiro MCP发展成为一系列精心设计的开发人员工具，在保持其轻量级理念的同时，改善visionOS和空间计算的人工智能辅助开发。

路线图

Seiro MCP将继续发展成为人工智能辅助空间计算工作的重点开发工具包。计划的方向包括：

其他visionOS开发工具
项目分析工具
visionOS的其他开发工作流程
Swift包支持
更好的AI代理工作流程指导
更多空间计算开发工具

路线图仍然与轻量级理念保持一致：Seiro MCP应该为AI代理提供正确的开发工具，而不是成为功能齐全的Xcode MCP服务器。

贡献

目录布局

src/
  lib/            # shared logic: errors, telemetry, filesystem helpers
  server/         # config + RMCP runtime
  tools/          # visionOS tools
tests/
  integration/    # integration tests (separate crate)
docs/             # configuration, runbook, review checklists

对于贡献者（克隆+本地构建）

如果您正在开发此存储库本身，请使用克隆流：

git clone git@github.com:karad/seiro-mcp.git
cd seiro-mcp
cargo fetch
cargo run -p xtask -- langscan
cargo run -p xtask -- docs-langscan
cargo run -p xtask -- check-docs-links
cargo run -p xtask -- preflight

如果任何步骤失败，请修复并重新运行。

关于成功， target/release/seiro-mcp 生产。

维护人员（发布准备就绪）

之前 cargo publish，运行：

cargo check
cargo test --all -- --nocapture
cargo fmt -- --check
cargo clippy -- -D warnings
cargo build --release
cargo package --list
cargo publish --dry-run

--locked 建议用于再现性，但并非所有环境都是强制性的。

测试和质量门

首选： cargo run -p xtask -- preflight （按顺序运行fetch/check/test/fmt/clippy/build）。
手册： cargo fetch -> cargo check -> cargo test --all -> cargo fmt -- --check -> cargo clippy -- -D warnings -> cargo build --release.
单元测试 src/server/config/mod.rs 覆盖配置验证（成功和错误案例）。
tests/integration/visionos_build.rs 覆盖 validate_sandbox_policy, build_visionos_app, inspect_build_diagnostics，以及 fetch_build_output，包括TTL行为。

开源

许可证： LICENSE
贡献： CONTRIBUTING.md
行为准则： CODE_OF_CONDUCT.md
安全： SECURITY.md