2.10.3 • Published 1 week agoCLI

ios-agent-mcp

Licence

MIT

Version

2.10.3

Deps

Size

9.7 MB

Vulns

Weekly

Stars

Summary Dependency Versions

iOS Agent MCP

Explore the website · Choose your AI and install

Version 2.10.3: experimental native conversion

Adds the experimental Universal App IR pipeline: bounded HTML, React/TSX, static Vue and Svelte inputs can generate editable native SwiftUI projects. React includes supported literal props/defaults, primitive constants, typed syntax, controlled state/events and flat memory routes. Explicit centered horizontal rows share one native layout mapping. Unsupported syntax fails explicitly; imported application code is never executed.

Evidence comparison, resumable checks, reference approval and separately authorized baseline promotion remain distinct. This is not arbitrary framework conversion or a completed visual-fidelity/repair system. Native builds and simulator evidence cover specific fixtures, not every supported combination. Existing iOS build, review and readiness workflows remain available.

2.10.0 adds the /ios-build agent. Describe an app in one sentence and it plans the screens and capabilities, writes PLAN.md with a budget, creates the Xcode project, writes the SwiftUI code, builds and fixes errors (at most 8 attempts and 25 minutes per cycle), launches the app in the iOS Simulator, screenshots each screen and writes RUN_REPORT.md. Thirteen ios_* tools drive it, and 41 capability modules supply sign-in, payments, maps, charts, widgets and more. Every module is marked untested until its own verify run passes on a Mac. How the agent works and what has been verified.

Earlier releases added color generation and review, backend integration review, Apple system integrations, Screenshot Studio, layered app icons and dated Apple references. See the release notes for scope and evidence. User accounts, signing profiles and credentials are not package resources. Gemini CLI uses the repository extension; ChatGPT uses the skills package or a separately configured MCP connection. See the client setup guide.

One install, one MCP connection

Connect the published server and optionally install the Claude Code command:

claude mcp add ios-agent -- npx -y ios-agent-mcp@latest
npx -y ios-agent-mcp@latest install-command --global

The unified server includes source reviews, local references, simulator tools and build-agent tools. Optional AI/provider and environment workflows are additional CLI commands. App scaffolding and simulator packages install automatically as dependencies; no separate installation or MCP connection is needed. Remove the separate knowledge/simulator connections if you previously configured them to avoid duplicate tools.

Which entry point to use:

You want	Use
A whole app from a sentence, built and screenshotted	`/ios-build "<description>"` in Claude Code, or `ios-agent-mcp build "<description>"`
An editable starter and a brief, then build it yourself	`ios-agent-mcp new MyApp --brief "..." --xcodegen`
An existing project driven until your own checks pass	`ios-agent-mcp loop init --project PATH ...`

Requires Node.js 20 or later. Building and simulator operations require macOS and Xcode 16 or later. XcodeGen is optional: without it the built-in writer creates a folder-synchronized Xcode project. The default connection includes tools that write files and operate the simulator; review and reference tools remain read-only.

Website and quick start · GitHub source

Feedback from your terminal AI

For a confirmed, significant gap in this repository's iOS guidance or a package failure that blocks development, the connected AI can use prepare_issue_report to create and open a category-only GitHub draft. It excludes app code, prompts, logs, paths and credentials. The issue is public: review the draft and click Submit yourself. The tool does not submit issues. Ordinary bugs in your app are not sent as package feedback. Browse existing issues or open a bug report manually.

Local source retrieval in 2.4.0

The knowledge server now searches bundled repository source, templates and guides, outlines sections, and reads exact content with bounded output and continuation offsets. It exposes eight knowledge tools separately from the eleven analyzer tools. No runtime browsing is needed for local source retrieval. See offline source workflow.

New in 2.4.0: Apple knowledge tools for more clients

This package includes two MCP binaries: ios-agent-mcp for local Swift project analysis and ios-agent-knowledge for public Apple references and app/icon planning. Claude, Codex and Gemini CLI can run either over stdio. The knowledge server also supports Streamable HTTP for a hosted ChatGPT connection.

npx -y --package=ios-agent-mcp@2.4.0 ios-agent-knowledge

Knowledge tools search 405 technologies and 98 update/release-note sources, retrieve guides, plan an app implementation, and specify separate Icon Composer layers. They do not write apps, access arbitrary project paths or claim native icon generation. Setup.

ios-agent-mcp

An MCP server that reviews Swift projects against the rules in ios-agent-skill.

