@lehaotech/walmart-mcp 0.5.4

package/build/utils/env-file.js

@@ -0,0 +1,27 @@
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+/**
+ * Insert or update `KEY=VALUE` pairs in a .env file, preserving the rest of
+ * the file. An existing (optionally commented-out) line for a key is replaced
+ * in place; otherwise the pair is appended.
+ *
+ * The replacement uses a *function* form of `String.prototype.replace` so that
+ * values containing `$` sequences (e.g. `$1`, `$&`, `$$`) are written literally
+ * instead of being interpreted as regex replacement patterns. Walmart access
+ * tokens and client secrets are opaque and can contain `$`, which would
+ * otherwise corrupt the persisted value and break authentication on restart.
+ */
+export function upsertEnvVars(updates, envPath = join(process.cwd(), '.env')) {
+    let content = existsSync(envPath) ? readFileSync(envPath, 'utf-8') : '';
+    for (const [key, value] of Object.entries(updates)) {
+        const regex = new RegExp(`^(#\\s*)?${key}=.*$`, 'gm');
+        const newLine = `${key}=${value}`;
+        if (regex.test(content)) {
+            content = content.replace(regex, () => newLine);
+        }
+        else {
+            content += `\n${newLine}`;
+        }
+    }
+    writeFileSync(envPath, content, 'utf-8');
+}

package/build/utils/known-issues.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Walmart known issues / hint lookup.
+ *
+ * When the marketplace API returns a 4xx/5xx for a documented "broken or
+ * deprecated endpoint", we attach a hint to the error response so the LLM can
+ * fall back without burning more tokens guessing. This file is the single
+ * source of truth — keep README.md "Known Issues" section aligned.
+ *
+ * Add an entry when:
+ *   - Walmart's endpoint is confirmed broken or removed (404/405/520).
+ *   - The endpoint requires a seller-program enrollment (Repricer / WFS / Ads)
+ *     and the failure pattern is consistent enough that a hint helps.
+ *   - There is a deterministic workaround a calling agent can apply.
+ *
+ * Do NOT add entries for:
+ *   - Transient infrastructure errors (those should retry, not steer).
+ *   - Per-call validation errors (those should be caught by zod, not here).
+ */
+export interface KnownIssue {
+    /** HTTP method, uppercase. */
+    method: string;
+    /** Regex against the request URL path (not host). */
+    pathPattern: RegExp;
+    /** What the LLM should do instead. Keep one sentence, actionable. */
+    hint: string;
+}
+export declare const KNOWN_ISSUES: ReadonlyArray<KnownIssue>;
+/** Returns the workaround hint for a known-broken endpoint, or undefined. */
+export declare function findKnownIssueHint(method: string | undefined, url: string | undefined): string | undefined;

package/build/utils/known-issues.js

