ebay-mcp 1.14.2 → 1.15.0

package/build/schemas/inventory-management/inventory.js

@@ -55,7 +55,7 @@ const productIdentifierSchema = z.object({
     ktype: z.string().optional(),
 });
 const productSchema = z.object({
-    title: z.string().optional(),
+    title: z.string().max(80).optional(),
     aspects: z.record(z.array(z.string())).optional(),
     brand: z.string().optional(),
     description: z.string().optional(),
@@ -244,7 +244,7 @@ export const offerResponseSchema = offerSchema.extend({
  */
 export const getOffersInputSchema = z.object({
     format: z.string().optional().describe('Filter offers by listing format'),
-    sku: z.string().optional().describe('Filter offers by SKU'),
+    sku: z.string().min(1).describe('Seller-defined SKU whose offers to return'),
     marketplaceId: z.nativeEnum(MarketplaceId).optional().describe('Filter offers by marketplace'),
     limit: z.number().optional().describe('Number of offers to return'),
     offset: z.number().optional().describe('Number of offers to skip'),
@@ -263,6 +263,25 @@ export const getOffersOutputSchema = z.object({
     total: z.number().optional(),
     warnings: z.array(errorSchema).optional(),
 });
+/** Validates the aggregate response from the bounded multi-SKU offer lookup. */
+export const getOffersBySkusOutputSchema = z.object({
+    requestedSkuCount: z.number(),
+    uniqueSkuCount: z.number(),
+    successCount: z.number(),
+    failureCount: z.number(),
+    results: z.array(z.union([
+        z.object({
+            sku: z.string(),
+            status: z.enum(['success']),
+            response: getOffersOutputSchema,
+        }),
+        z.object({
+            sku: z.string(),
+            status: z.enum(['failure']),
+            error: z.object({ type: z.string(), message: z.string() }),
+        }),
+    ])),
+});
 /**
  * Validates the Inventory Management API create offer request payload.
  */

package/build/scripts/diagnostics.js

@@ -3,11 +3,12 @@
  *
  * Usage:
  *   npm run diagnose
- *   npx ebay-mcp --diagnose
+ *   ebay-mcp diagnose
+ *   ebay-mcp diagnose --export
  */
 import chalk from 'chalk';
 import { writeFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { runSecurityChecks, displaySecurityResults } from '../scripts/securityChecker.js';
 import { validateSetup, displayRecommendations } from '../scripts/setupValidator.js';
@@ -235,7 +236,7 @@ async function generateDiagnosticReport(exportPath) {
 /**
  * Main diagnostics function
  */
-async function runDiagnostics(exportReport = false) {
+export const runDiagnostics = async (exportReport = false) => {
     displayHeader();
     displaySystemInfo();
     await displayUpdateStatus();
@@ -295,16 +296,21 @@ async function runDiagnostics(exportReport = false) {
     console.log(chalk.bold.green('✅ Diagnostics complete!\n'));
     console.log(chalk.gray('For more help, visit:'));
     console.log(chalk.blue.underline('  https://github.com/YosefHayim/ebay-mcp#troubleshooting\n'));
+};
+// Direct script entry (`node build/scripts/diagnostics.js` / `npm run diagnose`).
+// Guarded so importing from the bin does not auto-run diagnostics.
+const entryPath = process.argv[1] ? resolve(process.argv[1]) : undefined;
+const modulePath = resolve(fileURLToPath(import.meta.url));
+if (entryPath && modulePath === entryPath) {
+    const cliArgs = process.argv.slice(2);
+    const exportReport = cliArgs.includes('--export') || cliArgs.includes('-e');
+    void Effect.runPromise(Effect.either(Effect.tryPromise({
+        try: () => runDiagnostics(exportReport),
+        catch: (error) => error,
+    }))).then((result) => {
+        if (Either.isLeft(result)) {
+            console.error(chalk.red('\n❌ Diagnostics failed:'), getErrorMessage(result.left));
+            process.exitCode = 1;
+        }
+    });
 }
-// CLI handler
-const args = process.argv.slice(2);
-const exportReport = args.includes('--export') || args.includes('-e');
-void Effect.runPromise(Effect.either(Effect.tryPromise({
-    try: () => runDiagnostics(exportReport),
-    catch: (error) => error,
-}))).then((result) => {
-    if (Either.isLeft(result)) {
-        console.error(chalk.red('\n❌ Diagnostics failed:'), getErrorMessage(result.left));
-        process.exitCode = 1;
-    }
-});

package/build/skills/content.js

@@ -40,12 +40,10 @@ export const buildUsingDoc = (snapshot) => ({
             body: [
                 '**Publish a fixed-price listing (REST Inventory model).**',
                 '1. One-time account setup: `ebay_opt_in_to_program` (business-policy management), then `ebay_create_payment_policy`, `ebay_create_return_policy`, `ebay_create_fulfillment_policy` for reusable policy IDs, and `ebay_create_inventory_location` for a `merchantLocationKey`.',
-                '2. `ebay_create_or_replace_inventory_item` (SKU + product details + availability).',
-                '3. `ebay_create_offer` (SKU, marketplace, price, the policy IDs, location).',
-                '4. `ebay_publish_offer` (offerId) → a live `listingId`. Use `ebay_bulk_publish_offer` for many at once.',
-                '',
-                '**Pick the right category & required item specifics first.**',
-                '`ebay_get_default_category_tree_id` (marketplace) → `ebay_get_category_suggestions` (query) → `ebay_get_item_aspects_for_category` to learn the required aspects to put on the inventory item.',
+                '2. Pick the category and fetch its current item-specific requirements: `ebay_get_default_category_tree_id` (marketplace) → `ebay_get_category_suggestions` (query) → `ebay_get_item_aspects_for_category`.',
+                '3. Add every required aspect from that response to `ebay_create_or_replace_inventory_item` (SKU + product details + availability). Requirements vary by category and marketplace; do not treat examples from another category as permanent rules.',
+                '4. `ebay_create_offer` (SKU, marketplace, price, the policy IDs, location).',
+                '5. Check the aspects again when the category changes and before `ebay_get_listing_fees`, then `ebay_publish_offer` (offerId) → a live `listingId`. Use `ebay_bulk_publish_offer` for many at once.',
                 '',
                 '**Fulfill an order.**',
                 '`ebay_get_orders` (filter unfulfilled) → `ebay_get_order` (detail) → `ebay_create_shipping_fulfillment` (tracking number + carrier).',
@@ -68,6 +66,7 @@ export const buildUsingDoc = (snapshot) => ({
             body: [
                 '- **Two listing models.** REST Inventory (`inventory_item` → `offer` → `publish`) vs legacy Trading (XML). Pick one per SKU and stay in it.',
                 '- **Offers need policies + a location first.** A "policy not found" error usually means the one-time account setup was skipped.',
+                '- **Item specifics are category-specific.** Use `ebay_get_item_aspects_for_category` for the selected category instead of relying on a fixed fallback value or requirements learned from another category.',
                 '- **`search` and `fetch` are ChatGPT-connector only** — ignore them when driving the Sell API directly.',
                 '- **Write actions are real.** `publish`, `issue_refund`, `end_listing`, and any `bulk_*` change live seller data — confirm intent before calling.',
             ].join('\n'),

package/build/tools/categories/account.js

@@ -63,7 +63,16 @@ export const accountEntries = [
     }),
     defineTool({
         name: 'ebay_create_fulfillment_policy',
-        description: 'Create a new fulfillment policy.\n\nRequired OAuth Scope: sell.account\nMinimum Scope: https://api.ebay.com/oauth/api_scope/sell.account',
+        description: 'Create a new fulfillment policy.\n\n' +
+            'shippingServiceCode must be a marketplace-valid eBay service enum (not a free-form carrier nickname). ' +
+            'Invalid codes return "Please select a valid shipping service". eBay may cite DomesticItemShippingService[0] ' +
+            'and [1] for a single bad entry — that is remote validation, not client array duplication. ' +
+            'Discover valid codes via Trading GeteBayDetails (ShippingServiceDetails). ' +
+            'Known-good EBAY_US FLAT_RATE sketch: policy.name, policy.marketplaceId=EBAY_US, ' +
+            'policy.categoryTypes=[{name:ALL_EXCLUDING_MOTORS_VEHICLES}], policy.handlingTime={unit:DAY,value:1}, ' +
+            'policy.shippingOptions=[{costType:FLAT_RATE,optionType:DOMESTIC,shippingServices:[{shippingServiceCode:USPSPriority,shippingCost:{currency:USD,value:"5.99"}}]}]. ' +
+            'Avoid invented codes like USPSPriorityMail. Sandbox may accept a smaller code set than production.\n\n' +
+            'Required OAuth Scope: sell.account\nMinimum Scope: https://api.ebay.com/oauth/api_scope/sell.account',
         inputSchema: createFulfillmentPolicyInputSchema.shape,
         outputSchema: zodToJsonSchema(createFulfillmentPolicyOutputSchema, {
             name: 'CreateFulfillmentPolicyResponse',
@@ -96,7 +105,7 @@ export const accountEntries = [
     }),
     defineTool({
         name: 'ebay_update_fulfillment_policy',
-        description: 'Update an existing fulfillment policy',
+        description: 'Update an existing fulfillment policy.\n\nRequired OAuth Scope: sell.account\nMinimum Scope: https://api.ebay.com/oauth/api_scope/sell.account',
         inputSchema: updateFulfillmentPolicyInputSchema.shape,
         outputSchema: zodToJsonSchema(createFulfillmentPolicyOutputSchema, {
             name: 'UpdateFulfillmentPolicyResponse',

package/build/tools/categories/inventory.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
 import { defineTool } from '../../tools/defineTool.js';
 import { mapInventoryItemsToTable, mapInventoryItemToCard, mapLocationsToTable, mapOffersToTable, mapOfferToCard, } from '../../tools/ui/maps.js';
 import { MarketplaceId } from '../../types/ebayEnums.js';
-import { bulkInventoryItemResponseSchema, bulkOfferResponseSchema, bulkPublishResponseSchema, createInventoryItemOutputSchema, createInventoryLocationOutputSchema, createOfferOutputSchema, getInventoryItemGroupOutputSchema, getInventoryItemOutputSchema, getInventoryItemsOutputSchema, getInventoryLocationsOutputSchema, getOffersOutputSchema, getProductCompatibilityOutputSchema, offerResponseSchema, publishOfferOutputSchema, } from '../../schemas/inventory-management/inventory.js';
+import { bulkInventoryItemResponseSchema, bulkOfferResponseSchema, bulkPublishResponseSchema, createInventoryItemOutputSchema, createInventoryLocationOutputSchema, createOfferOutputSchema, getInventoryItemGroupOutputSchema, getInventoryItemOutputSchema, getInventoryItemsOutputSchema, getInventoryLocationsOutputSchema, getOffersInputSchema, getOffersOutputSchema, getOffersBySkusOutputSchema, getProductCompatibilityOutputSchema, inventoryItemSchema, offerResponseSchema, publishOfferOutputSchema, } from '../../schemas/inventory-management/inventory.js';
 const emptyOutputSchema = {
     type: 'object',
     properties: {},
@@ -23,7 +23,7 @@ const inventoryPaginationInputSchema = z.object({
     offset: z.number().optional().describe('Number of records to skip'),
 });
 const createOrReplaceInventoryItemInputSchema = skuInputSchema.extend({
-    body: generatedBodySchema('Generated InventoryItem request body'),
+    body: inventoryItemSchema,
 });
 const bulkCreateOrReplaceInventoryItemInputSchema = z.object({
     body: generatedBodySchema('Generated BulkInventoryItem request body'),
@@ -52,12 +52,14 @@ const createInventoryLocationInputSchema = merchantLocationKeyInputSchema.extend
 const updateInventoryLocationInputSchema = merchantLocationKeyInputSchema.extend({
     body: generatedBodySchema('Generated InventoryLocation request body'),
 });
-const getOffersInputSchema = z.object({
+const getOffersBySkusInputSchema = z.object({
+    skus: z
+        .array(z.string().min(1).max(50))
+        .min(1)
+        .max(25)
+        .describe('1-25 seller SKUs; exact duplicates are queried once in first-occurrence order'),
     format: z.string().optional().describe('Filter by listing format'),
-    limit: z.number().optional().describe('Number of offers to return'),
     marketplaceId: z.nativeEnum(MarketplaceId).optional().describe('Filter by marketplace ID'),
-    offset: z.number().optional().describe('Number of offers to skip'),
-    sku: z.string().optional().describe('Filter by SKU'),
 });
 const offerIdInputSchema = z.object({
     offerId: z.string().describe('The offer ID'),
@@ -145,7 +147,12 @@ export const inventoryEntries = [
             name: 'CreateOrReplaceInventoryItemResponse',
             $refStrategy: 'none',
         }),
-        handler: (api, args) => Effect.runPromise(api.inventory.createOrReplaceInventoryItem(args)),
+        handler: (api, args) => Effect.runPromise(api.inventory.createOrReplaceInventoryItem({
+            ...args,
+            // The generated OpenAPI type incorrectly models `product.aspects` as a
+            // string; the endpoint wire contract and validation schema use a map.
+            body: args.body,
+        })),
     }),
     defineTool({
         name: 'ebay_delete_inventory_item',
@@ -302,7 +309,7 @@ export const inventoryEntries = [
     }),
     defineTool({
         name: 'ebay_get_offers',
-        description: 'Get all offers for the seller',
+        description: 'Get offers for one seller-defined SKU. To enumerate offers across SKUs, call ebay_get_inventory_items first, then call this tool once per SKU.',
         inputSchema: getOffersInputSchema.shape,
         outputSchema: zodToJsonSchema(getOffersOutputSchema, {
             name: 'GetOffersResponse',
@@ -311,6 +318,16 @@ export const inventoryEntries = [
         handler: (api, args) => Effect.runPromise(api.inventory.getOffers(args)),
         ui: { archetype: 'table', map: mapOffersToTable },
     }),
+    defineTool({
+        name: 'ebay_get_offers_by_skus',
+        description: 'Get offers for 1-25 SKUs. Exact duplicates are queried once, at most 3 eBay requests run concurrently, and every SKU has its own success or failure result.',
+        inputSchema: getOffersBySkusInputSchema.shape,
+        outputSchema: zodToJsonSchema(getOffersBySkusOutputSchema, {
+            name: 'GetOffersBySkusResponse',
+            $refStrategy: 'none',
+        }),
+        handler: (api, args) => Effect.runPromise(api.inventory.getOffersBySkus(args)),
+    }),
     defineTool({
         name: 'ebay_get_offer',
         description: 'Get a specific offer by ID',

package/build/tools/categories/taxonomy.js

@@ -65,14 +65,14 @@ export const taxonomyEntries = [
     }),
     defineTool({
         name: 'ebay_get_item_aspects_for_category',
-        description: 'Get item aspects for a specific category',
+        description: 'Identify required and recommended item specifics for a category before creating an inventory item or checking listing fees',
         inputSchema: getItemAspectsForCategorySchema.shape,
         outputSchema: {
             type: 'object',
             properties: {
                 aspects: { type: 'array' },
             },
-            description: 'Item aspects for category',
+            description: 'Required and recommended item specifics for the category',
         },
         handler: (api, args) => Effect.runPromise(api.taxonomy.getItemAspectsForCategory(args)),
     }),

package/build/utils/errors.js

@@ -1,3 +1,4 @@
+import { Cause, Runtime } from 'effect';
 /**
  * Normalize an unknown thrown value into a human-readable message string.
  *
@@ -18,3 +19,86 @@
  * ```
  */
 export const getErrorMessage = (error, fallback = 'Unknown error') => error instanceof Error ? error.message : fallback;
+const asRecord = (value) => typeof value === 'object' && value !== null ? value : undefined;
+const nextErrorNode = (node) => {
+    const fiberCause = node[Runtime.FiberFailureCauseId];
+    if (fiberCause !== undefined) {
+        return Cause.squash(fiberCause);
+    }
+    return node.cause;
+};
+const firstEbayErrorMessage = (errors) => {
+    const first = asRecord(errors[0]);
+    if (!first) {
+        return;
+    }
+    const detail = first.longMessage ?? first.message;
+    return typeof detail === 'string' ? detail : undefined;
+};
+const KIND_IS_GUIDANCE = {
+    missingCredentials: true,
+    localRateLimit: true,
+    tokenAcquisition: true,
+    missingAccessToken: true,
+    tokenRefresh: true,
+    remoteRateLimit: true,
+    httpStatus: false,
+    transport: false,
+};
+const isGuidanceKind = (kind) => Object.hasOwn(KIND_IS_GUIDANCE, kind) && KIND_IS_GUIDANCE[kind];
+const collectEbayErrorNode = (node, acc) => {
+    const message = typeof node.message === 'string' && node.message.length > 0 ? node.message : undefined;
+    if (message !== undefined && !acc.messageLocked) {
+        acc.message = message;
+        if (typeof node.kind === 'string' && isGuidanceKind(node.kind)) {
+            acc.messageLocked = true;
+        }
+    }
+    if (typeof node.status === 'number') {
+        acc.status = node.status;
+    }
+    const data = asRecord(node.data);
+    if (data && Array.isArray(data.errors)) {
+        acc.errors = data.errors;
+        const detail = firstEbayErrorMessage(data.errors);
+        if (detail && !acc.messageLocked) {
+            acc.message = detail;
+        }
+        return;
+    }
+    // Trading XML failures store their structured entries directly on `cause`.
+    if (acc.errors === undefined && Array.isArray(node.cause) && node.cause.length > 0) {
+        acc.errors = node.cause;
+    }
+};
+/**
+ * Recovers status, structured eBay errors, and the best message from nested
+ * tagged errors and Effect FiberFailures.
+ *
+ * @param error - Failure caught at an external boundary.
+ * @returns Structured details suitable for an MCP error result.
+ *
+ * @example
+ * ```ts
+ * const details = getEbayErrorDetails(error);
+ * ```
+ */
+export const getEbayErrorDetails = (error) => {
+    const acc = { message: getErrorMessage(error) };
+    const seen = new Set();
+    let current = error;
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const node = asRecord(current);
+        if (!node) {
+            break;
+        }
+        collectEbayErrorNode(node, acc);
+        current = nextErrorNode(node);
+    }
+    return {
+        message: acc.message,
+        ...(acc.status === undefined ? {} : { status: acc.status }),
+        ...(acc.errors === undefined ? {} : { errors: acc.errors }),
+    };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ebay-mcp",
-  "version": "1.14.2",
-  "description": "Model Context Protocol (MCP) server that exposes 100% of eBay's Sell APIs (322 tools across 270 endpoints) to AI assistants like Claude, Cursor, and Cline, covering inventory, order fulfillment, marketing, analytics, and developer tools with OAuth authentication and refresh-token support.",
+  "version": "1.15.0",
+  "description": "Model Context Protocol (MCP) server that exposes 100% of eBay's Sell APIs (299 tools across 270 endpoints) to AI assistants like Claude, Cursor, and Cline, covering inventory, order fulfillment, marketing, analytics, and developer tools with OAuth authentication and refresh-token support.",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -109,10 +109,10 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:integration": "vitest run --config vitest.integration.config.cts",
-    "setup": "tsx src/scripts/setup.ts",
-    "skills": "tsx src/scripts/skills.ts",
+    "setup": "node build/scripts/setup.js",
+    "skills": "node build/scripts/skills.js",
     "sync": "tsx src/scripts/devSync.ts",
-    "diagnose": "tsx src/scripts/diagnostics.ts",
+    "diagnose": "node build/scripts/diagnostics.js",
     "typecheck": "tsc --noEmit",
     "typecheck:ui": "tsc -p ui/tsconfig.json --noEmit",
     "check": "tsc --noEmit && tsc -p ui/tsconfig.json --noEmit && biome check \"{src,ui}/**/*.{ts,tsx,js,json,md,css,html}\"",