appstore-api-mcp 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [1.0.3] - 2026-06-02
+
+### Changed
+- README Quick start reworked to be agent-agnostic: the **agent-setup prompt is
+  now shown inline**, and manual setup leads with the universal config block
+  (Claude Code is presented as one shortcut among equals, not the default).
+
+### Fixed
+- Publish workflow now triggers on tag push **only** (removed the duplicate
+  `release: published` trigger that caused a second, failing publish run), and
+  skips publishing if the version is already on npm.
+
+## [1.0.2] - 2026-06-02
+
+### Added
+- Setup instructions for more MCP clients: **Google Antigravity**,
+  **Amazon Q Developer CLI**, **Goose**, and a list of others (Kiro, Roo Code,
+  Trae, JetBrains AI, Warp, …).
+- **Agent-assisted setup** (`docs/AGENT-SETUP.md`) — a copy-paste prompt so your
+  AI agent configures the server from just your Key ID, Issuer ID, and `.p8` path.
+- `.github/workflows/npm-publish.yml` — publish to npm on version-tag push /
+  release, with provenance and a version-match guard.
+
+### Changed
+- Install docs default to `--scope user` (global) with an opt-out comment for
+  project-only installs; fixed stale server aliases.
+
 ## [1.0.1] - 2026-06-02
 
 ### Added

package/README.md

@@ -10,7 +10,7 @@ versions — plus a raw-request tool that reaches the **entire**
 > *"show the English description for MyApp"*, or
 > *"upload these screenshots to the 6.7-inch set"* — the agent calls the right tools.
 
-- 🤖 **Works with any MCP client** — Claude Code/Desktop, OpenAI Codex CLI, Cursor, Cline, Windsurf, VS Code (agent mode), Zed, Continue, Gemini CLI, and custom agents on the MCP SDKs. Standard stdio server, no client-specific code. → [docs/CLIENTS.md](docs/CLIENTS.md)
+- 🤖 **Works with any MCP client** — Claude Code/Desktop, OpenAI Codex CLI, Cursor, Cline, Windsurf, VS Code (agent mode), Zed, Continue, Gemini CLI, Google Antigravity, Amazon Q, Goose, JetBrains AI, Warp, and custom agents on the MCP SDKs. Standard stdio server, no client-specific code. → [docs/CLIENTS.md](docs/CLIENTS.md)
 - ✅ **One-line install** via `npx` — no clone, no build
 - ✅ **Credentials stay on your machine** — calls go straight to Apple, nothing is proxied
 - ✅ **Slim, well-described tool set** + a `raw_request` escape hatch for the whole API
@@ -22,7 +22,7 @@ versions — plus a raw-request tool that reaches the **entire**
 
 ## Table of contents
 
