aso-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenan Atmaca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# ASO MCP Server
+
+[![npm version](https://img.shields.io/npm/v/aso-mcp.svg)](https://www.npmjs.com/package/aso-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-22%2B-green.svg)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
+
+**App Store Optimization toolkit for AI assistants.** Keyword research, competitor analysis, review sentiment, metadata optimization — all through the Model Context Protocol.
+
+> **No API key required.** Works out of the box with real App Store data. Supports 155+ countries.
+
+## Quick Start
+
+```bash
+npx aso-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g aso-mcp
+```
+
+## Why aso-mcp?
+
+- **18 specialized ASO tools** — from keyword discovery to App Store Connect metadata management
+- **Real App Store data** — live search results, ratings, reviews, and suggestions
+- **Custom scoring engine** — proprietary algorithm independent of Apple Search Ads API issues
+- **No API key needed** — zero configuration, install and go
+- **Smart caching** — SQLite-backed cache for fast repeated queries
+- **Rate limiting** — built-in request management to avoid Apple throttling
+- **Multi-country** — analyze keywords across 155+ App Store markets
+
+## Integration
+
+### Claude Desktop
+
+Add to your config file:
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+```json
+{
+  "mcpServers": {
+    "aso-mcp": {
+      "command": "aso-mcp"
+    }
+  }
+}
+```
+
+<details>
+<summary>Running from source instead?</summary>
+
+```json
+{
+  "mcpServers": {
+    "aso-mcp": {
+      "command": "npx",
+      "args": ["tsx", "/ABSOLUTE/PATH/TO/aso-mcp/src/server.ts"],
+      "cwd": "/ABSOLUTE/PATH/TO/aso-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+### Claude Code
+
+```bash
+claude mcp add -s user aso-mcp -- npx aso-mcp
+```
+
+### Other MCP Clients
+
+Any MCP-compatible client (ChatGPT, Cursor, Windsurf, etc.) can connect via stdio transport. Point it to the `aso-mcp` command.
+
+## Tools
+
+### Phase 1 — Keyword Research
+
+| Tool | Description |
+|------|-------------|
+| `search_keywords` | Traffic/difficulty scores + top-ranking apps for a keyword |
+| `suggest_keywords` | Keyword suggestions by app ID (category, similar, competition strategies) |
+| `get_app_details` | Full ASO info for an app + metadata analysis |
+
+### Phase 2 — Competitor Analysis & Optimization
+
+| Tool | Description |
+|------|-------------|
+| `analyze_competitors` | Metadata comparison of top apps for a keyword + keyword gap |
+| `optimize_metadata` | Title/subtitle/keyword field suggestions with character limit checks |
+| `analyze_reviews` | Sentiment analysis, complaint and feature request extraction |
+| `track_ranking` | App's ranking position across multiple keywords |
+| `keyword_gap` | Keyword difference between two apps + opportunity analysis |
+
+### Phase 3 — Localization & Reporting
+
+| Tool | Description |
+|------|-------------|
+| `localized_keywords` | Keyword performance comparison across different countries |
+| `get_aso_report` | Comprehensive ASO report: scores + competitors + reviews in one call |
+
+### Phase 4 — ASO Generation
+
+| Tool | Description |
+|------|-------------|
+| `discover_keywords` | Keyword discovery from scratch for a new app |
+| `generate_aso_brief` | Complete ASO brief with keyword pool, competitor patterns, and metadata suggestions |
+
+### Phase 5 — App Store Connect
+
+Directly read and update your app's metadata on App Store Connect without leaving the AI assistant.
+
+| Tool | Description |
+|------|-------------|
+| `connect_setup` | Configure & validate App Store Connect API credentials |
+| `connect_get_app` | Find app by bundle ID, get ASC ID + version status |
+| `connect_get_metadata` | Read current metadata (title, subtitle, keywords, description) for a locale |
+| `connect_update_metadata` | Update metadata with character limit validation + before/after diff |
+| `connect_list_localizations` | List all locales and metadata completeness status |
+
+<details>
+<summary>App Store Connect Setup</summary>
+
+Requires an [App Store Connect API Key](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api):
+
+**Option A — Environment variables:**
+```bash
+export ASC_ISSUER_ID="your-issuer-id"
+export ASC_KEY_ID="your-key-id"
+export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey_XXXXX.p8"
+```
+
+**Option B — Use the setup tool:**
+```
+"Set up App Store Connect with issuer ID xxx, key ID yyy, and key at /path/to/AuthKey.p8"
+```
+
+Credentials are saved to `~/.aso-mcp/connect-config.json` for future sessions.
+
+</details>
+
+### Utility
+
+| Tool | Description |
+|------|-------------|
+| `clear_cache` | Clears the local data cache for fresh App Store results |
+
+## Usage Examples
+
+Just ask your AI assistant naturally:
+
+```
+"How competitive is the 'fitness' keyword in the US?"
+
+"Analyze Spotify's competitors and find keyword opportunities"
+
+"Generate an ASO report for com.spotify.client"
+
+"Compare 'music' and 'podcast' keywords across US, UK, and DE markets"
+
+"Do a keyword gap analysis: Spotify vs Apple Music"
+
+"Analyze Shazam's user reviews"
+
+"Suggest title and subtitle for my fitness app targeting: workout, training, exercise"
+
+"Discover keywords for a new calorie tracking app"
+
+"Update my app's subtitle to 'AI Workout Planner' on App Store Connect"
+
+"Show all locales and metadata status for my app"
+```
+
+## Scoring Algorithm
+
+The server calculates its own scores, independent of Apple Search Ads API:
+
+| Score | Description |
+|-------|-------------|
+| **Visibility** | Based on rating, review count, and ranking position |
+| **Competitive** | Difficulty derived from the strength of top-ranking apps |
+| **Opportunity** | High traffic + low difficulty = high opportunity |
+| **Overall** | Weighted combination of all scores (0-10) |
+
+When the `aso` npm package fails to reach Apple (503 errors), the server automatically falls back to custom scoring using search result analysis — so scores are always available.
+
+## Development
+
+```bash
+git clone https://github.com/kenanatmaca/aso-mcp.git
+cd aso-mcp
+npm install
+
+npm run dev          # Run with tsx (development)
+npm run build        # Compile TypeScript
+npm run inspect      # MCP Inspector UI
+
+# Tests
+npx tsx test.ts              # Core tests (17)
+npx tsx test-phase3.ts       # Localization & report tests (4)
+npx tsx test-generation.ts   # ASO generation tests (8)
+```
+
+## Tech Stack
+
+- **TypeScript** + **Node.js 22+**
+- **[MCP SDK](https://modelcontextprotocol.io)** — Model Context Protocol
+- **[app-store-scraper](https://www.npmjs.com/package/app-store-scraper)** — App Store data
+- **[aso](https://www.npmjs.com/package/aso)** — ASO scoring with automatic fallback
+- **[better-sqlite3](https://www.npmjs.com/package/better-sqlite3)** — Cache layer
+- **[Zod](https://www.npmjs.com/package/zod)** — Schema validation
+
+## License
+
+MIT
+
+## Author
+
+[Kenan Atmaca](https://github.com/kenanatmaca)

package/build/cache/sqlite-cache.d.ts

@@ -0,0 +1,10 @@
+export declare function initCache(): void;
+export declare function getFromCache(key: string): string | null;
+export declare function setCache(key: string, value: string, ttlSeconds?: number): void;
+export declare function clearCache(): void;
+export declare function getCacheStats(): {
+    totalEntries: number;
+    expiredEntries: number;
+    dbPath: string;
+};
+//# sourceMappingURL=sqlite-cache.d.ts.map

package/build/cache/sqlite-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-cache.d.ts","sourceRoot":"","sources":["../../src/cache/sqlite-cache.ts"],"names":[],"mappings":"AAOA,wBAAgB,SAAS,IAAI,IAAI,CAsBhC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQvD;AAED,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,UAAU,GAAE,MAAa,GACxB,IAAI,CAKN;AAED,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED,wBAAgB,aAAa,IAAI;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,CAeA"}

package/build/cache/sqlite-cache.js

@@ -0,0 +1,51 @@
+import Database from "better-sqlite3";
+import path from "path";
+import os from "os";
+import fs from "fs";
+let db;
+export function initCache() {
+    const dataDir = path.join(os.homedir(), ".aso-mcp");
+    if (!fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true });
+    }
+    const dbPath = path.join(dataDir, "cache.db");
+    db = new Database(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS cache (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      expires_at INTEGER NOT NULL,
+      created_at INTEGER DEFAULT (strftime('%s', 'now'))
+    )
+  `);
+    // Clean up expired entries
+    db.exec(`DELETE FROM cache WHERE expires_at < strftime('%s', 'now')`);
+}
+export function getFromCache(key) {
+    const row = db
+        .prepare("SELECT value FROM cache WHERE key = ? AND expires_at > strftime('%s', 'now')")
+        .get(key);
+    return row?.value ?? null;
+}
+export function setCache(key, value, ttlSeconds = 3600) {
+    const expiresAt = Math.floor(Date.now() / 1000) + ttlSeconds;
+    db.prepare("INSERT OR REPLACE INTO cache (key, value, expires_at) VALUES (?, ?, ?)").run(key, value, expiresAt);
+}
+export function clearCache() {
+    db.exec("DELETE FROM cache");
+}
+export function getCacheStats() {
+    const total = db
+        .prepare("SELECT COUNT(*) as count FROM cache")
+        .get();
+    const expired = db
+        .prepare("SELECT COUNT(*) as count FROM cache WHERE expires_at < strftime('%s', 'now')")
+        .get();
+    return {
+        totalEntries: total.count,
+        expiredEntries: expired.count,
+        dbPath: path.join(os.homedir(), ".aso-mcp", "cache.db"),
+    };
+}
+//# sourceMappingURL=sqlite-cache.js.map

