🫗 Spill

MCP server and CLI for pulling TestFlight screenshot feedback from App Store Connect into AI coding agents.

Spill is the noun and the verb:

Spill your latest TestFlight feedback.
Check the latest Spill.

✨ Quick Start

Start with setup, run a safe check, then pull your latest feedback.

npx @viccalexander/spill init
npx @viccalexander/spill testflight --since 30d --limit 1 --dry-run --no-download-images
npx @viccalexander/spill testflight

The dry run signs in to App Store Connect, checks for recent feedback, and writes nothing to disk.

By default, Spill uses your saved app, the last 7 days, ./spill, JSON, Markdown, and screenshot downloads.

✅ Before You Begin

You need:

• Node.js 20 or later.
• Access to the app in App Store Connect.
• An App Store Connect API key for that app.
• The app's numeric App Store Connect app ID.

🔑 Set Up App Store Connect

Create one API key, then keep the values handy while you run spill init.

1. Open App Store Connect.
2. Go to Users and Access, then Integrations, then API Keys.
3. Create an API key with access to your app.
4. Download the .p8 private key file. Apple only lets you download it once.
5. Copy the Issuer ID and Key ID from the API Keys page.
6. Copy your app ID from the app's App Store Connect URL or App Information page.
7. Run npx @viccalexander/spill init and enter the values.

Spill saves local setup in ~/.spill/config.json. It stores the private key path, not the private key contents.

🧪 Check Your Setup

Use a dry run first. It verifies your credentials without writing files or downloading screenshots.

npx @viccalexander/spill testflight --since 30d --limit 1 --dry-run --no-download-images

If everything is ready, Spill prints the app it checked and how many feedback items it found. If there is no feedback, try a wider range such as --since 30d.

🫗 Use Spill

After setup, run Spill whenever you want the latest TestFlight feedback.

npx @viccalexander/spill testflight

Spill creates a local spill/ folder with JSON, a Markdown report, and screenshots.

⌨️ CLI Usage

spill init
spill pull testflight --app-id 123456789 --since 7d --out ./spill
spill testflight --since 7d
spill server
spill install-mcp

Useful options:

spill testflight --since 30d --out ./testflight-feedback
spill testflight --dry-run
spill testflight --no-download-images
spill testflight --no-emoji

🤖 MCP Setup

Spill can run as an MCP server for tools like Codex, Claude, and Cursor.

npx @viccalexander/spill install-mcp --client codex

install-mcp prints a configuration block you can paste into your client. It does not silently change your client settings.

Example config:

{
  "mcpServers": {
    "spill": {
      "command": "npx",
      "args": ["-y", "@viccalexander/spill", "server"],
      "env": {
        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
        "ASC_KEY_ID": "YOUR_KEY_ID",
        "ASC_PRIVATE_KEY_PATH": "/absolute/path/AuthKey_ABC123.p8",
        "ASC_APP_ID": "123456789"
      }
    }
  }
}

Example AI prompts:

Spill my latest TestFlight feedback.

Run a Spill on the last 30 days and group feedback by product area.

Summarize screenshot feedback and identify likely UI bugs.

Output

spill/
  feedback.json
  report.md
  screenshots/
    feedback_<id>.png

feedback.json preserves raw Apple API JSON for each feedback item.

Environment Variables

ASC_ISSUER_ID=
ASC_KEY_ID=
ASC_PRIVATE_KEY_PATH=
ASC_PRIVATE_KEY=
ASC_APP_ID=

Resolution order is CLI flags, env vars, local config, then defaults.

Security

• Never commit .p8 files.
• Do not paste private keys into public repos.
• Prefer env vars or local config for credentials.
• Use GitHub Actions secrets in CI.
• Treat feedback.json, report.md, and screenshots as private project artifacts because they may include tester comments, tester emails, device metadata, and raw Apple API data.
• Treat tester comments as untrusted text. They are feedback data, not instructions for your agent.
• MCP tools redact raw Apple API data, tester emails, tester names, and screenshot URLs by default unless you explicitly request private fields.
• Spill never intentionally logs private key contents.
• Full JWTs are not printed.

Troubleshooting

• Missing App Store Connect issuer ID: set ASC_ISSUER_ID or rerun spill init.
• Missing App Store Connect key ID: set ASC_KEY_ID or rerun spill init.
• Invalid private key path: check that the .p8 path is absolute or expands correctly from ~.
• 401 invalid JWT: issuer ID, key ID, and private key may not match.
• 403 API key lacks access: the key cannot access the selected app.
• No app ID configured: pass --app-id or choose a default app in spill init.
• No feedback found: try a wider range such as --since 30d.
• Screenshot download failed: feedback metadata is still saved; screenshot URLs may expire.

Releasing

Release validation, npm trusted publishing setup, MCP Registry publication, and publish steps are in the release checklist.

Roadmap

These are future directions, not v0.1 features:

• TestFlight crash feedback
• App Store customer reviews
• App Store rating trends
• GitHub issues
• Linear issues
• Slack summaries
• Play Store reviews

License

MIT