listingbureau-mcp 0.1.5 → 0.1.7

package/README.md

@@ -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/client/lb-client.d.ts

@@ -30,6 +30,6 @@ export declare class LBClient {
      * Make an authenticated API request.
      * Retries once on 401 (token expired mid-request).
      */
-    request<T>(method: string, path: string, body?: Record<string, unknown>, query?: Record<string, string>): Promise<ApiSuccessResponse<T>>;
+    request<T>(method: string, path: string, body?: Record<string, unknown>, query?: Record<string, string>, toolName?: string): Promise<ApiSuccessResponse<T>>;
     private doRequest;
 }

package/dist/client/lb-client.js

@@ -153,14 +153,14 @@ export class LBClient {
      * Make an authenticated API request.
      * Retries once on 401 (token expired mid-request).
      */
-    async request(method, path, body, query) {
+    async request(method, path, body, query, toolName) {
         await this.ensureAuth();
-        const response = await this.doRequest(method, path, body, query);
+        const response = await this.doRequest(method, path, body, query, toolName);
         // Single retry on 401
         if (response.status === "error" && response._statusCode === 401) {
             this.jwt = null;
             await this.ensureAuth();
-            const retry = await this.doRequest(method, path, body, query);
+            const retry = await this.doRequest(method, path, body, query, toolName);
             if (retry.status === "error") {
                 throw new LBApiError(retry._statusCode ?? 500, retry.error.code, retry.error.message);
             }
@@ -171,7 +171,7 @@ export class LBClient {
         }
         return response;
     }
-    async doRequest(method, path, body, query) {
+    async doRequest(method, path, body, query, toolName) {
         let url = `${this.baseUrl}${path}`;
         if (query) {
             const params = new URLSearchParams(Object.entries(query).filter(([, v]) => v !== undefined && v !== ""));
@@ -181,6 +181,8 @@ export class LBClient {
         }
         const headers = {
             Authorization: `Bearer ${this.jwt.access_token}`,
+            "X-LB-Source": "mcp",
+            ...(toolName && { "X-LB-Tool": toolName }),
         };
         const options = { method, headers };
         if (body && method !== "GET") {

package/dist/index.js

@@ -10,6 +10,7 @@ import { registerOrdersTools } from "./tools/orders.tools.js";
 import { registerFeedbackTools } from "./tools/feedback.tools.js";
 import { registerCostTools } from "./tools/cost.tools.js";
 import { validateBaseUrl } from "./utils/validate-url.js";
+import { checkForUpdate } from "./utils/update-check.js";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -32,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);
@@ -42,3 +59,4 @@ registerFeedbackTools(server, client);
 registerCostTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);
+checkForUpdate(pkg.version).catch(() => { });

package/dist/tools/account.tools.js

@@ -4,8 +4,8 @@ export function registerAccountTools(server, client) {
     server.tool("lb_account_get", "Get Listing Bureau account info (email, name, account status, wallet balance)", {}, { readOnlyHint: true }, async () => {
         try {
             const [accountRes, walletRes] = await Promise.all([
-                client.request("GET", "/api/v1/account"),
-                client.request("GET", "/api/v1/wallet"),
+                client.request("GET", "/api/v1/account", undefined, undefined, "lb_account_get"),
+                client.request("GET", "/api/v1/wallet", undefined, undefined, "lb_account_get"),
             ]);
             const account = accountRes.data;
             const wallet = walletRes.data;
@@ -55,7 +55,7 @@ export function registerAccountTools(server, client) {
             if (Object.keys(body).length === 0) {
                 return formatErrorResult(new Error("At least one field (first_name, last_name, company) must be provided"));
             }
-            const res = await client.request("PATCH", "/api/v1/account/profile", body);
+            const res = await client.request("PATCH", "/api/v1/account/profile", body, undefined, "lb_account_update_profile");
             return formatResult(res.data);
         }
         catch (e) {
@@ -64,7 +64,7 @@ export function registerAccountTools(server, client) {
     });
     server.tool("lb_account_get_service_rates", "Get current Listing Bureau service pricing rates. Returns empty object if no plan is active.", {}, { readOnlyHint: true }, async () => {
         try {
-            const res = await client.request("GET", "/api/v1/account/service-rates");
+            const res = await client.request("GET", "/api/v1/account/service-rates", undefined, undefined, "lb_account_get_service_rates");
             return formatResult(res.data);
         }
         catch (e) {
@@ -73,7 +73,7 @@ export function registerAccountTools(server, client) {
     });
     server.tool("lb_account_get_subscription", "Get Listing Bureau subscription info (plan label, fee, discount, wallet usage)", {}, { readOnlyHint: true }, async () => {
         try {
-            const res = await client.request("GET", "/api/v1/account/subscription");
+            const res = await client.request("GET", "/api/v1/account/subscription", undefined, undefined, "lb_account_get_subscription");
             return formatResult(res.data);
         }
         catch (e) {

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,9 +38,19 @@ 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"),
-                client.request("GET", "/api/v1/wallet"),
+                client.request("GET", "/api/v1/account/service-rates", undefined, undefined, "lb_estimate_cost"),
+                client.request("GET", "/api/v1/wallet", undefined, undefined, "lb_estimate_cost"),
             ]);
             const rates = ratesRes.data;
             const wallet = walletRes.data;
@@ -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)
@@ -9,7 +9,7 @@ export function registerFeedbackTools(server, client) {
             .describe("Feedback text (10-5000 characters)"),
     }, { idempotentHint: false }, async (params) => {
         try {
-            const res = await client.request("POST", "/api/v1/feedback", { feedback: params.feedback });
+            const res = await client.request("POST", "/api/v1/feedback", { feedback: params.feedback }, undefined, "lb_feedback_submit");
             return formatResult(res.data);
         }
         catch (e) {

package/dist/tools/orders.tools.js

@@ -17,7 +17,7 @@ export function registerOrdersTools(server, client) {
                 query.page = String(params.page);
             if (params.per_page !== undefined)
                 query.per_page = String(params.per_page);
-            const res = await client.request("GET", "/api/v1/orders", undefined, query);
+            const res = await client.request("GET", "/api/v1/orders", undefined, query, "lb_orders_list");
             if (res.meta) {
                 return formatPaginatedResult(res.data, res.meta);
             }
@@ -31,7 +31,7 @@ export function registerOrdersTools(server, client) {
         order_id: z.string().describe("Order identifier"),
     }, { readOnlyHint: true }, async (params) => {
         try {
-            const res = await client.request("GET", `/api/v1/orders/${encodeURIComponent(params.order_id)}`);
+            const res = await client.request("GET", `/api/v1/orders/${encodeURIComponent(params.order_id)}`, undefined, undefined, "lb_orders_get");
             return formatResult(res.data);
         }
         catch (e) {
@@ -47,7 +47,7 @@ export function registerOrdersTools(server, client) {
             .describe("Issue description (1-1000 characters)"),
     }, { idempotentHint: false }, async (params) => {
         try {
-            const res = await client.request("POST", `/api/v1/orders/${encodeURIComponent(params.order_id)}/report-issue`, { description: params.description });
+            const res = await client.request("POST", `/api/v1/orders/${encodeURIComponent(params.order_id)}/report-issue`, { description: params.description }, undefined, "lb_orders_report_issue");
             return formatResult(res.data);
         }
         catch (e) {

package/dist/tools/projects.tools.js

@@ -1,28 +1,21 @@
 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);
+            const res = await client.request("GET", "/api/v1/projects", undefined, query, "lb_projects_list");
             return formatResult(res.data);
         }
         catch (e) {
@@ -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,14 +43,14 @@ export function registerProjectsTools(server, client) {
         try {
             const body = {
                 marketplace: "amazon",
-                region: params.region,
+                region: normalizeRegion(params.region),
                 asin: params.asin,
                 keyword: params.keyword,
             };
             if (params.expected_retail_price !== undefined) {
                 body.expected_retail_price = params.expected_retail_price;
             }
-            const res = await client.request("POST", "/api/v1/projects", body);
+            const res = await client.request("POST", "/api/v1/projects", body, undefined, "lb_projects_create");
             return formatResult(res.data);
         }
         catch (e) {
@@ -68,7 +61,7 @@ export function registerProjectsTools(server, client) {
         ui_id: z.string().describe("Project unique identifier"),
     }, { readOnlyHint: true }, async (params) => {
         try {
-            const res = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`);
+            const res = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`, undefined, undefined, "lb_projects_get");
             return formatResult(res.data);
         }
         catch (e) {
@@ -86,7 +79,7 @@ export function registerProjectsTools(server, client) {
             if (Object.keys(body).length === 0) {
                 return formatErrorResult(new Error("At least one field (active) must be provided"));
             }
-            const res = await client.request("PATCH", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`, body);
+            const res = await client.request("PATCH", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`, body, undefined, "lb_projects_update");
             return formatResult(res.data);
         }
         catch (e) {
@@ -97,7 +90,7 @@ export function registerProjectsTools(server, client) {
         ui_id: z.string().describe("Project unique identifier"),
     }, { destructiveHint: true }, async (params) => {
         try {
-            const res = await client.request("DELETE", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`);
+            const res = await client.request("DELETE", `/api/v1/projects/${encodeURIComponent(params.ui_id)}`, undefined, undefined, "lb_projects_archive");
             return formatResult(res.data);
         }
         catch (e) {
@@ -118,7 +111,7 @@ export function registerProjectsTools(server, client) {
             const query = {};
             if (params.days !== undefined)
                 query.days = String(params.days);
-            const res = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/stats`, undefined, query);
+            const res = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/stats`, undefined, query, "lb_projects_get_stats");
             return formatResult(res.data);
         }
         catch (e) {

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.
@@ -18,13 +19,15 @@ const scheduleEntrySchema = z.object({
 async function appendCostSummary(data, client) {
     const result = { ...data };
     try {
+        // Internal enrichment fetch — no tool attribution in audit log
         const ratesRes = await client.request("GET", "/api/v1/account/service-rates");
         const rates = ratesRes.data;
         const { dated, ongoing } = mapScheduleEntries(data.scheduling);
         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);
@@ -98,11 +101,11 @@ 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 {
-            const res = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule`);
+            const res = await client.request("GET", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule`, undefined, undefined, "lb_schedule_get");
             const augmented = await appendCostSummary(res.data, client);
             return formatResult(augmented);
         }
@@ -110,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)
@@ -119,28 +122,84 @@ export function registerScheduleTools(server, client) {
             .describe("Array of daily schedule entries"),
     }, { destructiveHint: true, idempotentHint: true }, async (params) => {
         try {
-            const res = await client.request("PUT", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule`, { schedule: params.schedule });
+            // 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,
                 pgv: params.pgv ?? 0,
             };
-            const res = await client.request("POST", `/api/v1/projects/${encodeURIComponent(params.ui_id)}/schedule/quick`, body);
+            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/tools/wallet.tools.js

@@ -3,7 +3,7 @@ import { formatResult, formatPaginatedResult, formatErrorResult, } from "../util
 export function registerWalletTools(server, client) {
     server.tool("lb_wallet_get_balance", "Get Listing Bureau wallet balance (credits and USD). May include a warning if data is temporarily unavailable.", {}, { readOnlyHint: true }, async () => {
         try {
-            const res = await client.request("GET", "/api/v1/wallet");
+            const res = await client.request("GET", "/api/v1/wallet", undefined, undefined, "lb_wallet_get_balance");
             return formatResult(res.data);
         }
         catch (e) {
@@ -26,7 +26,7 @@ export function registerWalletTools(server, client) {
                 query.page = String(params.page);
             if (params.per_page !== undefined)
                 query.per_page = String(params.per_page);
-            const res = await client.request("GET", "/api/v1/wallet/transactions", undefined, query);
+            const res = await client.request("GET", "/api/v1/wallet/transactions", undefined, query, "lb_wallet_get_transactions");
             if (res.meta) {
                 return formatPaginatedResult(res.data, res.meta);
             }
@@ -44,7 +44,7 @@ export function registerWalletTools(server, client) {
             .describe("Top-up amount in USD (minimum $5, maximum $5,000)"),
     }, { destructiveHint: true }, async (params) => {
         try {
-            const res = await client.request("POST", "/api/v1/wallet/topup", { amount: params.amount });
+            const res = await client.request("POST", "/api/v1/wallet/topup", { amount: params.amount }, undefined, "lb_wallet_topup");
             return formatResult(res.data);
         }
         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/dist/utils/response.js

@@ -1,4 +1,5 @@
 import { formatError } from "./errors.js";
+import { getUpdateNotice } from "./update-check.js";
 /**
  * Format a successful API response as an MCP tool result.
  * Handles both entity responses and message-only responses.
@@ -36,6 +37,10 @@ export function formatResult(data) {
     for (const w of warnings) {
         text += `\n\n⚠️ Warning: ${w}`;
     }
+    const notice = getUpdateNotice();
+    if (notice) {
+        text += `\n\n${notice}`;
+    }
     return {
         content: [{ type: "text", text }],
     };
@@ -49,8 +54,13 @@ export function formatPaginatedResult(data, meta) {
         data,
         pagination: meta,
     };
+    let text = JSON.stringify(result, null, 2);
+    const notice = getUpdateNotice();
+    if (notice) {
+        text += `\n\n${notice}`;
+    }
     return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        content: [{ type: "text", text }],
     };
 }
 /** Format an error as an MCP tool error result. */

package/dist/utils/update-check.d.ts

@@ -0,0 +1,8 @@
+/** Compare semver strings. Returns true only if latest > current. */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+/** Fire-and-forget npm registry check. Stores notice for later retrieval. */
+export declare function checkForUpdate(currentVersion: string): Promise<void>;
+/** Returns the update notice once, then null for all subsequent calls. */
+export declare function getUpdateNotice(): string | null;
+/** Reset state for testing. */
+export declare function resetForTesting(): void;

package/dist/utils/update-check.js

@@ -0,0 +1,61 @@
+// Module-level state — reset via resetForTesting() in test files.
+// Once noticeConsumed is true, subsequent checkForUpdate calls still overwrite
+// updateNotice but getUpdateNotice will return null. This is intentional:
+// the notice is designed to fire once per process lifetime.
+let updateNotice = null;
+let noticeConsumed = false;
+/** Compare semver strings. Returns true only if latest > current. */
+export function isNewerVersion(latest, current) {
+    const latestParts = latest.split(".").map(Number);
+    const currentParts = current.split(".").map(Number);
+    if (latestParts.length !== 3 || currentParts.length !== 3)
+        return false;
+    if (latestParts.some((n) => !Number.isFinite(n)) || currentParts.some((n) => !Number.isFinite(n)))
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (latestParts[i] > currentParts[i])
+            return true;
+        if (latestParts[i] < currentParts[i])
+            return false;
+    }
+    return false;
+}
+/** Fire-and-forget npm registry check. Stores notice for later retrieval. */
+export async function checkForUpdate(currentVersion) {
+    try {
+        const res = await fetch("https://registry.npmjs.org/listingbureau-mcp/latest", {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return;
+        const json = (await res.json());
+        const latest = json.version;
+        if (typeof latest !== "string" || !/^\d+\.\d+\.\d+$/.test(latest))
+            return;
+        if (isNewerVersion(latest, currentVersion)) {
+            updateNotice =
+                `📦 Update available: v${currentVersion} → v${latest}\n` +
+                    `To update:\n` +
+                    `  npm: npx listingbureau-mcp@latest (or npm update -g listingbureau-mcp)\n` +
+                    `  Desktop: Download from https://github.com/listingbureau/listingbureau-mcp/releases/latest`;
+        }
+    }
+    catch {
+        // Silent failure — network errors, TimeoutError, AbortError, bad JSON all swallowed
+    }
+}
+/** Returns the update notice once, then null for all subsequent calls. */
+export function getUpdateNotice() {
+    if (noticeConsumed)
+        return null;
+    if (updateNotice) {
+        noticeConsumed = true;
+        return updateNotice;
+    }
+    return null;
+}
+/** Reset state for testing. */
+export function resetForTesting() {
+    updateNotice = null;
+    noticeConsumed = false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listingbureau-mcp",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",