Total npm downloads for ios-agent-mcp, refreshed daily through the latest complete UTC day. Downloads are not unique users.
claude mcp add ios-agent -- npx -y ios-agent-mcp@2.5.1The default server exposes 34 tools: 11 Swift reviews, 8 Apple reference tools, 14 simulator tools, and create_app. 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.
Create a starter directly:
npx -y ios-agent-mcp@2.5.1 new MyApp --brief "A reading list with local storage" --xcodegenRequires Node.js 20+. Simulator operations require macOS and Xcode; XcodeGen is required to generate an Xcode project from the starter specification. The agent implements app features using the starter, source tools and verification tools. One install is not autonomous app generation. The default connection now includes tools that write files and operate the simulator; review and reference tools remain read-only.
Give your AI coding agent local Swift source, Apple guides, code review tools, and a way to see the app running.
Build with Claude, Codex, or Gemini CLI. Portable references are also available for ChatGPT workflows. Free and open source under MIT.
Install the skill into your coding agent:
npx skills add Nagarjuna2997/ios-agent-skillFor build/run/screenshot tools, also configure the optional simulator MCP on a Mac with Xcode. Installing the skill alone adds guidance, not runtime tools.
Then ask:
Build a SwiftUI reading list with local persistence, search, and accessible empty/error states. Reuse this skill's local source where it fits. Run the build and tests, and show simulator evidence for what you verified.
Already have an app? Ask: “Review this project for concurrency, architecture, accessibility, and security issues. Give me file locations and fix the blockers first.”
Client setup · Start a new app · Download integrations · Contribute
| Feature | What you can do |
|---|---|
| Local source, retrieved in small sections | Search complete editable Swift files, templates, and guides; read only the matching section using offline commands or MCP. No need to load the whole library into each prompt. |
| Apple technology discovery: Accelerate → XPC | Navigate 405 unique technology entries, plus updates and release notes, with official Apple attribution and dated snapshots. |
| 11 read-only Swift review tools | Find concurrency, architecture, SwiftUI, memory, security, testing, performance, and App Store readiness issues with file-level findings. |
| Build → run → see | Use 14 simulator tools to build/test, launch an app, capture screenshots, and open a private browser preview alongside your agent. Requires macOS and Xcode. |
| An app starter you own | Generate a Swift starter, app brief, optional XcodeGen spec, and editable icon layers. Your coding agent implements the features; you keep the source. |
| Examples with tests | Reuse SkillPatterns and AppleRecipes: persistence, networking, cryptography, language, vector statistics, and PDF recipes. |
Local retrieval bounds output size; token and cost savings depend on the model and task and have not been benchmarked. The catalog is a discovery map, not 405 completed framework implementations or Apple's proprietary source. Static reviews are heuristic findings; builds, tests, and runtime checks supply separate evidence.
ios-agent-skill is a repo you can install into AI coding tools so they behave more like senior iOS engineers:
- The skill teaches the agent what good Apple-platform code looks like.
- The static MCP server reviews an existing Swift project and returns structured findings.
- The CLI scaffolds a clean iOS project layout.
- The simulator MCP package is the first runtime slice: build, test, install, launch, deep link, and screenshot through Xcode and Simulator.
- The subagents route specialized work to reviewers for SwiftUI, UIKit, RealityKit, Metal, WebKit, testing, security, performance, App Store readiness, and more.
The central rule is simple: do not let an agent say "it works" without evidence. Build output, test output, screenshots, logs, and structured findings matter more than confident prose.
The complete Apple technology directory covers 405 unique entries, from Accelerate to XPC, checked against Apple on 2026-09-10. It reuses existing guides for 83 technology entries and adds 322 dedicated reference pages, with platform metadata and 11,500 API/topic links. Five Apple directory entries lead to external resources.
The machine-readable snapshot and python3 scripts/sync-apple-technologies.py --check keep names, URLs, routes, and generated pages consistent. Use --refresh to retrieve the live directory again. This is complete technology-level discovery, not a per-symbol documentation mirror or a claim that every integration has been compiled.
AI-generated Swift often compiles while still being wrong in production-shaped ways.
| Problem | Common AI output | This repo enforces |
|---|---|---|
| Concurrency | @Observable state read by SwiftUI with no @MainActor isolation |
Main-actor UI state, Sendable boundaries, structured tasks |
| Architecture | View models creating URLSession, ModelContext, or singletons directly |
Protocol boundaries, dependency injection, preview-safe screens |
| Availability | #available(iOS 27, *) around an API introduced earlier |
Guards on the symbol's real introduction version |
| Error handling | try!, empty catch, swallowed failures |
User-visible outcomes or documented deliberate no-ops |
| Design | Fixed fonts, literal colors, inaccessible icon buttons | Design tokens, Dynamic Type, contrast, VoiceOver labels |
| Verification | "Should work now" | Commands run, output shown, evidence labelled |
npx -y @nagarjuna2002/ios-agent@0.2.0 new MyApp --brief "Describe the app you want" --xcodegenOpen the generated folder with your coding agent and ask it to implement App/APP_BRIEF.md through build and screen verification. The starter includes an XcodeGen project spec and separate editable icon layers. Full idea-to-app workflow.
- Claude and Codex: local MCP analyzers plus eight Apple knowledge/source tools. A Codex plugin ZIP is included in releases.
- ChatGPT: a portable skills-only plugin ZIP with bundled references. The optional knowledge server supports HTTP for deployment to your own HTTPS host.
- Gemini CLI: install this GitHub repository as an extension; it includes both MCP connections and GEMINI guidance.
Client installation · Knowledge MCP · Apple updates and release notes · Layer-by-layer Icon Composer workflow · Release downloads
The release artifacts are installable packages, not a claim of acceptance into a public plugin marketplace. Xcode builds and native Icon Composer editing require a compatible Mac environment.
Use this when you want your AI agent to load the iOS rules while writing code:
npx skills add Nagarjuna2997/ios-agent-skillOr clone it into an iOS project so tools can read the mirrored instruction files:
cd /path/to/YourApp
git clone https://github.com/Nagarjuna2997/ios-agent-skill.git .ios-skillios-agent-mcp is published on npm. Reviews and references are read-only; app creation and simulator tools have write/runtime effects. Simulator operations require Xcode.
claude mcp add ios-agent -- npx -y ios-agent-mcp --project /path/to/YourAppGeneric MCP config:
More client setup is in docs/mcp/installation.md.
The CLI is published on npm. For a quick start, use npx -y @nagarjuna2002/ios-agent@0.2.0 new MyApp --xcodegen. To develop it from source:
cd cli
npm install
npm run build
node dist/index.js new MyAppThe CLI creates a visible app root and keeps tool-owned state under .ios-agent/.
ios-simulator-mcp is intentionally separate from ios-agent-mcp because it requires macOS, Xcode, and simulator side effects.
cd ios-simulator-mcp
npm install
npm run build
node dist/index.js --help| Package | Status | Runtime | Purpose |
|---|---|---|---|
| ios-agent-mcp | Version: 2.5.1 |
Node 20+; runtime tools need Mac/Xcode | 34 tools in one default connection |
| @nagarjuna2002/ios-agent | Published: 0.2.0 |
Node 20+ | Project scaffolding, app briefs, editable icon layers |
| @nagarjuna2002/ios-simulator-mcp | Published: 0.2.0 |
macOS + Xcode | 14 tools for runtime evidence and browser preview |
| samples/SkillPatterns | CI sample | Swift Package Manager | Compile-checked examples of the rules |
The unified server includes these eleven read-only review tools:
| Tool | Use when |
|---|---|
analyze_swift_project |
You need a project overview, file counts, frameworks, architecture signals, DI evidence, and issue totals |
review_swift_concurrency |
You are checking actor isolation, @MainActor, Sendable, task structure, and empty catches |
review_swift_architecture |
You are checking MVVM/Clean Architecture boundaries and dependency injection |
review_swiftui |
You are checking SwiftUI layout, state, deprecated APIs, design tokens, and accessibility basics |
check_availability_guards |
You are checking iOS version guards and runtime model availability |
audit_app_store_readiness |
You are checking Info.plist permissions, privacy manifest risk, localization, labels, and diagnostics |
review_swift_memory |
You are checking retain cycles, delegates, timers, Combine sinks, and unowned self |
review_swift_security |
You are checking secrets, ATS, HTTP, Keychain accessibility, weak hashes, randomness, and JS injection |
review_swift_testing |
You are checking test quality, flakiness, sleeps, live network, and vacuous tests |
review_swift_performance |
You are checking SwiftUI render-path work, formatters, sorting, stacks, and blocking I/O |
lint_skill |
You are checking this skill repo or another Agent Skill for metadata, mirrors, agents, and references |
Every review returns markdown plus structuredContent with counts, issues, score, checked files, and suggestions.
@nagarjuna2002/ios-simulator-mcp exposes 14 runtime tools:
| Tool | Backend |
|---|---|
simulator_list |
xcrun simctl list devices available --json |
simulator_environment |
Installed Xcode, runtime and device availability |
simulator_show |
Open native Simulator |
simulator_preview_start |
Start private, read-only browser screenshot preview |
simulator_preview_stop |
Stop browser preview |
simulator_boot |
xcrun simctl boot |
simulator_shutdown |
xcrun simctl shutdown |
build_project |
xcodebuild build |
run_tests |
xcodebuild test |
install_app |
xcrun simctl install |
launch_app |
xcrun simctl launch |
terminate_app |
xcrun simctl terminate |
open_deep_link |
xcrun simctl openurl |
screenshot |
xcrun simctl io screenshot |
No current simulator tool erases all simulator content. Video, logs, UI gestures, accessibility-tree inspection, and visual comparison are planned next. See docs/tooling/ios-simulator-mcp.md.
Example MCP finding:
Sources/FeedModel.swift:3
Severity: blocker
Rule: observable-without-mainactor
@Observable type is not @MainActor-isolated.
Why it matters:
SwiftUI reads observable state during layout. A background write can become a
data race under Swift 5 mode and a compile error under Swift 6 strict checking.
Fix:
Annotate UI-rendered observable state:
@MainActor @Observable final class FeedModel { ... }
The same rules are documented in the skill docs so agents can learn the fix before generating new code.
Start here:
This smaller, curated guide index is separate from the 405-entry Apple directory above. “Covered” tracks documentation coverage, not compiled integrations.
Apple catalog tracked: 99 technologies. Covered: 99. Planned: 0. Skipped: 0. Deprecated: 0. Coverage: 100.0%.
Source of truth: frameworks.json. Human index: docs/apple-framework-index.md.
The catalog is generated and checked by CI. Update frameworks.json, then run:
node scripts/check-framework-catalog.mjsThe repo ships 24 specialist subagents in .claude/agents. Highlights:
| Agent | Use for |
|---|---|
swift-reviewer |
Independent read-only verification before shipping |
swift-debugger |
Reproduce, isolate, fix, and prove a Swift failure |
swiftui-expert |
SwiftUI layout, state, navigation, and modern interactions |
ui-ux-designer |
Product UI hierarchy, accessibility, state design, and polish |
realitykit-expert |
RealityKit, Model3D, ARKit integration, and spatial review |
metal-expert |
Metal rendering, shaders, compute, and frame-loop review |
testing-expert |
Swift Testing, XCTest, XCUIAutomation, and evaluations |
xcode-expert |
Xcode projects, schemes, Device Hub, and Instruments |
security-reviewer |
Authentication, Keychain, privacy, permissions, and threat modeling |
app-store-reviewer |
App Review, StoreKit, privacy manifests, release risk |
Read routing guidance in docs/orchestration/router.md and docs/orchestration/subagents.md.
For a new iOS app:
- Create the real Xcode project first in Xcode.
- Add this skill repo as
.ios-skill/or install it through your AI tool. - Configure
ios-agent-mcpwith--project /path/to/YourApp. - Ask the agent to build features inside the Xcode project, not beside it.
- Run static MCP reviews.
- Build and test in Xcode or with
ios-simulator-mcp. - Capture screenshots or logs before claiming the UI/runtime path works.
For an existing app:
claude mcp add ios-agent -- npx -y ios-agent-mcp --project /path/to/ExistingAppThen ask:
Analyze this Swift project and list blockers first.
Review concurrency, SwiftUI, security, testing, performance, and App Store readiness.
Show evidence and exact file locations.
Run repo consistency checks:
./scripts/hooks/verify-repo.sh
node scripts/check-framework-catalog.mjs
./scripts/eval-agents.sh --tableRun the static MCP package:
cd mcp-server
npm install
npm run typecheck
npm run build
npm testRun the CLI package:
cd cli
npm install
npm run typecheck
npm run build
npm testRun the simulator MCP package:
cd ios-simulator-mcp
npm install
npm run typecheck
npm run build
npm testios-agent-mcp@2.5.1 is published on npm:
npm view ios-agent-mcp versionnpm publishing is manual from a local trusted machine. GitHub Actions creates GitHub Releases but does not store npm tokens or run npm publish.
cd mcp-server
npm login
npm publish --access publicIf npm asks for security-key approval, use the browser link printed by the CLI and approve with the passkey/security key registered on the npm account.
Current state:
- v3.3.0 repository release: local source library, Apple catalog, cross-client integrations, and simulator preview.
- npm: unified package 2.5.1, app CLI 0.2.0, and simulator package 0.2.0.
Next work:
- Add runtime video capture and log streaming.
- Choose the UI automation backend for tap, swipe, type, and accessibility-tree inspection.
- Add visual-review loops that pair screenshots with UI/UX, accessibility, motion, RealityKit, Metal, and performance reviewers.
- Expand static review contracts for UI/UX, motion, haptics, 3D, AI safety, and evaluations.
Detailed planning lives in ROADMAP.md.
Primary support is intentionally focused on:
- Claude Code and Claude Desktop
- ChatGPT / Codex
- Gemini CLI
Other instruction-file mirrors may exist in the repo for compatibility, but the product direction is Claude, ChatGPT/Codex, and Gemini first.
Read CONTRIBUTING.md before changing docs, agents, mirrors, or package behavior.
Important rules:
- Edit
SKILL.md, then run./scripts/sync-mirrors.sh; do not hand-edit mirrors. - Keep examples complete and compiling.
- Add tests when behavior changes.
- Do not commit npm tokens, recovery codes,
.npmrccredentials, or GitHub secrets.
MIT. See LICENSE.
{ "mcpServers": { "ios-agent": { "command": "npx", "args": ["-y", "ios-agent-mcp", "--project", "/path/to/YourApp"] } } }