shipstores 0.1.0__tar.gz

shipstores-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,12 @@
+name: Bug
+description: Something is wrong in a tool that uses the public APIs
+labels: [bug]
+body:
+  - type: input
+    id: tool
+    attributes: {label: Tool}
+    validations: {required: true}
+  - type: textarea
+    id: details
+    attributes: {label: What happened, description: Input you passed and the error. Redact keys and ids.}
+    validations: {required: true}

shipstores-0.1.0/.github/ISSUE_TEMPLATE/console-flow-broke.yml

@@ -0,0 +1,19 @@
+name: Console flow broke
+description: A tool that drives App Store Connect or Play Console stopped working
+labels: [console-breakage]
+body:
+  - type: input
+    id: tool
+    attributes: {label: Tool, placeholder: apple_set_app_privacy}
+    validations: {required: true}
+  - type: dropdown
+    id: store
+    attributes: {label: Store, options: [App Store Connect, Google Play Console]}
+    validations: {required: true}
+  - type: input
+    id: lang
+    attributes: {label: Console language, placeholder: en-US}
+  - type: textarea
+    id: error
+    attributes: {label: What happened, description: Error output and what you saw in the console. Blur account names.}
+    validations: {required: true}

shipstores-0.1.0/.github/ISSUE_TEMPLATE/new-tool.yml

@@ -0,0 +1,11 @@
+name: New tool
+description: A store step you still do by hand
+labels: [new-tool]
+body:
+  - type: textarea
+    id: step
+    attributes: {label: Which step, description: What you click today, in which store.}
+    validations: {required: true}
+  - type: textarea
+    id: api
+    attributes: {label: API or endpoint, description: Public API docs link, or the console request you saw in DevTools (redact ids).}

shipstores-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## What
+
+## Tested against
+- [ ] Real store (which one, test app)
+- [ ] Only offline (compile/import)
+
+## Checklist
+- [ ] Publishing tools say "External action" in the docstring
+- [ ] No credentials, real account ids or personal data
+- [ ] README "Hard-won lessons" updated if this fixes a store quirk

shipstores-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,12 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run --with ruff ruff check src --select E9,F
+      - run: uv run python -W error -c "import glob; [compile(open(f).read(), f, 'exec') for f in glob.glob('src/shipstores/*.py')]"
+      - run: uv run python -c "import asyncio; from shipstores.server import mcp; print(len(asyncio.run(mcp.list_tools())), 'tools')"

shipstores-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,15 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uv publish --trusted-publishing always

shipstores-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Credentials live in ~/.config/shipstores, never in the repo
+.env
+*.p8
+*service-account*.json
+*play-ops*.json
+config.toml

shipstores-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

shipstores-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — first public release
+
+60 tools. Install with `uvx shipstores`.
+
+- App Store Connect: builds, versions, listing, screenshots, subscriptions, age rating, categories, price, availability, privacy label, review submission and cancellation, TestFlight internal invites.
+- App Review: read rejection messages, reply with attachments and resubmit the rejected version.
+- Google Play: bundles, tracks, listing, screenshots, contact details, signing, App content declarations and data safety via console automation.
+- Expo/EAS: start, poll, download and submit builds (iOS submit via altool).

shipstores-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Thanks for helping! Store consoles change every few months, so real-world fixes are the most valuable contributions.
+
+## Setup
+
+```bash
+uv sync
+uv run python -c "import asyncio; from shipstores.server import mcp; print(len(asyncio.run(mcp.list_tools())), 'tools')"
+```
+
+You don't need store credentials to work on most of the code. To try tools against real stores, see "Credentials" in the README and use a test app.
+
+## What we love to merge
+
+- **A quirk you hit in production**: a rejection reason, an undocumented API rule, a console change. Add the fix *and* a line in the README's "Hard-won lessons".
+- **New tools** for steps you still do by hand (open an issue first with the store endpoint or console flow).
+- **Console labels in other languages**: console automation matches UI text literally (`pt-BR` and `en-US` today). Adding your console language is a great first PR.
+- Docs, examples, workflows for other stacks (Flutter, native Xcode/Gradle, Capacitor).
+
+## Guidelines
+
+- One tool = one store operation. Tools that publish or submit must say so in the first line of their docstring ("External action").
+- Tool docstrings are what the agent reads: be precise about preconditions, side effects and the next step.
+- Never commit credentials, account ids, bundle ids of real apps or screenshots with personal data.
+- Keep console automation in its own module (`apple_console.py`, `apple_review.py`, `play_console.py`) so breakage stays contained.
+- Run before opening a PR:
+  ```bash
+  uv run ruff check src
+  uv run python -W error -c "import glob; [compile(open(f).read(), f, 'exec') for f in glob.glob('src/shipstores/*.py')]"
+  ```
+
+## Reporting a broken console flow
+
+Open a "Console flow broke" issue with the tool name, the store, your console language and the error. Screenshots help — blur account names.