The skill teaches an agent how to write iOS code. This server lets an agent check it — ten tools that read a Swift project and report defects with a file, a line, the consequence, and the fix, plus one that lints a skill repository's own metadata.

You:  Review my Swift project for concurrency problems.

Claude → review_swift_concurrency

🔴 Sources/FeedModel.swift:3 — @Observable type is not @MainActor-isolated.
   Why: @Observable grants no isolation. SwiftUI reads this state during layout
        while any task may write it — a data race under Swift 5 mode, a compile
        error under Swift 6.
   Fix: Annotate the type: `@MainActor @Observable final class …`

Install

Choose your client: Claude · ChatGPT / Codex · Gemini CLI · Muse Code. One server package; client connection methods differ.

Claude Code

claude mcp add ios-agent -- npx -y ios-agent-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ios-agent": {
      "command": "npx",
      "args": ["-y", "ios-agent-mcp"]
    }
  }
}

ChatGPT / Codex

Codex connects to the local unified server:

codex mcp add ios-agent -- npx -y ios-agent-mcp@latest

ChatGPT has a different setup: use the skills-only release package where your account supports it, or configure a hosted HTTPS knowledge server/private MCP tunnel through a supported developer-mode flow. ChatGPT web does not run this local npx command itself. This project does not provide a public hosted endpoint. See the ChatGPT setup guide for account requirements and connection limits.

Gemini CLI

gemini mcp add ios-agent -- npx -y ios-agent-mcp@latest

This adds a local MCP connection; Gemini web chat is a different product. The repository extension additionally supplies GEMINI.md, but its version pin must be available on npm before installing it. Use one connection method to avoid duplicate tools. Gemini setup and verification.

Muse Code

Install outside the agent sandbox:

npm install -g ios-agent-mcp@latest

Merge this into ~/.config/muse/settings.json, preserving your existing settings:

{
  "schema_version": 1,
  "mcpServers": {
    "ios-agent": {
      "command": "ios-agent-mcp",
      "args": []
    }
  }
}

Restart Muse. If the executable is not found, use its absolute path from command -v ios-agent-mcp. MCP discovery and a Stop hook have been verified; complete model-driven app creation has not. Muse setup and evidence.

Other clients, including Cursor

Our primary client families are Claude, ChatGPT/Codex, Gemini CLI and Muse. Cursor and other MCP-compatible clients may use the generic mcpServers configuration shown above, but are not actively verified in this support scope. Request another client or vote on an existing issue.

From source

git clone https://github.com/Nagarjuna2997/ios-agent-skill.git
cd ios-agent-skill/mcp-server
npm install && npm run build
# then point your client at: node /absolute/path/to/mcp-server/dist/unified.js

Tools

Tool	Finds
`analyze_swift_project`	Structure — file counts, deployment target, frameworks, tests — plus finding counts per category. Start here.
`review_swift_concurrency`	`@Observable` without `@MainActor`, `Task.detached`, `DispatchQueue.main.async`, `@unchecked Sendable`, `nonisolated(unsafe)`, unstructured `Task` in `onAppear`, empty `catch`, a type named `Task`
`review_swift_architecture`	Live-implementation default arguments, presentation naming `URLSession`/`APIClient`/`ModelContext`, singletons in view models, domain importing SwiftUI, nested `NavigationStack`, `NavigationView`
`review_swiftui`	Fixed font sizes and heights, `AnyView`, `.cornerRadius`, literal spacing, materials over solid backgrounds, view state on models, `ObservableObject`, `@EnvironmentObject`, `try!`
`check_availability_guards`	Per-target deployment minima, scoped guards and annotations, bounded local compiler evidence, SDK-derived static fallback, and advisory over-restrictive guards
`audit_app_store_readiness`	Selected-target purpose strings, required-reason declarations, entitlement operations, export-compliance questions, optional metadata review, and launch configuration; unresolved evidence is explicit
`review_swift_memory`	Repeating `Timer` and `NotificationCenter` blocks capturing self, Combine sinks, non-`weak` delegates, stored closures, `unowned self`
`review_swift_security`	Hardcoded secrets, credentials in `UserDefaults`, disabled ATS, cleartext HTTP, TLS trust accepted without evaluation, MD5/SHA-1, Keychain accessibility
`review_swift_testing`	Test files only. Sleeping, tests with no assertion, live `URLSession`, `await` in an `XCTAssert` autoclosure, order-dependent static state
`review_swift_performance`	Formatters and collection work inside `body`, `ForEach` over indices, eager stacks in a `ScrollView`, blocking I/O on the render path
`lint_skill`	Skill metadata, not Swift. `SKILL.md` frontmatter, subagent `name`/filename mismatches, misspelled tool names, read-only agents granted `Edit` or `Write`, mirror files drifted from `SKILL.md`, broken doc references

