~/asomium $
macOS 15+ · ● live

Tool reference

Every MCP tool exposed by the Asomium server — auto-generated from the registry.

The Asomium MCP server exposes 42 tools. Each maps to one action you can also take in the Mac app; the MCP server is a thin adapter that exposes them over stdio to MCP-aware clients (Claude Code, Claude Desktop, Cursor, Windsurf).

See MCP overview for the architecture, Auth & local state for how credentials reach the server, and Connect ASC for the one-time App Store Connect setup.

Discovery & ASO

asomium_competitor_intel

Pull a competitor app’s public metadata + screenshots from the App Store. Uses Apple’s public iTunes Search / Lookup API — no App Store Connect credentials required and doesn’t touch your apps. Useful for inspiration, gap analysis, and tracking what other apps in your category are shipping. Pass either bundleId, appId (numeric App Store id), or a full App Store URL.

Example prompt — Pull metadata + screenshots for net.ichi2.anki and compare to ThinkBud.

Parameters

  • url — string, optional. Full App Store URL — id is parsed out automatically.
  • appId — string, optional. Numeric App Store id, e.g. ‘373493387’.
  • country — string, optional. Two-letter ISO storefront code (default ‘us’). The description, price and review counts you see depend on which storefront you query.
  • bundleId — string, optional. Bundle id of the competitor, e.g. ‘net.ichi2.anki’.

asomium_discover_keywords

Sweep Apple’s App Store search autocomplete for one or more seed prefixes and return the popular completions real users see while typing. The autocomplete index is Apple’s own — no proprietary “search volume” estimate — so candidates that appear across multiple seed prefixes (probeCount > 1) and that surface at low bestRank (1 is the first suggestion shown) are the high-demand terms. Use to find keyword opportunities, refine your en-US keywords field, or scope a competitor-research push.

Example prompt — Sweep autocomplete for the seeds ‘flash’, ‘study’, ‘revis’, ‘cram’ in the US storefront and rank the top 30 candidates.

Parameters

  • country — string, optional. Two-letter storefront code. Default ‘us’.
  • seeds — array, required. Prefix strings to sweep. Each prefix probes Apple’s suggest endpoint and returns up to 10 suggestions; you typically want 2-6 seeds related to your domain (e.g. [‘flash’,‘study’,‘revis’,‘quizl’]).
  • limit — integer, optional. Max number of candidates returned (default 30). Results are already sorted by composite score (probeCount DESC, bestRank ASC).

asomium_keyword_rank

Live rank check: for the given app + keyword + country storefront, hit Apple’s public iTunes Search API and return where the app currently sits in the top 200 of Apple’s search results. One-shot, no history — for daily tracking + multi-day trend charts, set up keyword tracking inside the Asomium Mac app (Settings → ASO → Add Keyword). Returns rank null when the app isn’t in the top 200 for that term.

Example prompt — Where does ThinkBud rank for ‘flashcards’ in the UK storefront right now?

Parameters

  • keyword — string, required. The search term to check rank for, e.g. ‘flashcards’. Required.
  • country — string, optional. Two-letter storefront code. Default ‘us’. Note: search is country-scoped, not locale-scoped — ‘us’ and ‘gb’ return different result sets even though both are English.
  • app — string, required. App name, bundle id, or numeric App Store id. Required.

asomium_list_apps

List every app the configured App Store Connect API key can see. Use this first to discover what’s available before calling pull/push/expand on a specific app. Returns app id, name, bundle id, and SKU per row.

Example prompt — Show me every app this ASC key can see.

Parameters

No parameters.

Keyword tracking

asomium_list_tracked_keywords

List currently tracked keywords with their latest rank and snapshot count. Filterable by app / keyword / country. Set include_history: true to return the full per-entry snapshot list (can grow large after many refreshes).

Visualization tip: the history payload is chart-ready. In clients with React artifact support (Claude.ai, Claude Desktop), render directly as a multi-line recharts artifact (one line per keyword, x = ts, y = rank, remember rank is inverted — lower is better). In artifact-less clients (Claude Code, Cursor, Windsurf), pipe through asomium_render_chart for an SVG file.

Example prompt — Show all tracked keywords for ThinkBud with their full rank history.

Parameters

  • keyword — string, optional. Optional. Filter to one keyword.
  • country — string, optional. Optional. Filter to one storefront (2-letter code).
  • app — string, optional. Optional. Filter by app — name, bundle id, or numeric ASC id.
  • include_history — boolean, optional. Include the full snapshot history per entry. Default false.

asomium_refresh_tracked_ranks

For every tracked keyword (optionally scoped to one app), hit Apple’s search API and append a fresh rank snapshot. The on-disk store is written ONCE at the end after all polls finish — partial-failure runs preserve whatever snapshots completed before the interruption.