@@ -0,0 +1,122 @@
+/**
+ * Walmart known issues / hint lookup.
+ *
+ * When the marketplace API returns a 4xx/5xx for a documented "broken or
+ * deprecated endpoint", we attach a hint to the error response so the LLM can
+ * fall back without burning more tokens guessing. This file is the single
+ * source of truth — keep README.md "Known Issues" section aligned.
+ *
+ * Add an entry when:
+ *   - Walmart's endpoint is confirmed broken or removed (404/405/520).
+ *   - The endpoint requires a seller-program enrollment (Repricer / WFS / Ads)
+ *     and the failure pattern is consistent enough that a hint helps.
+ *   - There is a deterministic workaround a calling agent can apply.
+ *
+ * Do NOT add entries for:
+ *   - Transient infrastructure errors (those should retry, not steer).
+ *   - Per-call validation errors (those should be caught by zod, not here).
+ */
+export const KNOWN_ISSUES = [
+    // ---------- Insights API ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/insights\/items\/unpublished\/counts/,
+        hint: "Walmart's Aurora unpublished-item-service has been returning 404 since 2026-05. " +
+            "Use walmart_get_all_items + filter publishedStatus='UNPUBLISHED' client-side.",
+    },
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/insights\/items\/listingQuality\/categories/,
+        hint: "Walmart removed this Insights aggregation endpoint. No direct replacement; use " +
+            "walmart_get_item_quality_details per SKU once that endpoint is restored, or fall back to " +
+            "walmart_get_listing_quality for the store-aggregate score.",
+    },
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/insights\/items\/listingQuality\/items/,
+        hint: "Walmart's documented endpoint signature changed; current implementation returns 405. " +
+            "Track via walmart_get_listing_quality (store-aggregate) until docs are updated.",
+    },
+    // ---------- Returns ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/returns\/count/,
+        hint: "Walmart removed /v3/returns/count. Compute client-side: walmart_get_all_returns then " +
+            "group by status.",
+    },
+    // ---------- Settings ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/settings\/shipping/,
+        hint: "Walmart's /v3/settings/shipping endpoint returns 404 for sellers without elevated access. " +
+            "No known public-API workaround — check Seller Center settings UI manually.",
+    },
+    // ---------- Items / Hazmat ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/items\/onhold\/hazmat/,
+        hint: "walmart_get_hazmat_items now uses POST /v3/items/onhold/search (fixed in v0.3.2). " +
+            "If a 405 still appears, the implementation may be calling the old GET path.",
+    },
+    // ---------- WFS Fulfillment program-gated ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/fulfillment\/inbound-shipments/,
+        hint: "WFS endpoints return 404 for sellers without Walmart Fulfillment Services enrollment. " +
+            "Enroll at https://seller.walmart.com/ → Walmart Fulfillment Services; otherwise this and " +
+            "all walmart_*_wfs_* / walmart_*_inbound_* / walmart_*_mcs_* tools will fail.",
+    },
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/fulfillment\/carriers/,
+        hint: "Ship-with-Walmart carriers endpoint requires Ship with Walmart enrollment. " +
+            "If your seller account is not enrolled, walmart_get_shipping_carriers, walmart_create_shipping_label, " +
+            "and walmart_get_shipping_estimate will all 404.",
+    },
+    // ---------- Repricer program-gated ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/repricer\/strategies/,
+        hint: "Walmart Repricer is opt-in; 403 means your account is not enrolled. Apply via Seller Center " +
+            "(Pro Seller badge usually required) before walmart_*_repricer_* tools will work.",
+    },
+    {
+        method: 'POST',
+        pathPattern: /\/v3\/repricer\/strategies/,
+        hint: "Walmart Repricer 403 means your account is not enrolled. Apply via Seller Center " +
+            "(Pro Seller badge required).",
+    },
+    // ---------- Notifications / Subscriptions ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/notifications\/subscriptions/,
+        hint: "Walmart Webhooks API requires explicit allowlisting per seller account. If you see 404, " +
+            "request access via Seller Support before relying on walmart_*_subscription tools.",
+    },
+    // ---------- Reports — async download ----------
+    {
+        method: 'GET',
+        pathPattern: /\/v3\/reports\/reportRequests\/.+\/download/,
+        hint: "Report download URLs are valid only after status=READY. If you get 404 or 410, the report " +
+            "may have expired (Walmart keeps reports ~30 days). Re-request via walmart_create_report.",
+    },
+    // ---------- Walmart Connect Ads — endpoint catch-all ----------
+    // The ad client uses a different base URL, so these patterns are advisory.
+    {
+        method: 'GET',
+        pathPattern: /\/api-proxy\/service\/WPA\/Api/,
+        hint: "Walmart Connect (Advertising) needs WALMART_AD_CONSUMER_ID + WALMART_AD_PRIVATE_KEY env " +
+            "vars. Apply for Walmart Connect at https://www.walmartconnect.com/ first.",
+    },
+];
+/** Returns the workaround hint for a known-broken endpoint, or undefined. */
+export function findKnownIssueHint(method, url) {
+    if (!method || !url)
+        return undefined;
+    const m = method.toUpperCase();
+    for (const issue of KNOWN_ISSUES) {
+        if (issue.method === m && issue.pathPattern.test(url))
+            return issue.hint;
+    }
+    return undefined;
+}