-- [Quick start](#quick-start)
+- [Quick start](#quick-start) — incl. [agent-assisted setup](docs/AGENT-SETUP.md)
 - [Supported clients](#supported-clients) → full guide in [docs/CLIENTS.md](docs/CLIENTS.md)
 - [Getting your API key](#getting-your-api-key) → full guide in [docs/SETUP.md](docs/SETUP.md)
 - [Configuration](#configuration)
@@ -39,23 +39,45 @@ versions — plus a raw-request tool that reaches the **entire**
 **Requirements:** Node.js ≥ 18 and an Apple Developer account with an
 [App Store Connect API key](#getting-your-api-key).
 
-### Claude Code (CLI)
+### 🤖 Easiest: let your AI agent set it up (works with any agent)
 
-```bash
-claude mcp add appstore-api \
-  --env ASC_KEY_ID=YOUR_KEY_ID \
-  --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
-  --env ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8 \
-  -- npx -y appstore-api-mcp
+Don't want to touch config files? Paste this into your coding agent (Claude,
+Codex, Cursor, Windsurf, Antigravity, Gemini CLI, …), fill in your three values,
+and it will configure your client and verify it:
+
+```text
+Set up the "appstore-api-mcp" App Store Connect MCP server for me.
+
+My App Store Connect API credentials:
+- Key ID:    <YOUR_KEY_ID>
+- Issuer ID: <YOUR_ISSUER_ID>
+- Path to my .p8 private key file: <ABSOLUTE_PATH_TO_AuthKey_XXXX.p8>
+
+Please:
+1. Detect which MCP client I'm using and add the server to its config. Run it
+   with: npx -y appstore-api-mcp
+2. Pass these env vars: ASC_KEY_ID, ASC_ISSUER_ID, and ASC_PRIVATE_KEY_PATH
+   (point ASC_PRIVATE_KEY_PATH at my .p8 path — reference the PATH, do not
+   inline the key contents).
+3. Install it at user/global scope (for Claude Code use `--scope user`).
+4. Do NOT print, echo, log, or commit the key. Keep the .p8 outside any git repo.
+5. When done, verify by listing my App Store apps and report the result.
+
+Config formats per client: https://github.com/fil-technology/appstore-api-mcp/blob/main/docs/CLIENTS.md
 ```
 
-Add `--scope user` to make it available in **every** project (default is the
-current project only).
+> Give the file **path**, not the key contents — that keeps the private key off
+> the chat transcript. More detail + a remote/cloud variant in
+> [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md).
+
+Prefer to do it manually? See below.
 
-### Any other MCP client (Cursor, Cline, Windsurf, VS Code, Zed, Continue, …)
+### Manual setup — any MCP client
 
-Almost every client uses this same block (Claude Desktop config path:
-`~/Library/Application Support/Claude/claude_desktop_config.json`):
+This is a standard stdio MCP server, so **every** MCP client uses the same
+command (`npx -y appstore-api-mcp`) and the same three `ASC_*` env vars. Most
+clients (Cursor, Cline, Windsurf, Claude Desktop, Gemini CLI, Antigravity, …)
+take this exact block — just put it in that client's config file:
 
 ```json
 {
@@ -73,7 +95,24 @@ Almost every client uses this same block (Claude Desktop config path:
 }
 ```
 
-Restart the client, then ask it to *"list my App Store apps"* to confirm it works.
+A few clients differ (VS Code uses `servers`, Codex uses TOML, Zed uses
+`context_servers`) — see the [Supported clients](#supported-clients) table and
+[docs/CLIENTS.md](docs/CLIENTS.md) for each exact format/location.
+
+**Claude Code** has a one-line CLI shortcut instead of editing a file:
+
+```bash
+# --scope user installs it for ALL your projects (recommended).
+# Remove the --scope user line to install for the current project only.
+claude mcp add appstore-api \
+  --scope user \
+  --env ASC_KEY_ID=YOUR_KEY_ID \
+  --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
+  --env ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8 \
+  -- npx -y appstore-api-mcp
+```
+
+After configuring, restart the client and ask it to *"list my App Store apps"* to confirm it works.
 
 ---
 
@@ -95,6 +134,10 @@ the same; only each client's config format/location differs.
 | **Zed** | `settings.json` → `context_servers` |
 | **Continue** | `~/.continue/config.yaml` → `mcpServers` |
 | **Gemini CLI** | `~/.gemini/settings.json` → `mcpServers` |
+| **Google Antigravity** | MCP settings → `mcpServers` |
+| **Amazon Q Developer CLI** | `~/.aws/amazonq/mcp.json` → `mcpServers` |
+| **Goose** | `~/.config/goose/config.yaml` → `extensions` |
+| **Kiro / Roo Code / Trae / JetBrains AI / Warp / others** | standard `mcpServers` block — see docs |
 | **Custom agent** (MCP SDK / Agents SDK / LangChain) | spawn the stdio command with the env vars |
 
 Copy-paste config snippets for each are in **[docs/CLIENTS.md](docs/CLIENTS.md)**.

package/docs/AGENT-SETUP.md

@@ -0,0 +1,64 @@
+# Let an AI agent set it up for you
+
+You don't have to edit config files by hand. Paste the prompt below into your
+coding agent (Claude Code, Cursor, Codex, Windsurf, etc.), fill in your three
+credentials, and it will detect your client and wire everything up.
+
+## ✅ Copy-paste prompt
+
+```text
+Set up the "appstore-api-mcp" App Store Connect MCP server for me.
+
+My App Store Connect API credentials:
+- Key ID:    <YOUR_KEY_ID>
+- Issuer ID: <YOUR_ISSUER_ID>
+- Path to my .p8 private key file: <ABSOLUTE_PATH_TO_AuthKey_XXXX.p8>
+
+Please:
+1. Detect which MCP client I'm using and add the server to that client's
+   correct config file/command. Run it with: npx -y appstore-api-mcp
+2. Pass these env vars to the server:
+     ASC_KEY_ID         = my Key ID
+     ASC_ISSUER_ID      = my Issuer ID
+     ASC_PRIVATE_KEY_PATH = the path to my .p8 file (reference the PATH; do not
+                            inline the key contents)
+3. Install it at user/global scope so it's available in all my projects
+   (for Claude Code, use `claude mcp add ... --scope user`).
+4. Do NOT print, echo, log, or commit the key. Keep the .p8 outside any git repo.
+5. When done, verify it works by listing my App Store apps, then tell me the
+   result (or any error and how to fix it).
+
+Config formats per client are documented here:
+https://github.com/fil-technology/appstore-api-mcp/blob/main/docs/CLIENTS.md
+```
+
+## Why give the *path*, not the key contents
+
+Pasting the raw `.p8` contents into a chat sends your private key through the
+model/provider. Giving the **file path** instead keeps the key on your disk —
+the MCP config only stores a path, and the server reads the file locally at
+runtime. Same convenience, much smaller exposure.
+
+> If your agent runs in a remote/cloud sandbox that can't see your local disk,
+> you'll need the key available there. In that case prefer
+> `ASC_PRIVATE_KEY_BASE64` injected as a secret rather than committing the file.
+
+## Is this safe / good practice?
+
+- ✅ **Simple:** the user provides 3 values; the agent handles client detection
+  and the exact config format.
+- ✅ **Low exposure:** with the path approach, the secret never enters the
+  transcript and is never committed.
+- ✅ **Least privilege still applies:** use an **App Manager** API key, not Admin
+  (see [SECURITY.md](SECURITY.md)).
+- ⚠️ **Review what the agent writes:** confirm the key path is correct and that
+  no credential was echoed back. A good agent will say "configured" without
+  reprinting your key.
+
+## After setup
+
+Ask your agent things like:
+
+- "List my App Store apps."
+- "Audit all my apps for ASO gaps."
+- "Show the current keywords and description for <app> (dry-run a new set)."

package/docs/CLIENTS.md

@@ -27,6 +27,8 @@ with these three env vars (see [SETUP.md](SETUP.md) to get them):
 ## Claude Code (CLI)
 
 ```bash
+# --scope user installs it for ALL your projects (recommended).
+# Remove the --scope user line to install for the current project only.
 claude mcp add appstore-api \
   --scope user \
   --env ASC_KEY_ID=YOUR_KEY_ID \
@@ -176,6 +178,60 @@ In `~/.gemini/settings.json` — same `mcpServers` shape as Claude Desktop:
 }
 ```
 
+## Google Antigravity
+
+Antigravity is Google's agentic IDE and supports MCP servers. Open its **MCP
+settings** ("Manage MCP servers" → edit the JSON config) and add the standard
+`mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "appstore-api": {
+      "command": "npx",
+      "args": ["-y", "appstore-api-mcp"],
+      "env": {
+        "ASC_KEY_ID": "YOUR_KEY_ID",
+        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey.p8"
+      }
+    }
+  }
+}
+```
+
+## Amazon Q Developer CLI
+
+`~/.aws/amazonq/mcp.json` — same `mcpServers` shape as Claude Desktop.
+
+## Goose (Block)
+
+`~/.config/goose/config.yaml`, under `extensions` (type `stdio`):
+
+```yaml
+extensions:
+  appstore-api:
+    type: stdio
+    cmd: npx
+    args: ["-y", "appstore-api-mcp"]
+    envs:
+      ASC_KEY_ID: YOUR_KEY_ID
+      ASC_ISSUER_ID: YOUR_ISSUER_ID
+      ASC_PRIVATE_KEY_PATH: /absolute/path/to/AuthKey.p8
+```
+
+## More MCP-compatible clients
+
+The following also speak MCP and use the **same** `mcpServers` JSON block shown
+above (consult each client's MCP docs for the exact config file/UI):
+
+- **Kiro** (AWS agentic IDE) — `.kiro/settings/mcp.json`
+- **Roo Code** (VS Code) — MCP settings
+- **Trae** (ByteDance IDE)
+- **JetBrains AI Assistant / Junie** — Settings → Tools → MCP
+- **Warp** terminal — MCP servers settings
+- **BoltAI**, **LibreChat**, **Witsy**, **Tome**, **5ire** — desktop MCP clients
+
 ## Any other MCP client / custom agent
 
 Point your client at a stdio server with:

package/docs/SETUP.md

@@ -41,7 +41,9 @@ chmod 600 ~/.appstoreconnect/AuthKey_XXXXXXXXXX.p8
 ### Claude Code
 
 ```bash
-claude mcp add appstore-connect \
+# --scope user installs it for ALL your projects (recommended).
+# Remove the --scope user line to install for the current project only.
+claude mcp add appstore-api \
   --scope user \
   --env ASC_KEY_ID=YOUR_KEY_ID \
   --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
@@ -58,7 +60,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
-    "appstore-connect": {
+    "appstore-api": {
       "command": "npx",
       "args": ["-y", "appstore-api-mcp"],
       "env": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.0.1",
-  "description": "MCP server for Apple App Store Connect — manage apps, keywords, descriptions, titles, screenshots, versions and the full API from any MCP client (Claude, Codex, Cursor, Cline, Windsurf, VS Code, Zed, Continue, Gemini CLI, and custom agents). Includes a fleet-wide ASO audit and dry-run previews.",
+  "version": "1.0.3",
+  "description": "MCP server for Apple App Store Connect — manage apps, keywords, descriptions, titles, screenshots, versions and the full API from any MCP client (Claude, Codex, Cursor, Cline, Windsurf, VS Code, Zed, Continue, Gemini CLI, Google Antigravity, Amazon Q, Goose, and custom agents). Includes a fleet-wide ASO audit and dry-run previews.",
   "type": "module",
   "bin": {
     "appstore-api-mcp": "src/index.js"