@lehaotech/walmart-mcp 0.5.4

package/build/api/settings/settings-api.js

@@ -0,0 +1,21 @@
+export class SettingsApi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async getShippingSettings() {
+        return await this.client.get('/v3/settings/shipping');
+    }
+    async updateShippingSettings(data) {
+        return await this.client.put('/v3/settings/shipping', data);
+    }
+    async getFulfillmentCenters() {
+        return await this.client.get('/v3/settings/shippingprofile');
+    }
+    async getPartnerInfo() {
+        // Walmart has no dedicated partner endpoint; the seller/partner record is
+        // returned as the `partner` object on the shipping-profile settings payload.
+        const data = await this.client.get('/v3/settings/shippingprofile');
+        return data?.partner ?? data;
+    }
+}

package/build/auth/oauth.d.ts

@@ -0,0 +1,16 @@
+import { type WalmartConfig } from '../config/environment.js';
+export declare class WalmartOAuthClient {
+    private config;
+    private accessToken;
+    private tokenExpiry;
+    private isRefreshing;
+    private refreshPromise;
+    constructor(config: WalmartConfig);
+    initialize(): Promise<void>;
+    getAccessToken(): Promise<string>;
+    refreshToken(): Promise<void>;
+    private _doRefresh;
+    getTokenDetail(): Promise<object>;
+    getTokenInfo(): object;
+    private updateEnvFile;
+}

package/build/auth/oauth.js

@@ -0,0 +1,125 @@
+import axios from 'axios';
+import { randomUUID } from 'crypto';
+import { getBaseUrl } from '../config/environment.js';
+import { authLogger } from '../utils/logger.js';
+import { upsertEnvVars } from '../utils/env-file.js';
+export class WalmartOAuthClient {
+    config;
+    accessToken = null;
+    tokenExpiry = 0;
+    isRefreshing = false;
+    refreshPromise = null;
+    constructor(config) {
+        this.config = config;
+    }
+    async initialize() {
+        if (this.config.accessToken && this.config.accessTokenExpiry) {
+            this.accessToken = this.config.accessToken;
+            this.tokenExpiry = this.config.accessTokenExpiry;
+            if (Date.now() < this.tokenExpiry - 120_000) {
+                authLogger.info('Loaded cached token from .env');
+                return;
+            }
+        }
+        try {
+            await this.refreshToken();
+        }
+        catch (error) {
+            authLogger.warn('Initial token fetch failed (credentials may not be configured yet)');
+        }
+    }
+    async getAccessToken() {
+        // Token valid and more than 2 min remaining
+        if (this.accessToken && Date.now() < this.tokenExpiry - 120_000) {
+            return this.accessToken;
+        }
+        // Prevent concurrent refresh
+        if (this.isRefreshing && this.refreshPromise) {
+            await this.refreshPromise;
+            return this.accessToken;
+        }
+        await this.refreshToken();
+        return this.accessToken;
+    }
+    async refreshToken() {
+        this.isRefreshing = true;
+        this.refreshPromise = this._doRefresh();
+        try {
+            await this.refreshPromise;
+        }
+        finally {
+            this.isRefreshing = false;
+            this.refreshPromise = null;
+        }
+    }
+    async _doRefresh() {
+        if (!this.config.clientId || !this.config.clientSecret) {
+            throw new Error('Walmart API credentials are not configured. Set WALMART_CLIENT_ID and '
+                + 'WALMART_CLIENT_SECRET in your MCP server "env" (or a .env file), or call the '
+                + 'walmart_set_credentials tool with your Client ID and Secret. '
+                + 'Get credentials at https://developer.walmart.com/. '
+                + 'Run the walmart_setup_guide tool for step-by-step setup.');
+        }
+        const baseUrl = getBaseUrl(this.config.environment);
+        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        authLogger.info(`Requesting token from ${this.config.environment} environment`);
+        try {
+            const response = await axios.post(`${baseUrl}/v3/token`, 'grant_type=client_credentials', {
+                headers: {
+                    'Authorization': `Basic ${credentials}`,
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Accept': 'application/json',
+                    'WM_QOS.CORRELATION_ID': randomUUID(),
+                    'WM_SVC.NAME': this.config.svcName,
+                },
+                timeout: 15_000,
+            });
+            this.accessToken = response.data.access_token;
+            this.tokenExpiry = Date.now() + response.data.expires_in * 1000;
+            authLogger.info(`Token obtained, expires in ${response.data.expires_in}s`);
+            this.updateEnvFile({
+                WALMART_ACCESS_TOKEN: this.accessToken,
+                WALMART_ACCESS_TOKEN_EXPIRY: String(this.tokenExpiry),
+            });
+        }
+        catch (error) {
+            const msg = axios.isAxiosError(error)
+                ? error.response?.data?.error_description || error.message
+                : String(error);
+            authLogger.error(`Token refresh failed: ${msg}`);
+            throw new Error(`Authentication failed: ${msg}`);
+        }
+    }
+    async getTokenDetail() {
+        const token = await this.getAccessToken();
+        const baseUrl = getBaseUrl(this.config.environment);
+        const response = await axios.get(`${baseUrl}/v3/token/detail`, {
+            headers: {
+                'WM_SEC.ACCESS_TOKEN': token,
+                'WM_QOS.CORRELATION_ID': randomUUID(),
+                'WM_SVC.NAME': this.config.svcName,
+                'Content-Type': 'application/json',
+            },
+            timeout: 15_000,
+        });
+        return response.data;
+    }
+    getTokenInfo() {
+        return {
+            hasToken: !!this.accessToken,
+            expiresAt: this.tokenExpiry ? new Date(this.tokenExpiry).toISOString() : null,
+            expiresInSeconds: this.tokenExpiry
+                ? Math.max(0, Math.round((this.tokenExpiry - Date.now()) / 1000))
+                : 0,
+            environment: this.config.environment,
+        };
+    }
+    updateEnvFile(updates) {
+        try {
+            upsertEnvVars(updates);
+        }
+        catch {
+            // Silent failure - don't interfere with MCP stdout
+        }
+    }
+}