shipstores-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matheus Fidelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shipstores-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: shipstores
+Version: 0.1.0
+Summary: MCP server to ship iOS and Android apps from AI agents: App Store Connect, Google Play Console and Expo EAS
+Project-URL: Homepage, https://github.com/FidelisMM/shipstores
+Project-URL: Issues, https://github.com/FidelisMM/shipstores/issues
+Author: Matheus Fidelis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: android,app-store-connect,claude,eas,expo,fastlane-alternative,google-play,ios,mcp,model-context-protocol
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: google-auth>=2.57.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pyjwt[crypto]>=2.13.0
+Requires-Dist: requests>=2.34.2
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png">
+    <img alt="shipstores — ship iOS and Android apps from your AI agent" src="assets/banner-light.png" width="100%">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-7C6CFF"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white">
+  <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-C04CFD">
+  <img alt="Works with Claude Code" src="https://img.shields.io/badge/works%20with-Claude%20Code-D97757">
+  <a href="https://github.com/FidelisMM/shipstores/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/FidelisMM/shipstores/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/FidelisMM/shipstores/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/FidelisMM/shipstores?style=flat&color=7C6CFF"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#tools">60 tools</a> ·
+  <a href="#workflows">Workflows</a> ·
+  <a href="#hard-won-lessons">Hard-won lessons</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+---
+
+**shipstores** drives App Store Connect and Google Play Console end to end — builds, store listings, screenshots, privacy labels, review submission and even replying to App Review — so Claude (or any MCP client) can take an app from `eas build` to "Waiting for Review" without you clicking through two consoles.
+
+> Built because publishing was always the slowest part of shipping an app. Every quirk documented below cost at least one rejected build to discover.
+
+```mermaid
+flowchart LR
+    A["🤖 Claude / any MCP client"] -->|"tools"| M["shipstores"]
+    M -->|"public API"| ASC["App Store Connect"]
+    M -->|"public API"| GP["Google Play Developer API"]
+    M -->|"eas-cli"| EAS["Expo EAS builds"]
+    M -.->|"console automation<br/>(dedicated browser profile)"| C["Privacy label · availability<br/>App Review replies · Play App content"]
+```
+
+## Why
+
+Publishing a mobile app is ~40 manual steps across two consoles, half of which have no public API. AI agents can write your app, but they stall at the store. This server closes that gap:
+
+| | App Store Connect | Google Play |
+|---|---|---|
+| Upload build, versions, listing, screenshots | ✅ API | ✅ API |
+| Subscriptions / in-app purchases | ✅ API | — |
+| Age rating, categories, price, URLs | ✅ API | ✅ API |
+| **Privacy label & country availability** | ✅ console's internal API | ✅ Data safety via console |
+| **Read the rejection & reply to App Review (with video)** | ✅ console | — |
+| **"App content" declarations** (11 forms, no API) | — | ✅ console automation |
+| Create the app record | 🧭 opens the right form, tells you what to type | 🧭 same |
+| Expo / EAS builds | ✅ start, poll, download, submit | ✅ |
+
+Neither store lets anyone create an app record through an API, so `*_create_app_form` opens the right page in a logged-in browser and returns the exact values to fill. Everything else is automated.
+
+## Quick start
+
+Requirements: Python 3.12+, [uv](https://docs.astral.sh/uv/), an App Store Connect API key and/or a Google Play service account. Xcode command line tools for iOS uploads (`xcrun altool`).
+
+Add it to Claude Code (no clone needed, `uvx` fetches and runs it):
+
+```bash
+claude mcp add shipstores \
+  -e ASC_KEY_ID=ABC123XYZ \
+  -e ASC_ISSUER_ID=00000000-0000-0000-0000-000000000000 \
+  -e ASC_PRIVATE_KEY_PATH=~/.config/shipstores/AuthKey_ABC123XYZ.p8 \
+  -e PLAY_SERVICE_ACCOUNT_PATH=~/.config/shipstores/play-service-account.json \
+  -- uvx --from git+https://github.com/FidelisMM/shipstores shipstores
+```
+
+Then ask your agent: *"run store_doctor"*. It checks both credentials with real calls and detects your Apple Team ID for you.
+
+### Credentials
+
+| Variable | Required | What it is |
+|---|---|---|
+| `ASC_KEY_ID`, `ASC_ISSUER_ID` | iOS | App Store Connect → Users and Access → Integrations → API key (role **Admin** or **App Manager**) |
+| `ASC_PRIVATE_KEY_PATH` | iOS | the `.p8` file (default `~/.config/shipstores/AuthKey_<KEY_ID>.p8`) |
+| `APPLE_TEAM_ID` | no | detected by `store_doctor` from any bundle ID |
+| `PLAY_SERVICE_ACCOUNT_PATH` | Android | service account JSON invited in Play Console with release permissions |
+| `PLAY_DEVELOPER_ID` | console forms | the number after `/developers/` in the Play Console URL |
+
+Values can also live in `~/.config/shipstores/config.toml` — see [`config.example.toml`](config.example.toml). Nothing secret is ever written to the repo.
+
+### Console features (optional)
+
+Privacy labels, availability, App Review replies and Play "App content" forms run through the store consoles' own web endpoints in a dedicated, logged-in browser profile, driven by [browser-harness](https://github.com/browser-use/browser-harness). Log in once:
+
+```bash
+uvx --from git+https://github.com/FidelisMM/shipstores python -m shipstores.browser login   # opens a window; sign in to both consoles (2FA included)
+```
+
+> ⚠️ These features use undocumented console endpoints (the same family fastlane's Spaceship relies on). They work today and are isolated behind small modules, but Apple or Google can change them without notice. PRs that keep them working are very welcome.
+
+## Tools
+
+**Diagnostics** — `store_doctor`, `store_browser_session`, `store_audit_identity`
+
+**Apple: build & release** — `apple_list_apps`, `apple_register_bundle_id`, `apple_create_app_form`, `apple_upload_build`, `apple_list_builds`, `apple_create_version`, `apple_list_versions`, `apple_set_version_string`, `apple_attach_build`, `apple_submit_for_review`, `apple_resubmit_for_review`, `apple_cancel_submission`, `apple_testflight_invite`
+
+**Apple: listing & app setup** — `apple_update_listing`, `apple_upload_screenshots`, `apple_set_app_info` (subtitle, URLs, categories, copyright, content rights), `apple_set_age_rating`, `apple_set_free_price`, `apple_set_availability`, `apple_set_app_privacy`, `apple_review_details`, `apple_set_review_details`
+
+**Apple: App Review** — `apple_review_messages` (read the rejection and its guideline), `apple_reply_review` (answer with text + attachments; iPhone HEVC videos are converted to H.264)
+
+**Apple: subscriptions** — `apple_create_subscription_group`, `apple_create_subscription`, `apple_list_price_points`, `apple_set_subscription_price`, `apple_set_subscription_availability`, `apple_create_intro_offer`, `apple_list_subscriptions`, `apple_upload_subscription_screenshot`
+
+**Google Play** — `play_create_app_form`, `play_track_status`, `play_upload_bundle`, `play_promote_release`, `play_update_listing`, `play_upload_screenshots`, `play_list_screenshots`, `play_contact_details`, `play_set_contact_details`, `play_signing_sha1`, `play_submission_status`, `play_submit_for_review`
+
+**Play Console forms** — `play_content_status`, `play_content_open`, `play_content_options`, `play_content_answer`, `play_content_save`, `play_data_safety_fill`, `play_data_safety_export`, `play_data_safety_import`
+
+**Expo / EAS** — `eas_build_list`, `eas_build_start`, `eas_build_status`, `eas_build_download`, `eas_submit`
+
+Tools that publish or submit (`apple_submit_for_review`, `apple_resubmit_for_review`, `apple_reply_review`, `apple_cancel_submission`, `apple_set_*`, `apple_testflight_invite`, `play_upload_bundle`, `play_promote_release`, `play_upload_screenshots`) say so in their description, so the agent confirms with you first.
+
+## Workflows
+
+**New iOS app**
+```
+apple_register_bundle_id → apple_create_app_form → [fill in the browser]
+→ apple_list_apps → eas_build_start / apple_upload_build → apple_list_builds (wait for VALID)
+→ apple_attach_build → apple_update_listing → apple_set_app_info → apple_set_age_rating
+→ apple_set_free_price → apple_set_availability → apple_set_app_privacy
+→ apple_upload_screenshots → apple_set_review_details → apple_submit_for_review
+```
+
+**New Android app**
+```
+play_create_app_form → [fill in the browser] → play_upload_bundle (track=internal)
+→ play_update_listing → play_content_* / play_data_safety_fill → play_promote_release (production)
+```
+
+**Rejected with "Guideline 2.1 – Information Needed"** (standard for new developer accounts)
+```
+apple_review_messages → record the iPhone walkthrough → apple_set_review_details (answers in Notes)
+→ apple_reply_review (answers + video) → apple_resubmit_for_review
+```
+
+## Hard-won lessons
+
+The part people bookmark. Each one cost a rejected build or a lost afternoon.
+
+**App Store Connect**
+- **New developer accounts get "2.1 Information Needed" on the first submission**, regardless of app quality. Apple wants a screen recording from a *physical* device that starts at app launch from the Home Screen and shows login, the main flow and account deletion, plus purpose, access instructions, external services, regional differences and regulated-industry info — in the reply *and* in the review Notes. Replying is not enough: the version stays "Rejected" until you resubmit it (`apple_resubmit_for_review`, or "Update Review" on the version page).
+- **Health apps must ship from an organization account** (Guideline 5.1.1(ix)). An app rejected on an individual account can't be transferred (transfers need a released version): it becomes a new app with a new bundle ID.
+- **You can't learn your Team ID from the API until a bundle ID exists**; then it's the bundle's `seedId`.
+- **Privacy label records need category + purpose + protection in the same record.** Separate records are accepted one by one, then publishing fails with *"An app data usage is missing a category/purpose or data protection type"*.
+- **Availability needs every territory in the payload**, each flagged available or not — and the public API returns 409 anyway; the console endpoint works.
+- **Cancelling a submission also cancels its subscriptions, and that can't be undone by API.** Re-adding them requires the console (details in [`docs/apple-subscriptions.md`](docs/apple-subscriptions.md)).
+- **An app with an auto-renewable subscription is auto-rejected (3.1.2) without a working Terms of Use link** in the listing. The standard Apple EULA link fixes it without a new build.
+- **`xcrun altool` won't take a key path argument**, but it honors `API_PRIVATE_KEYS_DIR`.
+- **Screenshots belong to a version on iOS** (a released version won't accept new ones — create the next version) but to the listing on Play (live immediately).
+
+**Expo / EAS**
+- `eas submit --non-interactive` refuses App Store Connect API keys; this server downloads the `.ipa` and uploads with `altool` instead.
+- `eas build:view` rejects `--non-interactive` ("Nonexistent flag") — a classic source of silent failures in wrappers.
+- APNs keys are per team. After moving an app to another Apple team, a push key from the old team silently stops delivering (`InvalidProviderToken`).
+
+**Google Play**
+- The 11 "App content" declarations have no API. The Material radio `<input>` sits ~15px above the visible circle; clicking the center focuses but doesn't select. The accessibility tree is the source of truth.
+- Play Console app and developer ids only appear in console URLs; no API resolves them from a package name.
+
+## Contributing
+
+Contributions are what make this useful for everyone — new stores' quirks change monthly. See [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues are labeled [`good first issue`](https://github.com/FidelisMM/shipstores/labels/good%20first%20issue).
+
+### Contributors
+
+<a href="https://github.com/FidelisMM/shipstores/graphs/contributors">
+  <img alt="Contributors" src="https://contrib.rocks/image?repo=FidelisMM/shipstores" />
+</a>
+
+## Star history
+
+<a href="https://star-history.com/#FidelisMM/shipstores&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=FidelisMM/shipstores&type=Date&theme=dark" />
+    <img alt="Star history chart" src="https://api.star-history.com/svg?repos=FidelisMM/shipstores&type=Date" width="600" />
+  </picture>
+</a>
+
+## License
+
+[MIT](LICENSE) © Matheus Fidelis. Not affiliated with Apple or Google; App Store Connect and Google Play are trademarks of their owners.

shipstores-0.1.0/README.md

@@ -0,0 +1,184 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png">
+    <img alt="shipstores — ship iOS and Android apps from your AI agent" src="assets/banner-light.png" width="100%">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-7C6CFF"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white">
+  <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-C04CFD">
+  <img alt="Works with Claude Code" src="https://img.shields.io/badge/works%20with-Claude%20Code-D97757">
+  <a href="https://github.com/FidelisMM/shipstores/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/FidelisMM/shipstores/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/FidelisMM/shipstores/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/FidelisMM/shipstores?style=flat&color=7C6CFF"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#tools">60 tools</a> ·
+  <a href="#workflows">Workflows</a> ·
+  <a href="#hard-won-lessons">Hard-won lessons</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+---
+
+**shipstores** drives App Store Connect and Google Play Console end to end — builds, store listings, screenshots, privacy labels, review submission and even replying to App Review — so Claude (or any MCP client) can take an app from `eas build` to "Waiting for Review" without you clicking through two consoles.
+
+> Built because publishing was always the slowest part of shipping an app. Every quirk documented below cost at least one rejected build to discover.
+
+```mermaid
+flowchart LR
+    A["🤖 Claude / any MCP client"] -->|"tools"| M["shipstores"]
+    M -->|"public API"| ASC["App Store Connect"]
+    M -->|"public API"| GP["Google Play Developer API"]
+    M -->|"eas-cli"| EAS["Expo EAS builds"]
+    M -.->|"console automation<br/>(dedicated browser profile)"| C["Privacy label · availability<br/>App Review replies · Play App content"]
+```
+
+## Why
+
+Publishing a mobile app is ~40 manual steps across two consoles, half of which have no public API. AI agents can write your app, but they stall at the store. This server closes that gap:
+
+| | App Store Connect | Google Play |
+|---|---|---|
+| Upload build, versions, listing, screenshots | ✅ API | ✅ API |
+| Subscriptions / in-app purchases | ✅ API | — |
+| Age rating, categories, price, URLs | ✅ API | ✅ API |
+| **Privacy label & country availability** | ✅ console's internal API | ✅ Data safety via console |
+| **Read the rejection & reply to App Review (with video)** | ✅ console | — |
+| **"App content" declarations** (11 forms, no API) | — | ✅ console automation |
+| Create the app record | 🧭 opens the right form, tells you what to type | 🧭 same |
+| Expo / EAS builds | ✅ start, poll, download, submit | ✅ |
+
+Neither store lets anyone create an app record through an API, so `*_create_app_form` opens the right page in a logged-in browser and returns the exact values to fill. Everything else is automated.
+
+## Quick start
+
+Requirements: Python 3.12+, [uv](https://docs.astral.sh/uv/), an App Store Connect API key and/or a Google Play service account. Xcode command line tools for iOS uploads (`xcrun altool`).
+
+Add it to Claude Code (no clone needed, `uvx` fetches and runs it):
+
+```bash
+claude mcp add shipstores \
+  -e ASC_KEY_ID=ABC123XYZ \
+  -e ASC_ISSUER_ID=00000000-0000-0000-0000-000000000000 \
+  -e ASC_PRIVATE_KEY_PATH=~/.config/shipstores/AuthKey_ABC123XYZ.p8 \
+  -e PLAY_SERVICE_ACCOUNT_PATH=~/.config/shipstores/play-service-account.json \
+  -- uvx --from git+https://github.com/FidelisMM/shipstores shipstores
+```
+
+Then ask your agent: *"run store_doctor"*. It checks both credentials with real calls and detects your Apple Team ID for you.
+
+### Credentials
+
+| Variable | Required | What it is |
+|---|---|---|
+| `ASC_KEY_ID`, `ASC_ISSUER_ID` | iOS | App Store Connect → Users and Access → Integrations → API key (role **Admin** or **App Manager**) |
+| `ASC_PRIVATE_KEY_PATH` | iOS | the `.p8` file (default `~/.config/shipstores/AuthKey_<KEY_ID>.p8`) |
+| `APPLE_TEAM_ID` | no | detected by `store_doctor` from any bundle ID |
+| `PLAY_SERVICE_ACCOUNT_PATH` | Android | service account JSON invited in Play Console with release permissions |
+| `PLAY_DEVELOPER_ID` | console forms | the number after `/developers/` in the Play Console URL |
+
+Values can also live in `~/.config/shipstores/config.toml` — see [`config.example.toml`](config.example.toml). Nothing secret is ever written to the repo.
+
+### Console features (optional)
+
+Privacy labels, availability, App Review replies and Play "App content" forms run through the store consoles' own web endpoints in a dedicated, logged-in browser profile, driven by [browser-harness](https://github.com/browser-use/browser-harness). Log in once:
+
+```bash
+uvx --from git+https://github.com/FidelisMM/shipstores python -m shipstores.browser login   # opens a window; sign in to both consoles (2FA included)
+```
+
+> ⚠️ These features use undocumented console endpoints (the same family fastlane's Spaceship relies on). They work today and are isolated behind small modules, but Apple or Google can change them without notice. PRs that keep them working are very welcome.
+
+## Tools
+
+**Diagnostics** — `store_doctor`, `store_browser_session`, `store_audit_identity`
+
+**Apple: build & release** — `apple_list_apps`, `apple_register_bundle_id`, `apple_create_app_form`, `apple_upload_build`, `apple_list_builds`, `apple_create_version`, `apple_list_versions`, `apple_set_version_string`, `apple_attach_build`, `apple_submit_for_review`, `apple_resubmit_for_review`, `apple_cancel_submission`, `apple_testflight_invite`
+
+**Apple: listing & app setup** — `apple_update_listing`, `apple_upload_screenshots`, `apple_set_app_info` (subtitle, URLs, categories, copyright, content rights), `apple_set_age_rating`, `apple_set_free_price`, `apple_set_availability`, `apple_set_app_privacy`, `apple_review_details`, `apple_set_review_details`
+
+**Apple: App Review** — `apple_review_messages` (read the rejection and its guideline), `apple_reply_review` (answer with text + attachments; iPhone HEVC videos are converted to H.264)
+
+**Apple: subscriptions** — `apple_create_subscription_group`, `apple_create_subscription`, `apple_list_price_points`, `apple_set_subscription_price`, `apple_set_subscription_availability`, `apple_create_intro_offer`, `apple_list_subscriptions`, `apple_upload_subscription_screenshot`
+
+**Google Play** — `play_create_app_form`, `play_track_status`, `play_upload_bundle`, `play_promote_release`, `play_update_listing`, `play_upload_screenshots`, `play_list_screenshots`, `play_contact_details`, `play_set_contact_details`, `play_signing_sha1`, `play_submission_status`, `play_submit_for_review`
+
+**Play Console forms** — `play_content_status`, `play_content_open`, `play_content_options`, `play_content_answer`, `play_content_save`, `play_data_safety_fill`, `play_data_safety_export`, `play_data_safety_import`
+
+**Expo / EAS** — `eas_build_list`, `eas_build_start`, `eas_build_status`, `eas_build_download`, `eas_submit`
+
+Tools that publish or submit (`apple_submit_for_review`, `apple_resubmit_for_review`, `apple_reply_review`, `apple_cancel_submission`, `apple_set_*`, `apple_testflight_invite`, `play_upload_bundle`, `play_promote_release`, `play_upload_screenshots`) say so in their description, so the agent confirms with you first.
+
+## Workflows
+
+**New iOS app**
+```
+apple_register_bundle_id → apple_create_app_form → [fill in the browser]
+→ apple_list_apps → eas_build_start / apple_upload_build → apple_list_builds (wait for VALID)
+→ apple_attach_build → apple_update_listing → apple_set_app_info → apple_set_age_rating
+→ apple_set_free_price → apple_set_availability → apple_set_app_privacy
+→ apple_upload_screenshots → apple_set_review_details → apple_submit_for_review
+```
+
+**New Android app**
+```
+play_create_app_form → [fill in the browser] → play_upload_bundle (track=internal)
+→ play_update_listing → play_content_* / play_data_safety_fill → play_promote_release (production)
+```
+
+**Rejected with "Guideline 2.1 – Information Needed"** (standard for new developer accounts)
+```
+apple_review_messages → record the iPhone walkthrough → apple_set_review_details (answers in Notes)
+→ apple_reply_review (answers + video) → apple_resubmit_for_review
+```
+
+## Hard-won lessons
+
+The part people bookmark. Each one cost a rejected build or a lost afternoon.
+
+**App Store Connect**
+- **New developer accounts get "2.1 Information Needed" on the first submission**, regardless of app quality. Apple wants a screen recording from a *physical* device that starts at app launch from the Home Screen and shows login, the main flow and account deletion, plus purpose, access instructions, external services, regional differences and regulated-industry info — in the reply *and* in the review Notes. Replying is not enough: the version stays "Rejected" until you resubmit it (`apple_resubmit_for_review`, or "Update Review" on the version page).
+- **Health apps must ship from an organization account** (Guideline 5.1.1(ix)). An app rejected on an individual account can't be transferred (transfers need a released version): it becomes a new app with a new bundle ID.
+- **You can't learn your Team ID from the API until a bundle ID exists**; then it's the bundle's `seedId`.
+- **Privacy label records need category + purpose + protection in the same record.** Separate records are accepted one by one, then publishing fails with *"An app data usage is missing a category/purpose or data protection type"*.
+- **Availability needs every territory in the payload**, each flagged available or not — and the public API returns 409 anyway; the console endpoint works.
+- **Cancelling a submission also cancels its subscriptions, and that can't be undone by API.** Re-adding them requires the console (details in [`docs/apple-subscriptions.md`](docs/apple-subscriptions.md)).
+- **An app with an auto-renewable subscription is auto-rejected (3.1.2) without a working Terms of Use link** in the listing. The standard Apple EULA link fixes it without a new build.
+- **`xcrun altool` won't take a key path argument**, but it honors `API_PRIVATE_KEYS_DIR`.
+- **Screenshots belong to a version on iOS** (a released version won't accept new ones — create the next version) but to the listing on Play (live immediately).
+
+**Expo / EAS**
+- `eas submit --non-interactive` refuses App Store Connect API keys; this server downloads the `.ipa` and uploads with `altool` instead.
+- `eas build:view` rejects `--non-interactive` ("Nonexistent flag") — a classic source of silent failures in wrappers.
+- APNs keys are per team. After moving an app to another Apple team, a push key from the old team silently stops delivering (`InvalidProviderToken`).
+
+**Google Play**
+- The 11 "App content" declarations have no API. The Material radio `<input>` sits ~15px above the visible circle; clicking the center focuses but doesn't select. The accessibility tree is the source of truth.
+- Play Console app and developer ids only appear in console URLs; no API resolves them from a package name.
+
+## Contributing
+
+Contributions are what make this useful for everyone — new stores' quirks change monthly. See [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues are labeled [`good first issue`](https://github.com/FidelisMM/shipstores/labels/good%20first%20issue).
+
+### Contributors
+
+<a href="https://github.com/FidelisMM/shipstores/graphs/contributors">
+  <img alt="Contributors" src="https://contrib.rocks/image?repo=FidelisMM/shipstores" />
+</a>
+
+## Star history
+
+<a href="https://star-history.com/#FidelisMM/shipstores&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=FidelisMM/shipstores&type=Date&theme=dark" />
+    <img alt="Star history chart" src="https://api.star-history.com/svg?repos=FidelisMM/shipstores&type=Date" width="600" />
+  </picture>
+</a>
+
+## License
+
+[MIT](LICENSE) © Matheus Fidelis. Not affiliated with Apple or Google; App Store Connect and Google Play are trademarks of their owners.

shipstores-0.1.0/SECURITY.md

@@ -0,0 +1,5 @@
+# Security
+
+This server handles App Store Connect API keys and Google Play service accounts. It never stores or transmits them anywhere except to Apple and Google.
+
+If you find a vulnerability (for example, a way for a tool to leak credentials or act on an app the user didn't ask for), please **do not open a public issue**. Report it privately through GitHub's "Report a vulnerability" (Security tab) and we'll respond within a few days.

shipstores-0.1.0/config.example.toml

@@ -0,0 +1,18 @@
+# Copy to ~/.config/shipstores/config.toml (or point SHIPSTORES_CONFIG at it).
+# Environment variables with the same meaning always win over this file.
+# Never commit the real file: it holds paths to your keys.
+
+[apple]
+key_id = "ABC123XYZ"                                   # ASC_KEY_ID
+issuer_id = "00000000-0000-0000-0000-000000000000"     # ASC_ISSUER_ID
+private_key_path = "~/.config/shipstores/AuthKey_ABC123XYZ.p8"
+# team_id = "ABCDE12345"                               # optional: store_doctor detects it
+
+[play]
+service_account_path = "~/.config/shipstores/play-service-account.json"
+developer_id = "1234567890123456789"                   # number after /developers/ in the Play Console URL
+
+# Needed only for the Play Console form tools (App content, data safety):
+# packageName = number after /app/ in the Play Console URL
+[play.console_app_ids]
+"com.example.myapp" = "4970000000000000000"

shipstores-0.1.0/docs/apple-subscriptions.md

@@ -0,0 +1,29 @@
+# Subscriptions and review submissions on App Store Connect
+
+What it cost to learn while shipping an app with auto-renewable subscriptions.
+
+**The metadata bot rejects for a missing EULA without looking at the binary.** An app with an auto-renewable subscription needs a working Terms of Use link in the store listing; without it you get `3.1.2 Business: Payments - Subscriptions` minutes after submitting. No new build needed: `apple_update_listing` with a subscription block in the description (plan name, price, period, renewal, how to cancel) plus Apple's standard EULA link fixes it.
+
+```
+Terms of Use (EULA): https://www.apple.com/legal/internet-services/itunes/dev/stdeula/
+```
+
+A custom EULA is the other path: instead of the link, the text goes in the License Agreement field (`/v1/apps/{id}/endUserLicenseAgreement`, `null` when using Apple's standard one).
+
+**A version lives in one submission at a time.** Resubmitting a rejected version returns `409 ITEM_PART_OF_ANOTHER_SUBMISSION` while the old submission exists. Cancel with `PATCH /v1/reviewSubmissions/{id}` and `{"canceled": true}` (`apple_cancel_submission`); the state stays `CANCELING` for ~15 s before the version is free.
+
+**Cancelling the submission burns the subscription with it, and the API can't bring it back.** The `subscriptionVersion` becomes `DEVELOPER_REJECTED`, and from then on:
+
+- `POST /v1/subscriptionSubmissions` answers *"has no pending version for submission"*;
+- editing localization, price or `reviewNote` does **not** create a new version;
+- adding it to a submission (the valid relationship is `subscriptionVersion`, not `subscription`) fails with `STATE_ERROR.ENTITY_STATE_INVALID`.
+
+Only the console recreates the subscription items (App Store Connect → Distribution → App Review), and they land in a separate **draft** submission. That draft won't submit alone — *"add an app version for the selected platform"*: in-app purchases always travel with a version. If the version is already in another submission, regroup:
+
+1. cancel the submission that only has the version and wait for it to leave `CANCELING`;
+2. `POST /v1/reviewSubmissionItems` with `appStoreVersion` pointing at the draft;
+3. `PATCH` the draft with `{"submitted": true}`.
+
+You end with one submission holding three items: the version, the subscription group and the subscription.
+
+**`apple_submit_for_review` sends only the version.** Subscriptions need their own `subscriptionVersion` item in the same `reviewSubmission`, created before `submitted: true`.