{"_id":"@andrewlwn77/aso-report-mcp","name":"@andrewlwn77/aso-report-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@andrewlwn77/aso-report-mcp","version":"1.0.0","description":"MCP server for ASO Report API - Access Google Play Store and App Store ASO intelligence and analytics","main":"dist/index.js","type":"module","bin":{"aso-report-mcp":"dist/index.js"},"scripts":{"build":"tsc","postbuild":"chmod +x dist/index.js","start":"node dist/index.js","dev":"tsx watch src/index.ts","test":"jest","test:unit":"jest tests/unit","test:integration":"jest tests/integration","test:watch":"jest --watch","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","aso","app-store-optimization","google-play","apple-app-store","app-intelligence","app-analytics","rapidapi"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/andrewlwn77/aso-report-mcp.git"},"bugs":{"url":"https://github.com/andrewlwn77/aso-report-mcp/issues"},"homepage":"https://github.com/andrewlwn77/aso-report-mcp#readme","engines":{"node":">=16.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","axios":"^1.7.8","dotenv":"^16.4.7","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.10.2","tsx":"^4.19.2","typescript":"^5.7.2","jest":"^29.7.0","@types/jest":"^29.5.14","ts-jest":"^29.2.5","@jest/globals":"^29.7.0"},"_id":"@andrewlwn77/aso-report-mcp@1.0.0","gitHead":"88329173ef398edd1a5640fc0332c7a47d8554d9","types":"./dist/index.d.ts","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-LOK2uIQHCA7MNxdbuCDC+AReeaYpblomSMESlm6stgcGC/VaPFLGJEgBzyHvbCQjPbnd8h6ht3tR5t0Q6P+DGw==","shasum":"ee7e3f43716550dc4487d93c5afa66adc0f15e07","tarball":"https://registry.npmjs.org/@andrewlwn77/aso-report-mcp/-/aso-report-mcp-1.0.0.tgz","fileCount":9,"unpackedSize":80727,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFf6GDeg839MrVA0XYd6hEyjeaJaesLlow+lOUCDtjD5AiAFMVCWLqiS1jHbVixh+Ke2rWqmfKPggAPFQ/+JCFdmpQ=="}]},"_npmUser":{"name":"andrewlwn77","email":"andrewlwn@gmail.com"},"directories":{},"maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aso-report-mcp_1.0.0_1756097771680_0.5173988089248593"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-25T04:56:11.526Z","1.0.0":"2025-08-25T04:56:11.861Z","modified":"2025-08-25T04:56:12.146Z"},"maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"description":"MCP server for ASO Report API - Access Google Play Store and App Store ASO intelligence and analytics","homepage":"https://github.com/andrewlwn77/aso-report-mcp#readme","keywords":["mcp","model-context-protocol","aso","app-store-optimization","google-play","apple-app-store","app-intelligence","app-analytics","rapidapi"],"repository":{"type":"git","url":"git+https://github.com/andrewlwn77/aso-report-mcp.git"},"bugs":{"url":"https://github.com/andrewlwn77/aso-report-mcp/issues"},"license":"MIT","readme":"# ASO Report MCP Server\n\nA Model Context Protocol server providing comprehensive Google Play Store and App Store ASO (App Store Optimization) intelligence via the SafeDev ASO Report API.\n\n## Features\n\n- **44 Comprehensive Endpoints** across Google Play Store and App Store\n- **Complete ASO Intelligence**: App details, reviews, search, rankings, permissions, privacy\n- **Built-in Caching** with configurable TTL and LRU eviction\n- **Pagination Support** for all list endpoints\n- **Input Validation** using Zod schemas\n- **TypeScript Support** with full type safety\n\n## Installation\n\n```bash\nnpm install @andrewlwn77/aso-report-mcp\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `ASO_REPORT_API_KEY` | RapidAPI key for ASO Report API | Yes | - |\n| `ASO_REPORT_CACHE_ENABLED` | Enable response caching | No | `true` |\n| `ASO_REPORT_CACHE_TTL_SECONDS` | Cache TTL in seconds | No | `300` (5 min) |\n| `ASO_REPORT_CACHE_MAX_ENTRIES` | Maximum cache entries | No | `100` |\n| `ASO_REPORT_RESULTS_PER_PAGE` | Default results per page | No | `10` |\n\n### Get Your API Key\n\n1. Sign up at [RapidAPI](https://rapidapi.com/)\n2. Subscribe to [ASO Report API](https://rapidapi.com/SafeDev/api/aso-report)\n3. Copy your API key from the dashboard\n\n## MCP Configuration\n\nAdd to your `.mcp.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"aso-report-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"@andrewlwn77/aso-report-mcp\"],\n      \"env\": {\n        \"ASO_REPORT_API_KEY\": \"your-rapidapi-key-here\",\n        \"ASO_REPORT_CACHE_ENABLED\": \"true\",\n        \"ASO_REPORT_CACHE_TTL_SECONDS\": \"300\",\n        \"ASO_REPORT_CACHE_MAX_ENTRIES\": \"100\",\n        \"ASO_REPORT_RESULTS_PER_PAGE\": \"10\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Google Play Store (26 tools)\n\n#### Metadata\n- `get_supported_languages_playstore` - Get supported languages\n- `get_supported_countries_playstore` - Get supported countries\n- `get_app_collections_playstore` - Get app collections/charts\n- `get_app_categories_playstore` - Get app categories\n\n#### App Information\n- `get_app_details_playstore` - Get comprehensive app details\n- `get_app_details_filtered_playstore` - Get filtered app details\n- `get_app_reviews_playstore` - Get app reviews\n- `get_app_reviews_filtered_playstore` - Get filtered app reviews\n- `get_similar_apps_playstore` - Get similar apps\n- `get_similar_apps_filtered_playstore` - Get filtered similar apps\n- `get_similar_apps_full_playstore` - Get similar apps with full details\n- `get_app_permissions_playstore` - Get app permissions\n- `get_app_permissions_filtered_playstore` - Get filtered app permissions\n- `get_app_data_safety_playstore` - Get app data safety information\n- `get_app_data_safety_filtered_playstore` - Get filtered data safety info\n\n#### Search & Discovery\n- `basic_app_search_playstore` - Basic app search\n- `full_app_search_playstore` - Full app search\n- `filtered_app_search_playstore` - Filtered app search\n- `full_filtered_app_search_playstore` - Full and filtered app search\n- `basic_app_suggest_playstore` - Basic app suggestions\n- `filtered_app_suggest_playstore` - Filtered app suggestions\n- `get_developer_apps_playstore` - Get apps by developer\n- `get_developer_apps_filtered_playstore` - Get filtered developer apps\n\n#### Charts & Rankings\n- `get_apps_chart_playstore` - Get apps chart/rankings\n- `get_apps_chart_filtered_playstore` - Get filtered apps chart\n- `get_apps_chart_full_playstore` - Get chart with full details\n\n### App Store (18 tools)\n\n#### Metadata\n- `get_supported_languages_appstore` - Get supported languages\n- `get_supported_countries_appstore` - Get supported countries\n- `get_app_collections_appstore` - Get app collections\n- `get_app_categories_appstore` - Get app categories\n\n#### App Information\n- `get_app_details_appstore` - Get app details\n- `get_app_details_filtered_appstore` - Get filtered app details\n- `get_app_reviews_appstore` - Get app reviews\n- `get_app_reviews_filtered_appstore` - Get filtered app reviews\n- `get_app_version_history_appstore` - Get app version history\n- `get_app_ratings_appstore` - Get app ratings\n- `get_app_ratings_filtered_appstore` - Get filtered app ratings\n- `get_similar_apps_appstore` - Get similar apps\n- `get_app_privacy_appstore` - Get app privacy information\n\n#### Search & Discovery\n- `search_apps_appstore` - Search apps\n- `search_apps_filtered_appstore` - Search apps with filters\n- `keyword_suggest_appstore` - Get keyword suggestions\n- `get_developer_apps_appstore` - Get apps by developer\n- `get_developer_apps_filtered_appstore` - Get filtered developer apps\n\n#### Charts & Rankings\n- `get_apps_appstore` - Get apps from charts\n- `get_apps_filtered_appstore` - Get filtered apps from charts\n\n## Usage Examples\n\n### Get App Details\n\n```typescript\n// Google Play Store\n{\n  \"name\": \"get_app_details_playstore\",\n  \"arguments\": {\n    \"app_id\": \"com.spotify.music\",\n    \"lang\": \"en\",\n    \"country\": \"us\"\n  }\n}\n\n// App Store  \n{\n  \"name\": \"get_app_details_appstore\",\n  \"arguments\": {\n    \"app_id\": \"324684580\",\n    \"lang\": \"en\", \n    \"country\": \"us\"\n  }\n}\n```\n\n### Search Apps\n\n```typescript\n{\n  \"name\": \"full_app_search_playstore\",\n  \"arguments\": {\n    \"query\": \"music streaming\",\n    \"lang\": \"en\",\n    \"country\": \"us\",\n    \"limit\": 20,\n    \"page\": 1,\n    \"pageSize\": 10\n  }\n}\n```\n\n### Get App Reviews\n\n```typescript\n{\n  \"name\": \"get_app_reviews_playstore\",\n  \"arguments\": {\n    \"app_id\": \"com.spotify.music\",\n    \"limit\": 50,\n    \"page\": 1,\n    \"pageSize\": 10\n  }\n}\n```\n\n### Get Charts/Rankings\n\n```typescript\n{\n  \"name\": \"get_apps_chart_playstore\",\n  \"arguments\": {\n    \"collection\": \"topselling_free\",\n    \"category\": \"MUSIC_AND_AUDIO\",\n    \"country\": \"us\",\n    \"limit\": 100,\n    \"page\": 1,\n    \"pageSize\": 10\n  }\n}\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone <repository-url>\ncd aso-report-mcp\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\n### Testing\n\nApply the MCP Direct Testing Workflow (per learning registry):\n\n```bash\n# Test server startup and protocol\necho '{\"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\n\n# Test list tools\necho '{\"jsonrpc\": \"2.0\", \"id\": 2, \"method\": \"tools/list\", \"params\": {}}' | ASO_REPORT_API_KEY=your-key node dist/index.js\n\n# Test a tool call\necho '{\"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\n```\n\n### Publishing\n\n```bash\nnpm run build\nnpm pack --dry-run  # Verify package contents\nnpm publish\n```\n\n## Response Format\n\nAll responses include pagination metadata and cache status:\n\n```json\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"page\": 1,\n    \"pageSize\": 10,\n    \"total\": 150,\n    \"totalPages\": 15,\n    \"hasNext\": true,\n    \"hasPrev\": false\n  },\n  \"cached\": false\n}\n```\n\n## Error Handling\n\nThe server provides comprehensive error handling for:\n- Missing or invalid API keys\n- Invalid parameters (validated with Zod)\n- API rate limits and failures\n- Network timeouts\n- Malformed responses\n\n## Performance Features\n\n### Caching System\n- **LRU Eviction**: Automatically evicts least recently used entries\n- **TTL Expiration**: Configurable time-to-live for cache entries\n- **Memory Efficient**: Bounded cache size with configurable limits\n\n### Pagination\n- **Configurable Page Size**: Set default results per page\n- **Metadata Included**: Total counts, page info, navigation flags\n- **Cache-Aware**: Cached results also support pagination\n\n## Architecture\n\n- **TypeScript**: Full type safety throughout\n- **Zod Validation**: Runtime parameter validation\n- **Modular Design**: Clean separation of concerns\n- **Error Boundaries**: Comprehensive error handling\n- **Extensible**: Easy to add new endpoints\n\n## API Compatibility\n\nThis server is compatible with:\n- **ASO Report API v1**: All 44 endpoints supported\n- **MCP Protocol**: v2024-11-05\n- **Node.js**: v16.0.0+\n\n## Support\n\nFor API-related issues, contact SafeDev via [RapidAPI](https://rapidapi.com/SafeDev/api/aso-report).\n\nFor server issues, please open an issue in the repository.\n\n## License\n\nMIT","readmeFilename":"README.md","_rev":"1-160867e522d2e0115903f8c4d8b25983"}