package/build/config/environment.d.ts

@@ -0,0 +1,22 @@
+export type WalmartEnvironment = 'sandbox' | 'production';
+export type WalmartMarket = 'us' | 'CA' | 'mx';
+export interface WalmartConfig {
+    clientId: string;
+    clientSecret: string;
+    environment: WalmartEnvironment;
+    market: WalmartMarket;
+    svcName: string;
+    consumerChannelType?: string;
+    partnerId?: string;
+    accessToken?: string;
+    accessTokenExpiry?: number;
+    logLevel: string;
+    enableFileLogging: boolean;
+    adConsumerId?: string;
+    adPrivateKey?: string;
+    adKeyVersion?: string;
+}
+export declare function getBaseUrl(env: WalmartEnvironment): string;
+export declare function getAdBaseUrl(env: WalmartEnvironment): string;
+export declare function getConfig(): WalmartConfig;
+export declare function validateConfig(config: WalmartConfig): void;

package/build/config/environment.js

@@ -0,0 +1,50 @@
+import * as dotenv from 'dotenv';
+dotenv.config();
+const BASE_URLS = {
+    production: 'https://marketplace.walmartapis.com',
+    sandbox: 'https://sandbox.walmartapis.com',
+};
+const AD_BASE_URLS = {
+    production: 'https://developer.api.walmart.com/api-proxy/service/WPA/Api',
+    sandbox: 'https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api',
+};
+export function getBaseUrl(env) {
+    return BASE_URLS[env];
+}
+export function getAdBaseUrl(env) {
+    return AD_BASE_URLS[env];
+}
+export function getConfig() {
+    return {
+        clientId: process.env.WALMART_CLIENT_ID || '',
+        clientSecret: process.env.WALMART_CLIENT_SECRET || '',
+        environment: process.env.WALMART_ENVIRONMENT || 'sandbox',
+        market: process.env.WALMART_MARKET || 'us',
+        svcName: process.env.WALMART_SVC_NAME || 'Walmart Marketplace',
+        consumerChannelType: process.env.WALMART_CONSUMER_CHANNEL_TYPE || undefined,
+        partnerId: process.env.WALMART_PARTNER_ID || undefined,
+        accessToken: process.env.WALMART_ACCESS_TOKEN || undefined,
+        accessTokenExpiry: process.env.WALMART_ACCESS_TOKEN_EXPIRY
+            ? parseInt(process.env.WALMART_ACCESS_TOKEN_EXPIRY, 10)
+            : undefined,
+        logLevel: process.env.WALMART_LOG_LEVEL || 'info',
+        enableFileLogging: process.env.WALMART_ENABLE_FILE_LOGGING === 'true',
+        adConsumerId: process.env.WALMART_AD_CONSUMER_ID || undefined,
+        adPrivateKey: process.env.WALMART_AD_PRIVATE_KEY || undefined,
+        adKeyVersion: process.env.WALMART_AD_KEY_VERSION || '1',
+    };
+}
+export function validateConfig(config) {
+    if (!config.clientId || !config.clientSecret) {
+        console.error('\n┌─ walmart-mcp: setup required ────────────────────────────────────\n'
+            + '│ No API credentials found. The server will start, but Walmart calls\n'
+            + '│ will fail until you provide credentials. To fix:\n'
+            + '│   1. Get a Client ID + Secret at https://developer.walmart.com/\n'
+            + '│   2. Set WALMART_CLIENT_ID and WALMART_CLIENT_SECRET in your MCP\n'
+            + '│      server "env" (or a .env file), then restart — OR call the\n'
+            + '│      walmart_set_credentials tool at runtime.\n'
+            + '│   Run the walmart_setup_guide tool for full setup steps.\n'
+            + `│ Environment: ${config.environment}   Market: ${config.market}\n`
+            + '└──────────────────────────────────────────────────────────────────\n');
+    }
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z, ZodError } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getConfig, validateConfig } from './config/environment.js';
+import { WalmartSellerApi } from './api/index.js';
+import { getToolDefinitions, executeTool } from './tools/index.js';
+import { serverLogger } from './utils/logger.js';
+import { WalmartApiError } from './utils/api-error.js';
+// Resolve package.json once at module load so the MCP server's reported
+// version stays in lockstep with what's actually installed. Avoids drift like
+// the earlier hard-coded '0.3.2' which lagged through five releases.
+function readPackageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // build/index.js -> ../package.json. Works the same when running via tsx
+        // from src/ because tsx evaluates in place under the repo root.
+        const pkgPath = join(here, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const PACKAGE_VERSION = readPackageVersion();
+class WalmartMcpServer {
+    server;
+    api;
+    constructor() {
+        const config = getConfig();
+        validateConfig(config);
+        this.server = new McpServer({
+            name: 'walmart-mcp',
+            version: PACKAGE_VERSION,
+        });
+        this.api = new WalmartSellerApi(config);
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        const tools = getToolDefinitions();
+        serverLogger.info(`Registering ${tools.length} tools`);
+        for (const toolDef of tools) {
+            const hasSchema = Object.keys(toolDef.inputSchema).length > 0;
+            this.server.registerTool(toolDef.name, {
+                description: toolDef.description,
+                inputSchema: hasSchema
+                    ? toolDef.inputSchema
+                    : undefined,
+            }, async (rawArgs) => {
+                // Re-parse args through the tool's zod schema. The MCP SDK does shape
+                // validation against the inputSchema, but explicit z.object(...).parse
+                // here also runs any .refine() business rules and fills in defaults so
+                // the downstream dispatcher always sees a fully-resolved payload.
+                let args = rawArgs;
+                try {
+                    if (hasSchema) {
+                        const schemaObj = z.object(toolDef.inputSchema);
+                        args = schemaObj.parse(rawArgs);
+                    }
+                }
+                catch (validationError) {
+                    if (validationError instanceof ZodError) {
+                        serverLogger.warn(`Tool ${toolDef.name} input validation failed: ${validationError.message}`);
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: 'Input validation failed before any Walmart API call.',
+                                        tool: toolDef.name,
+                                        issues: validationError.issues.map((iss) => ({
+                                            path: iss.path,
+                                            message: iss.message,
+                                            code: iss.code,
+                                        })),
+                                    }, null, 2),
+                                }],
+                            isError: true,
+                        };
+                    }
+                    throw validationError;
+                }
+                try {
+                    const result = await executeTool(this.api, toolDef.name, args);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            }],
+                    };
+                }
+                catch (error) {
+                    const errorMsg = error instanceof Error ? error.message : String(error);
+                    serverLogger.error(`Tool ${toolDef.name} failed: ${errorMsg}`);
+                    let payload;
+                    if (error instanceof WalmartApiError) {
+                        // Attach the MCP tool name so the LLM can correlate the failing
+                        // call to a tool it knows about. endpoint + hint are already set
+                        // by the API client's interceptor.
+                        error.tool = toolDef.name;
+                        payload = error.toResponse();
+                    }
+                    else {
+                        payload = { error: errorMsg, tool: toolDef.name };
+                    }
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(payload, null, 2),
+                            }],
+                        isError: true,
+                    };
+                }
+            });
+        }
+    }
+    async run() {
+        await this.api.initialize();
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        serverLogger.info('Walmart MCP Server running on stdio');
+        process.on('SIGINT', async () => {
+            serverLogger.info('Shutting down...');
+            await this.server.close();
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            serverLogger.info('Shutting down...');
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+}
+// ============================================================
+// Subcommand dispatch — make a single bin handle:
+//   walmart-mcp           -> run the MCP server (default)
+//   walmart-mcp setup     -> run the interactive setup wizard
+//   walmart-mcp diagnose  -> run the self-check (--export OK)
+//   walmart-mcp version   -> print the package version
+// Everything after the subcommand is forwarded as process.argv to the
+// child script (so `walmart-mcp diagnose --export` works).
+// ============================================================
+const subcommand = process.argv[2];
+async function dispatch() {
+    if (subcommand === 'setup') {
+        process.argv = [process.argv[0], 'setup', ...process.argv.slice(3)];
+        await import('./scripts/setup.js');
+        return;
+    }
+    if (subcommand === 'diagnose') {
+        process.argv = [process.argv[0], 'diagnose', ...process.argv.slice(3)];
+        await import('./scripts/diagnose.js');
+        return;
+    }
+    if (subcommand === 'version' || subcommand === '--version' || subcommand === '-v') {
+        console.log(`walmart-mcp v${PACKAGE_VERSION}`);
+        return;
+    }
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+        console.log('walmart-mcp — Walmart Marketplace MCP server');
+        console.log('');
+        console.log('Usage:');
+        console.log('  walmart-mcp                Run the MCP server over stdio (default).');
+        console.log('  walmart-mcp setup          Interactive setup wizard.');
+        console.log('  walmart-mcp diagnose       Self-check (env / token / config).');
+        console.log('  walmart-mcp version        Print version.');
+        console.log('');
+        console.log('Docs: https://github.com/yufakang0826-hue/walmart-mcp');
+        return;
+    }
+    const server = new WalmartMcpServer();
+    await server.run();
+}
+dispatch().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/build/scripts/client-configs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP client config detection + write helpers used by `npm run setup`.
+ *
+ * Each client uses a slightly different config schema. Most follow Claude
+ * Desktop's `{ mcpServers: { name: { command, args, env } } }` shape, but
+ * Cursor and Zed differ.
+ */
+export type ClientId = 'claude-desktop' | 'claude-code-cli' | 'cursor' | 'cline' | 'continue' | 'windsurf' | 'zed';
+export interface ClientSpec {
+    id: ClientId;
+    name: string;
+    /** Get the OS-resolved absolute config path for this client. */
+    resolvePath: () => string | null;
+    /** How the `mcpServers` block is keyed in this client's config. */
+    serverKey: 'mcpServers' | 'servers';
+}
+export declare const CLIENT_SPECS: ReadonlyArray<ClientSpec>;
+/** Returns the subset of clients whose config files already exist. */
+export declare function detectInstalled(): ReadonlyArray<ClientSpec & {
+    path: string;
+}>;
+export interface WalmartMcpEntry {
+    type: 'stdio';
+    command: 'node';
+    args: string[];
+    env: Record<string, string>;
+}
+/**
+ * Read existing config (or start from empty), insert / overwrite the
+ * `walmart` entry under the appropriate server-key, and write back. Backs up
+ * the original to `.before-walmart-setup.bak` on first write.
+ */
+export declare function writeWalmartEntry(spec: ClientSpec, configPath: string, walmartEntry: WalmartMcpEntry): {
+    backedUp: boolean;
+    overwrote: boolean;
+};

package/build/scripts/client-configs.js

@@ -0,0 +1,132 @@
+/**
+ * MCP client config detection + write helpers used by `npm run setup`.
+ *
+ * Each client uses a slightly different config schema. Most follow Claude
+ * Desktop's `{ mcpServers: { name: { command, args, env } } }` shape, but
+ * Cursor and Zed differ.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir, platform } from 'node:os';
+const APP_DATA = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+const LOCAL_APP_DATA = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+export const CLIENT_SPECS = [
+    {
+        id: 'claude-desktop',
+        name: 'Claude Desktop',
+        serverKey: 'mcpServers',
+        resolvePath: () => {
+            const plat = platform();
+            if (plat === 'darwin') {
+                return join(homedir(), 'Library/Application Support/Claude/claude_desktop_config.json');
+            }
+            if (plat === 'win32') {
+                return join(APP_DATA, 'Claude', 'claude_desktop_config.json');
+            }
+            return join(homedir(), '.config/Claude/claude_desktop_config.json');
+        },
+    },
+    {
+        id: 'claude-code-cli',
+        name: 'Claude Code CLI',
+        serverKey: 'mcpServers',
+        resolvePath: () => join(homedir(), '.claude.json'),
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        serverKey: 'mcpServers',
+        resolvePath: () => join(homedir(), '.cursor', 'mcp.json'),
+    },
+    {
+        id: 'cline',
+        name: 'Cline (VSCode extension)',
+        serverKey: 'mcpServers',
+        resolvePath: () => {
+            const plat = platform();
+            const segment = 'User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json';
+            if (plat === 'darwin') {
+                return join(homedir(), 'Library/Application Support/Code', segment);
+            }
+            if (plat === 'win32') {
+                return join(APP_DATA, 'Code', segment);
+            }
+            return join(homedir(), '.config/Code', segment);
+        },
+    },
+    {
+        id: 'continue',
+        name: 'Continue.dev',
+        serverKey: 'mcpServers',
+        resolvePath: () => join(homedir(), '.continue', 'config.json'),
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf (Codeium)',
+        serverKey: 'mcpServers',
+        resolvePath: () => join(homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+    },
+    {
+        id: 'zed',
+        name: 'Zed Editor',
+        serverKey: 'servers',
+        resolvePath: () => {
+            const plat = platform();
+            if (plat === 'darwin') {
+                return join(homedir(), 'Library/Application Support/Zed/settings.json');
+            }
+            if (plat === 'win32') {
+                return join(LOCAL_APP_DATA, 'Zed', 'settings.json');
+            }
+            return join(homedir(), '.config/zed/settings.json');
+        },
+    },
+];
+/** Returns the subset of clients whose config files already exist. */
+export function detectInstalled() {
+    const found = [];
+    for (const spec of CLIENT_SPECS) {
+        const p = spec.resolvePath();
+        if (p && existsSync(p))
+            found.push({ ...spec, path: p });
+    }
+    return found;
+}
+/**
+ * Read existing config (or start from empty), insert / overwrite the
+ * `walmart` entry under the appropriate server-key, and write back. Backs up
+ * the original to `.before-walmart-setup.bak` on first write.
+ */
+export function writeWalmartEntry(spec, configPath, walmartEntry) {
+    let backedUp = false;
+    let overwrote = false;
+    let config = {};
+    if (existsSync(configPath)) {
+        config = JSON.parse(readFileSync(configPath, 'utf8'));
+        const backup = `${configPath}.before-walmart-setup.bak`;
+        writeFileSync(backup, readFileSync(configPath));
+        backedUp = true;
+    }
+    else {
+        mkdirSync(dirname(configPath), { recursive: true });
+    }
+    let servers = config[spec.serverKey] ?? {};
+    if (spec.id === 'zed') {
+        // Zed nests MCP under `mcp.servers`; load the nested level.
+        const mcp = config.mcp ?? {};
+        servers = mcp.servers ?? {};
+        if ('walmart' in servers)
+            overwrote = true;
+        servers.walmart = walmartEntry;
+        mcp.servers = servers;
+        config.mcp = mcp;
+    }
+    else {
+        if ('walmart' in servers)
+            overwrote = true;
+        servers.walmart = walmartEntry;
+        config[spec.serverKey] = servers;
+    }
+    writeFileSync(configPath, JSON.stringify(config, null, 2));
+    return { backedUp, overwrote };
+}

package/build/scripts/diagnose.d.ts

@@ -0,0 +1,15 @@
+/**
+ * walmart-mcp diagnose
+ * ------------------------------------------------------------
+ * Self-check script. Run via `npm run diagnose`.
+ *
+ * Reports environment readiness, credential validity, and MCP-client config
+ * presence without revealing credential values. Use `--export` to dump a
+ * JSON report suitable for attaching to bug reports.
+ *
+ * Exit codes:
+ *   0  all checks passed (or only warnings)
+ *   1  one or more errors — configuration must be fixed before the MCP works
+ *   2  fatal (script itself crashed)
+ */
+export {};