package/build/cache/sqlite-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-cache.js","sourceRoot":"","sources":["../../src/cache/sqlite-cache.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,IAAI,EAAqB,CAAC;AAE1B,MAAM,UAAU,SAAS;IACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC9C,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1B,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAEhC,EAAE,CAAC,IAAI,CAAC;;;;;;;GAOP,CAAC,CAAC;IAEH,2BAA2B;IAC3B,EAAE,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,GAAG,GAAG,EAAE;SACX,OAAO,CACN,8EAA8E,CAC/E;SACA,GAAG,CAAC,GAAG,CAAkC,CAAC;IAE7C,OAAO,GAAG,EAAE,KAAK,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,GAAW,EACX,KAAa,EACb,aAAqB,IAAI;IAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,UAAU,CAAC;IAC7D,EAAE,CAAC,OAAO,CACR,wEAAwE,CACzE,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,aAAa;IAK3B,MAAM,KAAK,GAAG,EAAE;SACb,OAAO,CAAC,qCAAqC,CAAC;SAC9C,GAAG,EAAuB,CAAC;IAC9B,MAAM,OAAO,GAAG,EAAE;SACf,OAAO,CACN,8EAA8E,CAC/E;SACA,GAAG,EAAuB,CAAC;IAE9B,OAAO;QACL,YAAY,EAAE,KAAK,CAAC,KAAK;QACzB,cAAc,EAAE,OAAO,CAAC,KAAK;QAC7B,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC;KACxD,CAAC;AACJ,CAAC"}

