# Google Play Store MCP

Secure, dry-run-first Google Play Store listing automation for humans, CI, and MCP agents.

This project manages Google Play Store listing text through the official Android Publisher API. It is intentionally not a browser automation tool and does not depend on fastlane at runtime.

## Why This Exists

Google Play listing work has two very different operators:

- Humans and CI need a CLI that can export, diff, validate, and apply listing metadata.
- Agents need an MCP server with safe tools that preview changes before committing them.

Both surfaces share one core library so security behavior, diffing, validation, and apply semantics stay consistent.

## Repo Layout

```text
packages/core   Typed Android Publisher API client, listing manifests, diff, validate, apply
packages/cli    gpstore command for humans and CI
packages/mcp    MCP stdio server for agent tools
examples        Safe example metadata, with no credentials
docs            Security and operating notes
```

## Roadmap

Read [ROADMAP.md](ROADMAP.md) for the current plan. Screenshot and media replacement details live in [docs/media-roadmap.md](docs/media-roadmap.md).

## Current Capabilities

- Export current localized listing text from Google Play.
- Load fastlane/supply-style metadata directories.
- Preview exact localized text changes.
- Stage and validate Google Play edits without committing them.
- Commit listing text only with explicit confirmation.
- Use service-account JSON from a local file path only.
- Redact and avoid logging secrets.

Screenshots and media asset replacement are designed into the core client as Android Publisher image primitives, but the first public workflow focuses on listing text. The screenshot pipeline should come next as a manifest-driven media diff/apply flow.

## Install

This repo is scaffolded as an npm workspace. After cloning:

```bash
npm install
npm run build
```

For local MCP usage after build:

```json
{
  "mcpServers": {
    "google-play-store": {
      "command": "node",
      "args": ["/absolute/path/to/google-play-store-mcp/packages/mcp/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account.json"
      }
    }
  }
}
```

## CLI Usage

Use a fastlane/supply-style metadata directory:

```text
metadata/android/en-US/title.txt
metadata/android/en-US/short_description.txt
metadata/android/en-US/full_description.txt
metadata/android/es-US/title.txt
metadata/android/es-US/short_description.txt
metadata/android/es-US/full_description.txt
```

Preview changes:

```bash
gpstore diff \
  --package-name com.example.app \
  --metadata-dir ./metadata/android \
  --credentials /absolute/path/to/service-account.json
```

Validate with Google Play and discard the edit:

```bash
gpstore validate \
  --package-name com.example.app \
  --metadata-dir ./metadata/android \
  --credentials /absolute/path/to/service-account.json
```

Apply only after review:

```bash
gpstore apply \
  --package-name com.example.app \
  --metadata-dir ./metadata/android \
  --credentials /absolute/path/to/service-account.json \
  --confirm APPLY_GOOGLE_PLAY_LISTING_CHANGES
```

Export current listing metadata:

```bash
gpstore export \
  --package-name com.example.app \
  --out ./metadata/android \
  --credentials /absolute/path/to/service-account.json
```

## MCP Tools

- `play_listing_diff`: dry-run listing diff.
- `play_listing_validate`: stages listing changes in a Google Play edit, validates them, then deletes the edit.
- `play_listing_apply`: commits listing changes only when `confirm` is exactly `APPLY_GOOGLE_PLAY_LISTING_CHANGES`.
- `play_listing_export`: returns current localized listing text as structured JSON.

MCP clients should still ask the user before calling `play_listing_apply`, because it modifies a cloud-managed public store listing.

## Security Model

Read [docs/security.md](docs/security.md) before using this with a real app.

Short version:

- No browser scraping.
- No credential upload.
- No credential persistence.
- No raw service-account JSON in config files.
- Dry-run and validation before apply.
- Apply requires explicit confirmation.
- Use least-privilege Play Console service accounts.

## Official API References

- Android Publisher API overview: https://developer.android.com/google/play/developer-api
- Localized listing updates: https://developers.google.com/android-publisher/api-ref/rest/v3/edits.listings/update
- Android Publisher media uploads: https://developers.google.com/android-publisher/upload
- MCP TypeScript SDK: https://modelcontextprotocol.io/docs/sdk