Best run on a cadence (manual or via a scheduled task) to build up rank history.

Example prompt — Re-poll every tracked keyword and append today’s snapshot.

Parameters

  • app — string, optional. Optional. Refresh only the keywords for this app — name, bundle id, or numeric ASC id.

asomium_track_keyword

Add one or more keywords to MCP’s tracking store for an app + country, persisting in a JSON file under ~/Library/Application Support/ReleaseKit/. By default the tool also takes an initial rank snapshot — set snapshot: false to skip if you plan to refresh shortly anyway.

Tracking is MCP-side only for now. The Mac app’s SwiftData-backed keyword tracker is a separate store; a future version may unify them.

Idempotent — re-tracking the same (keyword, country) just appends another snapshot to the existing history rather than duplicating it.

Example prompt — Track ‘flashcards’, ‘spaced repetition’, and ‘study app’ for ThinkBud in US and UK.

Parameters

  • country — string, optional. Two-letter storefront code. Default ‘us’. Ranks are country-scoped.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • keyword — string, optional. Single keyword to track. Use keywords for multiple.
  • snapshot — boolean, optional. Take an initial rank snapshot. Default true.
  • keywords — array, optional. Multiple keywords at once.

asomium_untrack_keyword

Stop tracking a (keyword, country) pair for an app. Removes the entry and discards its rank history — there’s no soft-archive.

Example prompt — Stop tracking ‘cram’ for ThinkBud in the UK.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • country — string, optional. Two-letter storefront code. Default ‘us’.
  • keyword — string, required. Keyword to stop tracking. Required.

Metadata

asomium_bulk_push_metadata

Apply the same field updates to one locale across multiple apps in one call. Useful for rolling out a uniform promo / whatsNew across a portfolio. Per-app failures don’t abort the run — each is collected and returned at the end so the caller can retry just the failures.

Example prompt — Push the same en-US whatsNew to ThinkBud, ApplyIQ, and Hushly in one go.

Parameters

  • description — string, optional. Full description (≤4000 chars)
  • locale — string, required. ASC locale code, e.g. ‘en-US’. Required.
  • apps — array, required. Apps to update — names, bundle ids, or numeric ASC ids. Required.
  • promotionalText — string, optional. Promotional text (≤170 chars)
  • subtitle — string, optional. App subtitle (≤30 chars)
  • name — string, optional. App name (≤30 chars)
  • whatsNew — string, optional. What’s new in this version (≤4000 chars)
  • keywords — string, optional. Comma-separated keywords (≤100 chars)

asomium_expand_english

Take the en-US version of selected metadata fields and copy them to en-AU, en-CA and en-GB. Creates the target localizations if they don’t already exist. Default fields are name, subtitle, description, keywords, promotional text.

Example prompt — Copy en-US name, subtitle, and promotional text to en-AU, en-CA, and en-GB.

Parameters

  • fields — array, optional. Optional. Subset of fields to copy. Defaults to all five.
  • app — string, required. App name or bundle ID. Required.

asomium_pull_metadata

Fetch the current App Store Connect metadata for an app — all locales, all editable fields, current version state. Read-only; never mutates ASC.

Example prompt — Pull the current ASC metadata for ThinkBud, all locales.

Parameters

  • app — string, required. App name (case-insensitive) or bundle ID. Required.
  • locales — array, optional. Optional. Subset of locales to fetch (e.g. [‘en-US’,‘de-DE’]). Defaults to all.

asomium_push_metadata

Write edits back to ASC for one locale. Pass any subset of fields you want to update; omitted fields are not touched. Validates against ASC’s character limits before sending.

When the locale doesn’t exist on ASC yet, this creates it. ASC requires supportUrl on every locale — if support_url isn’t passed explicitly, the en-US locale’s URL is copied so adding a new language doesn’t fail validation. The user can edit the per-locale URL later in ASC if they want a language-specific support page.

Example prompt — Set the en-US whatsNew for ThinkBud to ‘Smarter SRS, smoother podcasts.’

Parameters

  • keywords — string, optional. Comma-separated keywords (≤100 chars)
  • name — string, optional. App name (≤30 chars)
  • whatsNew — string, optional. What’s new in this version (≤4000 chars)
  • app — string, required. App name or bundle ID. Required.
  • description — string, optional. Full description (≤4000 chars)
  • support_url — string, optional. Override the support URL for this locale. Optional — when omitted on a brand-new locale, en-US’s value is copied to satisfy ASC’s required-field rule.
  • marketing_url — string, optional. Override the marketing URL for this locale. Optional — when omitted on a brand-new locale, en-US’s value is copied if set.
  • subtitle — string, optional. App subtitle (≤30 chars)
  • locale — string, required. ASC locale code, e.g. ‘en-US’ or ‘de-DE’. Required.
  • promotionalText — string, optional. Promotional text (≤170 chars)

