@lehaotech/walmart-mcp 0.5.4

package/build/tools/definitions/items.js

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+import { SkuSchema, GtinSchema } from './shared-schemas.js';
+// ---------- MP_ITEM feed envelope ----------
+const MpItemEnvelopeSchema = z
+    .object({
+    MPItemFeedHeader: z
+        .object({
+        version: z.string().default('5.0'),
+        sellingChannel: z.literal('marketplace').default('marketplace'),
+        locale: z.string().default('en'),
+        requestId: z.string().optional(),
+    })
+        .passthrough(),
+    MPItem: z
+        .array(z
+        .object({
+        Item: z
+            .object({
+            sku: SkuSchema,
+            productIdentifiers: z
+                .object({
+                productIdType: z.enum(['GTIN', 'UPC', 'ISBN', 'EAN']).optional(),
+                productId: z.string().min(1).optional(),
+            })
+                .passthrough()
+                .optional(),
+        })
+            .passthrough(),
+    })
+        .passthrough())
+        .min(1, 'MP_ITEM feed needs at least 1 item')
+        .max(10_000, 'Walmart caps MP_ITEM feeds at ~10000 items per submission'),
+})
+    .strict();
+// ---------- MP_MAINTENANCE feed envelope ----------
+const MpMaintenanceEnvelopeSchema = z
+    .object({
+    MPItemFeedHeader: z
+        .object({
+        version: z.string().default('5.0'),
+        sellingChannel: z.literal('marketplace').default('marketplace'),
+        locale: z.string().default('en'),
+        requestId: z.string().optional(),
+    })
+        .passthrough(),
+    MPItem: z
+        .array(z.object({ Item: z.object({ sku: SkuSchema }).passthrough() }).passthrough())
+        .min(1)
+        .max(10_000),
+})
+    .strict();
+// ---------- MP_RETIRE_ITEM bulk retire ----------
+const BulkRetireSchema = z
+    .object({
+    skus: z
+        .array(z.object({ sku: SkuSchema }).strict())
+        .min(1, 'Need at least 1 SKU to retire')
+        .max(1_000, 'Bulk retire capped at 1000 SKUs per call'),
+})
+    .strict();
+// ---------- Hazmat search ----------
+const HazmatSearchSchema = z
+    .object({
+    sku: SkuSchema.optional(),
+    gtin: GtinSchema.optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+    offset: z.number().int().min(0).optional(),
+})
+    .passthrough();
+// ---------- WFS item feed (feedType=WFS_ITEM) ----------
+// Walmart WFS item feed includes per-item dimensions, weight, and storage attributes.
+const WfsItemEnvelopeSchema = z
+    .object({
+    WFSItemFeedHeader: z
+        .object({
+        version: z.string().default('1.0'),
+        feedDate: z.string().datetime({ offset: true }).optional(),
+    })
+        .passthrough(),
+    WFSItem: z
+        .array(z
+        .object({
+        sku: SkuSchema,
+        wfsAttributes: z
+            .object({
+            weight: z.number().positive().optional(),
+            weightUnit: z.enum(['LB', 'OZ', 'KG', 'G']).optional(),
+            length: z.number().positive().optional(),
+            width: z.number().positive().optional(),
+            height: z.number().positive().optional(),
+            dimensionUnit: z.enum(['IN', 'CM']).optional(),
+        })
+            .passthrough()
+            .optional(),
+    })
+        .passthrough())
+        .min(1)
+        .max(10_000),
+})
+    .strict();
+// ---------- OMNI_WFS conversion feed ----------
+// Converts existing SF SKUs to WFS-fulfilled. Body has list of SKUs and unit attributes.
+const ConvertToWfsEnvelopeSchema = z
+    .object({
+    OmniWFSFeedHeader: z
+        .object({
+        version: z.string().default('1.0'),
+    })
+        .passthrough(),
+    OmniWFSItem: z
+        .array(z
+        .object({
+        sku: SkuSchema,
+        convertToWFS: z.boolean().default(true),
+    })
+        .passthrough())
+        .min(1)
+        .max(10_000),
+})
+    .strict();
+export const itemTools = [
+    {
+        name: 'walmart_get_all_items',
+        description: 'Get all items in the seller catalog with pagination. Returns item details including SKU, ' +
+            'title, price, publish status, and lifecycle status.',
+        inputSchema: {
+            limit: z.number().int().min(1).max(50).optional().describe('Items per page (default 20, max 50)'),
+            offset: z.string().optional().describe('Pagination offset token from previous response'),
+            lifecycleStatus: z.enum(['ACTIVE', 'RETIRED']).optional().describe('Filter by lifecycle status'),
+            publishedStatus: z.enum(['PUBLISHED', 'UNPUBLISHED', 'STAGE']).optional().describe('Filter by publish status'),
+            sku: z.string().optional().describe('Filter by specific SKU'),
+        },
+    },
+    {
+        name: 'walmart_get_item',
+        description: 'Get a single item by SKU. Returns full item details including product attributes, price, ' +
+            'inventory, and listing quality.',
+        inputSchema: {
+            sku: z.string().describe('Seller-defined SKU identifier'),
+        },
+    },
+    {
+        name: 'walmart_retire_item',
+        description: 'Retire (unpublish) an item by SKU. This removes the item from the Walmart marketplace. ' +
+            'The item can be re-listed later by submitting an MP_ITEM feed for the same SKU.',
+        inputSchema: {
+            sku: SkuSchema.describe('SKU of the item to retire'),
+        },
+    },
+    {
+        name: 'walmart_bulk_retire_items',
+        description: 'Retire multiple items at once. Pass `skus: [{ sku }, ...]`. Walmart caps bulk retire at ' +
+            '~1000 SKUs per call.',
+        inputSchema: {
+            skus: BulkRetireSchema.shape.skus,
+        },
+    },
+    {
+        name: 'walmart_get_item_count',
+        description: 'Get item count grouped by status. Useful for monitoring catalog health. The status ' +
+            'parameter is required by Walmart and defaults to PUBLISHED.',
+        inputSchema: {
+            status: z.enum(['PUBLISHED', 'UNPUBLISHED', 'STAGE']).optional().describe('Item status to count (defaults to PUBLISHED)'),
+            lifecycleStatus: z.enum(['ACTIVE', 'RETIRED']).optional().describe('Filter by lifecycle status'),
+            publishedStatus: z.enum(['PUBLISHED', 'UNPUBLISHED', 'STAGE']).optional().describe('Filter by publish status'),
+        },
+    },
+    {
+        name: 'walmart_get_taxonomy',
+        description: 'Get the complete Walmart product taxonomy (category hierarchy). Use this to find the correct category for item setup.',
+        inputSchema: {},
+    },
+    {
+        name: 'walmart_get_item_spec',
+        description: 'Get the item specification (required and optional attributes) for a product type. Use this before creating items to know which fields are needed.',
+        inputSchema: {
+            productType: z.string().describe('Product type name from taxonomy (e.g., "Electronics", "Clothing")'),
+            version: z.string().optional().describe('Spec version (optional)'),
+        },
+    },
+    {
+        name: 'walmart_submit_item_feed',
+        description: 'Submit a bulk item creation feed (feedType=item). Envelope: { MPItemFeedHeader, ' +
+            'MPItem: [{ Item: { sku, productIdentifiers, ...attributes } }] }. Per-item content fields ' +
+            'vary by productType — call walmart_get_item_spec first. Returns a feedId.',
+        inputSchema: {
+            feedData: MpItemEnvelopeSchema,
+        },
+    },
+    {
+        name: 'walmart_submit_item_update_feed',
+        description: 'Submit a bulk item update / maintenance feed (feedType=MP_MAINTENANCE). Same envelope as ' +
+            'item creation but for updating existing SKUs. Returns a feedId.',
+        inputSchema: {
+            feedData: MpMaintenanceEnvelopeSchema,
+        },
+    },
+    {
+        name: 'walmart_submit_wfs_item_feed',
+        description: 'Submit a WFS item setup feed (feedType=WFS_ITEM). Envelope: { WFSItemFeedHeader, ' +
+            'WFSItem: [{ sku, wfsAttributes: { weight, length, width, height, units } }] }. ' +
+            'Returns a feedId.',
+        inputSchema: {
+            feedData: WfsItemEnvelopeSchema,
+        },
+    },
+    {
+        name: 'walmart_convert_to_wfs',
+        description: 'Convert existing seller-fulfilled items to WFS fulfillment (feedType=OMNI_WFS). Envelope: ' +
+            '{ OmniWFSFeedHeader, OmniWFSItem: [{ sku, convertToWFS: true }] }.',
+        inputSchema: {
+            feedData: ConvertToWfsEnvelopeSchema,
+        },
+    },
+    {
+        name: 'walmart_get_hazmat_items',
+        description: 'Get items on hold for hazmat compliance review (POST /v3/items/onhold/search). These items ' +
+            'need compliance documentation before they can be published.',
+        inputSchema: {
+            requestData: HazmatSearchSchema.optional(),
+        },
+    },
+];

