Release Health MCP Server

An MCP server that lets any AI agent (Claude Code, Claude Desktop, Gemini CLI, …) answer one question:

Is this release healthy enough to expand the rollout?

It reads crash rate, ANR rate and top crashes per version from the Google Play Developer Reporting API and the staged-rollout state from the Play Developer API. It then recommends expand, hold or halt against your own thresholds.

The current version is read-only: it never changes a rollout. Approval-gated rollout changes are planned for milestone 3 (see docs/ROADMAP.md).

flowchart LR
  A[AI agent<br/>Claude Code / Gemini CLI] -- MCP stdio --> S[release-health-mcp]
  S -- read-only service account --> R[Play Developer Reporting API<br/>crash & ANR rates, error issues]
  S -- read-only service account --> P[Play Developer API<br/>tracks & staged rollouts]
  S --> T[(thresholds.yaml)]

Tools

app is an alias from config.yaml or a package name. If you omit version_code, the server uses the release currently rolling out on production. All tools return structured JSON and are annotated readOnlyHint.

Related MCP server: play-console-mcp

Quick start (demo data, no Google account needed)

# Python 3.12+ and uv required
uv sync
cp config.example.yaml config.yaml
cp thresholds.example.yaml thresholds.yaml
uv run pytest

Connect to Claude Code

This repo ships a project-scoped .mcp.json, so starting claude in the repo picks up the server (approve it on first use). To register it globally instead:

claude mcp add release-health -e RELEASE_HEALTH_CONFIG=$PWD/config.yaml -- uv --directory $PWD run release-health-mcp

Then ask: "Is the current rollout of regressed healthy enough to expand?"

Connect to Gemini CLI

Add this to ~/.gemini/settings.json:

{
  "mcpServers": {
    "release-health": {
      "command": "uv",
      "args": ["--directory", "/path/to/release-health-mcp", "run", "release-health-mcp"],
      "env": { "RELEASE_HEALTH_CONFIG": "/path/to/release-health-mcp/config.yaml" }
    }
  }
}

Inspect by hand

uv run mcp dev src/release_health_mcp/server.py opens the MCP Inspector (requires Node.js).

Using real Google Play data

1. In Google Cloud, enable the Google Play Developer Reporting API and the Google Play Android Developer API, then create a service account and a JSON key.

2. In Play Console → Users and permissions, invite the service account for the apps you want with exactly two permissions: View app information (read-only) (tracks and rollouts) and View app quality information (read-only) (Android vitals: crash/ANR rates and issues). Nothing under Releases. Don't reuse a CI/fastlane key that has release rights: least privilege matters, because milestone 3 adds a separate account for rollout changes.

3. In config.yaml:

   backend: play
   apps:
     ada: com.alturos.ada
     leo: app.alturos.leo
   default_app: ada
   read_key_file: ~/.config/release-health/play-read-only.json

4. Sanity check: compare get_release_health with Android vitals → Overview in Play Console for the same version and window.

Environment overrides: RELEASE_HEALTH_CONFIG, RELEASE_HEALTH_BACKEND, RELEASE_HEALTH_READ_KEY, RELEASE_HEALTH_THRESHOLDS.

How the numbers are computed

• Rates come from crashRateMetricSet / anrRateMetricSet, using daily rows for the versionCode dimension over the last health_window_days days of available data. Each rate is a user-weighted average. user_days is the summed daily distinct users and serves as the sample size.

• Previous version is the highest lower versionCode that has data in the same window.

• New issues are issues whose firstAppVersion (within issues_window_days) equals the version.

Recommendation rules

The thresholds are in thresholds.yaml (defaults plus per-package overrides):

The decision logic lives in src/release_health_mcp/recommend.py. It's a pure function with table-driven tests.

Development

uv run pytest                        # unit, recorded-API and in-process MCP tests
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests scripts        # strict

• tests/recorded/ holds Play API responses that PlayBackend is tested against with HttpMockSequence, so no network access is needed.

• scripts/record_responses.py --package <pkg> --key <json> --out tests/recorded/<name> --scrub captures real responses for new tests (read-only calls only).

src/release_health_mcp/
  server.py        MCP tools (MCPServer, mcp SDK v2)
  service.py       composes backend + recommendation
  recommend.py     pure decision logic
  backends/        fixture (demo JSON) | play (Google APIs)
  config.py, thresholds.py, models.py

Roadmap

See docs/ROADMAP.md: approval-gated propose_rollout_change (human approval, hard limits, audit log, dry-run by default), then the showcase, iOS, remote HTTP and tracing.

License

MIT, see LICENSE.