# Mogut

Read-only App Store growth analysis (ASO) MCP server for the Apple ecosystem (iOS + Mac App Store).

Mogut never writes to the App Store. Write actions are handed off as ready-to-run
[Heimdall](https://github.com/erayendes/app-store-connect-mcp) tool calls that the user approves.

> 1.0: 47 tools over 13 live data sources, ending in the report orchestrators.
> `report_app` produces the full App Report in one call; the periodic tiers
> (daily/weekly/monthly) report deltas from local history. See [CHANGELOG.md](https://github.com/erayendes/app-store-growth-mcp/blob/main/docs/CHANGELOG.md).

## Install

```bash
npm install -g mogut
mogut setup
```

The wizard registers Mogut with the MCP clients it finds (Claude Code & Desktop, Codex,
Cursor, VS Code, Windsurf, Antigravity) — restart the client once afterwards.

The wizard stores credentials in the macOS Keychain (`com.milowda.credentials`) with a `.env`
fallback. Secrets are entered in the terminal only — never in chat, never logged, never
displayed. See [SECURITY.md](https://github.com/erayendes/app-store-growth-mcp/blob/main/.github/SECURITY.md).

## MCP config

```json
{
  "mcpServers": {
    "mogut": { "command": "mogut", "args": [] }
  }
}
```

Nine tools are exposed by default: six `mogut_*` meta tools plus the three report
orchestrators (`report_app`, `report_competitor_deep`, `report_comparison` — the fourth,
`report_actions`, lands in v1.1). Everything else is opt-in per profile: set
`MOGUT_PROFILES="keyword,competitor"` (or `"all"`). `mogut_search_tools` finds a tool and
tells you which profile enables it. The flows are described in [GUIDE.md](https://github.com/erayendes/app-store-growth-mcp/blob/main/docs/GUIDE.md).

## What a result looks like

Every tool returns data (`structuredContent`) plus a writing instruction for the host model —
statistics are computed in code, never delegated to the model. Every result carries
`source`, `confidence` and `lastCheckedAt`; truncation is visible (fetched/analyzed counts);
review and competitor text is marked untrusted data. A broken source becomes a visibly
skipped section, never an invented number.

## Tiers

| Tier | Needs | Unlocks |
|---|---|---|
| 0 | nothing | all public sources — a full report is produced, marked low confidence |
| 1 | App Store Connect key | your own analytics, sales, reviews, metadata |
| 2 | + Apple Ads OAuth | real search term reports and measured demand |
| 3 | + a connector (RevenueCat/PostHog) | revenue-per-keyword analysis |

`mogut_status` shows the current tier, verifies credentials live (`verify: true`) and counts
down the 180-day Apple Ads key rotation.

### Which App Store Connect role unlocks what

| ASC role on the key | What works |
|---|---|
| Sales (Access to Reports) or Finance | sales reports, analytics report download, reviews, metadata import |
| **Admin** | additionally: the one-off `POST /v1/analyticsReportRequests` that turns the analytics feed on — Apple gates this single call behind Admin and offers no UI for it |

The feed only produces data after that one POST. Mogut never sends it from the MCP surface:
run `npx mogut analytics enable --app <id>` in the terminal (asks for the path to an Admin
.p8, uses it in memory, stores nothing), or `--print-only` to print the request for whoever
holds Admin. `disable` undoes it.

## Advanced: Apple Ads popularity index

The official Apple Ads API has no popularity index (verified live: `POST
/api/v5/keywords/popularities` → 404). The number the Ads UI shows comes from an
undocumented endpoint that authenticates with a web session, not OAuth. Mogut can read it,
but the wizard does not ask for it: it is a pasted browser cookie, it expires, and using it
is a grey area against the Apple Ads terms. Without it, `keyword_popularity_fetch` falls
back to a proxy score marked low confidence.

If you want it anyway:

1. Log in at <https://app-ads.apple.com> and open any campaign screen.
2. Open devtools → Network, filter on `/cm/api`, click one request.
3. Copy that request's `Cookie` request header, whole.
4. `export MOGUT_APPLE_ADS_SESSION='<the cookie header>'` in the environment your MCP client
   launches Mogut from — or store it under the `apple-ads-session` account of the
   `com.milowda.credentials` Keychain service.

Re-do it when the session expires. `mogut_discover_sources` shows the source as `down` once
the endpoint starts refusing.

## What a report looks like

`report_app` produces the on-demand full report; `daily_digest`, `weekly_change_report` and
`monthly_status_report` produce the periodic tiers, reading deltas from the same local
history. Anonymized golden examples of both:
[EXAMPLE_REPORT_FULL.md](https://github.com/erayendes/app-store-growth-mcp/blob/main/docs/EXAMPLE_REPORT_FULL.md) ·
[EXAMPLE_REPORT_PERIODIC.md](https://github.com/erayendes/app-store-growth-mcp/blob/main/docs/EXAMPLE_REPORT_PERIODIC.md).

## Development

```bash
npm install && npm run build && npm test
```

Adding a data source? Read [CONTRIBUTING.md](https://github.com/erayendes/app-store-growth-mcp/blob/main/.github/CONTRIBUTING.md) — the adapter contract and the
fixture requirement are enforced by tests.

`src/core/catalog.ts` is generated from `docs/TOOL_CATALOG.md` — regenerate with
`node scripts/gen-catalog.mjs`.

MIT.