Content
# ASO Copilot
A self-hosted, free alternative to tools like rankd.dev/AppTweak/ASOMobile for developers managing
their own apps. Single-user, no accounts, no billing — just your apps.
Also exposes an MCP server so an agent (Claude Code, Claude Desktop, etc.) can manage your ASO
directly: add apps, track keywords, pull health reports, spy on competitors, find keyword
opportunities, and write AI copy suggestions itself with no separate API key.
https://github.com/user-attachments/assets/970ce32e-a980-42ce-a0eb-529c425439af
## Features
- **Daily keyword rank tracking** — real ranks from live App Store / Google Play search results
- **Unlimited apps, keywords, competitors** — it's your database, no plan limits
- **Competitor spy** — track competitor apps and see their rank for every keyword you track
- **Health score analysis** — title/subtitle/screenshots/description/ratings/freshness breakdown
with suggestions, same shape as the paid tools
- **Keyword research** — "find winning keywords" derives candidates from your + competitors'
metadata and scores them by estimated demand/difficulty using live store search data
- **Global Reach** — scans your rank for a keyword across ~40 major App Store / Google Play
storefronts, plotted on a world map
- **Review analysis** — rating distribution, positive/negative theme extraction, and a keyword-gap
finder that mines your own reviews for untracked search terms
- **Product health overlay** — pairs your app's real daily active users (via a per-app PostHog
project) against its ASO health score over the same window
- **AI Copy Suggestions** — rewrites title/subtitle/description for 8 locales (US/UK/Canada
English, Spanish, German, French, Portuguese, Japanese), adapting keywords into real local
search terms rather than translating literally. Two ways to generate it, no lock-in to either:
- via [OpenRouter](https://openrouter.ai) (any backing model) through the web UI, or
- **key-free**, by pointing any MCP-connected model (e.g. Claude Code) at the
`prepare_copy_localization_brief` / `save_copy_suggestions` tools — the model composes the
copy itself, no API spend beyond what you're already paying for the agent
- **MCP server** at `/api/mcp` for agent-driven ASO management
## Stack
Next.js (App Router) + Prisma + PostgreSQL. Store data comes from the public iTunes Search/Lookup
API (App Store) and `google-play-scraper` (Google Play). There is no free official API for search
volume or keyword rank position, so:
- **Rank position** is real: it's your app's actual index in a live search for that term.
- **Volume/difficulty** are heuristics (0-100) derived from result-count and competitor-authority
proxies, not real search volume — there's no free source for that.
- iOS **subtitle** is scraped from the public App Store product page (not exposed by the iTunes
API). If Apple changes their page markup this can silently start returning `null` — see
`fetchSubtitle` in `src/lib/stores/appstore.ts`.
- Every store call (both platforms) retries transient failures (429s, 5xx, network errors) with
backoff via `src/lib/withRetry.ts`, so one rate-limited request doesn't fail an entire daily
tracking pass.
## Setup
```bash
npm install
docker compose up -d # local Postgres on port 5433
npx prisma migrate dev # create tables
npm run dev
```
Open http://localhost:3000, click **Add App**, search for your app, and add it.
Copy `.env.example` to `.env` and adjust `DATABASE_URL` if you're pointing at a different Postgres
instance (e.g. Supabase/Neon/RDS instead of the bundled docker-compose one).
## Daily tracking
Rank checks don't run automatically — trigger `POST /api/track` (protected by `CRON_SECRET` from
your `.env`) once a day:
```bash
curl -X POST http://localhost:3000/api/track -H "Authorization: Bearer $CRON_SECRET"
```
`scripts/daily-track.sh` wraps this for cron:
```cron
0 6 * * * APP_URL=http://localhost:3000 CRON_SECRET=... /path/to/scripts/daily-track.sh >> /var/log/aso-track.log 2>&1
```
Any external scheduler works the same way (GitHub Actions `schedule:` trigger, a hosting
provider's cron jobs, etc.) — it just needs to hit that one endpoint once a day.
### Or run the bundled cron container
`docker compose up -d cron` starts a small Alpine container (`docker/cron/`) that runs
`scripts/daily-track.sh` on a schedule via `crond`, hitting the app over `host.docker.internal`
since the app itself runs on the host, not in Docker. Configure it via `.env`:
```bash
CRON_SECRET="..." # required, shared with the app's own .env
APP_URL="http://host.docker.internal:3000" # optional, this is the default
CRON_SCHEDULE="0 6 * * *" # optional, standard 5-field cron syntax
```
## Connecting an agent (MCP)
The app exposes an MCP server at `/api/mcp` (Streamable HTTP transport) with tools for listing
apps, searching stores, adding apps/keywords/competitors, pulling health reports, finding winning
keywords, generating AI copy suggestions, and running a tracking pass on demand.
Point any MCP-compatible client at it, e.g. in Claude Code (`.mcp.json`, already checked in at the
repo root pointing at localhost):
```json
{
"mcpServers": {
"aso-copilot": {
"url": "http://localhost:3000/api/mcp"
}
}
}
```
There's no auth on this endpoint by default — it has full read/write access to your ASO data. Set
`MCP_AUTH_TOKEN` in `.env` before exposing it beyond localhost, then have your client send it:
```json
{
"mcpServers": {
"aso-copilot": {
"url": "http://localhost:3000/api/mcp",
"headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
}
}
}
```
## AI Copy Suggestions
Two independent ways to generate rewritten title/subtitle/description copy, in
`src/components/AICopySuggestions.tsx` on each app's Overview tab - pick either, both write to the
same `AiCopySuggestion` table so the panel shows whichever ran most recently:
- **OpenRouter** (works from the web UI): set `OPENROUTER_API_KEY` in `.env` (get one at
[openrouter.ai/keys](https://openrouter.ai/keys)); optionally `OPENROUTER_MODEL` to pick a
different model than the default. Click **Get AI suggestions**.
- **MCP, no key needed**: have an MCP-connected model call `prepare_copy_localization_brief` (returns
current copy, character limits, and a localization instruction per locale - no network call, no
key) and write the copy itself, then `save_copy_suggestions` to persist it. Useful if you're
already paying for an agent and don't want a second LLM bill for this.
## Analytics (optional)
Two separate PostHog integrations - don't mix them up:
<img width="1558" height="521" alt="image" src="https://github.com/user-attachments/assets/04985484-c04c-4e2d-95c4-65c56c2f9e1c" />
- **This tool's own usage analytics** (are you clicking around this app, not any tracked app's
users) — off by default. Set `NEXT_PUBLIC_POSTHOG_KEY` (and optionally
`NEXT_PUBLIC_POSTHOG_HOST` if self-hosting PostHog) in `.env` to enable pageview tracking via
`src/components/PostHogProvider.tsx` — no code changes needed, it's a no-op until the key is set.
- **Per-app product health** — each tracked app can link its *own* PostHog project (Settings tab,
`src/components/PostHogSettings.tsx`) so its real daily active users show up next to its ASO
health score on the Overview tab. Unrelated to the key above; configured per-app in the UI, not
via env vars.
## Project layout
- `src/lib/stores/` — App Store (iTunes) and Google Play data fetching
- `src/lib/health.ts` — health score engine
- `src/lib/research.ts` — keyword candidate generation + volume/difficulty scoring
- `src/lib/ai.ts` / `src/lib/aiLocales.ts` — AI Copy Suggestions: OpenRouter prompt + call, the
key-free localization-brief builder, and the 8-locale list
- `src/lib/reviewAnalysis.ts` — rating distribution + positive/negative theme extraction
- `src/lib/posthogIntegration.ts` — per-app PostHog client (daily active users query)
- `src/lib/storeLinks.ts` / `src/lib/metricColor.ts` — small shared UI helpers (outbound store
links, volume/difficulty coloring) kept out of `research.ts` so Client Components importing them
don't drag in server-only store-scraping dependencies
- `src/lib/appService.ts` — shared logic used by both the REST API and the MCP tools
- `src/app/api/` — REST routes
- `src/app/api/[transport]/route.ts` — MCP server
- `docker/cron/` — optional bundled cron container for daily tracking (see "Daily tracking" above)
