listingbureau-mcp 0.1.6 → 0.1.8

package/README.md

@@ -8,9 +8,9 @@
 
 Organic ranking campaigns for Amazon products, managed through your AI assistant.
 
-The only ranking-focused Amazon MCP server. Create ranking campaigns, set velocity schedules, track keyword positions, and monitor rank movement from Claude, Cursor, or any MCP-compatible client.
+The only ranking-focused Amazon MCP server. Create ranking campaigns, set campaign schedules, track keyword positions, and monitor rank movement from Claude, Cursor, or any MCP-compatible client.
 
-Built on the same infrastructure that moved 1,700+ products to page one. Median time: 48 days.
+Built on the same infrastructure associated with 1,700+ products reaching page one. Median time: 48 days. Past performance does not predict future results.
 
 <p align="center">
   <img src="assets/demo.gif" alt="listingbureau-mcp demo" width="800" />
@@ -35,10 +35,10 @@ Built on the same infrastructure that moved 1,700+ products to page one. Median
 This MCP server connects your AI assistant to [Listing Bureau](https://listingbureau.com/mcp?utm_source=github&utm_medium=readme&utm_campaign=mcp)'s Amazon ranking infrastructure. Three signal types drive organic rank improvement:
 
 - **Search-Find-Buy (SFB)** signals the A10 algorithm that real shoppers searched for a keyword, found the product, and purchased it
-- **Add-to-Cart (ATC)** builds conversion velocity and purchase intent signals
+- **Add-to-Cart (ATC)** builds conversion intent and purchase intent signals
 - **Page Views (PGV)** generate session-level browsing behavior that supports organic discovery
 
-Your assistant handles the entire workflow: create a project for any ASIN and keyword, set a daily velocity schedule, estimate costs before committing, and pull position reports to track movement.
+Your assistant handles the entire workflow: create a project for any ASIN and keyword, set a daily campaign schedule, estimate costs before committing, and pull position reports to track movement.
 
 ## 📦 Quick start
 
@@ -164,7 +164,7 @@ Create an account at [listingbureau.com](https://listingbureau.com/mcp?utm_sourc
 
 | Tool | Description |
 |------|-------------|
-| `lb_feedback_submit` | Submit feedback (10-5000 characters) |
+| `lb_feedback_submit` | Submit feedback, feature requests, or suggestions (10-5000 characters) |
 
 ## 🛠️ Development
 

package/dist/index.js

@@ -33,6 +33,22 @@ const client = new LBClient(apiKey, baseUrl);
 const server = new McpServer({
     name: "listingbureau",
     version: pkg.version,
+}, {
+    instructions: [
+        "Listing Bureau provides Amazon organic ranking services: SFB (Search Find Buy), ATC (Add to Cart), and PGV (page views).",
+        "SFB drives purchases that directly boost organic ranking. ATC and PGV support the funnel but alone rarely move ranking unless the keyword is very uncompetitive.",
+        "When a user schedules only ATC/PGV with no SFB, note that these are typically paired with SFB to maintain a healthy conversion ratio.",
+        "",
+        "When advising on service volumes, aim for a natural Amazon funnel with realistic conversion rates (10-15%). These are starting points — adjust based on the user's product, price point, and keyword competitiveness:",
+        "Default ratio per SFB: ~2 ATC, ~8-10 PGV.",
+        "Cheaper/high-intent keywords (e.g. branded): ~1-1.5 ATC, ~5-7 PGV per SFB.",
+        "Expensive/competitive keywords: ~2-3 ATC, ~10-15 PGV per SFB to reflect more browsing.",
+        "Avoid SFB-only schedules with near-100% conversion. Keep ratios consistent per keyword so traffic looks like natural shopper behavior.",
+        "",
+        "When the user asks about something outside current capabilities (other marketplaces, unsupported features), offer to submit their input as feedback via lb_feedback_submit.",
+        "",
+        "SFB units are real Amazon purchases of the user's product. The retail price in the SFB cost is not a net expense — the seller receives it back as normal Amazon sale proceeds. The actual out-of-pocket cost per SFB is the service fee plus the 11% tax/transfer overhead on the retail price.",
+    ].join("\n"),
 });
 registerAccountTools(server, client);
 registerWalletTools(server, client);

package/dist/tools/cost.tools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { sfbUnitCost, estimateCost, round2 } from "../utils/cost.js";
 import { formatResult, formatErrorResult } from "../utils/response.js";
+import { ACCEPTED_REGIONS, normalizeRegion, assertSfbAllowed } from "../utils/regions.js";
 const scheduleItemSchema = z.object({
     date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format").describe("Date in YYYY-MM-DD format"),
     atc: z.number().int().min(0).optional().describe("Add-to-cart volume (default 0)"),
@@ -8,9 +9,13 @@ const scheduleItemSchema = z.object({
     pgv: z.number().int().min(0).optional().describe("Page view volume (default 0)"),
 });
 const estimateCostShape = {
-    atc: z.number().int().min(0).optional().describe("Uniform daily add-to-cart volume"),
-    sfb: z.number().int().min(0).optional().describe("Uniform daily Search Find Buy (SFB) volume"),
-    pgv: z.number().int().min(0).optional().describe("Uniform daily page view volume"),
+    region: z
+        .enum(ACCEPTED_REGIONS)
+        .optional()
+        .describe("Amazon region code — if provided with SFB volumes, validates SFB is allowed (US only). GB accepted as alias for UK."),
+    atc: z.number().int().min(0).optional().describe("Uniform daily add-to-cart volume (all regions; lower execution rate outside US)"),
+    sfb: z.number().int().min(0).optional().describe("Uniform daily Search Find Buy (SFB) volume (US-region projects only)"),
+    pgv: z.number().int().min(0).optional().describe("Uniform daily page view volume (all regions; lower execution rate outside US)"),
     num_days: z.number().int().min(1).max(365).optional().describe("Number of days for uniform volumes"),
     schedule: z
         .array(scheduleItemSchema)
@@ -25,7 +30,7 @@ const estimateCostShape = {
         .describe("Product retail price in USD — needed for accurate SFB cost including product price and fees"),
 };
 export function registerCostTools(server, client) {
-    server.tool("lb_estimate_cost", "Estimate campaign cost before committing. Fetches current rates and wallet balance, then computes total cost, daily averages, and wallet sustainability. Provide either uniform daily volumes (atc/sfb/pgv + num_days) or a per-day schedule array. Include retail_price for accurate SFB costs.", estimateCostShape, { readOnlyHint: true }, async (params) => {
+    server.tool("lb_estimate_cost", "Estimate campaign cost before committing. Fetches current rates and wallet balance, then computes total cost, daily averages, and wallet sustainability. Provide either uniform daily volumes (atc/sfb/pgv + num_days) or a per-day schedule array. Include retail_price for accurate SFB costs. SFB is US-region only; ATC/PGV work in all regions (lower execution rate outside US). Pass region to validate SFB eligibility.", estimateCostShape, { readOnlyHint: true }, async (params) => {
         try {
             // Validate: either schedule array, or (volumes + num_days)
             const hasSchedule = params.schedule && params.schedule.length > 0;
@@ -33,6 +38,16 @@ export function registerCostTools(server, client) {
             if (!hasSchedule && !(hasVolume && params.num_days != null)) {
                 return formatErrorResult(new Error("Provide either a 'schedule' array, OR at least one volume (atc/sfb/pgv > 0) with 'num_days'"));
             }
+            // Normalize region once for all downstream use
+            const normalizedRegion = params.region ? normalizeRegion(params.region) : undefined;
+            // SFB region validation
+            const hasSfbInput = params.schedule
+                ? params.schedule.some((d) => (d.sfb ?? 0) > 0)
+                : (params.sfb ?? 0) > 0;
+            if (normalizedRegion) {
+                // Hard reject: region provided + non-US + has SFB
+                assertSfbAllowed(normalizedRegion, hasSfbInput);
+            }
             const [ratesRes, walletRes] = await Promise.all([
                 client.request("GET", "/api/v1/account/service-rates", undefined, undefined, "lb_estimate_cost"),
                 client.request("GET", "/api/v1/wallet", undefined, undefined, "lb_estimate_cost"),
@@ -72,8 +87,12 @@ export function registerCostTools(server, client) {
             if (hasSchedule && (hasVolume || params.num_days != null)) {
                 warnings.push("schedule array provided — num_days and uniform volumes (atc/sfb/pgv) were ignored.");
             }
-            // SFB without retail_price warning (0 is effectively the same as omitting)
+            // SFB without region warning
             const hasSfb = schedule.some((d) => d.sfb > 0);
+            if (hasSfb && !params.region) {
+                warnings.push("SFB volumes provided without region — estimate assumes US pricing. Pass region to validate SFB eligibility.");
+            }
+            // SFB without retail_price warning (0 is effectively the same as omitting)
             if (hasSfb && (params.retail_price == null || params.retail_price === 0)) {
                 warnings.push("SFB volumes provided without retail_price — estimate uses service fee only ($" +
                     rates.sfb_service_fee.toFixed(2) +

package/dist/tools/feedback.tools.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formatResult, formatErrorResult } from "../utils/response.js";
 export function registerFeedbackTools(server, client) {
-    server.tool("lb_feedback_submit", "Submit feedback about the Listing Bureau service (10-5000 characters).", {
+    server.tool("lb_feedback_submit", "Submit feedback, feature requests, or suggestions (10-5000 characters)", {
         feedback: z
             .string()
             .min(10)

package/dist/tools/projects.tools.js

@@ -1,25 +1,18 @@
 import { z } from "zod";
 import { formatResult, formatErrorResult } from "../utils/response.js";
-// Valid Amazon region codes (validated against CONSTANTS['MARKETPLACES'] in backend)
-const VALID_REGIONS = [
-    "US", "CA", "MX", // Americas
-    "UK", "DE", "FR", "IT", // Europe
-    "ES", "NL", "SE", "TR", // Europe cont.
-    "JP", "AU", "IN", // Asia-Pacific
-    "AE", "BR", "SG", "SA", // Rest of world
-];
+import { ACCEPTED_REGIONS, normalizeRegion } from "../utils/regions.js";
 export function registerProjectsTools(server, client) {
     server.tool("lb_projects_list", "List Listing Bureau Amazon projects with optional filters. Returns ASIN, keyword, active status, and current service volumes.", {
         region: z
-            .enum(VALID_REGIONS)
+            .enum(ACCEPTED_REGIONS)
             .optional()
-            .describe("Filter by Amazon region"),
+            .describe("Filter by Amazon region code (GB accepted as alias for UK)"),
         active: z.boolean().optional().describe("Filter by active status"),
     }, { readOnlyHint: true }, async (params) => {
         try {
             const query = { marketplace: "amazon" };
             if (params.region !== undefined)
-                query.region = params.region;
+                query.region = normalizeRegion(params.region);
             if (params.active !== undefined)
                 query.active = String(params.active);
             const res = await client.request("GET", "/api/v1/projects", undefined, query, "lb_projects_list");
@@ -31,8 +24,8 @@ export function registerProjectsTools(server, client) {
     });
     server.tool("lb_projects_create", "Create a new Listing Bureau Amazon project. If a project with the same ASIN+keyword+region was previously archived, it will be reactivated instead (returns 201). ASIN must be a valid Amazon ASIN. Keyword must be 3-200 characters.", {
         region: z
-            .enum(VALID_REGIONS)
-            .describe("Amazon region code"),
+            .enum(ACCEPTED_REGIONS)
+            .describe("Amazon region code (GB accepted as alias for UK)"),
         asin: z
             .string()
             .describe("Amazon ASIN (e.g. 'B01MTJK06C')"),
@@ -50,7 +43,7 @@ export function registerProjectsTools(server, client) {
         try {
             const body = {
                 marketplace: "amazon",
-                region: params.region,
+                region: normalizeRegion(params.region),
                 asin: params.asin,
                 keyword: params.keyword,
             };

package/dist/tools/schedule.tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatResult, formatErrorResult } from "../utils/response.js";
+import { assertSfbAllowed, SfbRegionError } from "../utils/regions.js";
 import { sfbUnitCost, estimateCost, mapScheduleEntries, round2 } from "../utils/cost.js";
 // Write schema: only YYYY-MM-DD dates (backend manages 'ongoing' entries internally)
 const scheduleEntrySchema = z.object({
@@ -7,9 +8,9 @@ const scheduleEntrySchema = z.object({
         .string()
         .regex(/^\d{4}-\d{2}-\d{2}$/, "Must be YYYY-MM-DD format")
         .describe("Date in YYYY-MM-DD format"),
-    atc: z.number().int().min(0).describe("Add-to-cart volume"),
-    sfb: z.number().int().min(0).describe("Search Find Buy (SFB) volume"),
-    pgv: z.number().int().min(0).describe("Page view volume"),
+    atc: z.number().int().min(0).describe("Add-to-cart volume (all regions; lower execution rate outside US)"),
+    sfb: z.number().int().min(0).describe("Search Find Buy (SFB) volume (US-region projects only)"),
+    pgv: z.number().int().min(0).describe("Page view volume (all regions; lower execution rate outside US)"),
 });
 /**
  * Best-effort: fetch rates and compute cost summary for a schedule response.
@@ -25,7 +26,8 @@ async function appendCostSummary(data, client) {
         if (dated.length === 0 && !ongoing)
             return result;
         const sfbNote = "SFB costs use service fee only ($" + rates.sfb_service_fee.toFixed(2) +
-            "), matching backend balance check behavior. Use lb_estimate_cost with retail_price for full SFB cost.";
+            "), matching backend balance check behavior. Use lb_estimate_cost with retail_price for full SFB cost." +
+            " Note: the retail price portion is not a net expense — it returns as Amazon sale proceeds.";
         if (dated.length > 0 && ongoing) {
             // Mixed: dated entries + ongoing
             const est = estimateCost(dated, rates);
@@ -99,7 +101,7 @@ async function appendCostSummary(data, client) {
     return result;
 }
 export function registerScheduleTools(server, client) {
-    server.tool("lb_schedule_get", "Get the current schedule for a Listing Bureau project. Shows per-day service volumes (atc, sfb, pgv).", {
+    server.tool("lb_schedule_get", "Get the current schedule for a Listing Bureau project. Shows per-day service volumes (atc, sfb, pgv). Note: SFB is only available for US-region projects.", {
         ui_id: z.string().describe("Project unique identifier"),
     }, { readOnlyHint: true }, async (params) => {
         try {
@@ -111,7 +113,7 @@ export function registerScheduleTools(server, client) {
             return formatErrorResult(e);
         }
     });
-    server.tool("lb_schedule_set", "Set the full per-day schedule for a Listing Bureau project. Replaces any existing schedule. Each entry represents one day with volumes for atc, sfb, and pgv. Max 365 entries.", {
+    server.tool("lb_schedule_set", "Set the full per-day schedule for a Listing Bureau project. Replaces any existing schedule. Each entry represents one day with volumes for atc, sfb, and pgv. Max 365 entries. SFB is US-region only; ATC/PGV work in all regions (lower execution rate outside US).", {
         ui_id: z.string().describe("Project unique identifier"),
         schedule: z
             .array(scheduleEntrySchema)
@@ -120,21 +122,64 @@ export function registerScheduleTools(server, client) {
             .describe("Array of daily schedule entries"),
     }, { destructiveHint: true, idempotentHint: true }, async (params) => {
         try {
+            // SFB region gate: only fetch project when schedule contains SFB > 0
+            let regionWarning;
+            if (params.schedule.some((e) => e.sfb > 0)) {
+                try {
+                    const projRes = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`, undefined, undefined, "lb_schedule_set");
+                    assertSfbAllowed(projRes.data.region, true);
+                }
+                catch (fetchErr) {
+                    // If assertSfbAllowed threw, re-throw (it's a validation error, not a fetch failure)
+                    if (fetchErr instanceof SfbRegionError) {
+                        throw fetchErr;
+                    }
+                    // Fetch failure: warn and proceed — backend enforces the real restriction
+                    regionWarning = "Could not verify project region for SFB eligibility. The backend will enforce region restrictions.";
+                }
+            }
             const res = await client.request("PUT", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule`, { schedule: params.schedule }, undefined, "lb_schedule_set");
             const augmented = await appendCostSummary(res.data, client);
+            if (regionWarning) {
+                augmented.region_warning = regionWarning;
+            }
+            // Note when schedule has ATC/PGV but no SFB
+            const hasAtcOrPgv = params.schedule.some((e) => e.atc > 0 || e.pgv > 0);
+            const hasSfb = params.schedule.some((e) => e.sfb > 0);
+            if (hasAtcOrPgv && !hasSfb) {
+                augmented.service_note =
+                    "This schedule has ATC/PGV but no SFB. " +
+                        "These services alone rarely move ranking unless the keyword is very uncompetitive. " +
+                        "They're typically paired with SFB to maintain a healthy organic conversion ratio. " +
+                        "You can update the schedule to add SFB if needed.";
+            }
             return formatResult(augmented);
         }
         catch (e) {
             return formatErrorResult(e);
         }
     });
-    server.tool("lb_schedule_quick_set", "Quick-set uniform daily volumes for a Listing Bureau project. WARNING: This clears any existing per-day schedule and replaces it with uniform values. All omitted fields default to 0.", {
+    server.tool("lb_schedule_quick_set", "Quick-set uniform daily volumes for a Listing Bureau project. WARNING: This clears any existing per-day schedule and replaces it with uniform values. All omitted fields default to 0. SFB is US-region only; ATC/PGV work in all regions (lower execution rate outside US).", {
         ui_id: z.string().describe("Project unique identifier"),
-        atc: z.number().int().min(0).optional().describe("Add-to-cart volume per day (default 0)"),
-        sfb: z.number().int().min(0).optional().describe("Search Find Buy (SFB) volume per day (default 0)"),
-        pgv: z.number().int().min(0).optional().describe("Page view volume per day (default 0)"),
+        atc: z.number().int().min(0).optional().describe("Add-to-cart volume per day (default 0) (all regions; lower execution rate outside US)"),
+        sfb: z.number().int().min(0).optional().describe("Search Find Buy (SFB) volume per day (default 0) (US-region projects only)"),
+        pgv: z.number().int().min(0).optional().describe("Page view volume per day (default 0) (all regions; lower execution rate outside US)"),
     }, { destructiveHint: true, idempotentHint: true }, async (params) => {
         try {
+            // SFB region gate: only fetch project when SFB > 0
+            let regionWarning;
+            if ((params.sfb ?? 0) > 0) {
+                try {
+                    const projRes = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`, undefined, undefined, "lb_schedule_quick_set");
+                    assertSfbAllowed(projRes.data.region, true);
+                }
+                catch (fetchErr) {
+                    if (fetchErr instanceof SfbRegionError) {
+                        throw fetchErr;
+                    }
+                    regionWarning = "Could not verify project region for SFB eligibility. The backend will enforce region restrictions.";
+                }
+            }
             const body = {
                 atc: params.atc ?? 0,
                 sfb: params.sfb ?? 0,
@@ -142,6 +187,19 @@ export function registerScheduleTools(server, client) {
             };
             const res = await client.request("POST", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule/quick`, body, undefined, "lb_schedule_quick_set");
             const augmented = await appendCostSummary(res.data, client);
+            if (regionWarning) {
+                augmented.region_warning = regionWarning;
+            }
+            // Note when schedule has ATC/PGV but no SFB
+            const hasAtcOrPgv = (params.atc ?? 0) > 0 || (params.pgv ?? 0) > 0;
+            const hasSfb = (params.sfb ?? 0) > 0;
+            if (hasAtcOrPgv && !hasSfb) {
+                augmented.service_note =
+                    "This schedule has ATC/PGV but no SFB. " +
+                        "These services alone rarely move ranking unless the keyword is very uncompetitive. " +
+                        "They're typically paired with SFB to maintain a healthy organic conversion ratio. " +
+                        "You can update the schedule to add SFB if needed.";
+            }
             return formatResult(augmented);
         }
         catch (e) {

package/dist/utils/regions.d.ts

@@ -0,0 +1,24 @@
+/** Canonical 18 backend region codes (matches CONSTANTS['MARKETPLACES'] in Flask). */
+export declare const VALID_REGIONS: readonly ["US", "CA", "MX", "UK", "DE", "FR", "IT", "ES", "NL", "SE", "TR", "JP", "AU", "IN", "AE", "BR", "SG", "SA"];
+/**
+ * All accepted region codes for MCP tool input (19-element tuple).
+ * Includes GB as an alias for UK. Declared as a flat literal tuple
+ * because z.enum() requires a literal non-empty tuple type.
+ */
+export declare const ACCEPTED_REGIONS: readonly ["US", "CA", "MX", "UK", "DE", "FR", "IT", "ES", "NL", "SE", "TR", "JP", "AU", "IN", "AE", "BR", "SG", "SA", "GB"];
+/** Regions where SFB (Search Find Buy) is available. */
+export declare const SFB_REGIONS: Set<"US" | "CA" | "MX" | "UK" | "DE" | "FR" | "IT" | "ES" | "NL" | "SE" | "TR" | "JP" | "AU" | "IN" | "AE" | "BR" | "SG" | "SA">;
+/** Normalize user-supplied region code: GB -> UK, all others passthrough. */
+export declare function normalizeRegion(region: string): string;
+/** Typed error thrown by assertSfbAllowed for non-US SFB requests. */
+export declare class SfbRegionError extends Error {
+    constructor(region: string);
+}
+/**
+ * Assert that SFB is allowed for the given region.
+ * Throws SfbRegionError if the region is not in SFB_REGIONS.
+ *
+ * @param region - Canonical region code (already normalized)
+ * @param hasSfb - Whether the request includes SFB volumes > 0
+ */
+export declare function assertSfbAllowed(region: string, hasSfb: boolean): void;

package/dist/utils/regions.js

@@ -0,0 +1,47 @@
+// Centralized region constants and validation for Listing Bureau MCP tools.
+/** Canonical 18 backend region codes (matches CONSTANTS['MARKETPLACES'] in Flask). */
+export const VALID_REGIONS = [
+    "US", "CA", "MX", // Americas
+    "UK", "DE", "FR", "IT", // Europe
+    "ES", "NL", "SE", "TR", // Europe cont.
+    "JP", "AU", "IN", // Asia-Pacific
+    "AE", "BR", "SG", "SA", // Rest of world
+];
+/**
+ * All accepted region codes for MCP tool input (19-element tuple).
+ * Includes GB as an alias for UK. Declared as a flat literal tuple
+ * because z.enum() requires a literal non-empty tuple type.
+ */
+export const ACCEPTED_REGIONS = [
+    "US", "CA", "MX",
+    "UK", "DE", "FR", "IT",
+    "ES", "NL", "SE", "TR",
+    "JP", "AU", "IN",
+    "AE", "BR", "SG", "SA",
+    "GB",
+];
+/** Regions where SFB (Search Find Buy) is available. */
+export const SFB_REGIONS = new Set(["US"]);
+/** Normalize user-supplied region code: GB -> UK, all others passthrough. */
+export function normalizeRegion(region) {
+    return region === "GB" ? "UK" : region;
+}
+/** Typed error thrown by assertSfbAllowed for non-US SFB requests. */
+export class SfbRegionError extends Error {
+    constructor(region) {
+        super(`SFB (Search Find Buy) is only available for US-region projects. This project's region is ${region}. Remove SFB volumes or use a US-region project.`);
+        this.name = "SfbRegionError";
+    }
+}
+/**
+ * Assert that SFB is allowed for the given region.
+ * Throws SfbRegionError if the region is not in SFB_REGIONS.
+ *
+ * @param region - Canonical region code (already normalized)
+ * @param hasSfb - Whether the request includes SFB volumes > 0
+ */
+export function assertSfbAllowed(region, hasSfb) {
+    if (hasSfb && !SFB_REGIONS.has(region)) {
+        throw new SfbRegionError(region);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listingbureau-mcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Amazon organic ranking MCP server. Run ranking campaigns, track keyword positions, and monitor rank movement from any AI assistant.",
   "type": "module",
   "main": "dist/index.js",