@viccalexander/spill

🫗 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.

• Open App Store Connect.
• Go to Users and Access, then Integrations, then API Keys.
• Create an API key with access to your app.
• Download the .p8 private key file. Apple only lets you download it once.
• Copy the Issuer ID and Key ID from the API Keys page.
• Copy your app ID from the app's App Store Connect URL or App Information page.
• 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