Seiro MCP

Lightweight visionOS Build MCP for AI Coding Agents

Seiro MCP is a lightweight MCP server focused on visionOS development workflows for AI coding agents. It enables Codex CLI and other MCP clients to safely build, validate, and inspect visionOS projects through a dedicated set of MCP tools.

The goal of Seiro MCP is not to expose every Xcode capability. Instead, it intentionally focuses on the developer workflows that AI coding agents perform most frequently during day-to-day development. Today it provides visionOS build tools together with bundled Codex skill guidance, and over time it will expand with additional developer-focused utilities for spatial computing while remaining focused on development rather than release management.

- Focused visionOS development workflows for AI coding agents
- Safe build automation through explicit project constraints
- AI-friendly MCP interface for build, diagnostics, and artifacts
- Codex Skill integration for preferred visionOS build operation
- Predictable local development workflow
- Written in Rust

General-purpose Xcode automation is powerful, but AI coding agents usually need a focused subset of development operations: validate the environment, build a project, inspect failures, and retrieve artifacts.

Seiro MCP keeps that interface intentionally small. Smaller MCP tool surfaces are easier for agents to reason about, easier for humans to review, and safer to run in local development environments. The project prioritizes predictable developer workflows over release automation, signing orchestration, or full Xcode replacement.

Lightweight does not mean fewer features. It means exposing the right capabilities for AI-assisted development while deliberately leaving release-oriented workflows, signing orchestration, and broad Xcode automation outside the project's scope.

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

- Paste the output ofseiro-mcp config mcpinto Codex CLI config (~/.codex/config.toml).
- Runseiro-mcp config projectfrom the target project root.
- Editseiro-mcp.tomlto allow the target project paths and schemes.
- Restart the MCP client and use the visionOS tools.

You are now ready to ask Codex to build your visionOS project with Seiro MCP.

- Rust 1.91.1 (recommendrustup override set 1.91.1)
- Cargo (thecargocommand must be available)
- Codex CLI
- Any MCP client (e.g., official MCP CLI / Inspector)
- git,bash/zsh

If DevToolsSecurity is disabled, enable it first:

$ DevToolsSecurity -status Developer mode is currently disabled. $ sudo DevToolsSecurity -enable

If you already installed an earlier version, upgrade tov0.5.1with:

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

Release history and upgrade notes are published inGitHub Releases.

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

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

Then create the project-local Seiro MCP config from the target project root:

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

MCP_CONFIG_PATHand--configremain available for non-default config locations. When neither is set, Seiro MCP readsseiro-mcp.tomlfrom the process current directory.

3. Optional: install and run bundled skill

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

- The bundled skill name uses theseiro-mcp-prefix to avoid collisions.
- The bundled skill canonical source is.agents/skills/seiro-mcp-visionos-build-operator/, includingSKILL.md,agents/openai.yaml, and icon assets under.agents/skills/seiro-mcp-visionos-build-operator/assets/.
- Useseiro-mcp skill remove seiro-mcp-visionos-build-operatorto roll back.
- skill removereturnsnot_foundwithout failing when the skill is already absent.
- Verify compatibility withseiro-mcp --versionbefore skill operations.
- For this release line,seiro-mcp skill installdefaults toseiro-mcp-visionos-build-operator. Passing that skill name explicitly is still supported.
- seiro-mcp skill installinstalls the bundled skill into the local Codex skills directory and does not install the Seiro MCP server binary or configure MCP settings.
- Useseiro-mcp --help,seiro-mcp skill --help, andseiro-mcp --versionfor self-check.

seiro-mcp --help seiro-mcp skill --help seiro-mcp skill install --help

Alternative GitHub install path for Codexskill-installer:

- Use Codexskill-installerwith these arguments when you want to install the skill directly from the public GitHub repository:

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

Add an entry like the following to Codex CLI config (~/.codex/config.toml) to call the visionOS tools:

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

- Codex CLI does not expand${HOME}, so use absolute paths and replace<your-username>.
- Preferseiro-mcp config mcpto print this snippet with the actual installed binary path.
- By default, Seiro MCP readsseiro-mcp.tomlfrom the project current directory.
- Restart Codex CLI and confirmmcp listshows the visionOS tools.

- The MCP client must spawn the server as a child process and perform the RMCP handshake over stdio. Runningcargo rundirectly without a client will fail immediately.
- Example with Inspector:

npx @modelcontextprotocol/inspector seiro-mcp

2. Validate sandbox policy before building

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" }'

- Ifstatus: "ok", proceed tobuild_visionos_app.
- Ifstatus: "error"or an MCP error, fix based on the code:

- path_not_allowed: add the project parent directory tovisionos.allowed_paths.
- sdk_missing: first inspectdetails.diagnostics(probe_mode,effective_required_sdks,detected_sdks_raw,detected_sdks_normalized), then install visionOS SDK from Xcode > Settings > Platforms.
- devtools_security_disabled: runDevToolsSecurity -enable.
- xcode_unlicensed: runsudo xcodebuild -license.
- disk_insufficient: ensure 20GB+ free space for the build.

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

- This read-only tool returnsmissing_required_sdksand the same SDK probe context used for sandbox validation.
- Recommended troubleshooting order:validate_sandbox_policydiagnostics ->inspect_xcode_sdks(optional) -> retry validate/build.

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

- Use this whenproject_pathorschemeis unknown.
- Ifproject_pathis omitted, resolution order is:
- .xcodeprojdiscovered in current working directory
- visionos.default_project_pathinseiro-mcp.toml

3. Start a build withbuild_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/workspacemust be absolute paths withinvisionos.allowed_paths.
- schememust be listed invisionos.allowed_schemes.
- configurationshould use lowercase canonical values:debugorrelease. For compatibility,Debug/Releaseare also accepted.
- Allowedextra_args:-quiet,-UseModernBuildSystem=YES,-skipPackagePluginValidation,-allowProvisioningUpdates.
- MOCK_XCODEBUILD_BEHAVIORswitches the test fixture (tests/fixtures/visionos/mock-xcodebuild.sh) amongsuccess/fail/timeout.
- On success, returnsjob_id,artifact_path,artifact_sha256,log_excerpt,duration_ms; on failure, returns errors such asbuild_failedortimeout.
- If multiple simulators match the destination name,build_visionos_appreturnsdestination_ambiguouswithmatched_devices,available_destinations, and a retry-readysuggested_destination.

If a build fails, inspect diagnostics without running manual shell commands:

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

- availability: "available"returnsprimary_location(file,line,column) from typecheck diagnostics.
- availability: "unavailable"falls back to anxcodebuild_logsummary with notes.

4. Download artifacts withfetch_build_output

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

- artifact_zippoints totarget/visionos-builds/<job_id>/artifact.zip; copy it beforedownload_ttl_secondsexpires.
- Setinclude_logs: falseto omitlog_excerptand reduce noise on the client side.

Seiro MCP keeps the MCP-only flow unchanged. You can choose either mode:

- MCP-only mode: callvalidate_sandbox_policy/build_visionos_app/inspect_build_diagnostics(on failure) /fetch_build_outputdirectly.
- Skill-assisted mode: use theseiro-mcp-visionos-build-operatorskill for Xcode / visionOS project workflows so Codex prefers Seiro MCP over directxcodebuild/swiftc.
- Ifproject_pathorschemeis missing in skill-assisted mode, runinspect_xcode_schemesfirst as optional preflight.
- When discovering a project locally, remember that.xcodeprojand.xcworkspaceare directory packages. Do not rely on file-only searches such asrg --filesto decide they are absent.

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

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

Install from GitHub with Codexskill-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.

- Skills provide orchestration guidance.
- MCP provides execution capability.
- In skill-assisted mode, the actual execution remains MCP tool calls with unchanged contracts.
- Installing the skill from GitHub orseiro-mcp skill installdoes not install the Seiro MCP server binary or configure the MCP client connection.
- For Xcode / visionOS project tasks, direct shellxcodebuild/swiftcshould be treated as fallback paths, not the default path.

- The server must be launched as a child process by an MCP client; runningcargo rundirectly will fail withMCP_CLIENT_REQUIRED(exit 44).
- Seiro MCP currently supports local stdio MCP startup. TCP mode is not part of the supported local workflow.
- Seedocs/runbook.mdfor the full startup recipe.

- visionOS quickstart:docs/quickstart.md
- runbook:docs/runbook.md
- Configuration details:docs/config.md

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

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

- License:LICENSE
- Contributing:CONTRIBUTING.md
- Code of Conduct:CODE_OF_CONDUCT.md
- Security:SECURITY.md

Remote, no-auth MCP server providing AI-powered codebase context and answers