asomium_translate_field

Translate one App Store metadata field from a source locale into one or more target locales using the Anthropic API key configured in Asomium. Respects ASC character limits per field (30 for name/subtitle, 100 for keywords, 170 for promotional text, 4000 for description/whatsNew) — auto-retries with a “too long” hint and trims at word boundary if the model still overshoots. Returns translations as JSON for review by default; set apply: true to push directly to ASC.

Example prompt — Translate the en-US whatsNew into de-DE, es-ES, fr-CA, it, and hr and push it.

Parameters

  • protected_terms — array, optional. Optional. Terms to preserve verbatim (brand names, product names like ‘FlashCards’).
  • source_locale — string, optional. Source ASC locale, e.g. ‘en-US’. Default ‘en-US’.
  • field — string (one of: name, subtitle, description, keywords, promotionalText, whatsNew), required. Which metadata field to translate.
  • target_locales — array, required. Target ASC locales, e.g. [‘de-DE’,‘fr-FR’]. Required.
  • apply — boolean, optional. If true, push translations to ASC immediately. Defaults to false — review JSON first.
  • brand_voice — string, optional. Optional. Free-text guidance on tone (e.g. ‘playful, concise, second-person’).
  • app — string, required. App name or bundle ID. Required.

asomium_validate_metadata

Dry-run validation of the editable AppStoreVersion + AppInfo localizations against ASC’s per-field rules. Per (locale, field), reports: · ERROR — exceeds Apple’s char limit, or required field is empty (name, description). · WARN — recommended field is empty (subtitle, keywords, whatsNew). No writes. Use before bulk push / translate to catch char-limit overruns that would otherwise leave a locale set half-updated.

Example prompt — Validate ThinkBud’s editable version metadata before I push — flag char-limit overruns.

Parameters

  • app — string, required. App name (case-insensitive) or bundle ID. Required.
  • locales — array, optional. Optional. Subset of locales to validate (e.g. [‘en-US’,‘de-DE’]). Defaults to all.

Snapshots & diff

asomium_diff_metadata

Compare a saved snapshot against the live ASC metadata (or against another snapshot, via against_snapshot). Returns per-(locale, field) changes plus locale add/remove deltas. Tracked fields: name, subtitle, description, keywords, promotionalText, whatsNew, supportUrl, marketingUrl.

Example prompt — Diff ThinkBud’s ‘pre-2.4.4’ snapshot against the live ASC state.

Parameters

  • snapshot — string, required. Snapshot name (the before side of the diff). Required.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • against_snapshot — string, optional. Optional. Another snapshot name to diff against (the after side). Default: live ASC state.

asomium_list_metadata_snapshots

List all saved metadata snapshots for an app, newest first.

Example prompt — List every saved snapshot for ThinkBud.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

asomium_snapshot_metadata

Save the app’s current ASC metadata to a local JSON file under ~/Library/Application Support/ReleaseKit/..., named for easy retrieval. Default name is an ISO-8601 timestamp. The payload shape matches asomium_pull_metadata so snapshots can be diffed against each other or against live ASC.

Example prompt — Take a snapshot of ThinkBud’s current metadata named ‘pre-2.4.4’.

Parameters

  • name — string, optional. Snapshot name (filename-safe). Defaults to ISO-8601 timestamp.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

App info

asomium_update_app_categories

PATCH the editable AppInfo’s primary and/or secondary category. Category ids are Apple’s slug strings: BOOKS, BUSINESS, DEVELOPER_TOOLS, EDUCATION, ENTERTAINMENT, FINANCE, FOOD_AND_DRINK, GAMES, GRAPHICS_AND_DESIGN, HEALTH_AND_FITNESS, LIFESTYLE, MAGAZINES_AND_NEWSPAPERS, MEDICAL, MUSIC, NAVIGATION, NEWS, PHOTO_AND_VIDEO, PRODUCTIVITY, REFERENCE, SHOPPING, SOCIAL_NETWORKING, SPORTS, STICKERS, TRAVEL, UTILITIES, WEATHER.

Works only while AppInfo is in an editable state (PREPARE_FOR_SUBMISSION or a rejected flavour). Game subcategories not yet exposed.

Example prompt — Set ThinkBud’s primary category to EDUCATION and secondary to PRODUCTIVITY.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • secondary_category — string, optional. Apple category id (uppercase slug). Optional.
  • primary_category — string, optional. Apple category id (uppercase slug). Optional — omit to leave unchanged.

asomium_update_app_privacy