package/build/utils/logger.d.ts

@@ -0,0 +1,15 @@
+interface ComponentLogger {
+    error: (msg: string, meta?: object) => void;
+    warn: (msg: string, meta?: object) => void;
+    info: (msg: string, meta?: object) => void;
+    debug: (msg: string, meta?: object) => void;
+    http: (msg: string, meta?: object) => void;
+}
+export declare function createLogger(component: string): ComponentLogger;
+export declare const serverLogger: ComponentLogger;
+export declare const apiLogger: ComponentLogger;
+export declare const authLogger: ComponentLogger;
+export declare const toolLogger: ComponentLogger;
+export declare const feedLogger: ComponentLogger;
+export declare function truncateData(data: unknown, maxLen?: number): string;
+export {};

package/build/utils/logger.js

@@ -0,0 +1,56 @@
+import winston from 'winston';
+import { join } from 'path';
+import { homedir } from 'os';
+import { mkdirSync } from 'fs';
+const LOG_DIR = join(homedir(), '.walmart-mcp', 'logs');
+const LOG_LEVEL = process.env.WALMART_LOG_LEVEL || 'info';
+const ENABLE_FILE_LOGGING = process.env.WALMART_ENABLE_FILE_LOGGING === 'true';
+const consoleFormat = winston.format.combine(winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.printf(({ level, message, timestamp, ...meta }) => {
+    const metaStr = Object.keys(meta).length ? ` ${JSON.stringify(meta)}` : '';
+    return `[${timestamp}] [${level.toUpperCase()}] ${message}${metaStr}`;
+}));
+const transports = [
+    new winston.transports.Console({
+        format: consoleFormat,
+        stderrLevels: ['error', 'warn', 'info', 'http', 'verbose', 'debug', 'silly'],
+    }),
+];
+if (ENABLE_FILE_LOGGING) {
+    try {
+        mkdirSync(LOG_DIR, { recursive: true });
+    }
+    catch { /* ignore */ }
+    transports.push(new winston.transports.File({
+        filename: join(LOG_DIR, 'error.log'),
+        level: 'error',
+        maxsize: 5 * 1024 * 1024,
+        maxFiles: 5,
+    }), new winston.transports.File({
+        filename: join(LOG_DIR, 'combined.log'),
+        maxsize: 10 * 1024 * 1024,
+        maxFiles: 5,
+    }));
+}
+const logger = winston.createLogger({
+    level: LOG_LEVEL,
+    transports,
+    exitOnError: false,
+});
+export function createLogger(component) {
+    return {
+        error: (msg, meta) => logger.error(`[${component}] ${msg}`, meta),
+        warn: (msg, meta) => logger.warn(`[${component}] ${msg}`, meta),
+        info: (msg, meta) => logger.info(`[${component}] ${msg}`, meta),
+        debug: (msg, meta) => logger.debug(`[${component}] ${msg}`, meta),
+        http: (msg, meta) => logger.http(`[${component}] ${msg}`, meta),
+    };
+}
+export const serverLogger = createLogger('Server');
+export const apiLogger = createLogger('API');
+export const authLogger = createLogger('Auth');
+export const toolLogger = createLogger('Tool');
+export const feedLogger = createLogger('Feed');
+export function truncateData(data, maxLen = 1000) {
+    const str = typeof data === 'string' ? data : JSON.stringify(data);
+    return str.length > maxLen ? str.substring(0, maxLen) + '...[truncated]' : str;
+}

