storelift-mcp 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# storelift-mcp
+
+App Store & Google Play ranking data as an MCP server. Ask your assistant which
+keywords you dropped on, who outranks you, and whether AI assistants mention
+your app at all — without opening a dashboard.
+
+Backed by [Storelift](https://storelift.vomcore.com), which measures keyword
+ranks, rivals and AI visibility nightly. **No store credentials required** —
+ranks are read from the public storefront.
+
+## Requirements
+
+- A **Studio** plan (the Public API is enabled on that plan)
+- An API key: Storelift → Settings → API keys → **Generate key**
+
+## Install
+
+Claude Code:
+
+```bash
+claude mcp add storelift -e STORELIFT_API_KEY=sl_live_... -- npx -y storelift-mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "storelift": {
+      "command": "npx",
+      "args": ["-y", "storelift-mcp"],
+      "env": { "STORELIFT_API_KEY": "sl_live_..." }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Returns |
+|---|---|
+| `list_apps` | tracked apps (id, name, countries, keywords) |
+| `get_keywords` | keyword ranks for one app in one country |
+| `get_rivals` | apps ranking **above** you, with their rank and yours |
+| `get_ai_visibility` | whether assistants name your app, per engine (Claude / ChatGPT / Gemini) |
+| `get_history` | rank history, `[day, rank]` points |
+
+## Reading the data
+
+Keyword results carry **three distinct states**, and they are not the same thing:
+
+- `measured: false` — the query **could not be measured**
+- `rank: null` (with `measured: true`) — measured, but **absent** from the top results
+- `rank: <number>` — the rank
+
+Counting an unmeasured day as zero produces a false chart. The tool descriptions
+repeat this so the model does not flatten the three into one.
+
+AI visibility is an **observation, not a ranking**: a model's knowledge is frozen
+at a date and the answer is not identical every time. Read the trend, not a
+single measurement.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `STORELIFT_API_KEY` | — | required; the server exits with a message if unset |
+| `STORELIFT_API` | `https://storelift.vomcore.com` | override the API base |
+
+No dependencies — a single file speaking JSON-RPC over stdio. Runs with
+`node index.mjs` just as well as through `npx`.
+
+## License
+
+MIT

package/index.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Storelift MCP sunucusu.
+//
+// NE İŞE YARIYOR: Claude (ya da MCP konuşan başka bir istemci) uygulamanın
+// sıralarını, rakiplerini ve AI görünürlüğünü DOĞRUDAN okuyabiliyor.
+// "Kelimece'nin TR'de düşen kelimeleri hangileri" diye sorup cevabı panoya
+// bakmadan alıyorsun.
+//
+// KURULUM (Claude Desktop → claude_desktop_config.json):
+//   {
+//     "mcpServers": {
+//       "storelift": {
+//         "command": "npx",
+//         "args": ["-y", "storelift-mcp"],
+//         "env": { "STORELIFT_API_KEY": "sl_live_..." }
+//       }
+//     }
+//   }
+//
+// BAĞIMLILIK YOK: stdio üzerinden JSON-RPC elle konuşuluyor. Tek dosya, npm
+// kurulumu gerektirmeden `node index.mjs` ile de çalışır.
+
+const BASE = process.env.STORELIFT_API || "https://storelift.vomcore.com";
+const KEY = process.env.STORELIFT_API_KEY;
+
+if (!KEY) {
+  console.error("STORELIFT_API_KEY tanımlı değil. Ayarlar → API anahtarları'ndan bir anahtar üret.");
+  process.exit(1);
+}
+
+async function api(path) {
+  const res = await fetch(BASE + path, { headers: { "x-api-key": KEY } });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(body.error || `HTTP ${res.status}`);
+  return body;
+}
+
+const TOOLS = [
+  {
+    name: "list_apps",
+    description: "Storelift hesabındaki izlenen uygulamaları listeler (id, ad, ülkeler, kelimeler).",
+    inputSchema: { type: "object", properties: {} },
+    run: () => api("/v1/apps"),
+  },
+  {
+    name: "get_keywords",
+    description:
+      "Bir uygulamanın bir ülkedeki kelime sıralarını verir. ÜÇ DURUM AYRIDIR: measured=false ölçülemedi, rank=null ölçüldü ama ilk sonuçlarda yok, rank=sayı sıra. Bunları birbirine karıştırma.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        appId: { type: "string", description: "list_apps'ten gelen uygulama kimliği" },
+        country: { type: "string", description: "ülke kodu, ör. tr" },
+        platform: { type: "string", enum: ["ios", "android"] },
+      },
+      required: ["appId"],
+    },
+    run: (a) => api(`/v1/apps/${a.appId}/keywords?country=${a.country || ""}&platform=${a.platform || "ios"}`),
+  },
+  {
+    name: "get_rivals",
+    description:
+      "Aramada uygulamanın ÜSTÜNDE çıkan uygulamalar. Her rakip için hangi kelimede kaçıncı olduğu ve bizim sıramız birlikte döner (ourRank null ise o kelimede hiç görünmüyoruz).",
+    inputSchema: {
+      type: "object",
+      properties: { appId: { type: "string" }, country: { type: "string" }, platform: { type: "string", enum: ["ios", "android"] } },
+      required: ["appId"],
+    },
+    run: (a) => api(`/v1/apps/${a.appId}/rivals?country=${a.country || ""}&platform=${a.platform || "ios"}`),
+  },
+  {
+    name: "get_ai_visibility",
+    description:
+      "Asistanlara sorulan doğal sorularda uygulamanın anılıp anılmadığı — motor başına (Claude/ChatGPT/Gemini). Bu bir sıralama değil gözlemdir; tek ölçüm kanıt değildir, eğilime bak.",
+    inputSchema: { type: "object", properties: { appId: { type: "string" }, country: { type: "string" } }, required: ["appId"] },
+    run: (a) => api(`/v1/apps/${a.appId}/ai?country=${a.country || ""}`),
+  },
+  {
+    name: "get_history",
+    description: "Bir ülkedeki kelime sıra geçmişi. Seri noktaları [gün, sıra] biçiminde; sıra null ise o gün ilk sonuçlarda yoktuk.",
+    inputSchema: { type: "object", properties: { appId: { type: "string" }, country: { type: "string" } }, required: ["appId"] },
+    run: (a) => api(`/v1/apps/${a.appId}/history?country=${a.country || ""}`),
+  },
+];
+
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const ok = (id, result) => send({ jsonrpc: "2.0", id, result });
+const err = (id, message) => send({ jsonrpc: "2.0", id, error: { code: -32000, message } });
+
+async function handle(req) {
+  const { id, method, params } = req;
+  if (method === "initialize") {
+    return ok(id, {
+      protocolVersion: "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "storelift", version: "1.0.0" },
+    });
+  }
+  if (method === "notifications/initialized") return; // bildirim, yanıt beklemez
+  if (method === "tools/list") {
+    return ok(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+  }
+  if (method === "tools/call") {
+    const tool = TOOLS.find((t) => t.name === params?.name);
+    if (!tool) return err(id, `bilinmeyen araç: ${params?.name}`);
+    try {
+      const data = await tool.run(params.arguments || {});
+      return ok(id, { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
+    } catch (e) {
+      // Hata metni araca DÖNÜYOR, sessizce yutulmuyor: model "veri yok" ile
+      // "okuyamadım" arasındaki farkı görmezse yanlış sonuç anlatır.
+      return ok(id, { content: [{ type: "text", text: `HATA: ${e.message}` }], isError: true });
+    }
+  }
+  if (id !== undefined) err(id, `desteklenmeyen metot: ${method}`);
+}
+
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", async (chunk) => {
+  buf += chunk;
+  let i;
+  while ((i = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, i).trim();
+    buf = buf.slice(i + 1);
+    if (!line) continue;
+    try {
+      await handle(JSON.parse(line));
+    } catch {
+      /* bozuk satır yok sayılır — akış kapanmamalı */
+    }
+  }
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "storelift-mcp",
+  "version": "1.0.0",
+  "description": "App Store & Google Play keyword ranks, rivals and AI visibility as an MCP server",
+  "type": "module",
+  "bin": {
+    "storelift-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "mcp-server",
+    "claude",
+    "aso",
+    "app-store-optimization",
+    "app-store",
+    "google-play",
+    "keyword-rank",
+    "ai-visibility"
+  ],
+  "homepage": "https://storelift.vomcore.com",
+  "bugs": {
+    "email": "hello@vomcore.com"
+  },
+  "author": "Vomcore",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}