ASO Report MCP Server

A Model Context Protocol server providing comprehensive Google Play Store and App Store ASO (App Store Optimization) intelligence via the SafeDev ASO Report API.

Features

• 44 Comprehensive Endpoints across Google Play Store and App Store
• Complete ASO Intelligence: App details, reviews, search, rankings, permissions, privacy
• Built-in Caching with configurable TTL and LRU eviction
• Pagination Support for all list endpoints
• Input Validation using Zod schemas
• TypeScript Support with full type safety

Installation

npm install @andrewlwn77/aso-report-mcp

Configuration

Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | ASO_REPORT_API_KEY | RapidAPI key for ASO Report API | Yes | - | | ASO_REPORT_CACHE_ENABLED | Enable response caching | No | true | | ASO_REPORT_CACHE_TTL_SECONDS | Cache TTL in seconds | No | 300 (5 min) | | ASO_REPORT_CACHE_MAX_ENTRIES | Maximum cache entries | No | 100 | | ASO_REPORT_RESULTS_PER_PAGE | Default results per page | No | 10 |

Get Your API Key

1. Sign up at RapidAPI
2. Subscribe to ASO Report API
3. Copy your API key from the dashboard

MCP Configuration

Add to your .mcp.json file:

{
  "mcpServers": {
    "aso-report-mcp": {
      "command": "npx",
      "args": ["@andrewlwn77/aso-report-mcp"],
      "env": {
        "ASO_REPORT_API_KEY": "your-rapidapi-key-here",
        "ASO_REPORT_CACHE_ENABLED": "true",
        "ASO_REPORT_CACHE_TTL_SECONDS": "300",
        "ASO_REPORT_CACHE_MAX_ENTRIES": "100",
        "ASO_REPORT_RESULTS_PER_PAGE": "10"
      }
    }
  }
}

Available Tools

Google Play Store (26 tools)

Metadata

• get_supported_languages_playstore - Get supported languages
• get_supported_countries_playstore - Get supported countries
• get_app_collections_playstore - Get app collections/charts
• get_app_categories_playstore - Get app categories

App Information

• get_app_details_playstore - Get comprehensive app details
• get_app_details_filtered_playstore - Get filtered app details
• get_app_reviews_playstore - Get app reviews
• get_app_reviews_filtered_playstore - Get filtered app reviews
• get_similar_apps_playstore - Get similar apps
• get_similar_apps_filtered_playstore - Get filtered similar apps
• get_similar_apps_full_playstore - Get similar apps with full details
• get_app_permissions_playstore - Get app permissions
• get_app_permissions_filtered_playstore - Get filtered app permissions
• get_app_data_safety_playstore - Get app data safety information
• get_app_data_safety_filtered_playstore - Get filtered data safety info

Search & Discovery

• basic_app_search_playstore - Basic app search
• full_app_search_playstore - Full app search
• filtered_app_search_playstore - Filtered app search
• full_filtered_app_search_playstore - Full and filtered app search
• basic_app_suggest_playstore - Basic app suggestions
• filtered_app_suggest_playstore - Filtered app suggestions
• get_developer_apps_playstore - Get apps by developer
• get_developer_apps_filtered_playstore - Get filtered developer apps

Charts & Rankings

• get_apps_chart_playstore - Get apps chart/rankings
• get_apps_chart_filtered_playstore - Get filtered apps chart
• get_apps_chart_full_playstore - Get chart with full details

App Store (18 tools)

Metadata

• get_supported_languages_appstore - Get supported languages
• get_supported_countries_appstore - Get supported countries
• get_app_collections_appstore - Get app collections
• get_app_categories_appstore - Get app categories

App Information

• get_app_details_appstore - Get app details
• get_app_details_filtered_appstore - Get filtered app details
• get_app_reviews_appstore - Get app reviews
• get_app_reviews_filtered_appstore - Get filtered app reviews
• get_app_version_history_appstore - Get app version history
• get_app_ratings_appstore - Get app ratings
• get_app_ratings_filtered_appstore - Get filtered app ratings
• get_similar_apps_appstore - Get similar apps
• get_app_privacy_appstore - Get app privacy information

Search & Discovery

• search_apps_appstore - Search apps
• search_apps_filtered_appstore - Search apps with filters
• keyword_suggest_appstore - Get keyword suggestions
• get_developer_apps_appstore - Get apps by developer
• get_developer_apps_filtered_appstore - Get filtered developer apps

Charts & Rankings

• get_apps_appstore - Get apps from charts
• get_apps_filtered_appstore - Get filtered apps from charts

Usage Examples

Get App Details

// Google Play Store
{
  "name": "get_app_details_playstore",
  "arguments": {
    "app_id": "com.spotify.music",
    "lang": "en",
    "country": "us"
  }
}

// App Store  
{
  "name": "get_app_details_appstore",
  "arguments": {
    "app_id": "324684580",
    "lang": "en", 
    "country": "us"
  }
}

Search Apps

{
  "name": "full_app_search_playstore",
  "arguments": {
    "query": "music streaming",
    "lang": "en",
    "country": "us",
    "limit": 20,
    "page": 1,
    "pageSize": 10
  }
}

Get App Reviews

{
  "name": "get_app_reviews_playstore",
  "arguments": {
    "app_id": "com.spotify.music",
    "limit": 50,
    "page": 1,
    "pageSize": 10
  }
}

Get Charts/Rankings

{
  "name": "get_apps_chart_playstore",
  "arguments": {
    "collection": "topselling_free",
    "category": "MUSIC_AND_AUDIO",
    "country": "us",
    "limit": 100,
    "page": 1,
    "pageSize": 10
  }
}

Development

Setup

git clone <repository-url>
cd aso-report-mcp
npm install

Build

npm run build

Development Mode

npm run dev

Testing

Apply the MCP Direct Testing Workflow (per learning registry):

# Test server startup and protocol
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}' | ASO_REPORT_API_KEY=your-key node dist/index.js

# Test list tools
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | ASO_REPORT_API_KEY=your-key node dist/index.js

# Test a tool call
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_supported_languages_playstore", "arguments": {}}}' | ASO_REPORT_API_KEY=your-key node dist/index.js

Publishing

npm run build
npm pack --dry-run  # Verify package contents
npm publish

Response Format

All responses include pagination metadata and cache status:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 150,
    "totalPages": 15,
    "hasNext": true,
    "hasPrev": false
  },
  "cached": false
}

Error Handling

The server provides comprehensive error handling for:

• Missing or invalid API keys
• Invalid parameters (validated with Zod)
• API rate limits and failures
• Network timeouts
• Malformed responses

Performance Features

Caching System

• LRU Eviction: Automatically evicts least recently used entries
• TTL Expiration: Configurable time-to-live for cache entries
• Memory Efficient: Bounded cache size with configurable limits

Pagination

• Configurable Page Size: Set default results per page
• Metadata Included: Total counts, page info, navigation flags
• Cache-Aware: Cached results also support pagination

Architecture

• TypeScript: Full type safety throughout
• Zod Validation: Runtime parameter validation
• Modular Design: Clean separation of concerns
• Error Boundaries: Comprehensive error handling
• Extensible: Easy to add new endpoints

API Compatibility

This server is compatible with:

• ASO Report API v1: All 44 endpoints supported
• MCP Protocol: v2024-11-05
• Node.js: v16.0.0+

Support

For API-related issues, contact SafeDev via RapidAPI.

For server issues, please open an issue in the repository.

License

MIT