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.

Features

• 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

Why Seiro MCP?

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.

Motivation

As AI coding agents become more capable, they also need reliable ways to interact with local development environments. Existing solutions often aim to expose broad Xcode functionality, but many autonomous development tasks require only a small, well-defined subset of those capabilities.

Seiro MCP started from a simple idea: provide only the tools that are actually needed for AI-assisted visionOS development, and make those tools reliable, secure, and easy for AI agents to use. Rather than becoming a full-featured Xcode automation server, Seiro MCP is designed to be a focused development companion that helps AI agents build, validate, inspect diagnostics, and support spatial computing projects.

The long-term vision is to grow Seiro MCP into a collection of carefully designed developer tools that improve AI-assisted development for visionOS and spatial computing while preserving its lightweight philosophy.

Roadmap

Seiro MCP will continue to grow as a focused development toolkit for AI-assisted spatial computing work. Planned directions include:

• Additional visionOS developer tools
• Project analysis utilities
• Additional development workflows for visionOS
• Swift Package support
• Better AI agent workflow guidance
• More spatial computing developer utilities

The roadmap remains aligned with the lightweight philosophy: Seiro MCP should expose the right development tools for AI agents, not become a full-featured Xcode MCP server.

Quick Start

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

1. Paste the output of seiro-mcp config mcp into Codex CLI config (~/.codex/config.toml).
2. Run seiro-mcp config project from the target project root.
3. Edit seiro-mcp.toml to allow the target project paths and schemes.
4. Restart the MCP client and use the visionOS tools.

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

Optional Codex Skill setup:

seiro-mcp skill install

Installation

Prerequisites

