Seiro MCP Docs

Seiro MCP spatial computing server and visionOS build tools

View the Project on GitHub karad/seiro-mcp

Quickstart

This repository ships the visionOS build MCP server. Follow these steps to finish cargo check → cargo test --all → cargo fmt -- --check → cargo build --release within ~30 minutes on a fresh machine and call the visionOS tools (inspect_xcode_schemes / validate_sandbox_policy / inspect_build_diagnostics / build_visionos_app / fetch_build_output) from an MCP client.

Prerequisites

Installation

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

--locked is recommended for reproducibility, but not mandatory for all environments.

2. Prepare config.toml

(see docs/config.md for details)

Switching configs with MCP_CONFIG_PATH

3. Optional: install bundled skill

seiro-mcp skill install seiro-mcp-visionos-build-operator --dry-run
seiro-mcp skill install seiro-mcp-visionos-build-operator

Alternative GitHub install path for Codex skill-installer:

4. Contributor-only build checks

If you are contributing to this repository, run:

cargo fetch
cargo check
cargo test --all -- --nocapture
cargo fmt -- --check
cargo clippy -- -D warnings
cargo build --release

Additional repository checks:

cargo run -p xtask -- langscan
cargo run -p xtask -- docs-langscan
cargo run -p xtask -- check-docs-links

5. Maintainer publish readiness (before cargo publish)

cargo package --list
cargo publish --dry-run

Use this sequence only when preparing a crates.io release.

If any step fails, fix and rerun.

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"
args = ["--transport=stdio"]
env.MCP_CONFIG_PATH = "/absolute/path/to/config.toml"
env.MCP_SHARED_TOKEN = "change-me-please"
working_directory = "/absolute/path/to/working-directory"

How It Works

1. Launch the server via 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"
}'

Optional read-only SDK inspection:

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

Optional scheme preflight:

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

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

If build fails and returns job_id, inspect diagnostics without running shell commands manually:

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

4. Download artifacts with fetch_build_output

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

Skill-assisted flow (Seiro MCP preferred for Xcode / visionOS)

You can run the same build flow with the bundled skill:

When to choose which mode:

Prompt examples:

If you installed the skill from GitHub with skill-installer, remember that the skill alone is not enough. The Seiro MCP server binary and client-side MCP configuration must still be installed separately.

The skill still executes the same MCP tools in order:

  1. inspect_xcode_schemes (when project or scheme discovery is needed)
  2. validate_sandbox_policy
  3. build_visionos_app
  4. inspect_build_diagnostics (on failure)
  5. fetch_build_output (on success)

Optional preflight with skill:

Contracts and payload schemas stay unchanged.

Startup modes and auth tips

Troubleshooting

Symptom Resolution
CONFIG_MISSING_FIELD auth [auth].token is missing. Set a 16+ character value.
path_not_allowed Add the project’s parent directory to visionos.allowed_paths, then restart the server.
sdk_missing Check details.diagnostics, run inspect_xcode_sdks, then install/fix SDK settings and retry.
scheme_not_allowed Add the scheme to visionos.allowed_schemes and restart the server.
timeout Increase max_build_minutes or reduce project size/clean build.
artifact_expired Call fetch_build_output sooner or raise artifact_ttl_secs.

Logs and telemetry