# ios-agent-mcp > MCP server for modern iOS/Swift development — concurrency isolation, architecture boundaries, SwiftUI, and App Store readiness analysis Latest version **2.10.3** (published 2026-10-28) · MIT license · 0 weekly downloads ## Install ```sh npm install ios-agent-mcp pnpm add ios-agent-mcp yarn add ios-agent-mcp bun add ios-agent-mcp ``` Provides the commands `ios-agent-mcp`, `ios-agent-knowledge`. ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; large bundle. ## Facts | | | |---|---| | Version | 2.10.3 | | Published | 2026-10-28 | | First published | 2026-07-31 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=20 | | Dependencies | 13 | | Unpacked size | 9.7 MB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | GitHub stars | 40 | | Maintainers | nagarjuna2002 | | Keywords | mcp, model-context-protocol, ios, swift, swiftui, claude, cursor, chatgpt, codex, gemini, apple-documentation, icon-composer | ## Links - npm: https://www.npmjs.com/package/ios-agent-mcp - Repository: https://github.com/Nagarjuna2997/ios-agent-skill - Homepage: https://nagarjuna2997.github.io/ios-agent-skill/ - Issues: https://github.com/Nagarjuna2997/ios-agent-skill/issues - npm.io page: https://npm.io/package/ios-agent-mcp ## Dependencies (13) - [zod](https://npm.io/package/zod.md) ^3.23.8 - [yaml](https://npm.io/package/yaml.md) 2.9.1 - [plist](https://npm.io/package/plist.md) 5.0.0 - [pngjs](https://npm.io/package/pngjs.md) 7.0.0 - [parse5](https://npm.io/package/parse5.md) 7.3.0 - [fontkit](https://npm.io/package/fontkit.md) 2.0.4 - [jpeg-js](https://npm.io/package/jpeg-js.md) 0.4.4 - [typescript](https://npm.io/package/typescript.md) 5.9.3 - [@resvg/resvg-js](https://npm.io/package/@resvg/resvg-js.md) 2.6.2 - [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) 5.11.1 - [@nagarjuna2002/ios-agent](https://npm.io/package/@nagarjuna2002/ios-agent.md) 0.4.1 - [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.32.1 - [@nagarjuna2002/ios-simulator-mcp](https://npm.io/package/@nagarjuna2002/ios-simulator-mcp.md) 0.2.0 ## Alternatives - [@cantoo/pdf-lib](https://npm.io/package/@cantoo/pdf-lib.md) — 297.9K weekly downloads - [datatables.net-buttons](https://npm.io/package/datatables.net-buttons.md) — 200.1K weekly downloads - [@ckeditor/ckeditor5-export-pdf](https://npm.io/package/@ckeditor/ckeditor5-export-pdf.md) — 167.0K weekly downloads - [scanbot-web-sdk](https://npm.io/package/scanbot-web-sdk.md) — 15.0K weekly downloads - [@syncfusion/ej2-angular-pdfviewer](https://npm.io/package/@syncfusion/ej2-angular-pdfviewer.md) — 8.8K weekly downloads ## Recent versions - 2.10.3 (latest) — 2026-10-28 - 2.10.2 — 2026-10-15 - 2.10.1 — 2026-10-04 - 2.10.0 — 2026-10-02 - 2.9.0 — 2026-09-30 - 2.8.0 — 2026-09-29 - 2.7.2 — 2026-09-22 - 2.7.1 — 2026-09-21 - 2.7.0 — 2026-09-16 - 2.6.0 — 2026-09-16 - 2.5.1 — 2026-09-10 - 2.5.0 — 2026-09-10 - 2.4.1 — 2026-09-10 - 2.4.0 — 2026-09-10 - 2.3.1 — 2026-09-10 - … 5 more at https://npm.io/package/ios-agent-mcp/versions ## README # iOS Agent MCP [Explore the website](https://nagarjuna2997.github.io/ios-agent-skill/) · [Choose your AI and install](https://nagarjuna2997.github.io/ios-agent-skill/install.html) ## 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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/tooling/ios-build-agent.md). 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](https://nagarjuna2997.github.io/ios-agent-skill/releases.html) 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](https://nagarjuna2997.github.io/ios-agent-skill/install.html). ## One install, one MCP connection Connect the published server and optionally install the Claude Code command: ```bash 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 ""` in Claude Code, or `ios-agent-mcp build ""` | | 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](https://nagarjuna2997.github.io/ios-agent-skill/) · [GitHub source](https://github.com/Nagarjuna2997/ios-agent-skill) ## 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](https://github.com/Nagarjuna2997/ios-agent-skill/issues) or [open a bug report](https://github.com/Nagarjuna2997/ios-agent-skill/issues/new?template=bug_report.md) 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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/tooling/offline-source-library.md). ## 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. ```bash 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](https://nagarjuna2997.github.io/ios-agent-skill/install.html). # ios-agent-mcp An MCP server that reviews Swift projects against the rules in [ios-agent-skill](https://github.com/Nagarjuna2997/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](#claude-code) · [ChatGPT / Codex](#chatgpt--codex) · [Gemini CLI](#gemini-cli) · [Muse Code](#muse-code). One server package; client connection methods differ. ### Claude Code ```bash claude mcp add ios-agent -- npx -y ios-agent-mcp ``` ### Claude Desktop `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "ios-agent": { "command": "npx", "args": ["-y", "ios-agent-mcp"] } } } ``` ### ChatGPT / Codex **Codex** connects to the local unified server: ```bash 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](https://nagarjuna2997.github.io/ios-agent-skill/install.html#chatgpt) for account requirements and connection limits. ### Gemini CLI ```bash 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](https://nagarjuna2997.github.io/ios-agent-skill/install.html#gemini). ### Muse Code Install outside the agent sandbox: ```bash npm install -g ios-agent-mcp@latest ``` Merge this into `~/.config/muse/settings.json`, preserving your existing settings: ```json { "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](https://nagarjuna2997.github.io/ios-agent-skill/install.html#muse). ### 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](https://github.com/Nagarjuna2997/ios-agent-skill/issues/new?template=client_support.md). ### From source ```bash 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: ```json { "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. ```jsonc { "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 ```bash 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) ```bash 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: ```bash 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: ```bash 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](./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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/tooling/app-building-loop.md) and [reading-list demo](../samples/ReadingList/README.md) 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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/apple/ios-27-release-verification.md) and [complete tools](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/mcp/tools.md). ## 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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/tooling/issue-reporting.md). ### 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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/tooling/launch-screen-review.md). 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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/tooling/local-release-package.md). ## 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](https://nagarjuna2997.github.io/ios-agent-skill/guides/design-palette-generation.html) · [Backend guides](https://nagarjuna2997.github.io/ios-agent-skill/guides/backend-overview.html) 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](../docs/screenshots/README.md). ## 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](https://github.com/Nagarjuna2997/ios-agent-skill/blob/main/docs/ai/providers.md). ## 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](https://nagarjuna2997.github.io/ios-agent-skill/guides/tooling-local-apple-documentation.html). ## 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](../docs/tooling/ship-testflight.md). 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](../docs/tooling/deployment-guard.md) and [readiness](../docs/tooling/app-store-readiness.md) for coverage and exit statuses. --- _Source: https://npm.io/package/ios-agent-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._