• Rust 1.91.1 (recommend rustup override set 1.91.1)
• Cargo (the cargo command 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

1. Install from crates.io

cargo install seiro-mcp --locked

Upgrade to v0.5.0

If you already installed an earlier version, upgrade to v0.5.0 with:

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

To refresh bundled skill guidance after upgrading:

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

2. Prepare Codex and project config

(see docs/config.md for details)

Generate the Codex-side MCP snippet:

seiro-mcp config mcp

Paste the output into Codex config (~/.codex/config.toml):

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

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

seiro-mcp config project

This creates seiro-mcp.toml:

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

MCP_CONFIG_PATH and --config remain available for non-default config locations. When neither is set, Seiro MCP reads seiro-mcp.toml from 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 the seiro-mcp- prefix to avoid collisions.
• The bundled skill canonical source is .agents/skills/seiro-mcp-visionos-build-operator/, including SKILL.md, agents/openai.yaml, and icon assets under .agents/skills/seiro-mcp-visionos-build-operator/assets/.
• Use seiro-mcp skill remove seiro-mcp-visionos-build-operator to roll back.
• skill remove returns not_found without failing when the skill is already absent.
• Verify compatibility with seiro-mcp --version before skill operations.
• For this release line, seiro-mcp skill install defaults to seiro-mcp-visionos-build-operator. Passing that skill name explicitly is still supported.
• seiro-mcp skill install installs the bundled skill into the local Codex skills directory and does not install the Seiro MCP server binary or configure MCP settings.
• Use seiro-mcp --help, seiro-mcp skill --help, and seiro-mcp --version for self-check.
  Copy

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

Alternative GitHub install path for Codex skill-installer:

• Use Codex skill-installer with 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
• This installs only the Codex skill files. You still need the seiro-mcp binary plus MCP server configuration (seiro-mcp config mcp and seiro-mcp config project).

Usage

Using from Codex CLI

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>.
• Prefer seiro-mcp config mcp to print this snippet with the actual installed binary path.
• By default, Seiro MCP reads seiro-mcp.toml from the project current directory.
• Restart Codex CLI and confirm mcp list shows the visionOS tools.

How It Works

1. Launch the server via an MCP client

• The MCP client must spawn the server as a child process and perform the RMCP handshake over stdio. Running cargo run directly without a client will fail immediately.
• Example with Inspector:
  Copy

  npx @modelcontextprotocol/inspector seiro-mcp

• If you need a non-default config path, pass MCP_CONFIG_PATH=/absolute/path/to/seiro-mcp.toml.
• If you are developing from source, build the binary and launch it through an MCP client.

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

• If status: "ok", proceed to build_visionos_app.
• If status: "error" or an MCP error, fix based on the code:
  • path_not_allowed: add the project parent directory to visionos.allowed_paths.
  • sdk_missing: first inspect details.diagnostics (probe_mode, effective_required_sdks, detected_sdks_raw, detected_sdks_normalized), then install visionOS SDK from Xcode > Settings > Platforms.
  • devtools_security_disabled: run DevToolsSecurity -enable.
  • xcode_unlicensed: run sudo xcodebuild -license.
  • disk_insufficient: ensure 20GB+ free space for the build.

Optional preflight before build:

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

• This read-only tool returns missing_required_sdks and the same SDK probe context used for sandbox validation.
• Recommended troubleshooting order: validate_sandbox_policy diagnostics -> inspect_xcode_sdks (optional) -> retry validate/build.

Optional scheme discovery before build:

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

• Use this when project_path or scheme is unknown.
• If project_path is omitted, resolution order is:
  1. .xcodeproj discovered in current working directory
  2. visionos.default_project_path in seiro-mcp.toml

3. Start a build with 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 must be absolute paths within visionos.allowed_paths.
• scheme must be listed in visionos.allowed_schemes.
• configuration should use lowercase canonical values: debug or release. For compatibility, Debug / Release are also accepted.
• Allowed extra_args: -quiet, -UseModernBuildSystem=YES, -skipPackagePluginValidation, -allowProvisioningUpdates.
• MOCK_XCODEBUILD_BEHAVIOR switches the test fixture (tests/fixtures/visionos/mock-xcodebuild.sh) among success / fail / timeout.
• On success, returns job_id, artifact_path, artifact_sha256, log_excerpt, duration_ms; on failure, returns errors such as build_failed or timeout.
• If multiple simulators match the destination name, build_visionos_app returns destination_ambiguous with matched_devices, available_destinations, and a retry-ready suggested_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" returns primary_location (file, line, column) from typecheck diagnostics.
• availability: "unavailable" falls back to an xcodebuild_log summary with notes.

4. Download artifacts with fetch_build_output

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

• artifact_zip points to target/visionos-builds/<job_id>/artifact.zip; copy it before download_ttl_seconds expires.
• Set include_logs: false to omit log_excerpt and reduce noise on the client side.

Skills Support

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

• MCP-only mode: call validate_sandbox_policy / build_visionos_app / inspect_build_diagnostics (on failure) / fetch_build_output directly.
• Skill-assisted mode: use the seiro-mcp-visionos-build-operator skill for Xcode / visionOS project workflows so Codex prefers Seiro MCP over direct xcodebuild / swiftc.
• If project_path or scheme is missing in skill-assisted mode, run inspect_xcode_schemes first as optional preflight.
• When discovering a project locally, remember that .xcodeproj and .xcworkspace are directory packages. Do not rely on file-only searches such as rg --files to decide they are absent.

Skill path in this repository:

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

Install from CLI:

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

Install from GitHub with Codex skill-installer:

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

Prompt examples:

• 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.

Important:

• 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 or seiro-mcp skill install does not install the Seiro MCP server binary or configure the MCP client connection.
• For Xcode / visionOS project tasks, direct shell xcodebuild / swiftc should be treated as fallback paths, not the default path.

Running

• The server must be launched as a child process by an MCP client; running cargo run directly will fail with MCP_CLIENT_REQUIRED (exit 44).
• Seiro MCP currently supports local stdio MCP startup. TCP mode is not part of the supported local workflow.
• See docs/runbook.md for the full startup recipe.

Startup Mode

• --config / MCP_CONFIG_PATH: --config wins; otherwise MCP_CONFIG_PATH -> ./seiro-mcp.toml (relative paths are resolved to absolute).
• Token setup is not required for the default local Codex workflow.
• Exit codes:
  • 44: MCP_CLIENT_REQUIRED (stdin/stdout is a TTY; must be launched via MCP client)
• See the Runbook section "Shutdown procedure and exit codes" for details.

Troubleshooting

• Config file not found: run seiro-mcp config project in the project root or set an absolute MCP_CONFIG_PATH.
• MCP_CLIENT_REQUIRED: occurs when running cargo run directly; always launch via an MCP client (Inspector / Codex, etc.).
• seiro-mcp: command not found: verify installation and use seiro-mcp config mcp to print the Codex MCP snippet.
• path_not_allowed: add the project parent to visionos.allowed_paths and restart.
• scheme_not_allowed: add the scheme to visionos.allowed_schemes and restart.
• sdk_missing: check details.diagnostics first; if probe_mode is env, verify VISIONOS_SANDBOX_SDKS. Then run inspect_xcode_sdks and retry after SDK/config fixes.
• build_failed: use job_id from the structured error and call inspect_build_diagnostics to identify file/line before retrying.

References

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