Set per-locale privacy fields on an AppInfoLocalization: privacy_url, optional privacy_choices_url, and optional privacy_policy_text (some apps need an in-app policy text when no URL is provided). The locale must already exist on the AppInfo — create it with push_metadata first if not.

Example prompt — Set ThinkBud’s en-US privacy URL to https://nativefirstapp.com/privacy.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • locale — string, required. ASC locale code, e.g. ‘en-US’. Required.
  • privacy_url — string, optional. URL to the privacy policy.
  • privacy_choices_url — string, optional. Optional. URL to a privacy-choices page (data deletion / opt-out).
  • privacy_policy_text — string, optional. Optional. In-app privacy policy text for kids-category apps.

Reviews

asomium_respond_to_review

Post a developer response to a customer review. Apple caps the body at 5970 characters; validated client-side. Each review can have one response — posting a second time returns DUPLICATE, which the tool surfaces with a hint pointing the user to ASC web UI for edits (PATCH on response isn’t yet exposed).

Get review ids by first calling asomium_review_status — its recentReviews array now includes id for each review.

Example prompt — Reply to review [reviewId] thanking them for the feedback and explaining we shipped the fix in 2.4.4.

Parameters

  • body — string, required. Response text. Up to 5970 chars. Required.
  • review_id — string, required. Customer review id from asomium_review_status (or from the ASC web UI URL). Required.

asomium_review_status

Inspect an app’s current App Store Connect review status — especially useful for diagnosing a rejection. Returns the most recent version’s state (with the rejection type explained if applicable — DEVELOPER_REJECTED, METADATA_REJECTED, INVALID_BINARY, or REJECTED), a timeline of recent version states, the most recent customer reviews (which often reveal what triggered Apple’s reviewer), and a deep link to the Resolution Center where Apple writes the actual rejection message — that exact text is NOT exposed via the public ASC API, only via the web UI.

Visualization tip: recentReviews makes a great rating-distribution chart (bar of 1-5 stars counted) or a sentiment-over-time timeline. In artifact-capable clients (Claude.ai, Claude Desktop), render directly; in others pipe through asomium_render_chart.

Example prompt — What state is ThinkBud’s latest version in, and what are the last 20 customer reviews?

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • reviewLimit — integer, optional. How many recent customer reviews to fetch. Default 10, max 50.

Build & ship

asomium_build_and_distribute_direct

Direct-distribution counterpart to asomium_build_and_ship — drives the notarized-DMG pipeline that ships Asomium itself (outside the Mac App Store, because Asomium’s subprocess-spawning core is incompatible with App Sandbox).

Pipeline (shelled to scripts/release.sh + scripts/append-appcast.sh):

  1. xcodebuild archive (Release config, Developer ID signed)
  2. xcodebuild -exportArchive → Asomium.app
  3. hdiutil create → DMG, codesign with Developer ID
  4. notarytool submit + wait (keychain profile AC_NOTARY)
  5. stapler staple → DMG is Gatekeeper-passable offline
  6. Sparkle sign_update → EdDSA signature for appcast
  7. Optionally update dist/appcast.xml with a new <item>

Long-running: 4-10 minutes typical. The notarytool wait phase dominates wall time. Pass skip_notarize: true for a faster local dry run (DMG is signed but not notarized; won’t pass Gatekeeper on other Macs).

Example prompt — Build Asomium 1.0.1 with managed-AI release notes, notarize it, and append the entry to the appcast.

Parameters

  • project_root — string, optional. Absolute path to the local Asomium source repo (the directory containing ReleaseKit.xcodeproj). Falls back to the ASOMIUM_PROJECT_ROOT env var. One of the two must be set.
  • skip_notarize — boolean, optional. Skip notarytool submit + staple. Result: signed DMG that runs locally but fails Gatekeeper on other Macs. Useful for fast iteration. Default false.
  • release_notes_path — string, optional. Path to a markdown file whose contents become the <description> of the new appcast <item>. Implies update_appcast: true.
  • update_appcast — boolean, optional. After the DMG is built, prepend a new <item> to dist/appcast.xml. Default false unless release_notes_path or download_url is set.
  • download_url — string, optional. Override the appcast enclosure URL (default: $APPCAST_BASE_URL/$dmgName from env). Implies update_appcast: true.
  • version — string, optional. Marketing version (e.g. “1.0.1”). If omitted, uses the current MARKETING_VERSION from the pbxproj. CFBundleVersion is auto-bumped on every run.

asomium_build_and_ship

Run the App Store Connect ship pipeline as an async background job: xcodebuild archive → exportArchive → altool upload, plus optional submit-for-review. Per-app build config (Xcode project path, scheme, platform, configuration) is read from the handoff file the Asomium Mac app writes via Settings → <app> → Build & Ship.

