tryastro-mcp 0.1.2

package/README.md

@@ -0,0 +1,69 @@
+# astro-mcp
+
+MCP server for Cursor with:
+- dedicated tools for core TryAstro scenarios;
+- one router tool for standard support/product queries.
+
+## Included tools
+
+1. `scenario_catalog`
+2. `scenario_onboarding_first_value`
+3. `scenario_keyword_research`
+4. `scenario_competitor_analysis`
+5. `scenario_localization_strategy`
+6. `scenario_rankings_and_ratings`
+7. `scenario_migration_and_transfer`
+8. `standard_topics`
+9. `standard_answer`
+
+Scenario decomposition details are in `/docs/scenario-decomposition.md`.
+
+## Local run
+
+```bash
+node /Users/vlad.korobkov/tryastro-mcp/server.js
+```
+
+Smoke test:
+
+```bash
+npm run smoke
+```
+
+Package dry run:
+
+```bash
+npm run pack:dry
+```
+
+## Cursor connection
+
+Use the published npm package:
+
+```json
+{
+  "mcpServers": {
+    "astro-mcp": {
+      "command": "npx",
+      "args": ["-y", "-p", "tryastro-mcp", "astro-mcp"],
+      "env": {
+        "NPM_CONFIG_CACHE": "/tmp/astro-mcp-npm-cache",
+        "npm_config_cache": "/tmp/astro-mcp-npm-cache"
+      }
+    }
+  }
+}
+```
+
+## Publish checklist
+
+1. Update `version` in `/package.json`.
+2. Login: `npm login`.
+3. Publish: `npm publish --access public`.
+4. Verify install: `npx -y -p tryastro-mcp astro-mcp`.
+
+## Data and source model
+
+- Tools use a static, verified knowledge layer from TryAstro public pages and docs.
+- Verification date is hardcoded in server output (`2026-02-22`).
+- If source facts change (pricing/legal/features), update `/server.js` constants.

package/bin/astro-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../server.js";

package/docs/scenario-decomposition.md