package/build/tools/definitions/notifications.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+export declare const notificationTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        subscriptionData: z.ZodEffects<z.ZodObject<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">>;
+        eventType?: undefined;
+        subscriptionId?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        eventType: z.ZodOptional<z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>>;
+        subscriptionData?: undefined;
+        subscriptionId?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        subscriptionId: z.ZodString;
+        subscriptionData?: undefined;
+        eventType?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        subscriptionId: z.ZodString;
+        subscriptionData: z.ZodEffects<z.ZodObject<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            eventType: z.ZodEnum<["PO_CREATED", "PO_LINE_AUTOCANCELLED", "OFFER_UNPUBLISHED", "BUYBOX_CHANGED", "PRICE_CHANGED", "INVENTORY_CHANGED", "RETURN_CREATED", "ITEM_PUBLISHED", "ITEM_UNPUBLISHED"]>;
+            destinationUrl: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<["JSON", "XML"]>>;
+            isActive: z.ZodDefault<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">>;
+        eventType?: undefined;
+    };
+})[];

package/build/tools/definitions/notifications.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+const WalmartEventTypeSchema = z.enum([
+    'PO_CREATED',
+    'PO_LINE_AUTOCANCELLED',
+    'OFFER_UNPUBLISHED',
+    'BUYBOX_CHANGED',
+    'PRICE_CHANGED',
+    'INVENTORY_CHANGED',
+    'RETURN_CREATED',
+    'ITEM_PUBLISHED',
+    'ITEM_UNPUBLISHED',
+]);
+const SubscriptionBodySchema = z
+    .object({
+    eventType: WalmartEventTypeSchema,
+    destinationUrl: z
+        .string()
+        .url('destinationUrl must be a valid HTTPS URL'),
+    format: z.enum(['JSON', 'XML']).default('JSON'),
+    isActive: z.boolean().default(true),
+})
+    .passthrough()
+    .refine((s) => s.destinationUrl.startsWith('https://'), {
+    message: 'Walmart requires HTTPS for webhook destinations',
+    path: ['destinationUrl'],
+});
+export const notificationTools = [
+    {
+        name: 'walmart_create_subscription',
+        description: 'Create a webhook subscription for event notifications. Required: eventType + destinationUrl ' +
+            '(HTTPS only). Events: PO_CREATED, PO_LINE_AUTOCANCELLED, OFFER_UNPUBLISHED, BUYBOX_CHANGED, ' +
+            'PRICE_CHANGED, INVENTORY_CHANGED, RETURN_CREATED, ITEM_PUBLISHED, ITEM_UNPUBLISHED.',
+        inputSchema: {
+            subscriptionData: SubscriptionBodySchema,
+        },
+    },
+    {
+        name: 'walmart_get_subscriptions',
+        description: 'List all webhook subscriptions with optional event type filter.',
+        inputSchema: {
+            eventType: WalmartEventTypeSchema.optional().describe('Filter by event type'),
+        },
+    },
+    {
+        name: 'walmart_get_subscription',
+        description: 'Get details of a specific webhook subscription.',
+        inputSchema: {
+            subscriptionId: z.string().describe('Subscription ID'),
+        },
+    },
+    {
+        name: 'walmart_update_subscription',
+        description: 'Update an existing webhook subscription (e.g., change URL or status).',
+        inputSchema: {
+            subscriptionId: z.string().describe('Subscription ID to update'),
+            subscriptionData: SubscriptionBodySchema,
+        },
+    },
+    {
+        name: 'walmart_delete_subscription',
+        description: 'Delete a webhook subscription. Events will no longer be sent to the destination URL.',
+        inputSchema: {
+            subscriptionId: z.string().describe('Subscription ID to delete'),
+        },
+    },
+    {
+        name: 'walmart_test_subscription',
+        description: 'Send a test event to a webhook subscription to verify the endpoint is working correctly.',
+        inputSchema: {
+            subscriptionId: z.string().describe('Subscription ID to test'),
+        },
+    },
+];