Returns INSTANTLY with { jobId, status: "queued" } — the real work runs in a detached worker process that survives MCP server restarts and client disconnects. Poll asomium_job_status(jobId) every 20-60 seconds until state is “succeeded” (read result) or “failed” (read error). Cancel with asomium_cancel_job(jobId).

Wall time per phase: archive 1-3 min, export 30s, altool upload 2-10 min, submit-for-review wait 5-20 min when submit:true. Total can exceed 30 minutes; the async-job model means MCP client timeouts (Claude Desktop, Claude mobile dispatch) don’t matter — the work finishes regardless.

Set submit: true to chain straight into the submit step after upload — the worker polls ASC until the build is VALID, declares export compliance, attaches to the editable AppStoreVersion, and submits for review.

Example prompt — Build and upload ThinkBud, then submit for review when the build is VALID.

Parameters

  • poll_minutes — integer, optional. Only honoured with submit:true. Maximum minutes to wait for ASC to finish processing the build before submit. Clamped to [1, 90]. Default 30.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • platform — string, optional. Which platform’s saved build config to ship (‘iOS’ or ‘macOS’). Optional — omit when only one is configured. Required if the app has both an iOS and a macOS pick saved; otherwise the tool errors with a list of configured platforms so you can re-call with the right one.
  • submit — boolean, optional. If true, after upload poll ASC until the build is VALID, then declare export compliance, attach to the editable AppStoreVersion, and submit for review. Defaults to false (upload only).

asomium_bump_xcode_version

Bump the local Xcode project’s MARKETING_VERSION and/or CURRENT_PROJECT_VERSION via Apple’s agvtool. Closes the last gap in mobile-dispatch ship pipelines: every other step (build, archive, upload, submit) is MCP-native, but bumping the local pbxproj used to require a Code Task spawning a desktop session and waiting for permission prompts — none of which works headlessly from mobile. This tool runs entirely inside the MCP server process on the user’s Mac.

The full ship now fits in three MCP calls:

  1. asomium_bump_xcode_version → updates pbxproj
  2. asomium_build_and_ship → returns jobId
  3. asomium_job_status(jobId) → poll until done

Reads the per-app build config from the same handoff file asomium_build_and_ship uses; if there’s no config yet, the tool errors with a pointer to the Mac app’s Build & Ship settings panel.

Behaviour: · marketing_version + bump_build → set marketing, bump build (full release bump) · marketing_version only → set marketing, leave build untouched (rare) · bump_build only → bump build only (resubmitting same marketing version after a rejection) · neither → defaults to bump_build (idempotent-ish)

Example prompt — Bump ThinkBud’s marketing version to 2.4.6 and reset the build number to 1.

Parameters

  • marketing_version — string, optional. New marketing version, e.g. ‘2.1.0’. Must match X.Y or X.Y.Z. Optional.
  • bump_build — boolean, optional. Increment CFBundleVersion by 1. Defaults to true when marketing_version isn’t set, false when it is.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • platform — string, optional. Which platform’s saved build config to use (‘iOS’ or ‘macOS’). Optional — omit when only one is configured. Required if the app has both an iOS and a macOS pick saved; otherwise the tool errors with a list of configured platforms.

asomium_create_version

Create a new AppStoreVersion on ASC for an app — the ”+ Version” step before any metadata edits or build submissions can happen for a new release. If a version with the same string already exists for the same platform, returns the existing one (idempotent). Defaults to iOS; pass platform explicitly for macOS / tvOS / visionOS apps.

Example prompt — Create version 2.4.5 for ThinkBud on iOS.

Parameters

  • version — string, required. Marketing version string, e.g. ‘2.4.4’. Must be greater than the current live version. Required.
  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform code. Defaults to IOS.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

asomium_list_builds

List recent uploaded builds for an app, with their processing state and export-compliance status. Filter by platform and/or marketing version. Read-only.

Example prompt — Show me ThinkBud’s last 10 iOS builds and their processing states.

Parameters

  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. Optional. Restrict to one platform.
  • marketing_version — string, optional. Optional. Restrict to builds matching a specific marketing version (e.g. ‘2.4.4’).
  • limit — integer, optional. Number of builds to return. Default 20. Capped at 200.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

asomium_submit_for_review

Finish the post-upload pipeline for an app that already has an editable AppStoreVersion and an uploaded build. Mirrors the Submit-for-Review flow in the Asomium Mac app:

  1. Locate the editable AppStoreVersion for the requested platform.
  2. Poll /v1/builds until the newest build matching that platform + marketing version is VALID (or surface FAILED/INVALID terminal states).
  3. PATCH usesNonExemptEncryption: false on the build if compliance isn’t declared.
  4. Attach the build to the AppStoreVersion.
  5. Find or create a draft Review Submission for the app + platform.
  6. Attach the version as a submission item.
  7. Flip submitted: true — Apple takes over.

