AGENTS.md
+56 −11
https://raw.githubusercontent.com/erayendes/app-store-connect-mcp/HEAD/AGENTS.md
− Heimdall is an MCP server for the App Store Connect API and the App Store Server API (StoreKit 2). It is published to npm as `@erayendes/asc-mcp` and runs via `npx` — there is **nothing to clone, build, or `npm install`** to use it. It is client-agnostic: standard MCP over stdio. It serves 929 tools across 13 profiles: 888 generated from Apple's 1011 operations (the 123 deprecated ones stay unloaded unless asked for) and 41 hand-written.− Ask what the user works on. If they have not said, `analytics`, `marketing` and `app-info` are a sensible default. Each profile is a small scoped server; the table is in [PROFILES_en.md](docs/PROFILES_en.md).− A big profile takes a colon and a list of its sub-profiles — `monetization:subscription-pricing,subscription-offers` is 56 tools where `monetization` is 212. Worth suggesting for `monetization`, `game-center`, `distribution`, `marketing` and `access`. The server is still called `ASC-Monetization`.− npx -y @erayendes/asc-mcp register monetization:subscription-pricing analytics− `register` only adds. It will not remove a profile the user set up earlier, and re-running it with the same arguments changes nothing.− If the user would rather do the whole thing themselves, `setup` alone covers both steps: it collects the credentials *and* registers with every client it finds.− - **Finding a tool that isn't loaded:** call `asc__search_tools` (searches all 1011 operations plus StoreKit) or `asc__discover_domains`. They name the sibling profile that owns a tool and print the exact command to add it.− - **`asc__load` is not a reliable way to get new tools.** It adds a sub-profile for this session and the server announces it, but some clients never show the new tools mid-session (the Claude desktop app's Code tab among them), and they do not appear next turn either. Reads work at once through `asc__call`. For the tools themselves, run the `register` command its reply names — e.g. `npx -y @erayendes/asc-mcp register access:users,beta-groups` — after the user says yes, then ask them to restart t− - **StoreKit / customer transactions** live on the `monetization` profile (`monetization:storekit`). Each tool takes an optional `app` (name, bundle ID or Apple ID) and looks the bundle ID up; it can be left out when the account has one app or `ASC_BUNDLE_ID` is set. `environment` (`Production` by default, or `Sandbox`) is optional too.− - **Safety:** `--read-only` mode blocks every mutating tool. `destructiveHint` no longer means "this is a DELETE" — it now covers every write whose consequence the HTTP method cannot show, so a description ending in `REVENUE-`, `RELEASE-`, `INFRASTRUCTURE-`, `ACCESS-` or `DESTRUCTIVE-level write.` is flagged too. Those change live data: say what will happen and get a yes before calling one.− - **Prefer the macro over the chain.** Hand-written tools (`pricing__*`, `listing__*`, `preflight__*`, `release__submit`, `testflight__*`, `ci__diagnose_run`, `analytics__get_report`, `reviews_ai__*`) answer in one call what the raw tools need a chain for; the table is in [GUIDE_en.md](docs/GUIDE_en.md#one-call-instead-of-a-chain). Three do something the raw tools cannot do at all: `listing__upload_screenshot` and `listing__upload_asset` perform Apple's reserve/upload/commit sequence, and `prici+ Heimdall is an MCP server for the App Store Connect API and the App Store Server API (StoreKit 2). It is published to npm as `@erayendes/asc-mcp` and runs via `npx` — there is **nothing to clone, build, or `npm install`** to use it. It is client-agnostic: standard MCP over stdio. It serves 786 tools across 14 profiles: 734 generated from Apple's 1036 operations (the 185 that Apple deprecated or replaced are not built) and 52 hand-written.+ Profiles are cut by the work the user does: `general`, `distribution`, `monetization`, `marketing`, `testflight`, `access` and so on. App lookup, `asc__search_tools`, `asc__discover_domains`, `asc__account_status` and the `media__*` tools are in none of them — they live in **ASC-Core** (`core`), a server of its own that `register` and `setup` add next to the profiles. A profile server also carries them when started with `--with-core`, as the Xcode plug-ins are. Every server, ASC-Core or not, has+ Without a profile argument, the server starts as **ASC-Default**: `core` + `general` + `analytics` in one process, forced read-only, even with `ASC_READ_ONLY=false`. It lists no write tools and can start and list tools without credentials; live account reads still need credentials. Its instructions and `asc__status` explain this default read-only set. For full use, tell the user to run `npx -y @erayendes/asc-mcp setup` in a terminal and pick profiles. An unknown or retired profile name still ser+ Ask what the user works on. If they have not said, `analytics`, `marketing` and `general` are a sensible default. Each profile is a small scoped server; the table, down to every tool, is in [PROFILES_en.md](docs/PROFILES_en.md).+ A big profile takes a colon and a list of its sub-profiles — `monetization:subscription,subscription-offers` is 65 tools where `monetization` is 186. Worth suggesting for `monetization`, `game-center`, `distribution`, `testflight`, `general` and `marketing`. The server is still called `ASC-Monetization`.+ npx -y @erayendes/asc-mcp register monetization:subscription,subscription-offers analytics+ What `register` changes, which is what the user is saying yes to:+ - **It adds** the profiles you name, and `ASC-Core` beside them.+ - **It never removes a live profile** the user set up earlier, and re-running it with the same arguments changes nothing.+ - **It does remove or rewrite three kinds of entry.** A server name from before 2.5 (`asc-analytics`) moves to the current name. An entry whose profile no longer exists (`app-info`, `monetization:subscription-pricing` from 2.x) is deleted, if it is Heimdall's own, carries no credentials of its own and could be read in full; any other such entry is reported and left as it is. An entry on the other release channel (stable or beta) is rewritten to this one, keeping its flags and env. ASC-Core goes + ASC-Core takes the strictest setting in each client: if any Heimdall entry there is read-only (`--read-only`, or `ASC_READ_ONLY` in its env), ASC-Core is registered `--read-only` too. It is **not added** where it cannot be shown to sign in as the same account, and the output says why:+ - the Heimdall entries there use different App Store Connect accounts;+ - they carry credentials of their own in their `env`, while ASC-Core would use the shared config;+ - the config, or one of its entries, could not be read in full — an entry that loads its environment from an `envFile` counts, since what it signs in with cannot be seen.+ Relay that reason; do not add ASC-Core by hand to get around it.+ For local installation problems, run `npx -y @erayendes/asc-mcp doctor`. It is read-only: it reports Node and package versions, release channel, client registrations and profiles, ASC-Core coverage, and credential availability without reading key contents or making network calls. It does not start client CLIs. Relay the next step it prints; restart the client after registration changes. `doctor` checks only local availability; use `asc__status` for the live connection check. If credentials are m+ If the user would rather do the whole thing themselves, `setup` alone covers both steps: it collects the credentials *and* registers with every client it finds, ASC-Core included.+ **Coming from 2.x.** A config from 2.x names profiles that no longer exist (`app-info`, `monetization:subscription-pricing`). Such a server starts with a single tool that says so. Neither `setup` nor `register` maps an old profile to a new one: they delete such entries (when they are Heimdall's own and clean, as above; others are reported), and the user picks the profiles again — `app-info` is now `general`, the old money sub-profiles are `monetization:subscription`, `in-app-purchases`, `subscri+ - **Finding a tool that isn't loaded:** call `asc__search_tools` or `asc__discover_domains`, both on ASC-Core. Search covers the 832 operations Heimdall builds, plus the StoreKit tools and Heimdall's macros (not the `reviews_ai__*` tools); under `--read-only` it leaves out the writes. It names the profile that owns a tool and prints the exact command to add it. Do not conclude an operation does not exist because it is not in this session's list.+ - **There is no way to add tools mid-session.** Some clients never show a changed tool list (the Claude desktop app's Code tab among them), and the tools do not appear next turn either. On a server started with only some of its sub-profiles, reads from the rest work at once through `asc__call`. For the tools themselves, run the `register` command the server's reply names — e.g. `npx -y @erayendes/asc-mcp register testflight:groups,testers` — after the user says yes, then ask them to restart thei+ - **When a 403 comes back,** call `asc__status` with `check_capabilities: true` before blaming the key: it probes `reports`, `metadata`, `reviews`, `userManagement` and `provisioning`, each `ok` / `forbidden` / `unauthorized` / `agreement` / `unknown`. `agreement` is an unsigned or expired agreement that only the Account Holder can clear, and no key fixes it; `unknown` is an inconclusive probe, not a denial. App Manager covers almost all day-to-day work; Admin is needed for user management and f+ - **Territories are ISO-3166 alpha-3:** `USA`, `TUR`, `DEU` — never `US`, `TR`, `DE`. The two-letter form is not rejected; it returns 200 and an empty list that reads as "no data here".+ - **StoreKit / customer transactions** live on `monetization:transactions`. Each tool takes an optional `app` (name, bundle ID or Apple ID) and looks the bundle ID up; it can be left out when the account has one app or `ASC_BUNDLE_ID` is set. `environment` (`Production` by default, or `Sandbox`) is optional too.+ - **Subscriptions and in-app purchases are v2 only.** The v1 localization, image and submission tools Apple retired are not served; use the `*_v2` tools and their versions.+ - **Safety:** a server started with `--read-only` (or `ASC_READ_ONLY=true`) does not list any tool that can change something. `destructiveHint` does not mean "this is a DELETE" — it covers every write whose consequence the HTTP method cannot show, so a description ending in `REVENUE-`, `RELEASE-`, `INFRASTRUCTURE-`, `ACCESS-` or `DESTRUCTIVE-level write.` is flagged too. Those change live data: say what will happen and get a yes before calling one.+ ## Prefer the macro over the chain+ Several questions have a one-call answer that replaces walking a chain of resources. Reach for these first — the raw tools stay available and are the right choice for anything the macro does not cover. The same table, for people, is in [GUIDE_en.md](docs/GUIDE_en.md#one-call-instead-of-a-chain).+ | Instead of | Call |+ |---|---|+ | app → group → subscription → price points | `pricing__get_subscription_price` / `pricing__set_subscription_price` (`monetization:subscription`) |+ | app → IAP → price schedule → prices | `pricing__get_iap_price` (`monetization:in-app-purchases`) |+ | rebuilding an IAP's whole price schedule to change one country | `pricing__set_iap_price` (`monetization:in-app-purchases`) — keeps every other price |+ | app → app price schedule → prices | `pricing__get_app_price` (`monetization:app-price`) |+ | setting a price country by country | `pricing__equalize_price` (`monetization:app-price`, `in-app-purchases` or `subscription`) — one anchor price, Apple derives the rest |+ | looking up a price point in every country, then building one offer body | `pricing__make_offer` (`monetization:subscription-offers`, `subscription-win-back` or `subscription-retention`) — win-back, promotional, retention or introductory offer, every country from one anchor price; introductory goes country by country and resumes |+ | group → subscription → version → localizations → availability → price for a new subscription | `pricing__setup_subscription` (`monetization:subscription`) — one confirmation; reuses an existing group without editing it |+ | page → localizations → library placements → images and videos | `media__list` (ASC-Core) — the version page, a custom product page, a product page test, an in-app event, a retention message or the library itself |+ | an owner → its image or file → reserve, upload, commit | `media__list` / `media__upload` / `media__delete` (ASC-Core) with a file `target`: App Clip header and advanced experience images, Game Center achievement, leaderboard, leaderboard set, activity and challenge images, in-app purchase and subscription images and review screenshots, encryption documents, App Review attachments, routing coverage, background asset files, build upload files — the targets and their rules are in [MEDIA_TARGETS_e+ | reserving a library image or video, uploading it, then placing it | `media__upload` (ASC-Core) |+ | placing, reordering, removing, archiving or renaming page media | `media__arrange` (ASC-Core) |