package/build/data-sources/app-store-connect.d.ts

@@ -0,0 +1,12 @@
+import type { ConnectConfig, ConnectAppInfo, ConnectLocalization, ConnectLocalizationSummary, ConnectMetadataUpdate } from "../types/index.js";
+export declare function loadConfig(): ConnectConfig | null;
+export declare function saveConfig(config: ConnectConfig): void;
+export declare function validateCredentials(config: ConnectConfig): Promise<boolean>;
+export declare function getApp(config: ConnectConfig, bundleId: string): Promise<ConnectAppInfo>;
+export declare function getMetadata(config: ConnectConfig, appId: string, locale?: string): Promise<ConnectLocalization>;
+export declare function updateMetadata(config: ConnectConfig, appId: string, locale: string | undefined, updates: ConnectMetadataUpdate): Promise<{
+    before: ConnectLocalization;
+    after: ConnectLocalization;
+}>;
+export declare function listLocalizations(config: ConnectConfig, appId: string): Promise<ConnectLocalizationSummary[]>;
+//# sourceMappingURL=app-store-connect.d.ts.map

package/build/data-sources/app-store-connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-store-connect.d.ts","sourceRoot":"","sources":["../../src/data-sources/app-store-connect.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAS3B,wBAAgB,UAAU,IAAI,aAAa,GAAG,IAAI,CAqBjD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAKtD;AAqED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED,wBAAsB,MAAM,CAC1B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC,CAuCzB;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAa,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAuF9B;AA2HD,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,YAAO,EACrB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC;IAAE,MAAM,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC,CA8FtE;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,0BAA0B,EAAE,CAAC,CA8EvC"}