Use this after asomium_build_and_ship (without submit:true), or when a build was uploaded via the Asomium GUI or another machine and you want Claude to drive the final submit.

Runs synchronously. The poll loop dominates wall time — give it up to poll_minutes (default 30) for Apple to finish processing the build.

Example prompt — Finish the submit pipeline for ThinkBud — wait up to 30 min for the build to process if needed.

Parameters

  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform code. Defaults to IOS.
  • poll_minutes — integer, optional. Maximum minutes to wait for ASC processing. Clamped to [1, 90]. Default 30.
  • wait_for_processing — boolean, optional. If true, poll until the newest build for this platform+version reaches VALID. If false, fail fast when there’s no VALID build yet. Default true.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

TestFlight

asomium_list_beta_groups

List every TestFlight beta-tester group on an app — both internal (team-only) and external (public). Use this to discover group ids before calling asomium_submit_for_beta_review with a specific groups list. Read-only.

Example prompt — List all internal and external TestFlight groups configured for ThinkBud.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

asomium_submit_for_beta_review

Submit a build to TestFlight beta testers. Mirrors the Submit-to-TestFlight sheet in the Asomium Mac app:

  1. Resolve the target build — explicit build_id, or auto-pick the newest VALID build for the requested platform (polling until ASC finishes processing).
  2. PATCH usesNonExemptEncryption: false on the build if compliance isn’t declared.
  3. POST/PATCH the “What to test” localization (whats_new text, locale defaults to en-US).
  4. Attach the build to each requested beta group (resolves names case-insensitively, or take ids verbatim). Empty list → defaults to every internal group on the app.
  5. If any selected group is external AND submit_for_external_review is true (default), POST betaAppReviewSubmissions so external testers can see the build once Apple approves.

Internal groups don’t need Beta App Review — they see the build immediately after attach. External groups only see APPROVED builds. The default behaviour is “submit external groups for review so they see this build automatically once approved” — set submit_for_external_review: false to attach without queueing for review (useful when you want to gate the external rollout manually).

Runs synchronously. The poll loop for build VALID dominates wall time; cap with poll_minutes.

Example prompt — Submit the freshly-uploaded build of ThinkBud to TestFlight beta groups ‘TF Internal’ and ‘Power Users’.

Parameters

  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform code. Defaults to IOS.
  • locale — string, optional. Locale for the ‘What to test’ text. Defaults to en-US (Apple’s fallback locale for international testers).
  • wait_for_processing — boolean, optional. If true, poll until the newest build for this platform reaches VALID. If false, fail fast when there’s no VALID build yet. Default true.
  • groups — array, optional. Beta group names or ids. Empty / omitted → every internal group on the app.
  • poll_minutes — integer, optional. Maximum minutes to wait for ASC processing. Clamped to [1, 90]. Default 30.
  • whats_new — string, optional. ‘What to test’ text shown to TestFlight users. Optional — omit to leave the build’s existing localization untouched.
  • submit_for_external_review — boolean, optional. If any selected group is external, also POST betaAppReviewSubmissions so external testers see the build once Apple approves. Default true.
  • build_id — string, optional. Optional. ASC build id to submit. If omitted, the newest VALID build on the platform is auto-picked.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

Release control

asomium_phased_release_control

Inspect or control an active phased rollout. Auto-discovers the version that has a phased-release resource attached on the requested platform, then applies the action:

· status → fetch current state + day · pause → PATCH state=PAUSED · resume → PATCH state=ACTIVE · release_to_all → PATCH state=COMPLETE · cancel → DELETE the phased resource

release_to_all ships the new version to all users early. cancel skips the staged rollout entirely (next App Store visit serves the new version to everyone).

Example prompt — Pause the phased rollout for ThinkBud on iOS — we’re seeing a crash on day 2.

Parameters

  • action — string (one of: status, pause, resume, release_to_all, cancel), required. Action to perform. Required.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform. Default IOS.

asomium_release_now

Trigger developer-driven release for the AppStoreVersion sitting in PENDING_DEVELOPER_RELEASE on the requested platform. Use after Apple approves a version that has releaseType: MANUAL. Errors with helpful state info if no version is waiting.

Example prompt — Release ThinkBud’s approved iOS version to users now.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform. Default IOS.

asomium_set_release_strategy

Configure how the editable AppStoreVersion is released once Apple approves it. PATCHes releaseType on the version and creates or deletes a phased-release resource so the on-ASC state matches the strategy you pick:

· manual → MANUAL, no phased rollout · automatic → AFTER_APPROVAL, no phased · phased → AFTER_APPROVAL + 7-day phased · scheduled → SCHEDULED + earliest_release_date

