asoradar-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to `asoradar-mcp` are documented here.
+
+## 1.0.0 — 2026-06-24
+
+First public release — an MCP server that turns the [ASORadar](https://asoradar.com)
+App Store / Google Play reviews + ASO API into tools for AI agents.
+
+### Added
+- **Auto-generated tools** — one MCP tool per non-deprecated endpoint, built from
+  the live ASORadar OpenAPI spec at startup. Covers App Store (`/a1/*`) and Google
+  Play (`/g1/*`): reviews, app metadata, version history, ratings histograms,
+  search, charts, similar apps, developer portfolios, privacy / Data Safety, the
+  AI-agent composites (clone-brief, niche-scan, metadata/version/privacy/data-safety
+  diffs, developer portfolio stats, review sentiment, reviews-by-version), and
+  webhook subscriptions.
+- **JSON request-body tools** — endpoints with a JSON object body (e.g.
+  `post_webhooks` to create a subscription) map their body fields onto tool
+  arguments; a body field that collides with a path/query param defers to the
+  addressing param.
+- **`get_capabilities`** — a built-in meta-tool returning the live tool catalog and
+  roadmap (no API request spent). Call it first to discover what's available.
+- **Auth + safety** — `ASORADAR_KEY` sent as the `x-access-key` header; trusted-host
+  check before the key is ever sent; upstream tool descriptions wrapped as untrusted
+  documentation to blunt prompt injection; required arguments validated locally so a
+  malformed call never spends a request; response size + timeout limits.
+- **Client install docs** for Claude Code, Claude Desktop, Cursor, OpenAI Codex,
+  Zed, and Windsurf. `stdio` transport.
+
+### Notes
+- Each tool call is one or more metered ASORadar API requests; composite tools fan
+  out to several. New accounts get [100 free requests](https://asoradar.com/registration).
+- Roadmap: synthesized composite tools with provenance + workflow prompts (0.2.x).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ASORadar
+
+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,198 @@
+# asoradar-mcp
+
+[![npm version](https://img.shields.io/npm/v/asoradar-mcp.svg)](https://www.npmjs.com/package/asoradar-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/asoradar-mcp.svg)](https://www.npmjs.com/package/asoradar-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for [ASORadar](https://asoradar.com) — App Reviews API for Apple App Store and Google Play. Available on npm: [`asoradar-mcp`](https://www.npmjs.com/package/asoradar-mcp).
+
+Auto-generates MCP tools from the ASORadar OpenAPI spec at startup, so every non-deprecated endpoint is exposed without hand-written wrappers (`GET /a1/reviews` → `get_a1_reviews`, `GET /a1/clone-brief/{app_id}` → `get_a1_clone-brief_app_id`, `POST /webhooks` → `post_webhooks`). The tool catalog tracks the live API — App Store (`/a1/*`) and Google Play (`/g1/*`) reviews, metadata, version history, ratings histograms, search/charts, AI-agent composites (clone-brief, niche-scan, diffs, sentiment, portfolio stats), and webhook subscriptions.
+
+## Get 100 Free API Requests
+
+[Sign up](https://asoradar.com/registration) and get **100 free ASORadar requests** — no credit card required. Enough to wire up the MCP server, try a few prompts in Claude/Cursor/Codex, and evaluate the data quality before committing.
+
+## Quick start
+
+```bash
+ASORADAR_KEY=your-api-key npx -y asoradar-mcp
+```
+
+`npx` fetches and runs the latest version every time — no install step.
+
+## Install in Claude Code
+
+```bash
+claude mcp add asoradar \
+  -e ASORADAR_KEY=your-api-key \
+  -- npx -y asoradar-mcp
+```
+
+The config is persisted in `~/.claude.json`.
+
+## Install in Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "asoradar": {
+      "command": "npx",
+      "args": ["-y", "asoradar-mcp"],
+      "env": {
+        "ASORADAR_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Install in Cursor
+
+Add to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "asoradar": {
+      "command": "npx",
+      "args": ["-y", "asoradar-mcp"],
+      "env": {
+        "ASORADAR_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Install in OpenAI Codex
+
+Append to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.asoradar]
+command = "npx"
+args = ["-y", "asoradar-mcp"]
+
+[mcp_servers.asoradar.env]
+ASORADAR_KEY = "your-api-key"
+```
+
+## Install in Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "asoradar": {
+      "command": "npx",
+      "args": ["-y", "asoradar-mcp"],
+      "env": {
+        "ASORADAR_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Install in Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "asoradar": {
+      "command": "npx",
+      "args": ["-y", "asoradar-mcp"],
+      "env": {
+        "ASORADAR_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## What you can ask
+
+Plain-English prompts work — the AI picks the right tool and parameters.
+
+| Prompt | Tool used |
+|---|---|
+| Pull recent App Store reviews for Instagram (id 389801252). | `get_a1_reviews` (`app_id`, `country`) |
+| Find 5-star reviews of `com.whatsapp` on Google Play mentioning "crash". | `get_g1_reviews` (`app_id`, `rating=5`, `search=crash`) |
+| What changed in Telegram's last few App Store releases? | `get_a1_version-history_app_id` |
+| Give me a clone brief for this app — metadata, ratings, top complaints. | `get_a1_clone-brief_app_id` |
+| Scout the top finance apps in the US and their rating distributions. | `get_a1_niche-scan` (`category`, `country`) |
+| Diff TikTok's data-safety declaration vs last snapshot. | `get_g1_datasafety_app_id_diff` |
+| Subscribe a webhook to notify me when this app ships a new version. | `post_webhooks` (`kind=app_changes`, `target_url`, `criteria`) |
+| What tools do you have, and what do they cost? | `get_capabilities` |
+
+Call **`get_capabilities`** first — it returns the live tool catalog (≈44 tools, auto-generated from the API) and the roadmap, and spends no API request.
+
+## Configuration
+
+| Env variable | Description | Required |
+|---|---|---|
+| `ASORADAR_KEY` | Your ASORadar access key (sent as `x-access-key` header). | yes |
+| `ASORADAR_URL` | Base URL. Default: `https://api.asoradar.com`. | no |
+| `ASORADAR_SPEC_URL` | OpenAPI spec URL. Default: `<ASORADAR_URL>/openapi.json`. | no |
+| `ASORADAR_TAGS` | Whitelist tags (comma-separated) to limit which tools are exposed. | no |
+| `ASORADAR_EXCLUDE_TAGS` | Additional tags to exclude (`System` is excluded by default). | no |
+| `ASORADAR_TIMEOUT_MS` | Per-request timeout in ms. Default: `30000`. | no |
+| `ASORADAR_SPEC_TIMEOUT_MS` | OpenAPI spec fetch timeout in ms. Default: `60000`. | no |
+| `ASORADAR_MAX_RESPONSE_BYTES` | Max response size in bytes. Default: `10485760` (10 MB). | no |
+| `ASORADAR_MAX_SPEC_BYTES` | Max OpenAPI spec size in bytes. Default: `8388608` (8 MB). | no |
+
+## How it works
+
+1. **Fetch spec.** On startup, `asoradar-mcp` fetches `/openapi.json` from `api.asoradar.com` and parses every endpoint.
+2. **Generate tools.** Each non-deprecated endpoint becomes one MCP tool with a typed input schema. Query and path params plus JSON request-body fields (e.g. `POST /webhooks`) all map onto the tool's arguments. Operations that require header/cookie params, or a non-JSON request body, are skipped since we can't safely forward them.
+3. **Forward calls.** When the AI calls a tool, the server validates required arguments locally (so a malformed call never spends a request), then forwards it with your `x-access-key` header — query/path in the URL, body fields as JSON — and returns the response.
+
+> **Metering.** Every tool call is one or more ASORadar API requests billed against your plan. Composite tools (`clone-brief`, `niche-scan`, `*-diff`, `portfolio-stats`, `reviews/sentiment`) fan out to several underlying calls each. Start with the [100 free requests](#get-100-free-api-requests); `get_capabilities` and local validation errors are free.
+
+## Filtering tools
+
+To keep the surface small and focused, set `ASORADAR_TAGS` to a comma-separated whitelist of OpenAPI tags. The live tags are: `App Store / Reviews`, `App Store / Metadata`, `App Store / Discovery`, `App Store / AI Agents`, the four `Google Play / …` equivalents, and `Webhooks`.
+
+```bash
+# Only the App Store AI-agent composites + reviews:
+ASORADAR_KEY=... ASORADAR_TAGS="App Store / AI Agents,App Store / Reviews" npx -y asoradar-mcp
+```
+
+Or remove specific groups with `ASORADAR_EXCLUDE_TAGS`:
+
+```bash
+ASORADAR_KEY=... ASORADAR_EXCLUDE_TAGS="Webhooks" npx -y asoradar-mcp
+```
+
+## Roadmap
+
+- **Now** — atomic tools auto-generated 1:1 from the API (reviews, metadata, discovery, AI-agent composites, webhook subscriptions) + `get_capabilities`.
+- **Next (0.2.x)** — synthesized composite tools that fan out across endpoints and return evidence with provenance (cited review/snapshot/version IDs), plus workflow prompts (research-competitor, scout-category, post-mortem-release).
+
+The MCP returns structured facts only — it never calls an LLM, never invents endpoints the API doesn't expose, and never emits recommendations. Synthesis is always the agent's job. `get_capabilities` reports the live `available` and `planned` lists.
+
+## Development
+
+```bash
+git clone https://github.com/asoradar/asoradar-mcp.git
+cd asoradar-mcp
+npm install
+npm run build      # compile TypeScript
+npm test           # mock-server smoke + unit tests
+npm run test:e2e   # real API e2e (needs ASORADAR_KEY env var)
+```
+
+Run from source without building:
+
+```bash
+ASORADAR_KEY=... npm run dev
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/http.js

@@ -0,0 +1,68 @@
+export class FetchError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = "FetchError";
+    }
+}
+export async function fetchWithLimit(url, init, maxBytes, timeoutMs) {
+    const signal = AbortSignal.timeout(timeoutMs);
+    // Disable connection reuse: some upstream HTTP servers close keep-alive
+    // sockets aggressively and undici's pool reuses a dead socket on the next
+    // request, hanging until the AbortSignal fires.
+    const headers = new Headers(init.headers);
+    headers.set("connection", "close");
+    let resp;
+    try {
+        resp = await fetch(url, { ...init, signal, headers });
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            throw new FetchError(`Request timed out after ${timeoutMs}ms`, "timeout");
+        }
+        throw new FetchError(`Network error: ${err instanceof Error ? err.message : String(err)}`, "network");
+    }
+    const body = resp.body;
+    if (!body) {
+        return { ok: resp.ok, status: resp.status, statusText: resp.statusText, text: "", truncated: false };
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes) {
+                truncated = true;
+                await reader.cancel();
+                break;
+            }
+            chunks.push(value);
+        }
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            throw new FetchError(`Response read timed out after ${timeoutMs}ms`, "timeout");
+        }
+        throw new FetchError(`Network error during read: ${err instanceof Error ? err.message : String(err)}`, "network");
+    }
+    if (truncated) {
+        throw new FetchError(`Response exceeded size limit (${maxBytes} bytes)`, "too-large");
+    }
+    const merged = new Uint8Array(size);
+    let offset = 0;
+    for (const c of chunks) {
+        merged.set(c, offset);
+        offset += c.byteLength;
+    }
+    const text = new TextDecoder("utf-8").decode(merged);
+    return { ok: resp.ok, status: resp.status, statusText: resp.statusText, text, truncated: false };
+}
+function isAbortError(err) {
+    return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+}

package/dist/index.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createRequire } from "node:module";
+import { buildTools, buildUrl, buildBody, isTrustedUrl, } from "./openapi.js";
+import { fetchWithLimit, FetchError } from "./http.js";
+// Single source of truth for the version: package.json (published alongside
+// dist/). Resolves to ../package.json from both dist/index.js and src/index.ts.
+const require = createRequire(import.meta.url);
+const VERSION = require("../package.json").version;
+const USER_AGENT = `asoradar-mcp/${VERSION}`;
+const CAPABILITIES_TOOL_NAME = "get_capabilities";
+const API_KEY = process.env.ASORADAR_KEY;
+const BASE_URL = (process.env.ASORADAR_URL ?? "https://api.asoradar.com").replace(/\/$/, "");
+const SPEC_URL = process.env.ASORADAR_SPEC_URL ?? `${BASE_URL}/openapi.json`;
+const SPEC_TIMEOUT_MS = numEnv("ASORADAR_SPEC_TIMEOUT_MS", 60_000);
+const API_TIMEOUT_MS = numEnv("ASORADAR_TIMEOUT_MS", 30_000);
+const MAX_SPEC_BYTES = numEnv("ASORADAR_MAX_SPEC_BYTES", 8 * 1024 * 1024);
+const MAX_RESPONSE_BYTES = numEnv("ASORADAR_MAX_RESPONSE_BYTES", 10 * 1024 * 1024);
+// System endpoints (health checks, internal probes) are noise for an AI client.
+// Operators can extend the list with ASORADAR_EXCLUDE_TAGS.
+const DEFAULT_EXCLUDED_TAGS = ["System"];
+const includeTags = parseTagList(process.env.ASORADAR_TAGS);
+const excludeTags = new Set([
+    ...DEFAULT_EXCLUDED_TAGS,
+    ...parseTagList(process.env.ASORADAR_EXCLUDE_TAGS),
+]);
+if (!API_KEY) {
+    process.stderr.write("Error: ASORADAR_KEY environment variable is required.\n" +
+        "Get your API key at https://asoradar.com/tokens\n");
+    process.exit(1);
+}
+if (!isTrustedUrl(BASE_URL)) {
+    process.stderr.write(`Warning: ASORADAR_URL points to a non-standard host (${BASE_URL}). ` +
+        `Your x-access-key will be sent there. ` +
+        `Only use this for self-hosted or proxied ASORadar over HTTPS or localhost.\n`);
+}
+// SPEC_URL controls the tool surface — a malicious spec can author tool
+// descriptions that prompt-inject the model. Default points back to BASE_URL,
+// but explicit override deserves a warning if it goes off-domain.
+if (!isTrustedUrl(SPEC_URL)) {
+    process.stderr.write(`Warning: ASORADAR_SPEC_URL points to a non-standard host (${SPEC_URL}). ` +
+        `Tool definitions will be loaded from there. ` +
+        `Only override this if you trust that origin.\n`);
+}
+function parseTagList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean);
+}
+function numEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+async function loadSpec() {
+    process.stderr.write(`Fetching OpenAPI spec from ${SPEC_URL}...\n`);
+    const result = await fetchWithLimit(SPEC_URL, { method: "GET", headers: { accept: "application/json", "user-agent": USER_AGENT } }, MAX_SPEC_BYTES, SPEC_TIMEOUT_MS);
+    if (!result.ok) {
+        throw new Error(`Failed to fetch OpenAPI spec: ${result.status} ${result.statusText}`);
+    }
+    return JSON.parse(result.text);
+}
+async function main() {
+    const spec = await loadSpec();
+    const entries = buildTools(spec, {
+        includeTags,
+        excludeTags,
+        reservedNames: [CAPABILITIES_TOOL_NAME],
+    });
+    const byName = new Map(entries.map((e) => [e.tool.name, e]));
+    process.stderr.write(`Loaded ${entries.length} ASORadar tools` +
+        (includeTags.length ? ` (tags: ${includeTags.join(", ")})` : "") +
+        `\n`);
+    // A built-in introspection tool: lets an agent discover the available tool
+    // catalog and the roadmap deliberately, instead of shipping non-functional
+    // "coming soon" stubs that agents treat as broken tools.
+    const CAPABILITIES_TOOL = {
+        name: CAPABILITIES_TOOL_NAME,
+        description: "[meta] List the ASORadar tools this MCP server exposes (auto-generated from the live API) plus the planned roadmap. Takes no arguments — call it first to discover what you can do. Every underlying API call is metered against your ASORadar plan (100 free requests on signup); composite tools (clone-brief, niche-scan, *-diff, portfolio-stats, reviews/sentiment) each fan out to several API calls.",
+        inputSchema: { type: "object", properties: {} },
+    };
+    const capabilitiesPayload = () => ({
+        server: "asoradar-mcp",
+        version: VERSION,
+        docs: "https://github.com/asoradar/asoradar-mcp#readme",
+        available: entries.map((e) => ({ name: e.tool.name, description: e.tool.description })),
+        planned: [
+            { capability: "synthesized composite tools (provenance-cited evidence)", version: "0.2.x" },
+            { capability: "workflow prompts (research-competitor, scout-category, post-mortem-release)", version: "0.2.x" },
+        ],
+    });
+    const server = new Server({ name: "asoradar-mcp", version: VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [CAPABILITIES_TOOL, ...entries.map((e) => e.tool)],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (request.params.name === CAPABILITIES_TOOL.name) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(capabilitiesPayload(), null, 2) }],
+            };
+        }
+        const entry = byName.get(request.params.name);
+        if (!entry) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+            };
+        }
+        const args = (request.params.arguments ?? {});
+        // Validate required args before spending a request. A missing required
+        // path param leaves a literal `{name}` in the URL and a missing required
+        // body field would 422 — both would still bill the call.
+        const nullish = (v) => v === undefined || v === null;
+        const missing = [
+            ...entry.parameters.filter((p) => p.required && nullish(args[p.name])).map((p) => p.name),
+            ...entry.requiredBodyProperties.filter((n) => nullish(args[n])),
+        ];
+        if (missing.length > 0) {
+            return {
+                isError: true,
+                content: [
+                    { type: "text", text: `Missing required argument(s): ${missing.join(", ")}` },
+                ],
+            };
+        }
+        const url = buildUrl(BASE_URL, entry.path, args, entry.parameters);
+        const body = buildBody(args, entry.bodyProperties);
+        const headers = {
+            "x-access-key": API_KEY,
+            accept: "application/json",
+            "user-agent": USER_AGENT,
+        };
+        const init = { method: entry.method.toUpperCase(), headers };
+        if (body !== undefined) {
+            headers["content-type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        try {
+            const resp = await fetchWithLimit(url, init, MAX_RESPONSE_BYTES, API_TIMEOUT_MS);
+            if (!resp.ok) {
+                return {
+                    isError: true,
+                    content: [
+                        { type: "text", text: `HTTP ${resp.status} ${resp.statusText}\n${resp.text}` },
+                    ],
+                };
+            }
+            return { content: [{ type: "text", text: resp.text }] };
+        }
+        catch (err) {
+            const message = err instanceof FetchError ? `${err.kind}: ${err.message}` :
+                err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Request failed: ${message}` }],
+            };
+        }
+    });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Failed to start asoradar-mcp: ${message}\n`);
+    process.exit(1);
+});

package/dist/openapi.js

@@ -0,0 +1,260 @@
+const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head"]);
+export function sanitizeName(method, path) {
+    const raw = `${method}_${path}`
+        .replace(/^\/+/, "")
+        .replace(/\{([^}]+)\}/g, "$1")
+        .replace(/[^a-zA-Z0-9_-]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return raw.slice(0, 128) || "tool";
+}
+export function resolveRef(ref, spec) {
+    if (!ref.startsWith("#/"))
+        return {};
+    const parts = ref.slice(2).split("/");
+    let node = spec;
+    for (const part of parts) {
+        if (node && typeof node === "object" && part in node) {
+            node = node[part];
+        }
+        else {
+            return {};
+        }
+    }
+    return node ?? {};
+}
+export function expandSchema(schema, spec, seen = new Set()) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    if (Array.isArray(schema)) {
+        return schema.map((v) => expandSchema(v, spec, seen));
+    }
+    const obj = schema;
+    if (typeof obj.$ref === "string") {
+        const ref = obj.$ref;
+        if (seen.has(ref))
+            return {};
+        const next = new Set(seen);
+        next.add(ref);
+        return expandSchema(resolveRef(ref, spec), spec, next);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(obj)) {
+        out[key] = expandSchema(value, spec, seen);
+    }
+    return out;
+}
+export function resolveParameter(param, spec) {
+    if ("$ref" in param && typeof param.$ref === "string") {
+        const resolved = resolveRef(param.$ref, spec);
+        if (resolved && typeof resolved === "object" && "name" in resolved && "in" in resolved) {
+            return resolved;
+        }
+        return null;
+    }
+    return param;
+}
+export function mergeParameters(pathParams, opParams, spec) {
+    const byKey = new Map();
+    for (const raw of pathParams ?? []) {
+        const p = resolveParameter(raw, spec);
+        if (p)
+            byKey.set(`${p.in}:${p.name}`, p);
+    }
+    for (const raw of opParams ?? []) {
+        const p = resolveParameter(raw, spec);
+        if (p)
+            byKey.set(`${p.in}:${p.name}`, p);
+    }
+    return [...byKey.values()];
+}
+// Resolve an operation's JSON request body into a flat object schema we can map
+// onto MCP tool args. Only application/json object bodies are supported; any
+// other media type or non-object schema returns null so the caller can skip the
+// op rather than call it with an unserializable body. The body's required props
+// are honored only when the body itself is required.
+export function extractJsonBody(requestBody, spec) {
+    const content = requestBody?.content;
+    if (!content)
+        return null;
+    const media = content["application/json"] ?? content["application/*+json"];
+    if (!media?.schema)
+        return null;
+    const expanded = expandSchema(media.schema, spec);
+    const props = expanded?.properties;
+    if (!expanded || expanded.type !== "object" || !props || typeof props !== "object")
+        return null;
+    const propNames = Object.keys(props);
+    const required = requestBody.required !== false && Array.isArray(expanded.required)
+        ? expanded.required.filter((r) => propNames.includes(r))
+        : [];
+    return { schema: expanded, props: propNames, required };
+}
+export function buildInputSchema(parameters, spec, body) {
+    const properties = {};
+    const required = [];
+    for (const param of parameters) {
+        const schema = expandSchema(param.schema ?? { type: "string" }, spec);
+        if (param.description) {
+            schema.description = param.description;
+        }
+        properties[param.name] = schema;
+        if (param.required) {
+            required.push(param.name);
+        }
+    }
+    if (body) {
+        const bodyProps = (body.schema.properties ?? {});
+        for (const [name, sch] of Object.entries(bodyProps)) {
+            // A path/query param of the same name wins (it is the addressing arg).
+            if (!(name in properties))
+                properties[name] = sch;
+        }
+        for (const r of body.required) {
+            if (!required.includes(r))
+                required.push(r);
+        }
+    }
+    const result = { type: "object", properties };
+    if (required.length > 0) {
+        result.required = required;
+    }
+    return result;
+}
+// Pick the JSON request-body object from tool args (only the declared body
+// props). Returns undefined when the op has no body or no body args were given.
+export function buildBody(args, bodyProperties) {
+    if (bodyProperties.length === 0)
+        return undefined;
+    const body = {};
+    for (const name of bodyProperties) {
+        if (args[name] !== undefined && args[name] !== null)
+            body[name] = args[name];
+    }
+    return Object.keys(body).length > 0 ? body : undefined;
+}
+export function shouldIncludeOperation(op, includeTags, excludeTags) {
+    if (op.deprecated)
+        return false;
+    const tags = op.tags ?? [];
+    if (tags.some((t) => excludeTags.has(t)))
+        return false;
+    if (includeTags.length > 0) {
+        return tags.some((t) => includeTags.includes(t));
+    }
+    return true;
+}
+export function buildTools(spec, opts = {}) {
+    const includeTags = opts.includeTags ?? [];
+    const excludeTags = opts.excludeTags ?? new Set();
+    const entries = [];
+    // Seed reserved (built-in) names so a same-named spec endpoint is suffixed
+    // and stays reachable instead of being silently shadowed by the built-in.
+    const usedNames = new Set(opts.reservedNames ?? []);
+    for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
+        if (!pathItem || typeof pathItem !== "object")
+            continue;
+        const pathParams = pathItem.parameters;
+        for (const [method, raw] of Object.entries(pathItem)) {
+            if (!HTTP_METHODS.has(method))
+                continue;
+            if (!raw || typeof raw !== "object")
+                continue;
+            const op = raw;
+            if (!shouldIncludeOperation(op, includeTags, excludeTags))
+                continue;
+            // A JSON object request body is mapped onto tool args (e.g. POST
+            // /webhooks). A requestBody we can't serialize (non-JSON or non-object)
+            // means the op promises semantics we don't honor — skip it.
+            const body = extractJsonBody(op.requestBody, spec);
+            if (op.requestBody && !body)
+                continue;
+            // Skip operations whose parameters include header/cookie/etc. — we only
+            // forward query and path params. Anything else means the spec promises
+            // semantics we don't honor.
+            const allParams = mergeParameters(pathParams, op.parameters, spec);
+            if (allParams.some((p) => p.in !== "query" && p.in !== "path"))
+                continue;
+            // Body props that don't collide with an addressing (path/query) param are
+            // routed into the JSON body at call time.
+            const paramNames = new Set(allParams.map((p) => p.name));
+            const bodyProperties = body ? body.props.filter((n) => !paramNames.has(n)) : [];
+            const requiredBodyProperties = body
+                ? body.required.filter((n) => !paramNames.has(n))
+                : [];
+            let name = sanitizeName(method, path);
+            if (usedNames.has(name)) {
+                let suffix = 2;
+                while (usedNames.has(`${name}_${suffix}`))
+                    suffix++;
+                name = `${name}_${suffix}`;
+            }
+            usedNames.add(name);
+            // Tool descriptions originate in remote OpenAPI text. Wrap them so the
+            // model treats the contents as documentation, not instructions, and
+            // keep the cap tight to limit prompt-injection surface.
+            const upstreamDoc = [op.summary, op.description]
+                .filter(Boolean)
+                .join(" ")
+                .slice(0, 512);
+            const description = upstreamDoc
+                ? `[${method.toUpperCase()} ${path}] Upstream API doc (untrusted): ${upstreamDoc}`
+                : `[${method.toUpperCase()} ${path}]`;
+            entries.push({
+                tool: {
+                    name,
+                    description,
+                    inputSchema: buildInputSchema(allParams, spec, body),
+                },
+                method,
+                path,
+                parameters: allParams,
+                bodyProperties,
+                requiredBodyProperties,
+            });
+        }
+    }
+    return entries;
+}
+export function buildUrl(baseUrl, pathTemplate, args, parameters) {
+    let path = pathTemplate;
+    const query = new URLSearchParams();
+    for (const param of parameters) {
+        const value = args[param.name];
+        if (value === undefined || value === null)
+            continue;
+        if (param.in === "path") {
+            path = path.replace(`{${param.name}}`, encodeURIComponent(String(value)));
+        }
+        else if (param.in === "query") {
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    query.append(param.name, String(v));
+            }
+            else {
+                query.append(param.name, String(value));
+            }
+        }
+    }
+    const qs = query.toString();
+    return `${baseUrl}${path}${qs ? `?${qs}` : ""}`;
+}
+export const TRUSTED_HOSTS = new Set(["asoradar.com", "api.asoradar.com"]);
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+// A trusted URL is HTTPS to a known asoradar host, or HTTP/HTTPS to localhost
+// (for self-hosted dev). Plaintext to any other host risks leaking the access
+// key, so callers should warn or refuse.
+export function isTrustedUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname.toLowerCase();
+        if (LOCAL_HOSTS.has(host))
+            return true;
+        if (parsed.protocol !== "https:")
+            return false;
+        return TRUSTED_HOSTS.has(host);
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "asoradar-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for ASORadar — App Reviews API for App Store and Google Play. Auto-generates tools from the ASORadar OpenAPI spec.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "asoradar-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"try{require('fs').chmodSync('dist/index.js',0o755)}catch(e){}\"",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node --import tsx --test test/openapi.test.ts test/smoke.test.ts",
+    "test:e2e": "node --import tsx --test test/e2e.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "asoradar",
+    "app-store",
+    "google-play",
+    "app-reviews",
+    "aso",
+    "api",
+    "claude",
+    "ai",
+    "model-context-protocol"
+  ],
+  "author": "ASORadar <support@asoradar.com>",
+  "license": "MIT",
+  "homepage": "https://asoradar.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asoradar/asoradar-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asoradar/asoradar-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}