@@ -0,0 +1,61 @@
+# TryAstro: main scenario decomposition
+
+Verification date: `2026-02-22`
+
+## Scenario 1: Onboarding to first value
+
+- Goal: create first-day baseline for ASO work.
+- User outcome: app is connected, keywords are tracked, initial rankings and ratings baseline is captured.
+- MCP tool: `scenario_onboarding_first_value`.
+
+## Scenario 2: Keyword research loop
+
+- Goal: build prioritized keyword pool for target stores/locales.
+- User outcome: saved, segmented keyword list with ranking watchlist.
+- MCP tool: `scenario_keyword_research`.
+
+## Scenario 3: Competitor benchmarking
+
+- Goal: find ranking and semantic gaps vs direct competitors.
+- User outcome: actionable gap matrix and optimization backlog.
+- MCP tool: `scenario_competitor_analysis`.
+
+## Scenario 4: Localization expansion
+
+- Goal: select countries/locales and roll out metadata localization by priority waves.
+- User outcome: localized keyword sets and post-release monitoring plan.
+- MCP tool: `scenario_localization_strategy`.
+
+## Scenario 5: Rankings and ratings monitoring
+
+- Goal: maintain regular monitoring and response loop for ranking/rating changes.
+- User outcome: scheduled checks, alert logic, and weekly root-cause reviews.
+- MCP tool: `scenario_rankings_and_ratings`.
+
+## Scenario 6: Migration/import and transfer
+
+- Goal: move data from other ASO tools or another Mac without losing history.
+- User outcome: validated data parity and active license on target device.
+- MCP tool: `scenario_migration_and_transfer`.
+
+## Standard request layer
+
+- Goal: answer typical product/support/legal/pricing questions quickly.
+- MCP tools: `standard_topics` and `standard_answer`.
+
+## Source pages
+
+1. https://tryastro.app/
+2. https://docs.tryastro.app/
+3. https://docs.tryastro.app/first-access/
+4. https://docs.tryastro.app/add-app/
+5. https://docs.tryastro.app/add-keywords/
+6. https://docs.tryastro.app/suggestions/
+7. https://docs.tryastro.app/localizations/
+8. https://docs.tryastro.app/rankings/
+9. https://docs.tryastro.app/ratings/
+10. https://docs.tryastro.app/import-export/
+11. https://docs.tryastro.app/transfer/
+12. https://tryastro.app/pricing/
+13. https://tryastro.app/terms/
+14. https://tryastro.app/privacy/

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "tryastro-mcp",
+  "version": "0.1.2",
+  "description": "MCP server for TryAstro scenarios and standard support requests",
+  "type": "module",
+  "main": "server.js",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "cursor",
+    "tryastro",
+    "aso",
+    "app-store-optimization"
+  ],
+  "bin": {
+    "astro-mcp": "./bin/astro-mcp.js"
+  },
+  "exports": {
+    ".": "./server.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "server.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "smoke": "node scripts/smoke-test.js",
+    "smoke:npx": "node scripts/smoke-test-npx.js",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.js

@@ -0,0 +1,893 @@
+#!/usr/bin/env node
+import process from "node:process";
+
+const SERVER_INFO = {
+  name: "astro-mcp",
+  version: "0.1.2",
+};
+
+const PROTOCOL_VERSION = "2024-11-05";
+const VERIFIED_ON = "2026-02-22";
+
+const SOURCES = {
+  homepage: "https://tryastro.app/",
+  docs: "https://docs.tryastro.app/",
+  firstAccess: "https://docs.tryastro.app/first-access/",
+  addApp: "https://docs.tryastro.app/add-app/",
+  addKeywords: "https://docs.tryastro.app/add-keywords/",
+  suggestions: "https://docs.tryastro.app/suggestions/",
+  localizations: "https://docs.tryastro.app/localizations/",
+  rankings: "https://docs.tryastro.app/rankings/",
+  ratings: "https://docs.tryastro.app/ratings/",
+  importExport: "https://docs.tryastro.app/import-export/",
+  transfer: "https://docs.tryastro.app/transfer/",
+  pricing: "https://tryastro.app/pricing/",
+  terms: "https://tryastro.app/terms/",
+  privacy: "https://tryastro.app/privacy/",
+};
+
+const STANDARD_TOPICS = [
+  {
+    id: "capabilities",
+    title: "Product capabilities",
+    patterns: [
+      /what can .*astro|feature|capabilit|возможност|что умеет/i,
+      /keyword|competitor|localization|rankings|ratings|review/i,
+    ],
+    answerRu:
+      "Astro фокусируется на ASO-операциях: поиск ключевых слов, анализ конкурентов, локализации, мониторинг позиций, мониторинг рейтинга и отзывов, а также импорт/экспорт ASO-данных.",
+    answerEn:
+      "Astro is focused on ASO operations: keyword research, competitor analysis, localization workflows, keyword ranking monitoring, ratings/reviews monitoring, and ASO data import/export.",
+    next: [
+      "Выберите сценарий через scenario_catalog и запустите соответствующий scenario tool.",
+      "Зафиксируйте список целевых стран/языков до старта keyword и localization сценариев.",
+    ],
+    sources: [SOURCES.homepage, SOURCES.docs],
+  },
+  {
+    id: "pricing_billing",
+    title: "Pricing and billing",
+    patterns: [
+      /pricing|price|cost|billing|subscription|подписк|тариф|цена|стоимост/i,
+      /refund|возврат|renew|продлен/i,
+    ],
+    answerRu:
+      "На сайте указан единый annual-план: $108 в год (приблизительно $9/месяц). Политика возврата: 14 дней с момента покупки через запрос на hello@tryastro.app. Биллинг обрабатывается через Lemon Squeezy.",
+    answerEn:
+      "The site shows a single annual plan: $108/year (about $9/month). Refund policy: 14 days from purchase via hello@tryastro.app. Billing is handled via Lemon Squeezy.",
+    next: [
+      "Для актуальной суммы и валюты проверяйте pricing page перед оплатой.",
+      "Для возврата отправьте email с данными покупки в течение 14 дней.",
+    ],
+    sources: [SOURCES.pricing, SOURCES.terms],
+  },
+  {
+    id: "platform_coverage",
+    title: "Platform and geo coverage",
+    patterns: [
+      /platform|device|ios|ipados|macos|visionos|store|country|geo|регион|страны|поддержк/i,
+      /apple search ads|stores/i,
+    ],
+    answerRu:
+      "Astro доступен на iOS, iPadOS, macOS и VisionOS, требует macOS 14+ для desktop. В коммуникации продукта фигурируют 60+ стран для Apple Search Ads и поддержка работы с 91 стором в keyword search.",
+    answerEn:
+      "Astro is available on iOS, iPadOS, macOS, and VisionOS, with macOS 14+ required for desktop. Product messaging mentions 60+ Apple Search Ads countries and support for 91 stores in keyword search.",
+    next: [
+      "Перед запуском сценариев зафиксируйте целевые сторы и локали в одном документе.",
+      "Если есть расхождения по охвату, сверяйте docs и приложение одновременно.",
+    ],
+    sources: [SOURCES.homepage, SOURCES.firstAccess],
+  },
+  {
+    id: "privacy_legal",
+    title: "Privacy and legal",
+    patterns: [
+      /privacy|gdpr|legal|terms|dpa|subprocessor|данные|персональ|политик|услови/i,
+      /security|безопас/i,
+    ],
+    answerRu:
+      "Согласно Privacy page, пользовательские данные хранятся локально на устройстве, а Astro по умолчанию не передает их на свои серверы. Юридические условия и ограничения использования описаны в Terms.",
+    answerEn:
+      "According to the Privacy page, user data is stored locally on the device and Astro does not send it to Astro servers by default. Legal terms and usage restrictions are defined in Terms.",
+    next: [
+      "Для комплаенса проверьте DPA/Sub-processors ссылки в футере перед закупкой.",
+      "Для юридических вопросов эскалируйте на hello@tryastro.app.",
+    ],
+    sources: [SOURCES.privacy, SOURCES.terms],
+  },
+  {
+    id: "support_feedback",
+    title: "Support and feedback",
+    patterns: [
+      /support|help|ticket|contact|feedback|roadmap|баг|поддержк|тикет|контакт/i,
+      /hello@tryastro\.app/i,
+    ],
+    answerRu:
+      "Базовые материалы доступны в docs.tryastro.app. Для запросов по подписке и возвратам используется hello@tryastro.app. На сайте также отмечены каналы feature requests и support ticket.",
+    answerEn:
+      "Core documentation is available at docs.tryastro.app. For subscription and refund requests, use hello@tryastro.app. The site also mentions feature requests and support ticket channels.",
+    next: [
+      "В тикете прикладывайте точный store/country/date диапазон и скриншоты.",
+      "Для продуктовых запросов сначала проверьте docs, потом отправляйте gap в feature request.",
+    ],
+    sources: [SOURCES.docs, SOURCES.homepage, SOURCES.terms],
+  },
+  {
+    id: "migration_transfer",
+    title: "Migration and transfer",
+    patterns: [
+      /import|export|migration|transfer|switch|перенос|миграц|импорт|экспорт|лиценз/i,
+      /apptweak|sensor tower|mobile action|appfollow/i,
+    ],
+    answerRu:
+      "Astro поддерживает импорт/экспорт ключевых слов через CSV и отдельный перенос всей истории через файл model.sqlite. Отдельно описан перенос лицензии на другой Mac через Lemon Squeezy.",
+    answerEn:
+      "Astro supports keyword import/export via CSV and full history migration through the model.sqlite file. License transfer to another Mac is described as a separate Lemon Squeezy flow.",
+    next: [
+      "Для полного переноса истории используйте сценарий с model.sqlite, не CSV.",
+      "Перед переносом лицензии выйдите из аккаунта на старом устройстве.",
+    ],
+    sources: [SOURCES.importExport, SOURCES.transfer, SOURCES.terms],
+  },
+  {
+    id: "official_mcp_status",
+    title: "Official MCP availability",
+    patterns: [
+      /mcp|cursor|server|api|integration|интеграц|подключ/i,
+      /official|официальн/i,
+    ],
+    answerRu:
+      "В Terms у Astro указан будущий функционал MCP как planned capability. Это означает, что на момент последней проверки официальный MCP может быть не выпущен публично, поэтому текущий сервер в этом репозитории реализован как независимая интеграция.",
+    answerEn:
+      "Astro Terms mention MCP as a planned capability. That implies the official MCP may not yet be publicly released, so the server in this repository is built as an independent integration.",
+    next: [
+      "Используйте этот MCP как workflow assistant для сценариев Astro.",
+      "Периодически проверяйте docs/terms на появление официального API или MCP endpoint.",
+    ],
+    sources: [SOURCES.terms, SOURCES.docs],
+  },
+];
+
+const SCENARIO_SUMMARY = [
+  {
+    id: "scenario_onboarding_first_value",
+    title: "Onboarding to first value",
+    goal: "Поднять аккаунт, приложение и baseline-метрики в первый рабочий день.",
+  },
+  {
+    id: "scenario_keyword_research",
+    title: "Keyword research loop",
+    goal: "Собрать и приоритизировать семантическое ядро под целевые сторы.",
+  },
+  {
+    id: "scenario_competitor_analysis",
+    title: "Competitor benchmarking",
+    goal: "Собрать gap-анализ по конкурентам и найти быстрые точки роста.",
+  },
+  {
+    id: "scenario_localization_strategy",
+    title: "Localization expansion",
+    goal: "Спланировать и запустить локализацию по странам/языкам с приоритетами.",
+  },
+  {
+    id: "scenario_rankings_and_ratings",
+    title: "Rankings and ratings monitoring",
+    goal: "Сделать цикл регулярного контроля позиций и качества пользовательского фидбека.",
+  },
+  {
+    id: "scenario_migration_and_transfer",
+    title: "Migration/import and license transfer",
+    goal: "Без потери данных перейти с других ASO-сервисов или между устройствами.",
+  },
+];
+
+const TOOL_DEFINITIONS = [
+  {
+    name: "scenario_catalog",
+    description:
+      "Return decomposition of TryAstro core user scenarios and map each scenario to an MCP tool.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "scenario_onboarding_first_value",
+    description:
+      "Playbook for first-day onboarding: account setup, app setup, first keywords, and initial metrics baseline.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_name: { type: "string" },
+        primary_store: { type: "string" },
+        platform: {
+          type: "string",
+          enum: ["ios", "ipados", "macos", "visionos", "mixed"],
+        },
+        team_goal: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "scenario_keyword_research",
+    description:
+      "Run keyword research workflow using TryAstro search, suggestions, and save flow.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_name: { type: "string" },
+        country: { type: "string" },
+        language: { type: "string" },
+        seed_keywords: {
+          type: "array",
+          items: { type: "string" },
+        },
+        target_keywords_count: { type: "integer", minimum: 1, maximum: 200 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "scenario_competitor_analysis",
+    description:
+      "Competitor analysis workflow: compare overlap, position deltas, and actionable keyword gaps.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_name: { type: "string" },
+        country: { type: "string" },
+        competitors: {
+          type: "array",
+          items: { type: "string" },
+        },
+        focus_metric: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "scenario_localization_strategy",
+    description:
+      "Localization workflow based on TryAstro country-localization and app-localization tools.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_name: { type: "string" },
+        source_locale: { type: "string" },
+        target_countries: {
+          type: "array",
+          items: { type: "string" },
+        },
+        release_window: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "scenario_rankings_and_ratings",
+    description:
+      "Monitoring workflow for keyword rankings and ratings/reviews over time.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        app_name: { type: "string" },
+        countries: {
+          type: "array",
+          items: { type: "string" },
+        },
+        watch_keywords: {
+          type: "array",
+          items: { type: "string" },
+        },
+        check_cadence: {
+          type: "string",
+          enum: ["daily", "weekly"],
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "scenario_migration_and_transfer",
+    description:
+      "Migration workflow for CSV keyword data, full history transfer, and license transfer between Macs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_tool: { type: "string" },
+        transfer_mode: {
+          type: "string",
+          enum: ["csv_keywords", "full_history_sqlite", "license_transfer"],
+        },
+        need_history: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "standard_topics",
+    description:
+      "List standard support topics handled by this MCP (pricing, legal, privacy, support, migration, etc.).",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "standard_answer",
+    description:
+      "Answer standard TryAstro support questions by routing the query to known topic playbooks.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        topic: {
+          type: "string",
+          enum: STANDARD_TOPICS.map((topic) => topic.id),
+        },
+        language: {
+          type: "string",
+          enum: ["ru", "en"],
+          default: "ru",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+];
+
+const TOOL_HANDLERS = {
+  scenario_catalog: () => {
+    const lines = [
+      "TryAstro main scenario decomposition",
+      "",
+      ...SCENARIO_SUMMARY.flatMap((scenario, idx) => [
+        `${idx + 1}. ${scenario.title} (${scenario.id})`,
+        `Goal: ${scenario.goal}`,
+      ]),
+      "",
+      "Standard request handling",
+      "Use standard_answer for typical support and product questions (pricing, legal, privacy, support, migration, platform coverage).",
+      "",
+      "Verified sources",
+      ...Object.values(SOURCES).map((source, idx) => `${idx + 1}. ${source}`),
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+
+    return asText(lines.join("\n"));
+  },
+
+  scenario_onboarding_first_value: (args = {}) => {
+    const appName = safeText(args.app_name, "your app");
+    const store = safeText(args.primary_store, "primary target store");
+    const platform = safeText(args.platform, "ios");
+    const goal = safeText(
+      args.team_goal,
+      "launch ASO baseline and first optimization backlog"
+    );
+
+    const lines = [
+      "Scenario: Onboarding to first value",
+      `Context: app=${appName}, store=${store}, platform=${platform}, goal=${goal}`,
+      "",
+      "Steps",
+      "1. Verify access in the app and complete first run checks (docs: first-access).",
+      "2. Add the target app using URL or bundle ID flow (docs: add-app).",
+      "3. Add an initial keyword list and save it to persistent tracking (docs: add-keywords).",
+      "4. Run suggestions to expand the semantic pool and tag high-priority terms.",
+      "5. Open rankings and capture baseline positions for tracked keywords.",
+      "6. Open ratings view and capture baseline rating/review volume.",
+      "7. Export the initial snapshot so the team has a day-0 reference point.",
+      "",
+      "Definition of done",
+      "1. App is added and visible in working table.",
+      "2. Initial keyword set is saved and tracked.",
+      "3. Baseline ranking and rating snapshot is documented.",
+      "4. Team has a 7-day execution backlog based on gaps from baseline.",
+      "",
+      "Sources",
+      `1. ${SOURCES.firstAccess}`,
+      `2. ${SOURCES.addApp}`,
+      `3. ${SOURCES.addKeywords}`,
+      `4. ${SOURCES.rankings}`,
+      `5. ${SOURCES.ratings}`,
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+
+    return asText(lines.join("\n"));
+  },
+
+  scenario_keyword_research: (args = {}) => {
+    const appName = safeText(args.app_name, "your app");
+    const country = safeText(args.country, "US");
+    const language = safeText(args.language, "English");
+    const targetCount = Number.isInteger(args.target_keywords_count)
+      ? args.target_keywords_count
+      : 50;
+    const seeds = arrayToInline(args.seed_keywords, "none provided");
+
+    const lines = [
+      "Scenario: Keyword research loop",
+      `Context: app=${appName}, country=${country}, language=${language}, target_keywords=${targetCount}, seeds=${seeds}`,
+      "",
+      "Steps",
+      "1. Start from Add Keywords and enter seed terms relevant to the core use case.",
+      "2. Open Suggestions and switch to the target country/store scope.",
+      "3. Use Most Searched Keywords to discover high-volume opportunities.",
+      "4. Filter terms by relevance and intent, then save only commercially useful keywords.",
+      "5. Split selected terms into core/head, mid-tail, and long-tail batches.",
+      "6. Move selected keywords into rankings watchlist for daily/weekly monitoring.",
+      "7. Export shortlist for metadata and Apple Search Ads alignment.",
+      "",
+      "Definition of done",
+      `1. Prioritized keyword pool contains around ${targetCount} trackable candidates.`,
+      "2. Each selected keyword has owner and action (keep/test/remove).",
+      "3. Rankings watchlist is configured for all target locales.",
+      "",
+      "Sources",
+      `1. ${SOURCES.addKeywords}`,
+      `2. ${SOURCES.suggestions}`,
+      `3. ${SOURCES.rankings}`,
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+
+    return asText(lines.join("\n"));
+  },
+
+  scenario_competitor_analysis: (args = {}) => {
+    const appName = safeText(args.app_name, "your app");
+    const country = safeText(args.country, "US");
+    const competitors = arrayToInline(args.competitors, "not specified");
+    const metric = safeText(args.focus_metric, "keyword overlap and ranking gap");
+
+    const lines = [
+      "Scenario: Competitor benchmarking",
+      `Context: app=${appName}, country=${country}, competitors=${competitors}, focus_metric=${metric}`,
+      "",
+      "Steps",
+      "1. In Suggestions, set your app and add competitor app URLs via settings.",
+      "2. Compare overlapping keywords and identify terms where competitors outrank you.",
+      "3. Open Rankings to validate position deltas on shared terms.",
+      "4. Segment gaps into quick wins (low effort), strategic bets, and defend positions.",
+      "5. Convert findings into backlog: metadata updates, localization tasks, ASA tests.",
+      "6. Re-check competitor deltas after each product metadata release.",
+      "",
+      "Definition of done",
+      "1. Competitor matrix is prepared with overlap, gap, and opportunity labels.",
+      "2. Top gap keywords are assigned to concrete optimization actions.",
+      "3. Team has a repeating competitor review cadence.",
+      "",
+      "Sources",
+      `1. ${SOURCES.suggestions}`,
+      `2. ${SOURCES.rankings}`,
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+
+    return asText(lines.join("\n"));
+  },
+
+  scenario_localization_strategy: (args = {}) => {
+    const appName = safeText(args.app_name, "your app");
+    const sourceLocale = safeText(args.source_locale, "en-US");
+    const targets = arrayToInline(args.target_countries, "not specified");
+    const window = safeText(args.release_window, "next 30 days");
+
+    const lines = [
+      "Scenario: Localization expansion",
+      `Context: app=${appName}, source_locale=${sourceLocale}, target_countries=${targets}, release_window=${window}`,
+      "",
+      "Steps",
+      "1. Use Country Localizations to discover where your source locale is reused.",
+      "2. Prioritize countries by demand potential and current rank gap.",
+      "3. Build localized keyword sets for each target market.",
+      "4. Validate app-level localizations to avoid mismatch in metadata language.",
+      "5. Publish in waves (pilot countries first, then scale).",
+      "6. Track rankings and ratings after each localization release wave.",
+      "",
+      "Definition of done",
+      "1. Target country list is prioritized and approved.",
+      "2. Every market has localized keyword set and owner.",
+      "3. Post-release monitoring plan is active for each wave.",
+      "",
+      "Sources",
+      `1. ${SOURCES.localizations}`,
+      `2. ${SOURCES.rankings}`,
+      `3. ${SOURCES.ratings}`,
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+
+    return asText(lines.join("\n"));
+  },
+
+  scenario_rankings_and_ratings: (args = {}) => {
+    const appName = safeText(args.app_name, "your app");
+    const countries = arrayToInline(args.countries, "US");
+    const watch = arrayToInline(args.watch_keywords, "core app keywords");
+    const cadence = safeText(args.check_cadence, "daily");
+
+    const lines = [
+      "Scenario: Rankings and ratings monitoring",
+      `Context: app=${appName}, countries=${countries}, watch_keywords=${watch}, cadence=${cadence}`,
+      "",
+      "Steps",
+      "1. Ensure keyword list is saved and included in rankings tracking.",
+      "2. Review position movement and trend chart on fixed cadence.",
+      "3. Switch to Ratings view for each store to monitor score and review count.",
+      "4. Correlate ranking drops/spikes with rating swings and release events.",
+      "5. Trigger fast actions: metadata tweak, keyword replacement, or review-response cycle.",
+      "6. Keep a change log so each optimization can be measured against outcome.",
+      "",
+      "Definition of done",
+      "1. Monitoring routine is stable and scheduled.",
+      "2. Alerts/actions exist for major ranking or rating changes.",
+      "3. Team can explain top movers weekly with evidence.",
+      "",
+      "Sources",
+      `1. ${SOURCES.rankings}`,
+      `2. ${SOURCES.ratings}`,
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+
+    return asText(lines.join("\n"));
+  },
+
+  scenario_migration_and_transfer: (args = {}) => {
+    const sourceTool = safeText(args.source_tool, "AppTweak/Sensor Tower/Mobile Action/AppFollow");
+    const mode = safeText(args.transfer_mode, "csv_keywords");
+    const needHistory = typeof args.need_history === "boolean" ? args.need_history : true;
+
+    const lines = [
+      "Scenario: Migration/import and transfer",
+      `Context: source_tool=${sourceTool}, transfer_mode=${mode}, need_history=${needHistory}`,
+      "",
+      "Steps",
+      "1. Choose transfer mode: CSV keyword import, full history via model.sqlite, or license transfer.",
+      "2. For CSV mode, map columns to Astro schema and import in Add Keywords.",
+      "3. For full history migration, copy model.sqlite from old Mac and place it in Astro directory on the new Mac.",
+      "4. For license transfer, sign out on old Mac and use Lemon Squeezy link to transfer license.",
+      "5. Re-open app and validate keywords, rankings history, tags, and notes.",
+      "6. Keep rollback backup until parity checks are completed.",
+      "",
+      "Definition of done",
+      "1. Data parity is verified on key entities (keywords/rankings/history/tags).",
+      "2. License is active only on intended machine.",
+      "3. Team runbook includes rollback path.",
+      "",
+      "Sources",
+      `1. ${SOURCES.importExport}`,
+      `2. ${SOURCES.transfer}`,
+      `3. ${SOURCES.terms}`,
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+
+    return asText(lines.join("\n"));
+  },
+
+  standard_topics: () => {
+    const lines = [
+      "Standard topics supported by standard_answer",
+      "",
+      ...STANDARD_TOPICS.flatMap((topic, idx) => [
+        `${idx + 1}. ${topic.id} - ${topic.title}`,
+      ]),
+      "",
+      "How to use",
+      'Call standard_answer with {"query":"..."} or force routing via {"query":"...","topic":"pricing_billing"}.',
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+    return asText(lines.join("\n"));
+  },
+
+  standard_answer: (args = {}) => {
+    const query = safeText(args.query, "");
+    const language = safeText(args.language, "ru").toLowerCase() === "en" ? "en" : "ru";
+
+    if (!query) {
+      return asError("Input validation error: query is required.");
+    }
+
+    const forcedTopicId = safeText(args.topic, "");
+    const topic =
+      STANDARD_TOPICS.find((item) => item.id === forcedTopicId) ||
+      detectStandardTopic(query);
+
+    if (!topic) {
+      const lines = [
+        "No direct topic match found for this query.",
+        `Query: ${query}`,
+        "",
+        "Try one of these topic ids in the topic field:",
+        ...STANDARD_TOPICS.map((item) => `- ${item.id}`),
+        "",
+        "Or ask a more specific question (pricing, refund, legal, privacy, support, migration, platform coverage).",
+        "",
+        `Verified on: ${VERIFIED_ON}`,
+      ];
+      return asText(lines.join("\n"));
+    }
+
+    const answer = language === "en" ? topic.answerEn : topic.answerRu;
+    const lines = [
+      `Detected topic: ${topic.id}`,
+      `Question: ${query}`,
+      "",
+      `Answer: ${answer}`,
+      "",
+      "Recommended next actions",
+      ...topic.next.map((next, idx) => `${idx + 1}. ${next}`),
+      "",
+      "Sources",
+      ...topic.sources.map((source, idx) => `${idx + 1}. ${source}`),
+      "",
+      `Verified on: ${VERIFIED_ON}`,
+    ];
+    return asText(lines.join("\n"));
+  },
+};
+
+function detectStandardTopic(query) {
+  return STANDARD_TOPICS.find((topic) =>
+    topic.patterns.some((pattern) => pattern.test(query))
+  );
+}
+
+function arrayToInline(value, fallback) {
+  if (!Array.isArray(value)) {
+    return fallback;
+  }
+  const clean = value
+    .filter((entry) => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return clean.length > 0 ? clean.join(", ") : fallback;
+}
+
+function safeText(value, fallback) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function asText(text) {
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+  };
+}
+
+function asError(text) {
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+    isError: true,
+  };
+}
+
+function callTool(params) {
+  const name = safeText(params?.name, "");
+  const args = params?.arguments ?? {};
+
+  const handler = TOOL_HANDLERS[name];
+  if (!handler) {
+    return asError(`Unknown tool "${name}". Use tools/list to inspect supported tools.`);
+  }
+
+  try {
+    return handler(args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return asError(`Tool execution error in "${name}": ${message}`);
+  }
+}
+
+function handleRequest(message) {
+  const hasId = Object.prototype.hasOwnProperty.call(message, "id");
+  const id = message.id;
+  const method = message.method;
+
+  if (!method || typeof method !== "string") {
+    if (hasId) {
+      return makeError(id, -32600, "Invalid Request: method is required.");
+    }
+    return null;
+  }
+
+  if (method === "notifications/initialized") {
+    return null;
+  }
+
+  if (method === "exit") {
+    process.exit(0);
+  }
+
+  if (!hasId) {
+    return null;
+  }
+
+  switch (method) {
+    case "initialize":
+      return makeResult(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {
+          tools: {
+            listChanged: false,
+          },
+        },
+        serverInfo: SERVER_INFO,
+      });
+    case "ping":
+      return makeResult(id, {});
+    case "tools/list":
+      return makeResult(id, { tools: TOOL_DEFINITIONS });
+    case "tools/call":
+      return makeResult(id, callTool(message.params || {}));
+    case "shutdown":
+      return makeResult(id, null);
+    default:
+      return makeError(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+function makeResult(id, result) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result,
+  };
+}
+
+function makeError(id, code, message) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code,
+      message,
+    },
+  };
+}
+
+function sendMessage(payload) {
+  const encoded = JSON.stringify(payload);
+  const bytes = Buffer.byteLength(encoded, "utf8");
+  const header = `Content-Length: ${bytes}\r\n\r\n`;
+  process.stdout.write(header + encoded);
+}
+
+function parseContentLength(headerText) {
+  const lines = headerText.split(/\r?\n/);
+  for (const line of lines) {
+    const match = /^Content-Length:\s*(\d+)\s*$/i.exec(line.trim());
+    if (match) {
+      return Number.parseInt(match[1], 10);
+    }
+  }
+  return null;
+}
+
+function findHeaderBoundary(buffer) {
+  const crlfBoundary = buffer.indexOf("\r\n\r\n");
+  if (crlfBoundary !== -1) {
+    return { index: crlfBoundary, separatorLength: 4 };
+  }
+
+  const lfBoundary = buffer.indexOf("\n\n");
+  if (lfBoundary !== -1) {
+    return { index: lfBoundary, separatorLength: 2 };
+  }
+
+  return null;
+}
+
+function isObjectMessage(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+let incoming = Buffer.alloc(0);
+
+process.stdin.on("data", (chunk) => {
+  incoming = Buffer.concat([incoming, chunk]);
+  parseIncoming();
+});
+
+process.stdin.on("error", (error) => {
+  process.stderr.write(`stdin error: ${String(error)}\n`);
+});
+
+process.on("uncaughtException", (error) => {
+  process.stderr.write(`uncaught exception: ${String(error)}\n`);
+});
+
+function parseIncoming() {
+  while (incoming.length > 0) {
+    const boundary = findHeaderBoundary(incoming);
+    if (!boundary) {
+      return;
+    }
+
+    const header = incoming.slice(0, boundary.index).toString("utf8");
+    const contentLength = parseContentLength(header);
+
+    if (!Number.isFinite(contentLength)) {
+      incoming = incoming.slice(boundary.index + boundary.separatorLength);
+      continue;
+    }
+
+    const bodyStart = boundary.index + boundary.separatorLength;
+    const bodyEnd = bodyStart + contentLength;
+    if (incoming.length < bodyEnd) {
+      return;
+    }
+
+    const body = incoming.slice(bodyStart, bodyEnd).toString("utf8");
+    incoming = incoming.slice(bodyEnd);
+
+    let message;
+    try {
+      message = JSON.parse(body);
+    } catch (error) {
+      process.stderr.write(`json parse error: ${String(error)}\n`);
+      continue;
+    }
+
+    if (Array.isArray(message)) {
+      if (message.length === 0) {
+        sendMessage(makeError(null, -32600, "Invalid Request: empty batch."));
+        continue;
+      }
+
+      const responses = [];
+      for (const request of message) {
+        if (!isObjectMessage(request)) {
+          responses.push(
+            makeError(null, -32600, "Invalid Request: request must be an object."),
+          );
+          continue;
+        }
+
+        const response = handleRequest(request);
+        if (response) {
+          responses.push(response);
+        }
+      }
+
+      if (responses.length > 0) {
+        sendMessage(responses);
+      }
+      continue;
+    }
+
+    if (!isObjectMessage(message)) {
+      sendMessage(makeError(null, -32600, "Invalid Request: request must be an object."));
+      continue;
+    }
+
+    const response = handleRequest(message);
+    if (response) {
+      sendMessage(response);
+    }
+  }
+}