pabal-web-mcp 0.1.0 → 0.1.2

package/README.md

@@ -8,6 +8,164 @@ MCP (Model Context Protocol) server for ASO (App Store Optimization) data manage
 npm install pabal-web-mcp
 ```
 
+## 🛠️ MCP Client Installation
+
+### Requirements
+
+- Node.js >= 18
+- MCP client: Cursor, Claude Code, VS Code, Windsurf, etc.
+
+> [!TIP]
+> If you repeatedly do ASO/store tasks, add a client rule like "always use pabal-web-mcp" so the MCP server auto-invokes without typing it every time.
+
+### Global install (recommended)
+
+```bash
+npm install -g pabal-web-mcp
+
+# or
+
+yarn global add pabal-web-mcp
+```
+
+Install globally first for fastest starts and to avoid npm download issues (proxy/firewall/offline). You can still use `npx -y pabal-web-mcp`, but global install is recommended. After global install, set your MCP config to `command: "pabal-web-mcp"` (no `npx` needed).
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+Add to `~/.cursor/mcp.json` (global) or project `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pabal-web-mcp": {
+      "command": "npx",
+      "args": ["-y", "pabal-web-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "pabal-web-mcp": {
+      "command": "pabal-web-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in VS Code</b></summary>
+
+Example `settings.json` MCP section:
+
+```json
+"mcp": {
+  "servers": {
+    "pabal-web-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "pabal-web-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+"mcp": {
+  "servers": {
+    "pabal-web-mcp": {
+      "type": "stdio",
+      "command": "pabal-web-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Claude Code</b></summary>
+
+> [!TIP]
+> See the [official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp#setting-up-enterprise-mcp-configuration) for detailed configuration options.
+
+Add to Claude Code MCP settings (JSON format):
+
+```json
+{
+  "mcpServers": {
+    "pabal-web-mcp": {
+      "command": "npx",
+      "args": ["-y", "pabal-web-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally (`npm install -g pabal-web-mcp`):
+
+```json
+{
+  "mcpServers": {
+    "pabal-web-mcp": {
+      "command": "pabal-web-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Windsurf</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "pabal-web-mcp": {
+      "command": "npx",
+      "args": ["-y", "pabal-web-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "pabal-web-mcp": {
+      "command": "pabal-web-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+## MCP Server
+
+This package includes an MCP server for managing ASO data through Claude or other MCP-compatible clients.
+
+### Available Tools
+
+| Tool             | Description                                        |
+| ---------------- | -------------------------------------------------- |
+| `aso-to-public`  | Convert ASO data to public config format           |
+| `public-to-aso`  | Convert public config to ASO data format           |
+| `improve-public` | Improve product locale content with AI suggestions |
+| `init-project`   | Initialize a new product project structure         |
+
 ## Usage
 
 ### Importing Types
@@ -60,38 +218,6 @@ console.log(asoData.appStore?.name);
 console.log(asoData.googlePlay?.title);
 ```
 
-## MCP Server
-
-This package includes an MCP server for managing ASO data through Claude or other MCP-compatible clients.
-
-### Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `aso-to-public` | Convert ASO data to public config format |
-| `public-to-aso` | Convert public config to ASO data format |
-| `improve-public` | Improve product locale content with AI suggestions |
-| `init-project` | Initialize a new product project structure |
-
-### Running the MCP Server
-
-```bash
-npx pabal-web-mcp
-```
-
-Or add to your Claude Desktop config:
-
-```json
-{
-  "mcpServers": {
-    "pabal-web-mcp": {
-      "command": "npx",
-      "args": ["pabal-web-mcp"]
-    }
-  }
-}
-```
-
 ## Types Reference
 
 ### ASO Types
@@ -116,17 +242,17 @@ Or add to your Claude Desktop config:
 ## Supported Locales
 
 | Unified | App Store | Google Play |
-|---------|-----------|-------------|
-| en-US | en-US | en-US |
-| ko-KR | ko | ko-KR |
-| ja-JP | ja | ja-JP |
-| zh-CN | zh-Hans | zh-CN |
-| zh-TW | zh-Hant | zh-TW |
-| de-DE | de-DE | de-DE |
-| fr-FR | fr-FR | fr-FR |
-| es-ES | es-ES | es-ES |
-| pt-BR | pt-BR | pt-BR |
-| ... | ... | ... |
+| ------- | --------- | ----------- |
+| en-US   | en-US     | en-US       |
+| ko-KR   | ko        | ko-KR       |
+| ja-JP   | ja        | ja-JP       |
+| zh-CN   | zh-Hans   | zh-CN       |
+| zh-TW   | zh-Hant   | zh-TW       |
+| de-DE   | de-DE     | de-DE       |
+| fr-FR   | fr-FR     | fr-FR       |
+| es-ES   | es-ES     | es-ES       |
+| pt-BR   | pt-BR     | pt-BR       |
+| ...     | ...       | ...         |
 
 ## License
 

package/dist/bin/mcp-server.js

@@ -2,14 +2,20 @@
 import {
   DEFAULT_LOCALE,
   appStoreToUnified,
+  getProductsDir,
+  getPublicDir,
+  getPullDataDir,
+  getPushDataDir,
   googlePlayToUnified,
+  isAppStoreLocale,
   isAppStoreMultilingual,
+  isGooglePlayLocale,
   isGooglePlayMultilingual,
   loadAsoFromConfig,
   saveAsoToAsoDir,
   unifiedToAppStore,
   unifiedToGooglePlay
-} from "../chunk-YJWGBO7W.js";
+} from "../chunk-AM6RGDD4.js";
 
 // src/bin/mcp-server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -28,10 +34,9 @@ import fs from "fs";
 import path from "path";
 function loadPullData(slug) {
   const asoData = {};
+  const pullDataDir = getPullDataDir();
   const googlePlayPath = path.join(
-    process.cwd(),
-    ".aso",
-    "pullData",
+    pullDataDir,
     "products",
     slug,
     "store",
@@ -50,9 +55,7 @@ function loadPullData(slug) {
     }
   }
   const appStorePath = path.join(
-    process.cwd(),
-    ".aso",
-    "pullData",
+    pullDataDir,
     "products",
     slug,
     "store",
@@ -202,14 +205,14 @@ var jsonSchema = toJsonSchema(asoToPublicInputSchema, {
 var inputSchema = jsonSchema.definitions?.AsoToPublicInput || jsonSchema;
 var asoToPublicTool = {
   name: "aso-to-public",
-  description: `Converts ASO data from .aso/pullData to public/products/[slug]/ structure.
+  description: `Converts ASO data from pullData to public/products/[slug]/ structure.
 
 **IMPORTANT:** The 'slug' parameter is REQUIRED. If the user does not provide a slug, you MUST ask them to provide it. This tool processes only ONE product at a time.
 
 This tool:
-1. Loads ASO data from .aso/pullData/products/[slug]/store/
+1. Loads ASO data from pullData/products/[slug]/store/ (path from ~/.config/pabal-mcp/config.json dataDir)
 2. Generates per-locale conversion prompts to map fullDescription into structured locale JSON (template intro/outro + landing features/screenshots captions)
-3. Next steps (manual): paste converted JSON into public/products/[slug]/locales/[locale].json and copy screenshots from .aso/pullData if needed
+3. Next steps (manual): paste converted JSON into public/products/[slug]/locales/[locale].json and copy screenshots from pullData if needed
 
 The conversion from unstructured to structured format is performed by Claude based on the conversion prompt.`,
   inputSchema
@@ -218,7 +221,7 @@ async function handleAsoToPublic(input) {
   const { slug } = input;
   const asoData = loadPullData(slug);
   if (!asoData.googlePlay && !asoData.appStore) {
-    throw new Error(`No ASO data found in .aso/pullData for ${slug}`);
+    throw new Error(`No ASO data found in pullData for ${slug}`);
   }
   const mergedDataByLocale = /* @__PURE__ */ new Map();
   if (asoData.googlePlay) {
@@ -270,7 +273,8 @@ async function handleAsoToPublic(input) {
       ).find((loc) => googlePlayToUnified(loc) === unifiedLocale);
       if (googlePlayLocale) {
         if (!screenshotPaths) screenshotPaths = {};
-        screenshotPaths.googlePlay = `.aso/pullData/products/${slug}/store/google-play/screenshots/${googlePlayLocale}/`;
+        const pullDataDir2 = getPullDataDir();
+        screenshotPaths.googlePlay = `${pullDataDir2}/products/${slug}/store/google-play/screenshots/${googlePlayLocale}/`;
       }
     }
     if (mergedData.appStore) {
@@ -279,7 +283,8 @@ async function handleAsoToPublic(input) {
       ).find((loc) => appStoreToUnified(loc) === unifiedLocale);
       if (appStoreLocale) {
         if (!screenshotPaths) screenshotPaths = {};
-        screenshotPaths.appStore = `.aso/pullData/products/${slug}/store/app-store/screenshots/${appStoreLocale}/`;
+        const pullDataDir2 = getPullDataDir();
+        screenshotPaths.appStore = `${pullDataDir2}/products/${slug}/store/app-store/screenshots/${appStoreLocale}/`;
       }
     }
     const prompt = generateConversionPrompt(
@@ -303,7 +308,8 @@ async function handleAsoToPublic(input) {
 --- ${unifiedLocale} (${sourcesText}) ---
 ${prompt}`);
   }
-  let responseText = `Converting ASO data from .aso/pullData to public/products/${slug}/ structure.
+  const pullDataDir = getPullDataDir();
+  let responseText = `Converting ASO data from pullData to public/products/${slug}/ structure.
 
 `;
   responseText += `Found ${conversionTasks.length} unified locale(s) to convert.
@@ -322,7 +328,7 @@ Next steps (manual):
 `;
   responseText += `   Example: public/products/${slug}/locales/ar.json (not ar-SA.json)
 `;
-  responseText += `2. Copy screenshots from .aso/pullData/products/${slug}/store/ to public/products/${slug}/screenshots/
+  responseText += `2. Copy screenshots from ${pullDataDir}/products/${slug}/store/ to public/products/${slug}/screenshots/
 `;
   return {
     content: [
@@ -413,7 +419,7 @@ function prepareAsoDataForPush(slug, configData) {
 
 // src/tools/utils/public-to-aso/save-raw-aso-data.util.ts
 function saveRawAsoData(slug, asoData, options) {
-  const rootDir = options?.rootDir ?? ".aso/pushData";
+  const rootDir = options?.rootDir ?? getPushDataDir();
   saveAsoToAsoDir(slug, asoData, { rootDir });
   const localeCounts = {};
   if (asoData.googlePlay) {
@@ -475,8 +481,9 @@ function isLocalAssetPath(assetPath) {
 import fs3 from "fs";
 import path3 from "path";
 function copyLocalAssetToAsoDir(assetPath, outputPath) {
+  const publicDir = getPublicDir();
   const trimmedPath = assetPath.replace(/^\.\//, "").replace(/^public\//, "").replace(/^\/+/, "");
-  const sourcePath = path3.join(process.cwd(), "public", trimmedPath);
+  const sourcePath = path3.join(publicDir, trimmedPath);
   if (!fs3.existsSync(sourcePath)) {
     console.warn(`\u26A0\uFE0F  Local image not found: ${sourcePath}`);
     return false;
@@ -501,6 +508,7 @@ function convertToMultilingual(data, locale) {
 }
 
 // src/tools/public-to-aso.ts
+import fs4 from "fs";
 var FIELD_LIMITS_DOC_PATH = "docs/aso/ASO_FIELD_LIMITS.md";
 var toJsonSchema2 = zodToJsonSchema2;
 var publicToAsoInputSchema = z2.object({
@@ -514,14 +522,8 @@ var jsonSchema2 = toJsonSchema2(publicToAsoInputSchema, {
 });
 var inputSchema2 = jsonSchema2.definitions?.PublicToAsoInput || jsonSchema2;
 async function downloadScreenshotsToAsoDir(slug, asoData, options) {
-  const rootDir = options?.rootDir ?? ".aso/pushData";
-  const productStoreRoot = path4.join(
-    process.cwd(),
-    rootDir,
-    "products",
-    slug,
-    "store"
-  );
+  const rootDir = options?.rootDir ?? getPushDataDir();
+  const productStoreRoot = path4.join(rootDir, "products", slug, "store");
   if (asoData.googlePlay) {
     let googlePlayData = asoData.googlePlay;
     if (!isGooglePlayMultilingual(googlePlayData)) {
@@ -654,15 +656,15 @@ async function downloadScreenshotsToAsoDir(slug, asoData, options) {
 }
 var publicToAsoTool = {
   name: "public-to-aso",
-  description: `Prepares ASO data from public/products/[slug]/ to .aso/pushData format.
+  description: `Prepares ASO data from public/products/[slug]/ to pushData format.
 
 **IMPORTANT:** The 'slug' parameter is REQUIRED. If the user does not provide a slug, you MUST ask them to provide it. This tool processes only ONE product at a time.
 
 This tool:
 1. Loads ASO data from public/products/[slug]/config.json + locales/
 2. Converts to store-compatible format (removes screenshots from metadata, sets contactWebsite/marketingUrl)
-3. Saves metadata to .aso/pushData/products/[slug]/store/
-4. Copies/downloads screenshots to .aso/pushData/products/[slug]/store/screenshots/
+3. Saves metadata to pushData/products/[slug]/store/ (path from ~/.config/pabal-mcp/config.json dataDir)
+4. Copies/downloads screenshots to pushData/products/[slug]/store/screenshots/
 
 Before running, review ${FIELD_LIMITS_DOC_PATH} for per-store limits. This prepares data for pushing to stores without actually uploading.`,
   inputSchema: inputSchema2
@@ -671,15 +673,94 @@ async function handlePublicToAso(input) {
   const { slug, dryRun } = input;
   const configData = loadAsoFromConfig(slug);
   if (!configData.googlePlay && !configData.appStore) {
-    throw new Error(`No ASO data found in config.json + locales/ for ${slug}`);
+    const productsDir = getProductsDir();
+    const configPath = path4.join(productsDir, slug, "config.json");
+    const localesDir = path4.join(productsDir, slug, "locales");
+    const errors = [];
+    if (!fs4.existsSync(configPath)) {
+      errors.push(`- config.json not found at ${configPath}`);
+    } else {
+      try {
+        const config = JSON.parse(fs4.readFileSync(configPath, "utf-8"));
+        if (!config.packageName && !config.bundleId) {
+          errors.push(
+            `- config.json exists but missing both packageName and bundleId`
+          );
+        } else {
+          if (config.packageName) {
+            errors.push(`- packageName found: ${config.packageName}`);
+          }
+          if (config.bundleId) {
+            errors.push(`- bundleId found: ${config.bundleId}`);
+          }
+        }
+      } catch (e) {
+        errors.push(
+          `- Failed to parse config.json: ${e instanceof Error ? e.message : String(e)}`
+        );
+      }
+    }
+    if (!fs4.existsSync(localesDir)) {
+      errors.push(`- locales directory not found at ${localesDir}`);
+    } else {
+      try {
+        const localeFiles = fs4.readdirSync(localesDir).filter((f) => f.endsWith(".json"));
+        if (localeFiles.length === 0) {
+          errors.push(`- locales directory exists but no .json files found`);
+        } else {
+          errors.push(
+            `- Found ${localeFiles.length} locale file(s): ${localeFiles.join(
+              ", "
+            )}`
+          );
+          const validLocales = [];
+          const invalidLocales = [];
+          for (const file of localeFiles) {
+            const localeCode = file.replace(".json", "");
+            if (isGooglePlayLocale(localeCode) || isAppStoreLocale(localeCode)) {
+              validLocales.push(localeCode);
+            } else {
+              invalidLocales.push(localeCode);
+            }
+          }
+          if (validLocales.length > 0) {
+            errors.push(`- Valid locales: ${validLocales.join(", ")}`);
+          }
+          if (invalidLocales.length > 0) {
+            errors.push(
+              `- Invalid locales (not supported by Google Play or App Store): ${invalidLocales.join(
+                ", "
+              )}`
+            );
+          }
+        }
+      } catch (e) {
+        errors.push(
+          `- Failed to read locales directory: ${e instanceof Error ? e.message : String(e)}`
+        );
+      }
+    }
+    throw new Error(
+      `No ASO data found in config.json + locales/ for ${slug}
+
+Diagnostics:
+${errors.join("\n")}
+
+Possible causes:
+1. config.json is missing packageName (for Google Play) or bundleId (for App Store)
+2. locales/ directory is missing or empty
+3. Locale files exist but don't match supported Google Play/App Store locales
+4. Locale files don't contain valid ASO data`
+    );
   }
   const storeData = prepareAsoDataForPush(slug, configData);
+  const pushDataRoot = getPushDataDir();
   if (dryRun) {
     return {
       content: [
         {
           type: "text",
-          text: `Preview mode - Data that would be saved to .aso/pushData:
+          text: `Preview mode - Data that would be saved to ${pushDataRoot}:
 
 ${JSON.stringify(
             storeData,
@@ -690,7 +771,6 @@ ${JSON.stringify(
       ]
     };
   }
-  const pushDataRoot = ".aso/pushData";
   saveRawAsoData(slug, storeData, { rootDir: pushDataRoot });
   await downloadScreenshotsToAsoDir(slug, configData, {
     rootDir: pushDataRoot
@@ -708,7 +788,7 @@ ${JSON.stringify(
     const locales = isAppStoreMultilingual(appStoreData) ? appStoreData.locales : { [appStoreData.locale || DEFAULT_LOCALE]: appStoreData };
     localeCounts.appStore = Object.keys(locales).length;
   }
-  let responseText = `\u2705 ${slug} .aso/pushData files prepared from config.json + locales/ (images + metadata synced)
+  let responseText = `\u2705 ${slug} pushData files prepared from config.json + locales/ (images + metadata synced)
 
 `;
   if (localeCounts.googlePlay) {
@@ -738,29 +818,30 @@ import { z as z3 } from "zod";
 import { zodToJsonSchema as zodToJsonSchema3 } from "zod-to-json-schema";
 
 // src/tools/utils/improve-public/load-product-locales.util.ts
-import fs4 from "fs";
+import fs5 from "fs";
 import path5 from "path";
 function loadProductLocales(slug) {
-  const productDir = path5.join(process.cwd(), "public", "products", slug);
+  const productsDir = getProductsDir();
+  const productDir = path5.join(productsDir, slug);
   const configPath = path5.join(productDir, "config.json");
   const localesDir = path5.join(productDir, "locales");
   let config = null;
-  if (fs4.existsSync(configPath)) {
-    const raw = fs4.readFileSync(configPath, "utf-8");
+  if (fs5.existsSync(configPath)) {
+    const raw = fs5.readFileSync(configPath, "utf-8");
     config = JSON.parse(raw);
   }
-  if (!fs4.existsSync(localesDir)) {
+  if (!fs5.existsSync(localesDir)) {
     throw new Error(`No locales directory found for ${slug}`);
   }
   const locales = {};
-  const localeFiles = fs4.readdirSync(localesDir).filter((file) => file.endsWith(".json"));
+  const localeFiles = fs5.readdirSync(localesDir).filter((file) => file.endsWith(".json"));
   if (localeFiles.length === 0) {
     throw new Error(`No locale files found for ${slug}`);
   }
   for (const file of localeFiles) {
     const localeCode = file.replace(".json", "");
     const localePath = path5.join(localesDir, file);
-    const content = fs4.readFileSync(localePath, "utf-8");
+    const content = fs5.readFileSync(localePath, "utf-8");
     locales[localeCode] = JSON.parse(content);
   }
   return { config, locales };
@@ -1701,17 +1782,17 @@ async function handleImprovePublic(input) {
 }
 
 // src/tools/init-project.ts
-import fs5 from "fs";
+import fs6 from "fs";
 import path6 from "path";
 import { z as z4 } from "zod";
 import { zodToJsonSchema as zodToJsonSchema4 } from "zod-to-json-schema";
 var listSlugDirs = (dir) => {
-  if (!fs5.existsSync(dir)) return [];
-  return fs5.readdirSync(dir, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
+  if (!fs6.existsSync(dir)) return [];
+  return fs6.readdirSync(dir, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
 };
 var initProjectInputSchema = z4.object({
   slug: z4.string().trim().optional().describe(
-    "Optional product slug to focus on. Defaults to all slugs in .aso/pullData/products/"
+    "Optional product slug to focus on. Defaults to all slugs in pullData/products/"
   )
 });
 var jsonSchema4 = zodToJsonSchema4(initProjectInputSchema, {
@@ -1727,14 +1808,14 @@ var initProjectTool = {
 This tool is read-only and returns a checklist. It does not call pabal-mcp directly or write files.
 
 Steps:
-1) Ensure pabal-mcp 'init' ran and .aso/pullData/products/[slug]/ exists
+1) Ensure pabal-mcp 'init' ran and pullData/products/[slug]/ exists (path from ~/.config/pabal-mcp/config.json dataDir)
 2) Convert pulled ASO data -> public/products/[slug]/ using pabal-web-mcp tools (aso-to-public, public-to-aso dry run)
 3) Validate outputs and next actions`,
   inputSchema: inputSchema4
 };
 async function handleInitProject(input) {
-  const pullDataDir = path6.join(process.cwd(), ".aso", "pullData", "products");
-  const publicDir = path6.join(process.cwd(), "public", "products");
+  const pullDataDir = path6.join(getPullDataDir(), "products");
+  const publicDir = getProductsDir();
   const pullDataSlugs = listSlugDirs(pullDataDir);
   const publicSlugs = listSlugDirs(publicDir);
   const targetSlugs = input.slug?.length && input.slug.trim().length > 0 ? [input.slug.trim()] : pullDataSlugs.length > 0 ? pullDataSlugs : publicSlugs;
@@ -1752,7 +1833,7 @@ async function handleInitProject(input) {
   lines.push("");
   if (targetSlugs.length === 0) {
     lines.push(
-      "No products detected. Run pabal-mcp 'init' for your slug(s) to populate .aso/pullData/products/, then rerun this tool."
+      "No products detected. Run pabal-mcp 'init' for your slug(s) to populate pullData/products/, then rerun this tool."
     );
     return {
       content: [
@@ -1790,7 +1871,7 @@ async function handleInitProject(input) {
   lines.push("");
   lines.push("Step 3: Verify and prepare for push (optional)");
   lines.push(
-    "Use pabal-web-mcp 'public-to-aso' with dryRun=true to validate structure and build .aso/pushData before uploading via store tooling."
+    "Use pabal-web-mcp 'public-to-aso' with dryRun=true to validate structure and build pushData before uploading via store tooling."
   );
   lines.push("");
   lines.push("Notes:");