# appstoreconnect-codex-mcp

Compliant App Store Connect automation for Codex and other MCP clients.

This project exposes read-only App Store Connect tools through a stdio MCP server, plus a Fastify webhook API for signed App Store Connect webhook events. It only uses the official App Store Connect API and webhook notifications. It does not automate Apple ID web login, store Apple ID credentials, store browser cookies, or bypass 2FA.

## What It Provides

- `packages/asc-core`: JWT signing, App Store Connect API client, pagination, error mapping, read-only service methods, webhook signature helpers, and write-operation guard logic.
- `apps/asc-mcp-server`: stdio MCP server exposing `asc.*` tools to Codex.
- `apps/webhook-api`: Fastify API with `GET /healthz` and signed `POST /webhooks/app-store-connect`.
- `docs/COMPLIANCE.md`: compliance boundaries and prohibited behavior.
- `docs/OPERATIONS.md`: deployment, secret, webhook, and troubleshooting notes.
- `docs/CODEX_DESKTOP_INSTALL.md`: local Codex Desktop MCP configuration.

## MCP Tools

- `asc.list_apps`
- `asc.get_app_status`
- `asc.list_app_versions`
- `asc.get_latest_version`
- `asc.list_builds`
- `asc.get_latest_build`
- `asc.list_review_submissions`
- `asc.get_beta_review_status`
- `asc.get_status_snapshot`

Write tools are intentionally not registered in V1/V2. V3 write operations are represented only by guard interfaces and remain disabled by default.

## Requirements

- Node.js 20+
- pnpm 10+
- App Store Connect API key with appropriate read permissions

## Local Setup

```bash
pnpm install
cp .env.example .env
pnpm build
pnpm test
```

Provide either `ASC_PRIVATE_KEY_PATH` or `ASC_PRIVATE_KEY_BASE64`. Do not commit private keys, JWTs, webhook secrets, Apple ID credentials, cookies, or generated `.env` files.

## Run

```bash
pnpm dev:mcp
pnpm dev:webhook
```

The webhook server listens on `PORT` or `3000` by default.

## Codex Desktop

Add an MCP server entry to your Codex config:

```toml
[mcp_servers.app_store_connect]
command = "/path/to/node"
args = ["/path/to/appstoreconnect-codex-mcp/apps/asc-mcp-server/dist/index.js"]
startup_timeout_sec = 120

[mcp_servers.app_store_connect.env]
ASC_ISSUER_ID = "your-issuer-id"
ASC_KEY_ID = "your-key-id"
ASC_PRIVATE_KEY_PATH = "/secure/path/AuthKey_YOURKEYID.p8"
ASC_ENABLE_WRITE_TOOLS = "false"
ASC_REQUIRE_CONFIRMATION = "true"
ASC_ALLOWED_APP_IDS = ""
LOG_LEVEL = "warn"
```

Build before launching Codex:

```bash
pnpm build
```

More detail is in `docs/CODEX_DESKTOP_INSTALL.md`.

## Compliance

This repository is designed around these rules:

- Use only official Apple App Store Connect API and webhook mechanisms.
- Do not simulate web login.
- Do not save Apple ID passwords, cookies, browser sessions, or 2FA tokens.
- Keep all write operations off by default.
- Require app allowlists, exact confirmation text, and audit logging before future write operations.

See `docs/COMPLIANCE.md`.

## Development

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

## License

MIT