Every tool takes one argument:

{ "path": "/absolute/path/to/your/project" }

The first ten want a Swift project root. lint_skill wants an Agent Skill repository root — the folder containing SKILL.md.

Every review tool also returns structuredContent — typed data with summary, score, counts, files_checked, issues, and suggestions — alongside the markdown, so a workflow can branch on a result without regexing prose.

Resources

Tools are verbs the model chooses to call. Resources are nouns a client can read without being asked, so a project's shape can be attached to context up front.

{
  "mcpServers": {
    "ios-agent": {
      "command": "npx",
      "args": ["-y", "ios-agent-mcp", "--project", "/absolute/path/to/project"]
    }
  }
}

Resource	Contains
`ios://project/info`	Counts, deployment target, UI framework, inferred architecture with its evidence, DI detection, frameworks
`ios://project/dependencies`	Third-party packages from `Package.swift` / `Package.resolved` / `Podfile`, plus Apple frameworks
`ios://project/issues`	Every finding across all nine categories, with counts by severity and category

The root comes from --project, then IOS_AGENT_PROJECT, then the working directory the client spawned the server in. Every payload reports which root it used, so an empty project is never mistaken for a wrong path.

Project resources remain read-only snapshots. Build, test and simulator actions are available as tools in the unified connection; they require macOS/Xcode.

What it does and does not do

Review tools: read project files without modifying them. App creation: writes a new starter. Simulator tools: build/test projects and operate devices; builds can fetch dependencies, and preview starts a loopback server.

Does not: prove your app builds or behaves correctly. Run swift build and swift test for that — the tools say so in their own output.

Findings are graded so you can triage:

	Meaning
blocker	Crashes, data races, or App Review rejection
serious	Real defect — untestable code, accessibility failure, deprecated API
minor	Maintainability and consistency

Test, mock, stub, and preview files are exempt from the app-code-only rules, and Package.swift is skipped — they legitimately do things app code must not.

Development

npm install
npm run build        # tsc
npm test             # 123 tests: unit + end-to-end over real MCP stdio
npm run typecheck

Analyzers are pure functions of (path, content) → Finding[], so they are tested without the MCP transport. test/server.smoke.test.js launches the real server and speaks the real protocol, because unit tests cannot tell you whether the server actually starts.

To add a rule: write the analyzer, then a test that fails without the rule. A test that passes either way is not a test.

Publishing (maintainers)

cd mcp-server
npm install          # REQUIRED FIRST — see below
npm login
npm publish

npm install is not optional. prepublishOnly runs npm run build && npm test, and build is tsc. On a fresh clone there is no node_modules, so the compiler is not present and publish fails with:

error TS2591: Cannot find name 'node:fs/promises'. Do you need to install
type definitions for node? Try `npm i --save-dev @types/node`

That is the guard working as intended — it refuses to publish an unbuilt package — but the fix is npm install, not disabling the hook.

After publishing, verify:

npm view ios-agent-mcp version     # registry has it
npx -y ios-agent-mcp --version     # 2.1.0
npx -y ios-agent-mcp --help        # usage, tool list, setup commands

--help and --version print and exit. Every other invocation starts the stdio server and blocks waiting for a client, which is correct but looks like a hang if you run it by hand.

To see exactly what would ship before committing to it:

npm pack --dry-run

Expect ~31 files: dist/, mcp.json, README.md, LICENSE, package.json. If dist/ is missing, the build did not run.

Version numbering

The npm package version and the repository version are independent:

	Version	Why
`ios-agent-mcp` on npm	`2.1.0`	Generated from `package.json` — see below
`ios-agent-skill` repo / `SKILL.md`	`2.1.0`	Kept in lockstep since 2.1.0

The version lives in package.json and nowhere else. mcp.json, package-lock.json, the CLI, and the MCP handshake are all generated from it by npm run sync-version, which build and typecheck run automatically.

This exists because 2.0.1 shipped to npm with an mcp.json declaring 1.0.0 — the version was maintained by hand in four places, so one was always wrong and nothing checked. CI runs sync-version --check, so a hand-edit fails the build rather than reaching the registry.

Since 2.1.0 the skill and the server share a version. They were independent before, which is exactly how 2.0.1 shipped with a manifest reading 1.0.0.