Operates on whichever version is currently editable for the requested platform.

Example prompt — Set ThinkBud’s release strategy to phased rollout on iOS.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • strategy — string (one of: manual, automatic, phased, scheduled), required. Release strategy. Required.
  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform. Default IOS.
  • earliest_release_date — string, optional. Required for strategy=scheduled. ISO 8601 timestamp, e.g. ‘2026-06-01T12:00:00Z’.

Assets

asomium_upload_screenshots

Upload screenshot image files to the editable AppStoreVersion across any number of locales / display types in one call. Each upload entry bundles a locale + display type (e.g. APP_IPHONE_67) + a list of absolute file paths. The tool delegates to the same ScreenshotPusher the Mac app uses — reservation, byte upload, commit, and per-set append/replace semantics behave identically.

Apple validates pixel dimensions per display_type after upload — wrong-size images fail at commit, not pre-flight. Display type codes are the same strings ASC uses internally (APP_IPHONE_67, APP_IPHONE_65, APP_IPAD_PRO_3GEN_129, APP_DESKTOP, APP_APPLE_VISION_PRO, etc.).

Example prompt — Upload screenshots/iphone67/.png to the en-US APP_IPHONE_67 set, replacing the existing screenshots.*

Parameters

  • uploads — array, required. Required. Array of upload groups.
  • mode — string (one of: append, replace_set), optional. append (default) leaves the existing screenshots in each touched set and adds new ones; replace_set deletes the existing set first.
  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform code. Default IOS.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

Monetization

asomium_list_iaps

List the app’s in-app purchases via the inAppPurchasesV2 endpoint — one-time consumables, non-consumables, and non-renewing subscriptions. Auto-renewing subscriptions live under a separate resource family (subscriptionGroups → subscriptions) and are not listed here.

Example prompt — List every in-app purchase configured for ThinkBud.

Parameters

  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • limit — integer, optional. Max IAPs to return. Default 50, capped at 200.

asomium_list_in_app_events

List the app’s in-app events (IAEs) — Apple’s time-bounded App Store promotions. Returns each event’s badge, state, primary locale, deep-link URL, purchase requirement, and the event/publish time windows.

Example prompt — Show ThinkBud’s current and upcoming in-app events.

Parameters

  • limit — integer, optional. Max events to return. Default 50, capped at 50 server-side.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.

Analytics

asomium_get_sales_report

Fetch an Apple Sales and Trends report — gzipped TSV body, decompressed and aggregated server-side. Returns total units sold and proceeds-by-currency (Apple reports each territory in its local currency, so per-currency breakdown is more useful than a fake combined total).

Vendor number is the developer team’s id, NOT the app id. Find it in App Store Connect → Payments and Financial Reports footer. Pass via vendor_number arg or set ASOMIUM_ASC_VENDOR_NUMBER in the environment Claude Code launches the MCP server with.

Availability: DAILY at T+1, WEEKLY on the Sunday after the reporting week, MONTHLY on the 5th of the following month. Default report_date is yesterday in Pacific Time (Apple’s reporting calendar).

Set include_rows: true to get the full parsed TSV back; default returns only totals

  • row count to keep responses small.

Visualization tip: the totals payload (units + proceedsByCurrency) and the per-row breakdown (with include_rows: true) are chart-ready. In Claude.ai / Desktop, render as a recharts artifact (bar per currency or pie per country). In artifact-less clients, pipe through asomium_render_chart.

Example prompt — Pull yesterday’s SALES SUMMARY for vendor 1234567 and tell me total units + proceeds by currency.

Parameters

  • include_rows — boolean, optional. If true, include the full parsed TSV rows. Default false (totals + row count only).
  • report_subtype — string (one of: SUMMARY, DETAILED, OPT_IN), optional. Apple report sub-type. Default SUMMARY.
  • vendor_number — string, optional. Developer team vendor number. Falls back to ASOMIUM_ASC_VENDOR_NUMBER env var if omitted.
  • report_type — string (one of: SALES, PRE_ORDER, SUBSCRIPTION, SUBSCRIPTION_EVENT, SUBSCRIBER, SUBSCRIPTION_OFFER_CODE_REDEMPTION, NEWSSTAND), optional. Apple report type. Default SALES.
  • frequency — string (one of: DAILY, WEEKLY, MONTHLY, YEARLY), optional. Reporting cadence. Default DAILY.
  • report_date — string, optional. YYYY-MM-DD. Default: yesterday in Pacific Time. For WEEKLY pass the Sunday end date; for MONTHLY pass YYYY-MM.

Visualization

asomium_dashboard

