appstore-api-mcp 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.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
+- Setup instructions for **OpenAI Codex CLI** (TOML config) and **Gemini CLI**.
+
+### Changed
+- Description and docs reworded to make the client-agnostic support explicit (no longer Claude-centric).
+
 ## [1.0.0] - 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, Cursor, Cline, Windsurf, VS Code (agent mode), Zed, Continue, 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,19 +39,29 @@ 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).
 
+### 🤖 Easiest: let your agent set it up
+
+Don't want to touch config files? Paste the prompt in
+**[docs/AGENT-SETUP.md](docs/AGENT-SETUP.md)** into your coding agent, give it
+your Key ID, Issuer ID, and the **path** to your `.p8` file, and it configures
+everything for your client and verifies it. (Give the file *path*, not the key
+contents — that keeps the key off the transcript.)
+
+Prefer to do it manually? Continue below.
+
 ### 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 \
   --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
   --env ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8 \
   -- npx -y appstore-api-mcp
 ```
 
-Add `--scope user` to make it available in **every** project (default is the
-current project only).
-
 ### Any other MCP client (Cursor, Cline, Windsurf, VS Code, Zed, Continue, …)
 
 Almost every client uses this same block (Claude Desktop config path:
@@ -87,12 +97,18 @@ the same; only each client's config format/location differs.
 | --- | --- |
 | **Claude Code** | `claude mcp add …` (see above) |
 | **Claude Desktop** | `claude_desktop_config.json` → `mcpServers` |
+| **OpenAI Codex CLI** | `~/.codex/config.toml` → `[mcp_servers.appstore-api]` |
 | **Cursor** | `.cursor/mcp.json` → `mcpServers` |
 | **Cline** (VS Code) | `cline_mcp_settings.json` → `mcpServers` |
 | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` → `mcpServers` |
 | **VS Code** (agent mode) | `.vscode/mcp.json` → `servers` (note: not `mcpServers`) |
 | **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 \
@@ -56,6 +58,19 @@ claude mcp add appstore-api \
 }
 ```
 
+## OpenAI Codex CLI
+
+Codex uses **TOML**, not JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.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" }
+```
+
+(You can also manage this with `codex mcp add` if your Codex version supports it.)
+
 ## Cursor
 
 Project-level `.cursor/mcp.json` (or global `~/.cursor/mcp.json`) — same shape:
@@ -143,6 +158,80 @@ mcpServers:
       ASC_PRIVATE_KEY_PATH: /absolute/path/to/AuthKey.p8
 ```
 
+## Gemini CLI
+
+In `~/.gemini/settings.json` — same `mcpServers` shape as Claude Desktop:
+
+```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"
+      }
+    }
+  }
+}
+```
+
+## 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.0",
-  "description": "MCP server for Apple App Store Connect — manage apps, keywords, descriptions, titles, screenshots, versions and the full API from any MCP client (Claude, Cursor, Cline, Windsurf, VS Code, Zed, Continue, and custom agents). Includes a fleet-wide ASO audit and dry-run previews.",
+  "version": "1.0.2",
+  "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"
@@ -29,6 +29,8 @@
     "ios",
     "apple",
     "claude",
+    "codex",
+    "cursor",
     "keywords",
     "screenshots",
     "metadata"