pabal-web-mcp 0.1.0 → 0.1.1

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,6 +2,10 @@
 import {
   DEFAULT_LOCALE,
   appStoreToUnified,
+  getProductsDir,
+  getPublicDir,
+  getPullDataDir,
+  getPushDataDir,
   googlePlayToUnified,
   isAppStoreMultilingual,
   isGooglePlayMultilingual,
@@ -9,7 +13,7 @@ import {
   saveAsoToAsoDir,
   unifiedToAppStore,
   unifiedToGooglePlay
-} from "../chunk-YJWGBO7W.js";
+} from "../chunk-MWXNTV3M.js";
 
 // src/bin/mcp-server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -28,10 +32,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 +53,7 @@ function loadPullData(slug) {
     }
   }
   const appStorePath = path.join(
-    process.cwd(),
-    ".aso",
-    "pullData",
+    pullDataDir,
     "products",
     slug,
     "store",
@@ -202,14 +203,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 +219,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 +271,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 +281,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 +306,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 +326,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 +417,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 +479,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;
@@ -514,9 +519,8 @@ var jsonSchema2 = toJsonSchema2(publicToAsoInputSchema, {
 });
 var inputSchema2 = jsonSchema2.definitions?.PublicToAsoInput || jsonSchema2;
 async function downloadScreenshotsToAsoDir(slug, asoData, options) {
-  const rootDir = options?.rootDir ?? ".aso/pushData";
+  const rootDir = options?.rootDir ?? getPushDataDir();
   const productStoreRoot = path4.join(
-    process.cwd(),
     rootDir,
     "products",
     slug,
@@ -654,15 +658,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
@@ -674,12 +678,13 @@ async function handlePublicToAso(input) {
     throw new Error(`No ASO data found in config.json + locales/ for ${slug}`);
   }
   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 +695,6 @@ ${JSON.stringify(
       ]
     };
   }
-  const pushDataRoot = ".aso/pushData";
   saveRawAsoData(slug, storeData, { rootDir: pushDataRoot });
   await downloadScreenshotsToAsoDir(slug, configData, {
     rootDir: pushDataRoot
@@ -708,7 +712,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) {
@@ -741,7 +745,8 @@ import { zodToJsonSchema as zodToJsonSchema3 } from "zod-to-json-schema";
 import fs4 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;
@@ -1711,7 +1716,7 @@ var listSlugDirs = (dir) => {
 };
 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 +1732,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 +1757,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 +1795,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:");