Visual overview
Use the workflow to follow the task, and the architecture map to separate responsibilities. These are conceptual maps; the guide below defines implementation details and verification limits.
- Choose review scope
- Run the relevant analyzer
- Interpret severity and location
- Validate the proposed change
- Boundary 1Project input
- Boundary 2Static review rules
- Boundary 3Structured findings
Connected responsibilities, not a required class hierarchy or an execution trace.
Load this when: choosing which ios-agent-mcp tool to call, or interpreting
a finding it returned.
Source-review tools take an absolute project path (some also accept review options):
{ "path": "/Users/you/Projects/MyApp" }
lint_skill reads a
skill repository's own metadata, so its path is the folder containing
SKILL.md.
All registered tools
Every tool the unified server exposes, grouped by area, with a link to the guide for each group. The sections after this index document the source-review tools in detail.
The unified ios-agent-mcp server registers 88 tools. "Access" repeats each tool's declared readOnlyHint annotation; "not declared" means the tool does not state it.
Profiles (full set remains the default):
all: screenshots, design-review, build, design, integrations, review, apple-docs, simulator, feedback, otherbuild: build, design-review, simulator, apple-docsreview: review, apple-docsdocs: apple-docsdesign: design, screenshots, integrations
Screenshot Studio (11)
Guide: ../screenshots/README.md
| Tool | Access | Purpose |
|---|---|---|
export_screenshot_set |
writes or runs | Copy validated PNG files and export metadata to a NEW directory, refusing invalid or modified outputs. |
generate_screenshot_set |
writes or runs | Render supplied PNG/JPEG captures offline into NEW local directories with neutral frames, supplied copy, hashed metadata and a gallery. |
generate_screenshot_variants |
writes or runs | Render supplied PNG/JPEG captures offline into NEW local directories with neutral frames, supplied copy, hashed metadata and a gallery. |
get_screenshot_template |
read-only | Choose a Screenshot Studio layout. |
inspect_screenshot_set |
read-only | Verify dimensions, RGB PNG format, hashes, recorded bounds, text contrast and duplicate sources. |
ios_screenshot |
writes or runs | Screenshot the simulator |
list_screenshot_templates |
read-only | List structurally distinct layouts and dated output profiles. |
localize_screenshot_set |
writes or runs | Render a new locale from supplied translated copy, preserving screen order and templates. |
preview_screenshot_set |
read-only | Locate the generated local contact sheet and HTML gallery after validating a screenshot set. |
render_app_store_screenshot |
writes or runs | Render supplied PNG/JPEG captures offline into NEW local directories with neutral frames, supplied copy, hashed metadata and a gallery. |
screenshot |
not declared | Capture a simulator screenshot |
Design contract and independent review (6)
Guide: ../tooling/design-review.md
| Tool | Access | Purpose |
|---|---|---|
design_contract |
writes or runs | Create, update or validate a design contract |
design_drift |
read-only | Compare a saved design with the current implementation |
design_resolve |
writes or runs | Disposition findings, compute readiness, record approval |
design_review |
writes or runs | Run or submit an independent design review |
design_status |
read-only | Inspect a design's state, flags and findings |
design_verify |
writes or runs | Record evidence and steps against acceptance criteria |
Build and app creation (15)
Guide: ../tooling/ios-build-agent.md
| Tool | Access | Purpose |
|---|---|---|
create_app |
not declared | Create an editable Swift app starter, implementation brief and optional XcodeGen specification/icon layers. |
ios_add_capabilities |
writes or runs | Add capabilities to the project |
ios_add_package |
writes or runs | Add a Swift package |
ios_build |
writes or runs | Build the app |
ios_capabilities |
read-only | Search app capabilities |
ios_create_project |
writes or runs | Create the Xcode project |
ios_design_evidence |
writes or runs | See the app for design review |
ios_import_html |
read-only | Inspect local source through Universal App IR |
ios_logs |
read-only | Read app logs |
ios_plan |
writes or runs | Write the build plan |
ios_preflight |
read-only | Check the Mac before building |
ios_progress |
writes or runs | Record a progress line |
ios_report |
writes or runs | Write the run report |
ios_run |
writes or runs | Run the app in the simulator |
ios_write_files |
writes or runs | Write app source files |
Color and backend (3)
Guide: ../backend/overview.md
| Tool | Access | Purpose |
|---|---|---|
generate_color_system |
read-only | Generate an iOS color system preview |
review_backend_integration |
read-only | Review iOS backend integration |
review_color_system |
read-only | Review an iOS color system |
Apple integrations (7)
Guide: ../integrations/README.md
| Tool | Access | Purpose |
|---|---|---|
check_apple_capabilities |
read-only | Check selected entitlements separately from usage descriptions for concrete HealthKit, Apple Pay, CloudKit and push usage. |
check_apple_permissions |
read-only | Report required versus detected privacy keys for concrete API operations. |
get_system_integration |
read-only | Get a supported integration’s APIs, guide routes, operations, permissions and device verification requirements. |
list_system_integrations |
read-only | List supported Apple system integration workflows, conditional permissions and verification limits. |
recommend_system_integrations |
read-only | Suggest verification of integrations already evidenced in source. |
review_system_integrations |
read-only | Review concrete API usage, selected privacy configuration and entitlements; reuse App Intents checks. |
scaffold_system_integration |
read-only | Return a reusable Swift file preview for a supported system integration. |
Source reviews (12)
Guide: this page
| Tool | Access | Purpose |
|---|---|---|
analyze_swift_project |
not declared | Analyze a Swift project |
audit_app_store_readiness |
not declared | Audit App Store submission readiness |
check_availability_guards |
not declared | Check iOS availability guards |
lint_skill |
not declared | Lint an Agent Skill repository |
review_app_intents |
read-only | Review App Intents integration |
review_swift_architecture |
not declared | Review iOS architecture boundaries |
review_swift_concurrency |
not declared | Review Swift concurrency and actor isolation |
review_swift_memory |
not declared | Review memory and retain cycles |
review_swift_performance |
not declared | Review SwiftUI and Swift performance |
review_swift_security |
not declared | Review iOS security |
review_swift_testing |
not declared | Review test suite quality |
review_swiftui |
not declared | Review SwiftUI views and state |
Apple documentation and local references (19)
Guide: knowledge-server.md
| Tool | Access | Purpose |
|---|---|---|
apple_docs_availability |
not declared | Retrieve bounded Apple documentation evidence for availability. |
apple_docs_examples |
not declared | Retrieve bounded Apple documentation evidence for examples. |
apple_docs_frameworks |
not declared | List frameworks present in installed SDKs, grouped by SDK. |
apple_docs_lookup_symbol |
not declared | Retrieve bounded Apple documentation evidence for lookup_symbol. |
apple_docs_platform_support |
not declared | Inspect dynamically installed SDK/platform inventory; not API availability. |
apple_docs_related_symbols |
not declared | Retrieve bounded Apple documentation evidence for related_symbols. |
apple_docs_sdk_diff |
not declared | Compare installed Xcode SDK inventories; not a symbol-level API diff. |
apple_docs_search |
not declared | Retrieve bounded Apple documentation evidence for search. |
apple_docs_status |
not declared | Discover installed Xcode, SDKs and local Apple documentation; does not prove bridge authorization. |
get_apple_technology |
read-only | Read Apple technology guide |
get_apple_updates |
read-only | Find Apple updates and release notes |
get_reference_outline |
read-only | Outline a local guide |
plan_app_icon |
read-only | Plan layered Icon Composer artwork |
plan_ios_app |
read-only | Plan an iOS app from a brief |
read_local_reference |
read-only | Read local source or guide |
search_apple_technologies |
read-only | Search Apple technologies |
search_local_references |
read-only | Search bundled source and guides |
xcode_mcp_status |
not declared | Discover Xcode MCP bridge, handshake and capabilities; discovery does not prove authorization. |
xcode_mcp_tools |
not declared | Discover actual Xcode tools, schemas, resources and prompts with category hints; unknown tools remain visible. |
Simulator and Xcode (13)
Guide: ../tooling/ios-simulator-mcp.md
| Tool | Access | Purpose |
|---|---|---|
build_project |
not declared | Build an Xcode project or workspace |
install_app |
not declared | Install an app bundle |
launch_app |
not declared | Launch an installed app |
open_deep_link |
not declared | Open a deep link |
run_tests |
not declared | Run Xcode tests |
simulator_boot |
not declared | Boot an iOS simulator |
simulator_environment |
not declared | Installed Xcode and device support |
simulator_list |
not declared | List available iOS simulators |
simulator_preview_start |
not declared | Open sidebar simulator preview |
simulator_preview_stop |
not declared | Close simulator preview |
simulator_show |
not declared | Show native Simulator |
simulator_shutdown |
not declared | Shut down an iOS simulator |
terminate_app |
not declared | Terminate an app |
Failure reports (2)
Guide: ../tooling/issue-reporting.md
| Tool | Access | Purpose |
|---|---|---|
prepare_issue_report |
read-only | Prepare a local category-only GitHub draft for a confirmed significant ios-agent-mcp knowledge gap, incorrect guidance, or package failure that blocks development. |
private_feedback |
writes or runs | Source-preview private feedback for a failure in iOS Agent tools, not the user app. |
Choosing a tool
| You want to… | Tool |
|---|---|
| Generate a semantic palette preview | generate_color_system (palette inputs; no project path required) |
| Review Swift colors and asset catalogs | review_color_system |
| Review backend/auth/policy evidence | review_backend_integration |
| Understand an unfamiliar codebase | analyze_swift_project |
| Diagnose a data race or migrate to Swift 6 | review_swift_concurrency |
| Find out why a screen can't be previewed | review_swift_architecture |
| Review SwiftUI views and state | review_swiftui |
| Check before shipping, or after an SDK bump | check_availability_guards |
| Prepare an App Store submission | audit_app_store_readiness |
Memory grows, or deinit never runs |
review_swift_memory |
| Handle credentials, or run a security pass | review_swift_security |
| Tests are flaky, or a green suite looks too easy | review_swift_testing |
| Scrolling stutters or launch is slow | review_swift_performance |
| Author or review an Agent Skill, or work out why a subagent never gets invoked | lint_skill |
Start with analyze_swift_project — it reports counts per category and names
the tool to run for each, so you do not run all ten blindly. lint_skill sits
outside that flow; it inspects skill metadata, not Swift.
Severity
| Meaning | Act | |
|---|---|---|
| 🔴 blocker | Crash, data race, or App Review rejection | Before shipping |
| 🟠 serious | Real defect — untestable code, accessibility failure, deprecated API | This sprint |
| 🟡 minor | Maintainability and consistency | When touching the file |
Findings are sorted most severe first.
analyze_swift_project
Structure — Swift file count, line count, deployment target, Swift tools version, frameworks in use, whether tests exist — plus a finding count for every category with the tool that explains it.
It also reports the project's shape: UI framework, inferred architecture, third-party dependencies, and whether dependency injection is in use.
The architecture read always ships its evidence. "MVVM" alone is a guess
presented as a fact; "MVVM — 12 ViewModel types, Views/ and ViewModels/
directories" is a claim you can check. When the signals are weak it says
not determined rather than picking the most popular answer.
Dependency injection is detected from any Protocol parameters in initializers,
not from a directory named DI/ — a project that only ever constructs concrete
types has no seam, whatever it calls itself.
review_swift_concurrency
| Rule | Severity |
|---|---|
observable-without-mainactor |
🔴 |
type-named-task |
🔴 |
task-detached |
🟠 |
dispatchqueue-main-async |
🟠 |
unchecked-sendable |
🟠 |
task-in-onappear |
🟠 |
empty-catch |
🟠 |
redundant-mainactor-run |
🟡 |
nonisolated-unsafe |
🟡 |
observable-not-final |
🟡 |
Background: ../swift/swift-concurrency.md, ../../patterns/mvvm.md.
review_swift_architecture
| Rule | Severity |
|---|---|
live-default-dependency |
🔴 |
domain-imports-ui |
🔴 |
presentation-names-data-type |
🟠 |
singleton-in-viewmodel |
🟠 |
nested-navigation-stack |
🟠 |
deprecated-navigationview |
🟠 |
Background: ../../patterns/clean-architecture.md.
review_swiftui
| Rule | Severity |
|---|---|
environmentobject |
🟠 |
force-try |
🟠 |
fixed-font-size |
🟠 |
any-view, fixed-height, literal-spacing, deprecated-corner-radius, material-possibly-on-solid, view-state-on-model, legacy-observableobject |
🟡 |
Only runs on files that import SwiftUI.
Background: ../swiftui/state-and-data-flow.md, ../design/design-tokens.md.
check_availability_guards
| Rule | Severity |
|---|---|
missing-availability-guard |
🔴 |
missing-runtime-model-check |
🔴 |
over-restrictive-guard |
🟠 |
over-restrictive-guard is the one worth understanding. Guarding an iOS 26
API at #available(iOS 27, *) compiles, ships, and silently sends every iOS 26
device down your fallback path. It is invisible when testing on a current
device, which is why a rule catches it.
missing-runtime-model-check covers the other half: an @available guard proves
the symbol exists; it does not prove Foundation Models is usable on this
device, in this region, with Apple Intelligence enabled.
Background: ../compatibility-matrix.md, ../frameworks/foundation-models.md.
audit_app_store_readiness
| Rule | Severity |
|---|---|
missing-purpose-string |
🔴 |
missing-privacy-manifest |
🔴 |
unlabeled-icon-button |
🟠 |
hardcoded-string, print-logging |
🟡 |
missing-privacy-manifest only fires on apps (an Info.plist or .xcodeproj
is present). A library is never submitted to App Review.
Background: ../../checklists/app-store-submission.md, ../frameworks/accessibility.md.
review_swift_memory
| Rule | Severity |
|---|---|
timer-retain-cycle, notification-observer-retain, sink-retain-cycle |
🟠 |
strong-delegate, stored-closure-captures-self, long-lived-task-captures-self |
🟠 |
unowned-self |
🟠 |
Deliberately narrow. A closure capturing self is not a leak — most closures
are consumed immediately. A leak needs the closure to be stored by something
the object itself owns, so these rules fire on the specific storing APIs rather
than on self. inside any closure, which would bury the real findings.
unowned-self is a crash rather than a leak: unlike weak it does not nil out,
so an escaping closure running after deallocation traps instead of no-oping.
review_swift_security
| Rule | Severity |
|---|---|
hardcoded-secret, secret-in-userdefaults, ats-disabled |
🔴 |
tls-validation-bypassed, keychain-always-accessible |
🔴 |
cleartext-http, weak-hash, non-cryptographic-randomness, secret-logged |
🟠 |
javascript-string-interpolation |
🟠 |
keychain-migrates-to-new-device |
🟡 |
hardcoded-secret skips the placeholders people legitimately commit
(YOUR_API_KEY, <your-key>, changeme) and values under 8 characters —
flagging those trains readers to ignore the rule, which is worse than not having
it. cleartext-http allows localhost and loopback.
review_swift_testing
The inverse of every other analyzer: it runs only on test files.
| Rule | Severity |
|---|---|
await-inside-xctassert |
🔴 |
test-sleeps, test-without-assertion, network-in-test, no-tests |
🟠 |
force-try-in-test, shared-mutable-test-state, long-test-timeout |
🟡 |
assert-true-on-equality, sparse-tests |
🟡 |
A flaky or vacuous test is worse than a missing one: it costs the same to run
and reports success either way. test-without-assertion catches the case that
passes as long as nothing throws; await-inside-xctassert catches code that
does not compile at all, because XCTAssert takes an autoclosure.
review_swift_performance
| Rule | Severity |
|---|---|
blocking-io-in-body |
🔴 |
formatter-allocated-in-body, collection-work-in-body, foreach-over-indices |
🟠 |
eager-stack-in-scrollview, image-decode-in-body |
🟠 |
asyncimage-without-frame, geometryreader-wraps-body, formatter-allocated-repeatedly |
🟡 |
The unifying rule: body runs many times per second, on the main actor, for
reasons you do not control. Anything expensive inside it is multiplied by a
number nobody measured. Rules that only matter on that path are scoped to the
var body: some View block and are silent elsewhere — the same DateFormatter()
is 🟠 inside body and 🟡 outside it.
lint_skill
The one tool that does not read Swift. It checks whether an Agent Skill repository is well-formed and internally consistent — the class of defect that produces no error anywhere, just an instruction nobody follows.
| Rule | Severity |
|---|---|
skill-file-missing, skill-missing-frontmatter, skill-frontmatter-missing-key |
🔴 |
agent-missing-frontmatter |
🔴 |
agent-read-only-holds-write-tool |
🔴 |
skill-version-not-semver, skill-name-not-kebab-case, skill-description-too-long |
🟠 |
skill-unknown-tool, agent-unknown-tool |
🟠 |
agent-name-filename-mismatch, agent-missing-name, agent-missing-description, agent-missing-tools, agent-name-not-kebab-case |
🟠 |
mirror-out-of-sync, broken-doc-reference |
🟠 |
skill-description-too-short, agent-description-lacks-trigger |
🟡 |
Three of these are worth calling out, because each fails silently:
agent-read-only-holds-write-tool— a subagent whose description promises it is read-only while its frontmatter grantsEditorWrite. The main agent delegates on the strength of that promise. A reviewer that can edit will fix what it was meant to report, and the separation of duties the review depends on is gone with nothing in the output to show it.agent-name-filename-mismatch— rename the file, forget the frontmatter, and every delegation prompt references an identifier the loader never registered.*-unknown-tool— a misspelled tool name is not granted and not reported. The agent's prompt assumes a capability it does not have, and only finds out at the moment it tries to use it.
Mirror checking is self-calibrating. Files like CLAUDE.md and AGENTS.md
are compared against SKILL.md's body only when at least one of them already
matches byte-for-byte. That proves the repository generates its mirrors; without
it, a project with a hand-written CLAUDE.md would be told all supported mirrors had
drifted. When no mirror matches, the check is skipped and the report says so.
The report opens with what it inspected — SKILL.md found or not, agents counted, mirrors compared, references resolved — because a clean report that never states its scope is indistinguishable from a check that never ran.
Background: ../orchestration/subagents.md, ../orchestration/verification.md.
Structured output
Every review tool returns both halves of a result:
content— markdown, for a human reading the transcript.structuredContent— typed data, declared viaoutputSchema, for a workflow that must branch on the result without regexing prose.
{
"summary": "Security Review: 1 blocker, 2 serious across 34 files.",
"score": 91,
"counts": { "blocker": 1, "serious": 2, "minor": 0, "total": 3 },
"files_checked": 34,
"issues": [ { "file": "…", "line": 12, "severity": "blocker", "rule": "…", "fix": "…" } ],
"suggestions": [ "hardcoded-secret: Move it server-side…" ]
}
About score. It is a defect density, computed as
100 × (1 − penalty / capacity) where penalty = 10·blockers + 3·serious +
1·minor and capacity = files × 10, clamped to 0–100. The formula is fixed and
published so the number is reproducible rather than a vibe.
It is not comparable between projects — a UI-heavy app and a networking
library have different rule surfaces. Use it as a direction of travel for one
codebase, and use counts for anything that matters.
suggestions deduplicates by rule rather than restating every issue's fix:
forty literal-spacing findings produce one instruction, not forty.
Limits
Static analysis. It reads source; it does not build, run, or type-check.
A clean report is not a passing build — run swift build and swift test.
lint_skill checks form, not content. It can prove a subagent is declared
correctly and that its tool grant matches its stated contract. It cannot judge
whether the instructions in it are any good.
Heuristics on paths. Layer rules infer the presentation and domain layers
from directory names (Views/, Presentation/, Domain/). An unconventional
layout produces fewer architecture findings, not wrong ones.
Exemptions are deliberate. Test, mock, stub, fake, and preview files skip
the app-code-only rules; Package.swift is skipped entirely. Doubling the noise
would halve the chance anyone reads the output.
Caps. 2000 files and 512 KB per file, so a huge monorepo returns something rather than hanging.
review_app_intents
Read-only project review. Inputs: absolute path, optional booleans appleIntelligence and onscreenContent (both default false). Returns the same structured findings as other reviewers. SiriKit migration, missing schema and missing onscreen association are minor advisories with scope limitations; no blanket SiriKit deprecation is asserted. See rule semantics.
Color and backend scope
See palette generation, color review and backend integration. All three tools are read-only. Provider logins require app-specific configuration; static evidence is not live-service verification.
Apple system integrations (GitHub source release)
Seven additional read-only tools are available from a local source build, bringing the unified catalog from 40 to 47. They are not in npm 2.7.2 yet. See workflow, supported operations and limits.
| Tool | Input | Result |
|---|---|---|
| list_system_integrations | none | Ten supported integration records |
| get_system_integration | integration | Frameworks, permissions, guides and verification |
| recommend_system_integrations | path, optional infoPlist/entitlements | Evidence-backed next checks only |
| scaffold_system_integration | path, integration, optional operations | Swift file preview; no writes |
| review_system_integrations | path, optional infoPlist/entitlements | Privacy/capability evidence and existing App Intents findings |
| check_apple_permissions | path, optional infoPlist/entitlements | Required versus detected keys, unknown configuration explicit |
| check_apple_capabilities | path, optional infoPlist/entitlements | Supported entitlement checks, separate from privacy strings |