Composite “executive summary” for one app — fans out 4-6 ASC + local reads in parallel and returns a single payload sized for one dashboard render. Sections:

· app identity + current version state · recent builds + processing-state counts · tracked keywords with latest rank, 30-day delta, and last-60-snapshot series for sparklines · reviews: average rating, 1-5 star distribution histogram, last N reviews · phased rollout (if active on the current version) · daily sales totals (if vendor_number provided or ASOMIUM_ASC_VENDOR_NUMBER env set)

Designed for one-shot dashboard rendering: in Claude.ai / Claude Desktop, the LLM should generate a single React artifact with one card per section (recharts for the sparklines + distribution). In terminal clients, summarise in markdown sections.

Wall time ≈ slowest single ASC call (~500ms) thanks to parallel fan-out, not the sum of all reads.

Example prompt — Pull the full health dashboard for ThinkBud on iOS — version state, builds, keyword ranks, reviews — and render it as one artifact.

Parameters

  • build_limit — integer, optional. Max recent builds to include. Default 5, capped at 50.
  • app — string, required. App name, bundle id, or numeric ASC app id. Required.
  • vendor_number — string, optional. Optional. Adds yesterday’s SALES SUMMARY to the dashboard. Falls back to ASOMIUM_ASC_VENDOR_NUMBER env var.
  • platform — string (one of: IOS, MAC_OS, TV_OS, VISION_OS), optional. ASC platform. Default IOS.
  • review_limit — integer, optional. Max recent reviews to include. Default 10, capped at 50.

asomium_render_chart

Render a line or bar chart from a generic data spec and return both raw SVG and a markdown- image-with-data-URI string. Composes nicely with other tools: call list_tracked_keywords(include_history: true) or get_sales_report(include_rows: true), shape the result into series[].points[], then render. Multi-series charts get colour-coded legend automatically.

For clients that render markdown images (Claude Desktop, Claude.ai) embed the markdownImage field directly in a reply. For terminal clients, save svg to a .svg file and open it.

Example prompt — Refresh ThinkBud’s tracked keyword ranks, then chart the last 30 days as a multi-line graph.

Parameters

  • height — integer, optional. SVG height in pixels. Default 420.
  • title — string, optional. Chart title, shown at top.
  • x_label — string, optional. X-axis label.
  • y_label — string, optional. Y-axis label.
  • type — string (one of: line, bar), optional. Chart type. Default ‘line’.
  • series — array, required. One or more data series. Multi-series gets a legend automatically.
  • width — integer, optional. SVG width in pixels. Default 800.

Async jobs

asomium_cancel_job

Request cancellation of a queued or running job. Flips a flag in the job’s status file; the worker checks the flag between phases and transitions to state=cancelled when it sees the request. Phases that are already in flight (e.g. an active altool upload) keep running until they complete or fail — there’s no force-kill. Use the workerPid from asomium_job_status if you need to escalate manually.

Idempotent. Terminal jobs (succeeded / failed / already cancelled) are no-ops.

Example prompt — Cancel job 8f3c2e1a — I started the wrong build target.

Parameters

  • jobId — string, required. Job id to cancel. Required.

asomium_job_status

Poll the status of an async-job tool call (today: asomium_build_and_ship). Returns the current state (queued, running, succeeded, failed, cancelled), the live progress message + stage, the last ~50 log entries, and (when terminal) the full result payload or error text. Idempotent and cheap — call every 20-60s while the job is running.

State transitions: · queued → running → succeeded | failed · queued | running → cancelled (if cancel request observed by the worker)

Example prompt — Poll job 8f3c2e1a — what stage is the build at and how long until it finishes?

Parameters

  • jobId — string, required. Job id returned by an async tool (e.g. asomium_build_and_ship). Required.

asomium_list_jobs

List recent async jobs on disk, newest first. Useful for “where did I leave off?” — works even in a fresh chat session after the original one that started the job has been closed. Returns a compact view (id, tool, state, last stage) without log tail / result text; call asomium_job_status for the full record.

Example prompt — Show me the last 10 async jobs and their states.

Parameters

  • limit — integer, optional. Max jobs to return. Default 25.

Account

asomium_usage_status

Show this month’s translate_field call count — just a stat in v1.0 (no managed quota, every user brings their own Anthropic key). Useful for the Mac-app UI to surface “translations this month: N”. v1.1 will turn this into a budget readout once the managed-AI proxy ships.

The counter auto-resets at the calendar month boundary; the on-disk file lives at ~/Library/Application Support/ReleaseKit/com.mariopek.releasekit/usage-ledger.json.

Example prompt — How many translate calls have I used this month?

Parameters

No parameters.

Every tool returns a structured JSON result an LLM can reason about, plus a human-readable summary field the model can paraphrase back to the user.

Last updated