License

MIT — see LICENSE.

App-building loop preview (source checkout)

The CLI now provides loop init, loop resume and loop status alongside the unified MCP connection. See the workflow guide and reading-list demo for reproducible acceptance checks, bounded Claude repairs, simulator evidence and saved progress. Real Claude repair is not yet integration-verified; the published npm version does not include this preview.

2.6.0

Adds review_app_intents with conservative SiriKit migration advice and opt-in Apple Intelligence schema/onscreen checks. Apple snapshots refreshed after the iOS 27 release. Includes the preview loop CLI; real Claude repair remains unverified. See release verification and complete tools.

Local issue previews (2.7.0)

prepare_issue_report is included in 2.7.0. It creates a local preview from fixed failure categories and links to this project’s issue tracker. It does not collect diagnostics, open a browser, make network calls or submit issues. Show the preview to the user before opening any link. GitHub sign-in and user submission are required.

Private chat feedback — experimental

Version 2.7.1 includes private_feedback as a 37th tool. It requires an operator-configured HTTPS receiver, a local preview, and explicit user approval before sending fixed categories to a private repository. Hosting is not configured; private delivery is not live by default. No user GitHub sign-in is needed once deployed. No source, logs or credentials are accepted, and there is no automatic public fallback. See the reporting workflow.

Launch-screen review (2.7.1)

The existing App Store audit and project analysis include target-aware static launch-screen checks. Unresolved settings are reported as coverage gaps. See checks and limitations. Included in npm 2.7.1.

Local release-package foundation (2.7.1)

npx -y ios-agent-mcp@latest apple analyze|prepare --project /path/to/app --target App --configuration Release --json collects selected-target facts, conservative feature/screen candidates, questions and hashed local draft packages. No Apple connection, AI provider, build, upload or submission is performed. See the Phase 1 workflow and limitations.

Color and backend tools (2.7.2)

generate_color_system: read-only palette preview with light/dark/high-contrast semantic roles and contrast evidence; no automatic project writes.
review_color_system: local Swift/catalog evidence and conservative color review.
review_backend_integration: supported service detection and credential-redacted auth, policy and transport findings. No provider network calls.

Color guide · Backend guides

The backend guides include login examples, not configured login services. Each app needs its own provider setup. Live sign-in, external SDK compilation and hosted-policy validation remain unverified. The full MCP suite passes 308 tests; no benchmark improvement is claimed.

Screenshot Studio

The source server includes nine local screenshot-composition tools and screenshots CLI commands. Capture stays in the existing simulator tools. Supply real images and factual copy; compare layouts, localize supplied text and export checked PNGs. No upload or Apple approval is implied. npm 2.7.2 does not include this feature. Workflow, templates and limits.

Optional AI and environment commands

ios-agent-mcp environment discovers actual installed Apple tooling. ios-agent-mcp ai models|doctor|config|ask provides optional text-provider workflows. Defaults: local Apple model, no cloud permission, no fallback. Cloud access requires API credentials and explicit provider allowlisting; existing MCP client use needs none. See provider setup and limitations.

Local Apple documentation

npm version 2.9.0 exposes 67 tools (2.10.0 adds the 13 build-agent tools, 80 in all) and includes the updated CLI dependency. Use xcode-mcp tools for discovered Xcode schemas and doctor xcode for setup diagnostics.

Use ios-agent-mcp docs status and ios-agent-mcp docs symbol SwiftUI.NavigationStack for version-aware documentation grounding. The adapter prefers Xcode MCP DocumentationSearch, then bounded SDK evidence. Apple’s archive is never bundled. Bridge authorization is required; retrieval is not automatic code validation. Setup, tools and limitations.

Ship to TestFlight

The GitHub ship command prepares screenshot sets and metadata, then uses separate digest-approved archive and upload steps. See the shipping guide. Included in 2.10.2; live Apple distribution remains unverified.

Offline pre-submission checks

From a built checkout, run node mcp-server/dist/unified.js availability --path /path/to/app or node mcp-server/dist/unified.js readiness --path /path/to/app --target App --configuration Release. These commands never call a paid model, upload code, or sign an app. Read the evidence mode and limitations: a static review is not compiler verification or Apple approval. ship prepare seals a readiness.json report alongside its existing reviewed artifacts. See deployment guard and readiness for coverage and exit statuses.

Keywords

mcp model-context-protocol ios swift swiftui claude cursor chatgpt codex gemini apple-documentation icon-composer