package/build/utils/rate-limiter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Sliding window rate limiter.
+ * Tracks requests in a time window and proactively blocks
+ * before hitting Walmart's API limits.
+ *
+ * Walmart Marketplace: ~20 requests/second (token bucket)
+ * Walmart Advertising: ~10 requests/second
+ */
+export declare class RateLimiter {
+    private maxRequests;
+    private windowMs;
+    private name;
+    private timestamps;
+    /** Latest x-current-token-count reported by Walmart (per-endpoint bucket). */
+    private latestServerTokens;
+    /** Latest x-next-replenish-time ISO 8601 string reported by Walmart. */
+    private latestReplenishTime;
+    /** When latestServerTokens was last updated (epoch ms). */
+    private latestServerSeenAt;
+    constructor(maxRequests: number, windowMs: number, name?: string);
+    /** Returns wait-time in ms (0 if allowed now). */
+    check(): number;
+    /** Synchronous acquire: throws if the request would exceed the limit. */
+    acquire(): void;
+    /** Async acquire: waits instead of throwing. */
+    acquireAsync(): Promise<void>;
+    /**
+     * Update from Walmart response headers. Caches the latest token count +
+     * replenish time so getStatus() can surface them via the
+     * walmart_get_rate_budget MCP tool.
+     */
+    updateFromHeaders(headers: Record<string, string>): void;
+    /** Snapshot for the rate-budget MCP tool. */
+    getStatus(): {
+        name: string;
+        localMaxRequests: number;
+        localWindowMs: number;
+        localCurrentCount: number;
+        localRemaining: number;
+        serverTokensRemaining: number | null;
+        serverReplenishTime: string | null;
+        serverTokensSeenAt: string | null;
+    };
+    private prune;
+    get currentCount(): number;
+    get remaining(): number;
+}
+export declare class RateLimitError extends Error {
+    waitMs: number;
+    constructor(message: string, waitMs: number);
+}

package/build/utils/rate-limiter.js

@@ -0,0 +1,109 @@
+import { apiLogger } from './logger.js';
+/**
+ * Sliding window rate limiter.
+ * Tracks requests in a time window and proactively blocks
+ * before hitting Walmart's API limits.
+ *
+ * Walmart Marketplace: ~20 requests/second (token bucket)
+ * Walmart Advertising: ~10 requests/second
+ */
+export class RateLimiter {
+    maxRequests;
+    windowMs;
+    name;
+    timestamps = [];
+    /** Latest x-current-token-count reported by Walmart (per-endpoint bucket). */
+    latestServerTokens = null;
+    /** Latest x-next-replenish-time ISO 8601 string reported by Walmart. */
+    latestReplenishTime = null;
+    /** When latestServerTokens was last updated (epoch ms). */
+    latestServerSeenAt = null;
+    constructor(maxRequests, windowMs, name = 'default') {
+        this.maxRequests = maxRequests;
+        this.windowMs = windowMs;
+        this.name = name;
+    }
+    /** Returns wait-time in ms (0 if allowed now). */
+    check() {
+        this.prune();
+        if (this.timestamps.length < this.maxRequests)
+            return 0;
+        const oldest = this.timestamps[0];
+        const waitMs = (oldest ?? Date.now()) + this.windowMs - Date.now();
+        return Math.max(0, waitMs);
+    }
+    /** Synchronous acquire: throws if the request would exceed the limit. */
+    acquire() {
+        const waitMs = this.check();
+        if (waitMs > 0) {
+            apiLogger.warn(`[RateLimiter:${this.name}] Rate limit reached (${this.maxRequests}/${this.windowMs}ms). Need to wait ${waitMs}ms.`);
+            throw new RateLimitError(`Rate limit reached for ${this.name}. Try again in ${Math.ceil(waitMs / 1000)} seconds.`, waitMs);
+        }
+        this.timestamps.push(Date.now());
+    }
+    /** Async acquire: waits instead of throwing. */
+    async acquireAsync() {
+        const waitMs = this.check();
+        if (waitMs > 0) {
+            apiLogger.warn(`[RateLimiter:${this.name}] Throttling for ${waitMs}ms (${this.maxRequests}/${this.windowMs}ms)`);
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+        }
+        this.timestamps.push(Date.now());
+    }
+    /**
+     * Update from Walmart response headers. Caches the latest token count +
+     * replenish time so getStatus() can surface them via the
+     * walmart_get_rate_budget MCP tool.
+     */
+    updateFromHeaders(headers) {
+        const remaining = headers['x-current-token-count'];
+        if (remaining !== undefined) {
+            const count = parseInt(remaining, 10);
+            if (!Number.isNaN(count)) {
+                this.latestServerTokens = count;
+                this.latestServerSeenAt = Date.now();
+                if (count <= 5) {
+                    apiLogger.warn(`[RateLimiter:${this.name}] Only ${count} API tokens remaining. Replenish at: ${headers['x-next-replenish-time'] || 'unknown'}`);
+                }
+            }
+        }
+        const replenish = headers['x-next-replenish-time'];
+        if (replenish !== undefined)
+            this.latestReplenishTime = replenish;
+    }
+    /** Snapshot for the rate-budget MCP tool. */
+    getStatus() {
+        return {
+            name: this.name,
+            localMaxRequests: this.maxRequests,
+            localWindowMs: this.windowMs,
+            localCurrentCount: this.currentCount,
+            localRemaining: this.remaining,
+            serverTokensRemaining: this.latestServerTokens,
+            serverReplenishTime: this.latestReplenishTime,
+            serverTokensSeenAt: this.latestServerSeenAt != null ? new Date(this.latestServerSeenAt).toISOString() : null,
+        };
+    }
+    prune() {
+        const cutoff = Date.now() - this.windowMs;
+        while (this.timestamps.length > 0 && (this.timestamps[0] ?? 0) <= cutoff) {
+            this.timestamps.shift();
+        }
+    }
+    get currentCount() {
+        this.prune();
+        return this.timestamps.length;
+    }
+    get remaining() {
+        this.prune();
+        return Math.max(0, this.maxRequests - this.timestamps.length);
+    }
+}
+export class RateLimitError extends Error {
+    waitMs;
+    constructor(message, waitMs) {
+        super(message);
+        this.waitMs = waitMs;
+        this.name = 'RateLimitError';
+    }
+}

