AI agent context for the mcp-sim Go project (mobile emulator lifecycle MCP server).
mcp-sim is an MCP server for managing iOS Simulator and Android Emulator lifecycle, runnable on macOS, Linux, or Windows. Built-in adapters for iOS (xcrun simctl, macOS-only — requires Xcode), Android (emulator + adb, cross-platform), and agent-device controller (cross-platform).
We use a GitHub project as project backlog.
Issues #1–#21 cover M1 milestone tasks. M2 hardening tracked separately.
v0.2.0 — cross-platform support (Windows/Linux), native service install, hosted doc site. Branch main holds released commits. Use develop for
new work. Versions live in internal/version/version.go and are injected at
build time via -ldflags "-X .../internal/version.Version=...".
| Document | Purpose |
|---|---|
docs/architecture.md |
Adapter model + separation of concerns |
docs/tailscale.md |
Network deployment over Tailscale |
docs/service.md |
Running mcp-sim as a native OS service (launchd/systemd/Windows Service) |
docs/adding-platform.md |
Implementing new Platform adapters |
CONTRIBUTING.md |
PR process + load-bearing separation rule |
pkg/contract/platform.go |
Platform interface |
pkg/contract/controller.go |
Controller interface |
- Run validate:
task validate(typecheck + lint + test) - Build:
task buildproducesbin/mcp-sim - Run locally:
task run -- --listen :9090 - Read per-package docs before modifying adapters
- Atomic commits: each commit is a single self-contained logical change
- Conventional commit format (feat:, fix:, chore:, docs:, ci:)
- Pass CI locally before committing
main: protected, release commits onlydevelop: integration branch, feature branches merge hererelease/vX.Y.Z: release brancheshotfix/vX.Y.Z: emergency fixes from main
- Language: Go 1.25+
- MCP:
github.com/modelcontextprotocol/go-sdkv1.6+ - Config:
gopkg.in/yaml.v3+ stdlibos.Getenv - Logging: stdlib
log/slog - HTTP: stdlib
net/http(1.22+ServeMux)
cmd/mcp-sim/ Entry point: serve | mcp | version
pkg/contract/ Platform + Controller interfaces (public)
pkg/mcp/ MCP server wiring (public)
internal/config/ CLI > env > file > default resolution
internal/log/ slog wrapper
internal/http/ HTTP server with graceful shutdown
internal/core/ Registry, lifecycle, tool handlers
platforms/ios/ iOS Simulator adapter (xcrun simctl)
platforms/android/ Android Emulator adapter (emulator + adb)
controllers/agentdevice/ agent-device proxy adapter