@lehaotech/walmart-mcp 0.5.4

package/build/tools/definitions/advertising.js

@@ -0,0 +1,315 @@
+import { z } from 'zod';
+// ---------- Shared Ad atoms ----------
+const StatusSchema = z.enum(['enabled', 'paused', 'completed', 'archived']);
+const CampaignTypeSchema = z.enum(['sponsoredProducts', 'sba', 'video']);
+const TargetingTypeSchema = z.enum(['auto', 'manual']);
+const BudgetTypeSchema = z.enum(['daily', 'total']);
+const MatchTypeSchema = z.enum(['exact', 'phrase', 'broad']);
+const DateOnlySchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be YYYY-MM-DD');
+// Walmart Connect uses arrays at the top level for batch ops.
+const CampaignCreateEntry = z
+    .object({
+    name: z.string().min(1).max(200),
+    campaignType: CampaignTypeSchema,
+    targetingType: TargetingTypeSchema,
+    budgetType: BudgetTypeSchema.default('daily'),
+    dailyBudget: z.number().positive(),
+    totalBudget: z.number().positive().optional(),
+    startDate: DateOnlySchema,
+    endDate: DateOnlySchema.optional(),
+    status: StatusSchema.default('enabled'),
+})
+    .passthrough()
+    .refine((c) => !c.endDate || c.endDate >= c.startDate, {
+    message: 'endDate must be >= startDate',
+    path: ['endDate'],
+});
+const CampaignUpdateEntry = z
+    .object({
+    campaignId: z.number().int().positive(),
+    name: z.string().min(1).max(200).optional(),
+    status: StatusSchema.optional(),
+    dailyBudget: z.number().positive().optional(),
+    totalBudget: z.number().positive().optional(),
+    endDate: DateOnlySchema.optional(),
+})
+    .passthrough();
+const AdGroupCreateEntry = z
+    .object({
+    campaignId: z.number().int().positive(),
+    name: z.string().min(1).max(200),
+    status: StatusSchema.default('enabled'),
+    defaultBid: z.number().positive(),
+})
+    .passthrough();
+const AdGroupUpdateEntry = z
+    .object({
+    adGroupId: z.number().int().positive(),
+    name: z.string().min(1).max(200).optional(),
+    status: StatusSchema.optional(),
+    defaultBid: z.number().positive().optional(),
+})
+    .passthrough();
+const AdItemAddEntry = z
+    .object({
+    campaignId: z.number().int().positive(),
+    adGroupId: z.number().int().positive(),
+    itemId: z.string().min(1),
+    bid: z.number().positive(),
+    status: StatusSchema.default('enabled'),
+})
+    .passthrough();
+const AdItemUpdateEntry = z
+    .object({
+    adItemId: z.number().int().positive(),
+    bid: z.number().positive().optional(),
+    status: StatusSchema.optional(),
+})
+    .passthrough();
+const KeywordAddEntry = z
+    .object({
+    campaignId: z.number().int().positive(),
+    adGroupId: z.number().int().positive(),
+    keywordText: z.string().min(1).max(80),
+    matchType: MatchTypeSchema,
+    bid: z.number().positive(),
+    state: StatusSchema.default('enabled'),
+})
+    .passthrough();
+const KeywordUpdateEntry = z
+    .object({
+    keywordId: z.number().int().positive(),
+    bid: z.number().positive().optional(),
+    state: StatusSchema.optional(),
+})
+    .passthrough();
+const PlacementBidEntry = z
+    .object({
+    campaignId: z.number().int().positive(),
+    placement: z.string().min(1),
+    bidMultiplier: z.number().positive(),
+})
+    .passthrough();
+const PlatformBidEntry = z
+    .object({
+    campaignId: z.number().int().positive(),
+    platform: z.enum(['desktop', 'mobile', 'app']),
+    bidMultiplier: z.number().positive(),
+})
+    .passthrough();
+const ReportSnapshotCreateSchema = z
+    .object({
+    reportType: z.enum([
+        'campaign',
+        'adGroup',
+        'keyword',
+        'item',
+        'pageType',
+        'platform',
+        'placement',
+    ]),
+    reportDate: DateOnlySchema,
+    format: z.enum(['JSON', 'CSV']).default('JSON'),
+})
+    .passthrough();
+export const advertisingTools = [
+    // ===== Campaigns =====
+    {
+        name: 'walmart_ad_get_campaigns',
+        description: 'List Walmart Connect advertising campaigns. Supports Sponsored Products (auto/keyword), Sponsored Brands, and Sponsored Videos.',
+        inputSchema: {
+            campaignId: z.number().int().optional().describe('Filter by campaign ID'),
+            status: StatusSchema.optional().describe('Filter by status'),
+            name: z.string().optional().describe('Filter by campaign name'),
+        },
+    },
+    {
+        name: 'walmart_ad_create_campaign',
+        description: 'Create new advertising campaign(s). Body is an ARRAY of campaign objects (Walmart Connect ' +
+            'batch API). Each: { name, campaignType, targetingType, budgetType, dailyBudget, startDate ' +
+            '(YYYY-MM-DD), endDate?, status }. Default budgetType=daily, status=enabled.',
+        inputSchema: {
+            campaignData: z.array(CampaignCreateEntry).min(1, 'Need at least 1 campaign'),
+        },
+    },
+    {
+        name: 'walmart_ad_update_campaign',
+        description: 'Update existing campaigns. Body is ARRAY; each entry needs campaignId; updatable: name, ' +
+            'status, dailyBudget, totalBudget, endDate.',
+        inputSchema: {
+            campaignData: z.array(CampaignUpdateEntry).min(1),
+        },
+    },
+    {
+        name: 'walmart_ad_delete_campaign',
+        description: 'Archive/delete a campaign by ID. Cannot be undone.',
+        inputSchema: {
+            campaignId: z.number().int().positive().describe('Campaign ID to delete'),
+        },
+    },
+    // ===== Ad Groups =====
+    {
+        name: 'walmart_ad_get_ad_groups',
+        description: 'List ad groups, optionally filtered by campaign.',
+        inputSchema: {
+            campaignId: z.number().int().optional().describe('Filter by campaign ID'),
+            adGroupId: z.number().int().optional().describe('Filter by ad group ID'),
+            status: StatusSchema.optional(),
+        },
+    },
+    {
+        name: 'walmart_ad_create_ad_groups',
+        description: 'Create ad groups. Body is ARRAY; each entry needs campaignId, name, defaultBid. Status ' +
+            'defaults to enabled.',
+        inputSchema: {
+            groupData: z.array(AdGroupCreateEntry).min(1),
+        },
+    },
+    {
+        name: 'walmart_ad_update_ad_groups',
+        description: 'Update ad groups. Body is ARRAY; each needs adGroupId; updatable: name, status, defaultBid.',
+        inputSchema: {
+            groupData: z.array(AdGroupUpdateEntry).min(1),
+        },
+    },
+    // ===== Ad Items =====
+    {
+        name: 'walmart_ad_get_ad_items',
+        description: 'List ad items (SKUs in ad groups).',
+        inputSchema: {
+            campaignId: z.number().int().optional(),
+            adGroupId: z.number().int().optional(),
+        },
+    },
+    {
+        name: 'walmart_ad_add_ad_items',
+        description: 'Add SKUs to an ad group. Body is ARRAY; each entry needs campaignId, adGroupId, itemId, bid.',
+        inputSchema: {
+            itemData: z.array(AdItemAddEntry).min(1),
+        },
+    },
+    {
+        name: 'walmart_ad_update_ad_items',
+        description: 'Update ad items. Body is ARRAY; each needs adItemId; updatable: bid, status.',
+        inputSchema: {
+            itemData: z.array(AdItemUpdateEntry).min(1),
+        },
+    },
+    // ===== Keywords =====
+    {
+        name: 'walmart_ad_get_keywords',
+        description: 'List keywords in an ad group.',
+        inputSchema: {
+            campaignId: z.number().int().optional(),
+            adGroupId: z.number().int().optional(),
+            state: StatusSchema.optional(),
+        },
+    },
+    {
+        name: 'walmart_ad_add_keywords',
+        description: 'Add keywords to an ad group. Body is ARRAY; each entry needs campaignId, adGroupId, ' +
+            'keywordText, matchType (exact|phrase|broad), bid.',
+        inputSchema: {
+            keywordData: z.array(KeywordAddEntry).min(1),
+        },
+    },
+    {
+        name: 'walmart_ad_update_keywords',
+        description: 'Update keywords. Body is ARRAY; each needs keywordId; updatable: bid, state.',
+        inputSchema: {
+            keywordData: z.array(KeywordUpdateEntry).min(1),
+        },
+    },
+    {
+        name: 'walmart_ad_get_keyword_analytics',
+        description: 'Get keyword performance analytics (impressions, clicks, conversions).',
+        inputSchema: {
+            campaignId: z.number().int().optional(),
+            adGroupId: z.number().int().optional(),
+            keywordId: z.number().int().optional(),
+            startDate: DateOnlySchema.optional(),
+            endDate: DateOnlySchema.optional(),
+        },
+    },
+    // ===== Placement / Platform Bids =====
+    {
+        name: 'walmart_ad_create_placement_bids',
+        description: 'Set placement-specific bid multipliers. Body is ARRAY; each entry needs campaignId, ' +
+            'placement, bidMultiplier (e.g. 1.25 for +25%).',
+        inputSchema: {
+            bidData: z.array(PlacementBidEntry).min(1),
+        },
+    },
+    {
+        name: 'walmart_ad_get_placement_bids',
+        description: 'Get current placement bids for a campaign.',
+        inputSchema: {
+            campaignId: z.number().int().describe('Campaign ID'),
+        },
+    },
+    {
+        name: 'walmart_ad_create_platform_bids',
+        description: 'Set platform-specific (desktop/mobile/app) bid multipliers. Body is ARRAY; each entry ' +
+            'needs campaignId, platform, bidMultiplier.',
+        inputSchema: {
+            bidData: z.array(PlatformBidEntry).min(1),
+        },
+    },
+    // ===== Reports / Insights =====
+    {
+        name: 'walmart_ad_create_report_snapshot',
+        description: 'Request a Walmart Connect report snapshot. reportType: campaign|adGroup|keyword|item|' +
+            'pageType|platform|placement. reportDate is YYYY-MM-DD.',
+        inputSchema: {
+            reportData: ReportSnapshotCreateSchema,
+        },
+    },
+    {
+        name: 'walmart_ad_get_report_snapshots',
+        description: 'List previously requested report snapshots.',
+        inputSchema: {
+            reportType: z.string().optional(),
+        },
+    },
+    {
+        name: 'walmart_ad_get_realtime_stats',
+        description: 'Get realtime campaign stats (latency ~1-5 min, partial data).',
+        inputSchema: {
+            campaignId: z.number().int().optional(),
+        },
+    },
+    {
+        name: 'walmart_ad_get_latest_report_date',
+        description: 'Get the latest available data date for analytic reports.',
+        inputSchema: {},
+    },
+    {
+        name: 'walmart_ad_get_item_recommendations',
+        description: 'Get item recommendations to add to a campaign based on performance.',
+        inputSchema: {
+            campaignId: z.number().int().describe('Campaign ID'),
+        },
+    },
+    {
+        name: 'walmart_ad_get_keyword_recommendations',
+        description: 'Get keyword suggestions for an ad group based on indexed items.',
+        inputSchema: {
+            adGroupId: z.number().int().describe('Ad group ID'),
+            campaignId: z.number().int().optional(),
+        },
+    },
+    {
+        name: 'walmart_ad_get_search_trends',
+        description: 'Get top search trends on Walmart.com to inform keyword strategy.',
+        inputSchema: {
+            category: z.string().optional(),
+        },
+    },
+    {
+        name: 'walmart_ad_get_sba_profile',
+        description: 'Get Sponsored Brands (SBA) advertiser profile. Shows eligibility, brand info, and account status.',
+        inputSchema: {},
+    },
+];

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

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export declare const discoveryTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        method: z.ZodEnum<["GET", "POST", "PUT", "DELETE", "PATCH"]>;
+        path: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        query?: undefined;
+        limit?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        query: z.ZodString;
+        limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        method?: undefined;
+        path?: undefined;
+        params?: undefined;
+        body?: undefined;
+    };
+})[];