package/package.json

@@ -0,0 +1 @@
+{  "name": "@lehaotech/walmart-mcp",  "version": "0.5.4",  "publishConfig": {    "access": "public"  },  "description": "Walmart Marketplace MCP Server for AI-powered seller operations",  "type": "module",  "main": "build/index.js",  "types": "build/index.d.ts",  "bin": {    "walmart-mcp": "build/index.js"  },  "files": [    "build",    "README.md",    "CHANGELOG.md",    "LICENSE",    ".env.example"  ],  "scripts": {    "build": "tsc && tsc-alias",    "start": "node build/index.js",    "dev": "tsx src/index.ts",    "diagnose": "tsx src/scripts/diagnose.ts",    "test": "vitest",    "test:run": "vitest run",    "test:sandbox": "npm run build && node test-sandbox.mjs",    "inspect": "npm run build && npx @modelcontextprotocol/inspector node build/index.js",    "prepublishOnly": "npm run build",    "setup": "tsx src/scripts/setup.ts",    "typecheck": "tsc --noEmit",    "test:coverage": "vitest run --coverage"  },  "keywords": [    "mcp",    "model-context-protocol",    "walmart",    "marketplace",    "seller",    "claude",    "ai"  ],  "author": "Fakang Yu",  "license": "MIT",  "repository": {    "type": "git",    "url": "git+https://github.com/yufakang0826-hue/walmart-mcp.git"  },  "bugs": {    "url": "https://github.com/yufakang0826-hue/walmart-mcp/issues"  },  "homepage": "https://github.com/yufakang0826-hue/walmart-mcp#readme",  "dependencies": {    "@modelcontextprotocol/sdk": "^1.21.0",    "axios": "^1.7.9",    "dotenv": "^17.0.0",    "winston": "^3.19.0",    "zod": "^3.23.8",    "zod-to-json-schema": "^3.24.1"  },  "devDependencies": {    "@types/node": "^22",    "tsc-alias": "^1.8.10",    "tsx": "^4.19.0",    "typescript": "^5.9.0",    "vitest": "^3",    "@vitest/coverage-v8": "^3"  },  "engines": {    "node": ">=22"  }}