aso-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package Info

• npm: https://www.npmjs.com/package/aso-mcp
• GitHub: https://github.com/KenanAtmaca/aso-mcp
• Version: 1.4.0
• Install: npm install -g aso-mcp or npx aso-mcp

The server reads its version dynamically from package.json at startup (src/server.ts), so MCP clients always see the published version without a manual sync step.

Build & Run Commands

npm run dev          # Run server directly with tsx (development)
npm run build        # Compile TypeScript to ./build + chmod 755
npm run start        # Run compiled server (production)
npm run inspect      # Open MCP Inspector in browser for interactive testing
npx tsx test.ts              # Core test suite (18 tests: cache, ranking history, scoring, scraping, integration)
npx tsx test-generation.ts   # ASO generation scenario tests (8 tests)
npx tsx test-phase3.ts       # Localization & report tests (4 tests)
npx tsx test-connect.ts      # App Store Connect tests (9 tests, locale mapping + optional live API)

Publishing

npm version patch|minor|major   # Bump version + git commit + tag
npm publish --access public     # Publish to npm (requires auth token)

Architecture

MCP Server serving 20 tools over stdio transport. Tools are registered in src/server.ts grouped by phase.

Data flow: Tool Handler → Zod Validation (min/max constraints) → SQLite Cache check → Rate Limiter (token bucket + exponential backoff retry) → Data Source → Custom Scoring (fallback) → Cache result (max 5000 entries) → Return JSON to client.

Tools (20)

#	Tool	Phase	Description
1	search_keywords	1	Keyword traffic/difficulty scores + competitor apps
2	suggest_keywords	1	Keyword suggestions (category, similar, competition strategies, parallel execution). topOpportunities filtered via isHighOpportunity
3	get_app_details	1	Full app metadata, ratings, reviews count
4	analyze_competitors	2	Top-ranking apps comparison. Returns commonKeywords, uniqueKeywords, and competitorCoverage (per-app missing common analysis)
5	optimize_metadata	2	Title/subtitle/keyword field optimization suggestions
6	analyze_reviews	2	Sentiment analysis hybrid (keyword score + star-rating weight, fixes sarcastic reviews), complaints, feature requests
7	track_ranking	2	App ranking position for specific keywords. ID match cleanly distinguishes numeric track IDs from bundle IDs. Each fresh run saves snapshots to ranking_history
8	get_ranking_history	2	Position trends over time from locally saved track_ranking snapshots: daily positions, best/worst, change, improving/declining/stable per keyword
9	keyword_gap	2	Keyword difference between two apps (batch scoring)
10	localized_keywords	3	Multi-country keyword score comparison (parallel per country). Cache key sorts keywords + countries
11	get_aso_report	3	Comprehensive ASO report for an app
12	discover_keywords	Gen	Keyword discovery from scratch for new apps. Brand stop list filters competitor names from suggestions
13	generate_aso_brief	Gen	Complete ASO brief: greedy keyword-field packer, concrete suggested title + subtitle with char counts, parallel multi-market scoring
14	connect_setup	5	Configure & validate App Store Connect credentials
15	connect_get_app	5	Find app by bundle ID, get ASC ID + version state
16	connect_get_metadata	5	Read current metadata (name, subtitle, keywords, desc, supportUrl, marketingUrl) for a locale. Returns appInfoId + versionId for reuse
17	connect_update_metadata	5	Write metadata with char limit validation, HTML entity sanitization, cache invalidation, before/after diff. Reuses parent IDs from getMetadata
18	connect_batch_update_metadata	5	Batch update metadata for multiple locales in one call (max 40 locales)
19	connect_list_localizations	5	List all locales and metadata completeness status
20	clear_cache	Util	Clear local SQLite cache (does NOT touch ranking history)