package/build/tools/definitions/discovery.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+/**
+ * Discovery-pattern escape hatch for Walmart Marketplace endpoints not covered
+ * by a dedicated wrapped tool. The 127 wrapped tools cover ~90 % of common
+ * seller workflows, but Walmart ships new endpoints frequently and the long
+ * tail (esoteric report types, partner-only beta endpoints, etc.) can be
+ * reached via this single meta-tool until a dedicated wrapper is added.
+ *
+ * Trade-offs vs a wrapped tool:
+ *   - No business-rule validation (LLM must build the payload).
+ *   - No known-issues hint specific to the call (still gets the generic
+ *     endpoint + tool fields in error responses).
+ *   - Auth headers + rate limiting + retry still applied — the call goes
+ *     through the same WalmartApiClient.
+ *
+ * Use sparingly. If you find yourself calling the same custom endpoint
+ * repeatedly, open an issue requesting a wrapped tool.
+ */
+const MethodSchema = z
+    .enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])
+    .describe('HTTP method, uppercase.');
+const PathSchema = z
+    .string()
+    .regex(/^\/v\d+\//, "path must start with /v<digit>/ (e.g. '/v3/items')")
+    .max(500, 'path too long');
+const QueryParamsSchema = z
+    .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+    .optional()
+    .describe('Optional query string parameters.');
+const BodySchema = z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe('Optional request body. Use a plain JSON object — the MCP serializes it to JSON. ' +
+    'Walmart will respond with its own validation error if fields are missing.');
+export const discoveryTools = [
+    {
+        name: 'walmart_call_endpoint',
+        description: 'Discovery escape hatch: call any Walmart Marketplace endpoint by method + path. Auth, ' +
+            'correlation ID, rate limiting, and 401/429/5xx retry are still applied — this is NOT a ' +
+            'raw socket. The response is wrapped with the same EXTERNAL DATA marker as wrapped tools. ' +
+            'Use this only for endpoints not covered by a dedicated walmart_* tool. If you call the ' +
+            'same endpoint repeatedly, open an issue requesting a wrapped tool with a strict schema. ' +
+            "Example: walmart_call_endpoint({ method: 'GET', path: '/v3/items', params: { limit: 5 } }).",
+        inputSchema: {
+            method: MethodSchema,
+            path: PathSchema,
+            params: QueryParamsSchema,
+            body: BodySchema,
+        },
+    },
+    {
+        name: 'walmart_search_endpoints',
+        description: 'Search known Walmart Marketplace endpoint patterns by keyword. Returns suggestions for ' +
+            'the dedicated wrapped tool to use (if any), plus the raw method + path so you can fall ' +
+            'back to walmart_call_endpoint. Use this when you do not know which tool wraps a given ' +
+            'Walmart capability.',
+        inputSchema: {
+            query: z
+                .string()
+                .min(2, 'query too short')
+                .describe("Search keyword, e.g. 'feed status', 'return refund', 'lag time'."),
+            limit: z.number().int().min(1).max(20).default(10).optional(),
+        },
+    },
+];

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

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export declare const feedTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        limit: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
+        feedType: z.ZodOptional<z.ZodString>;
+        feedId?: undefined;
+        feedData?: undefined;
+        maxWaitSeconds?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        feedId: z.ZodString;
+        limit?: undefined;
+        offset?: undefined;
+        feedType?: undefined;
+        feedData?: undefined;
+        maxWaitSeconds?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        feedType: z.ZodString;
+        feedData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        limit?: undefined;
+        offset?: undefined;
+        feedId?: undefined;
+        maxWaitSeconds?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        feedId: z.ZodString;
+        maxWaitSeconds: z.ZodOptional<z.ZodNumber>;
+        limit?: undefined;
+        offset?: undefined;
+        feedType?: undefined;
+        feedData?: undefined;
+    };
+})[];

