appstore-connect-MCP: Instructions file for Claude Code

App Store Connect MCP Server

Open Source Project — IMPORTANT

This is a public open-source repository. Every change you make may be seen by anyone. Follow these rules strictly:

Never leak secrets

• NEVER hardcode, log, or commit API keys, key IDs, issuer IDs, vendor numbers, private key paths, or any credential.
• NEVER include real app IDs, bundle IDs, or user-specific data in code, tests, comments, or documentation. Use placeholder values (e.g., "your-key-id", "123", "com.example.myapp").
• If a tool call result or conversation context contains real credentials or user data, do not copy it into any file.

Keep documentation up to date

When adding, modifying, or removing a tool or feature:

1. README.md — Update the Tools section (parameters, description), response examples, test count, and local testing commands.
2. CLAUDE.md — Update the Architecture tree, Key Patterns, and Agent-Friendly Response Format sections.
3. Tool description in index.ts — Keep the server.tool() description accurate and complete for agent consumption.
4. scripts/test-tools.ts — Add an integration test block for any new tool.

Tests are mandatory

• Every new tool handler must have a corresponding test file in src/__tests__/.
• All tests must pass (npm test) before considering work complete.
• Keep the test count in README.md accurate.

Build & Test

npm run build    # TypeScript compilation
npm test         # Run all tests (vitest)
npm run test:watch  # Watch mode
npx tsx scripts/test-tools.ts              # Run all tools against the real API
npx tsx scripts/test-tools.ts list-apps    # Run a single tool

Architecture

src/
  index.ts              # MCP server entry point, tool registration and descriptions
  auth.ts               # JWT generation + caching for App Store Connect API
  api/
    client.ts           # HTTP client with retry logic (429/5xx backoff) + fetchUrl for pre-signed S3 URLs
    apps.ts             # Apps, metadata, and versions API calls (with in-memory app list cache)
    sales-reports.ts    # Sales reports (gzip download + TSV parsing)
    analytics.ts        # Analytics reports (async report request/instance/segment flow, with segment cache)
    reviews.ts          # Customer reviews (paginated) + App Store rating via iTunes Lookup API
  tools/
    list-apps.ts        # List apps — returns id, name, bundleId, SKU
    get-app-metadata.ts # Localized metadata — name, subtitle, keywords, description, promotionalText
    get-sales-report.ts # Sales/installs reports — column mapping, product type labels, truncation
    get-analytics-report.ts  # Analytics — aggregated or raw mode, engagement enriched with COMMERCE data
    get-app-store-versions.ts  # App versions with App Store state
    get-downloads-summary.ts   # Download trends — daily/monthly auto-selection from sales reports
    get-customer-reviews.ts  # Customer reviews — written reviews + App Store rating, date/rating/territory filtering
  utils/
    tsv.ts              # TSV parser (first row = headers)
    compression.ts      # Gzip decompression via node:zlib
  __tests__/            # Unit tests (vitest)
scripts/
  test-tools.ts         # Manual integration test — calls handlers against the real API