package/build/tools/definitions/feeds.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export const feedTools = [
+    {
+        name: 'walmart_get_all_feed_statuses',
+        description: 'Get status of all feeds with optional filtering. Returns feedId, feedType, status, and timestamps.',
+        inputSchema: {
+            limit: z.number().int().min(1).max(50).optional().describe('Results per page (default 50)'),
+            offset: z.number().int().min(0).optional().describe('Pagination offset'),
+            feedType: z.string().optional().describe('Filter by feed type (e.g., item, inventory, price)'),
+        },
+    },
+    {
+        name: 'walmart_get_feed_status',
+        description: 'Get the status of a specific feed by feedId. Returns overall feed status: RECEIVED, INPROGRESS, PROCESSED, or ERROR.',
+        inputSchema: {
+            feedId: z.string().describe('Feed ID returned from a feed submission'),
+        },
+    },
+    {
+        name: 'walmart_get_feed_item_status',
+        description: 'Get per-item results for a feed. Shows SUCCESS, DATA_ERROR, SYSTEM_ERROR, or TIMEOUT_ERROR for each item in the feed.',
+        inputSchema: {
+            feedId: z.string().describe('Feed ID to get item-level details for'),
+        },
+    },
+    {
+        name: 'walmart_submit_generic_feed',
+        description: 'Submit a feed of any type. Use specific feed tools (walmart_submit_item_feed, etc.) when possible. This is for custom feed types.',
+        inputSchema: {
+            feedType: z.string().describe('Feed type (e.g., item, MP_MAINTENANCE, inventory, price, PROMO_PRICE, LAGTIME)'),
+            feedData: z.record(z.string(), z.unknown()).describe('Feed payload data'),
+        },
+    },
+    {
+        name: 'walmart_poll_feed_until_complete',
+        description: 'Poll a feed status until it completes (PROCESSED or ERROR) or times out. Uses progressive polling intervals: 15s, 30s, 1m, 2m, then every 4m. Max wait: 2 hours.',
+        inputSchema: {
+            feedId: z.string().describe('Feed ID to poll'),
+            maxWaitSeconds: z.number().int().min(30).max(7200).optional().describe('Max wait time in seconds (default 7200 = 2 hours)'),
+        },
+    },
+];