ebay-mcp 1.14.3 → 1.15.0

package/README.ru.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>MCP-сервер eBay — дайте Claude, Cursor и любому ИИ-ассистенту полный доступ к Sell API eBay. 298 инструмента для инвентаря, заказов, маркетинга и аналитики, работающих локально с вашими собственными ключами.</strong>
+  <strong>MCP-сервер eBay — дайте Claude, Cursor и любому ИИ-ассистенту полный доступ к Sell API eBay. 299 инструмента для инвентаря, заказов, маркетинга и аналитики, работающих локально с вашими собственными ключами.</strong>
 </p>
 
 <p align="center"><sub>Неофициальный проект с открытым исходным кодом — не связан с eBay Inc., не авторизован и не одобрен ею.</sub></p>
@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tools-298-8957e5?logo=ebay&logoColor=white" alt="298 инструмента API eBay" />
+  <img src="https://img.shields.io/badge/tools-299-8957e5?logo=ebay&logoColor=white" alt="299 инструмента API eBay" />
   <img src="https://img.shields.io/badge/Sell%20API%20coverage-100%25-success" alt="100% покрытие Sell API eBay" />
   <img src="https://img.shields.io/badge/Model%20Context%20Protocol-compatible-000000" alt="совместим с Model Context Protocol" />
   <img src="https://img.shields.io/badge/tests-1%2C000%2B%20passing-3fb950?logo=vitest&logoColor=white" alt="более 1000 пройденных тестов" />
@@ -47,7 +47,7 @@
 
 > **Примечание:** английский [README.md](README.md) — источник истины для актуальных продуктовых формулировок (семейства инструментов, вывод API из эксплуатации, заметки о версиях). Этот перевод может отставать.
 
-**eBay MCP** — это локальный сервер [Model Context Protocol](https://modelcontextprotocol.io), который подключает ИИ-ассистентов —Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code и Amazon Q— напрямую к **Sell API eBay**. Он предоставляет **298 инструмента**, охватывающих **100% поверхности Sell API eBay** (270 уникальных эндпоинтов): управление инвентарём, обработка заказов, маркетинг продвигаемых объявлений, аналитика и инструменты разработчика. Всё работает на вашей машине через STDIO или локальный HTTP — **без облачного ретранслятора**, и ваши учётные данные eBay никогда не покидают компьютер.
+**eBay MCP** — это локальный сервер [Model Context Protocol](https://modelcontextprotocol.io), который подключает ИИ-ассистентов —Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code и Amazon Q— напрямую к **Sell API eBay**. Он предоставляет **299 инструмента**, охватывающих **100% поверхности Sell API eBay** (270 уникальных эндпоинтов): управление инвентарём, обработка заказов, маркетинг продвигаемых объявлений, аналитика и инструменты разработчика. Всё работает на вашей машине через STDIO или локальный HTTP — **без облачного ретранслятора**, и ваши учётные данные eBay никогда не покидают компьютер.
 
 > **Отказ от ответственности:** Неофициальный сторонний проект — **не связан с eBay Inc. и не одобрен ею.** Предоставляется «как есть», без гарантий. Вы сами отвечаете за соблюдение [Лицензионного соглашения API eBay](https://developer.ebay.com/join/api-license-agreement) и [требований к обработке данных](https://developer.ebay.com/api-docs/static/data-handling-update.html), за сохранность учётных данных и за соблюдение лимитов запросов. Протестируйте в песочнице перед продакшеном. См. [LICENSE](LICENSE), [SECURITY.md](SECURITY.md) и [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md).
 
@@ -71,7 +71,7 @@
 
 ## Возможности
 
-- **298 инструмента API eBay** — 100% покрытие Sell API eBay: инвентарь, заказы, маркетинг, аналитика, метаданные, таксономия и инструменты разработчика.
+- **299 инструмента API eBay** — 100% покрытие Sell API eBay: инвентарь, заказы, маркетинг, аналитика, метаданные, таксономия и инструменты разработчика.
 - **9 ИИ-клиентов с автонастройкой** — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI и Amazon Q Developer.
 - **Встроенный OAuth 2.0** — полное управление пользовательскими токенами с автоматическим обновлением и умным переходом от пользовательских токенов (10–50 тыс. запросов/день) к клиентским учётным данным (1 тыс. запросов/день).
 - **Надёжность по умолчанию** — автоматический повтор с экспоненциальной задержкой при лимитах `429` и понятный, последовательный вывод ошибок.
@@ -93,7 +93,7 @@
 | Валидация входных данных | Схемы Zod + типы TypeScript на каждом инструменте | Нет — вы проверяете свои полезные данные сами |
 | Настройка | Один мастер (`npm run setup`) | Авторизация, заголовки и маркетплейс на каждый вызов |
 | Поддержка ИИ-клиентов | 9 клиентов с автонастройкой | Неприменимо |
-| Покрытие API | 298 инструмента на 100% Sell API, готовы к вызову | Вы строите каждый запрос по документации |
+| Покрытие API | 299 инструмента на 100% Sell API, готовы к вызову | Вы строите каждый запрос по документации |
 | Размещение | Работает локально, без облачного ретранслятора | Ваша собственная инфраструктура |
 
 ## Настройка с помощью ИИ в один клик
@@ -236,7 +236,7 @@ EBAY_MCP_UI=on                      # интерактивные предста
 
 ## Доступные инструменты
 
-**298 инструмента**, 100% покрытие Sell API, сгруппированы по категориям. Каждая ссылка ведёт к определениям инструментов и их обработчикам в [`src/tools/categories/`](src/tools/categories/):
+**299 инструмента**, 100% покрытие Sell API, сгруппированы по категориям. Каждая ссылка ведёт к определениям инструментов и их обработчикам в [`src/tools/categories/`](src/tools/categories/):
 
 | Категория | Что вы можете делать |
 | --- | --- |
@@ -299,7 +299,7 @@ EBAY_MCP_UI=on                      # интерактивные предста
 
 ### Что такое MCP-сервер eBay?
 
-Локальный сервер [Model Context Protocol](https://modelcontextprotocol.io), предоставляющий **298 инструмента**, охватывающих **100% Sell API eBay** (270 эндпоинтов), ИИ-ассистентам — инвентарь, обработка заказов, маркетинг, аналитика и инструменты разработчика.
+Локальный сервер [Model Context Protocol](https://modelcontextprotocol.io), предоставляющий **299 инструмента**, охватывающих **100% Sell API eBay** (270 эндпоинтов), ИИ-ассистентам — инвентарь, обработка заказов, маркетинг, аналитика и инструменты разработчика.
 
 ### Это официальный продукт eBay?
 
@@ -319,7 +319,7 @@ EBAY_MCP_UI=on                      # интерактивные предста
 
 ### Сколько API и инструментов eBay он охватывает?
 
-298 инструмента на 270 уникальных эндпоинтах — 100% Sell API eBay.
+299 инструмента на 270 уникальных эндпоинтах — 100% Sell API eBay.
 
 ### Это бесплатно и с открытым исходным кодом?
 

package/README.zh-CN.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>eBay MCP 服务器 — 让 Claude、Cursor 以及任意 AI 助手完全访问 eBay 的 Sell API。298 个工具覆盖库存、订单、营销与分析，使用你自己的密钥在本地运行。</strong>
+  <strong>eBay MCP 服务器 — 让 Claude、Cursor 以及任意 AI 助手完全访问 eBay 的 Sell API。299 个工具覆盖库存、订单、营销与分析，使用你自己的密钥在本地运行。</strong>
 </p>
 
 <p align="center"><sub>非官方开源项目 — 与 eBay Inc. 无任何关联，未获其授权或认可。</sub></p>
@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tools-298-8957e5?logo=ebay&logoColor=white" alt="298 个 eBay API 工具" />
+  <img src="https://img.shields.io/badge/tools-299-8957e5?logo=ebay&logoColor=white" alt="299 个 eBay API 工具" />
   <img src="https://img.shields.io/badge/Sell%20API%20coverage-100%25-success" alt="100% 覆盖 eBay Sell API" />
   <img src="https://img.shields.io/badge/Model%20Context%20Protocol-compatible-000000" alt="兼容 Model Context Protocol" />
   <img src="https://img.shields.io/badge/tests-1%2C000%2B%20passing-3fb950?logo=vitest&logoColor=white" alt="超过 1000 个通过的测试" />
@@ -47,7 +47,7 @@
 
 > **说明：** 英文 [README.md](README.md) 是最新产品说明（工具族、API 下线、版本说明）的权威来源。本翻译可能滞后。
 
-**eBay MCP** 是一个本地的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，可将 AI 助手 —Claude Desktop、Claude Code、Cursor、Cline、Windsurf、Zed、Continue.dev、Roo Code 和 Amazon Q— 直接连接到 **eBay 的 Sell API**。它提供 **298 个工具**，覆盖 **eBay Sell API 的 100% 范围**（270 个唯一端点），涵盖库存管理、订单履行、推广刊登营销、分析和开发者工具。一切都在你的机器上通过 STDIO 或本地 HTTP 运行 — **没有云端中继**，你的 eBay 凭据永远不会离开你的电脑。
+**eBay MCP** 是一个本地的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，可将 AI 助手 —Claude Desktop、Claude Code、Cursor、Cline、Windsurf、Zed、Continue.dev、Roo Code 和 Amazon Q— 直接连接到 **eBay 的 Sell API**。它提供 **299 个工具**，覆盖 **eBay Sell API 的 100% 范围**（270 个唯一端点），涵盖库存管理、订单履行、推广刊登营销、分析和开发者工具。一切都在你的机器上通过 STDIO 或本地 HTTP 运行 — **没有云端中继**，你的 eBay 凭据永远不会离开你的电脑。
 
 > **免责声明：** 非官方第三方项目 — **与 eBay Inc. 无关联，也未获其认可。** 按"原样"提供，不附带任何担保。你需自行负责遵守 [eBay API 许可协议](https://developer.ebay.com/join/api-license-agreement) 和 [数据处理要求](https://developer.ebay.com/api-docs/static/data-handling-update.html)、妥善保管你的凭据并遵守速率限制。在投入生产前请先在沙盒中测试。参见 [LICENSE](LICENSE)、[SECURITY.md](SECURITY.md) 和 [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md)。
 
@@ -71,7 +71,7 @@
 
 ## 功能特性
 
-- **298 个 eBay API 工具** — 100% 覆盖 eBay Sell API，涵盖库存、订单、营销、分析、元数据、分类法和开发者工具。
+- **299 个 eBay API 工具** — 100% 覆盖 eBay Sell API，涵盖库存、订单、营销、分析、元数据、分类法和开发者工具。
 - **自动配置 9 个 AI 客户端** — Claude Desktop、Cursor、Zed、Cline、Continue.dev、Windsurf、Roo Code、Claude Code CLI 和 Amazon Q Developer。
 - **内置 OAuth 2.0** — 完整的用户令牌管理与自动刷新，并能从用户令牌（每天 1 万–5 万次请求）智能回退到客户端凭据（每天 1 千次请求）。
 - **默认具备韧性** — 遇到 `429` 速率限制时自动重试并采用指数退避，错误提示清晰一致。
@@ -93,7 +93,7 @@
 | 输入校验 | 每个工具都有 Zod 模式 + TypeScript 类型 | 无 — 由你校验自己的载荷 |
 | 配置 | 一个向导（`npm run setup`） | 每次调用都要处理认证、请求头和站点 |
 | AI 客户端支持 | 自动配置 9 个客户端 | 不适用 |
-| API 覆盖 | 298 个工具覆盖 100% Sell API，开箱即用 | 你需根据文档构建每个请求 |
+| API 覆盖 | 299 个工具覆盖 100% Sell API，开箱即用 | 你需根据文档构建每个请求 |
 | 托管 | 本地运行，无云端中继 | 你自己的基础设施 |
 
 ## AI 一键配置
@@ -236,7 +236,7 @@ EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）
 
 ## 可用工具
 
-**298 个工具**，100% Sell API 覆盖，按类别组织。每个链接都指向 [`src/tools/categories/`](src/tools/categories/) 中的工具定义及其处理程序：
+**299 个工具**，100% Sell API 覆盖，按类别组织。每个链接都指向 [`src/tools/categories/`](src/tools/categories/) 中的工具定义及其处理程序：
 
 | 类别 | 你可以做什么 |
 | --- | --- |
@@ -299,7 +299,7 @@ EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）
 
 ### 什么是 eBay MCP 服务器？
 
-一个本地的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，向 AI 助手提供 **298 个工具**，覆盖 **eBay Sell API 的 100%**（270 个端点）—— 库存、订单履行、营销、分析和开发者工具。
+一个本地的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，向 AI 助手提供 **299 个工具**，覆盖 **eBay Sell API 的 100%**（270 个端点）—— 库存、订单履行、营销、分析和开发者工具。
 
 ### 这是 eBay 的官方产品吗？
 
@@ -319,7 +319,7 @@ EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）
 
 ### 它覆盖多少 eBay API 和工具？
 
-298 个工具，覆盖 270 个唯一端点 —— eBay Sell API 的 100%。
+299 个工具，覆盖 270 个唯一端点 —— eBay Sell API 的 100%。
 
 ### 它是免费且开源的吗？
 

package/build/api/client.js

@@ -6,7 +6,7 @@ import { getErrorMessage } from '../utils/errors.js';
 import { httpRequestEffect, isHttpError } from '../utils/http.js';
 import { isRecord } from '../utils/typeGuards.js';
 import { apiLogger, logRequest, logResponse, logErrorResponse } from '../utils/logger.js';
-import { Effect } from 'effect';
+import { Cause, Effect, Exit } from 'effect';
 /** Sleep for a retry backoff delay without exposing timers to callers. */
 const sleep = (delayMs) => Effect.promise(() => new Promise((resolve) => {
     setTimeout(resolve, delayMs);
@@ -96,7 +96,13 @@ export class EbayApiClient {
      * Core request boundary shared by every verb.
      */
     async request(method, endpoint, options) {
-        return await Effect.runPromise(this.requestEffect(method, endpoint, options));
+        // Preserve the typed request error for endpoint adapters. Plain runPromise
+        // rejects with a FiberFailure whose generic message hides eBay response data.
+        const exit = await Effect.runPromiseExit(this.requestEffect(method, endpoint, options));
+        if (Exit.isSuccess(exit)) {
+            return exit.value;
+        }
+        throw Cause.squash(exit.cause);
     }
     /**
      * Build the request Effect that owns auth, logging, retry, and transport errors.

package/build/api/listing-management/offers.js

@@ -1,6 +1,30 @@
-import { buildEndpointParams, optionalNonNegativeNumberEffect, optionalPositiveNumberEffect, optionalStringEffect, requestDeleteEffect, requestGetEffect, requestPostEffect, requestPutEffect, requireObjectEffect, requireStringEffect, } from '../../api/shared/request.js';
-import { Effect } from 'effect';
+import { EndpointInputError, buildEndpointParams, optionalNonNegativeNumberEffect, optionalPositiveNumberEffect, optionalStringEffect, requestDeleteEffect, requestGetEffect, requestPostEffect, requestPutEffect, requireObjectEffect, requireStringEffect, } from '../../api/shared/request.js';
+import { Effect, Either } from 'effect';
 import { INVENTORY_BASE_PATH } from './shared.js';
+/** Maximum number of SKU entries accepted by one batch lookup. */
+export const MAX_BATCH_GET_OFFERS_SKUS = 25;
+/** Maximum number of simultaneous eBay requests made by a batch lookup. */
+export const BATCH_GET_OFFERS_CONCURRENCY = 3;
+// Keep the shared request implementation private so the existing and batch methods cannot drift.
+const getOffersEffect = (client, input) => {
+    const path = `${INVENTORY_BASE_PATH}/offer`;
+    return Effect.gen(function* () {
+        const validatedInput = yield* requireObjectEffect(input, 'input');
+        const format = yield* optionalStringEffect(validatedInput.format, 'format');
+        const limit = yield* optionalPositiveNumberEffect(validatedInput.limit, 'limit');
+        const marketplaceId = yield* optionalStringEffect(validatedInput.marketplaceId, 'marketplaceId');
+        const offset = yield* optionalNonNegativeNumberEffect(validatedInput.offset, 'offset');
+        const sku = yield* requireStringEffect(validatedInput.sku, 'sku');
+        const params = buildEndpointParams({
+            format: { wireName: 'format', value: format },
+            limit: { wireName: 'limit', value: limit === undefined ? undefined : String(limit) },
+            marketplaceId: { wireName: 'marketplace_id', value: marketplaceId },
+            offset: { wireName: 'offset', value: offset === undefined ? undefined : String(offset) },
+            sku: { wireName: 'sku', value: sku },
+        });
+        return yield* requestGetEffect(client, path, params);
+    });
+};
 /** Inventory API — offers methods closed over a shared client. */
 export const createInventoryOffersMethods = (client) => ({
     /**
@@ -46,9 +70,9 @@ export const createInventoryOffersMethods = (client) => ({
         });
     },
     /**
-     * Retrieves offers with optional filters.
+     * Retrieves offers for one seller-defined SKU.
      *
-     * @param input - Optional offer filters and pagination controls.
+     * @param input - Required SKU plus optional offer filters and pagination controls.
      * @returns An Effect that succeeds with eBay's Offers response.
      *
      * @example
@@ -60,25 +84,56 @@ export const createInventoryOffersMethods = (client) => ({
      *
      * @see https://developer.ebay.com/api-docs/sell/inventory/resources/offer/methods/getOffers
      */
-    getOffers: (input = {}) => {
-        const path = `${INVENTORY_BASE_PATH}/offer`;
-        return Effect.gen(function* () {
-            const validatedInput = yield* requireObjectEffect(input, 'input');
-            const format = yield* optionalStringEffect(validatedInput.format, 'format');
-            const limit = yield* optionalPositiveNumberEffect(validatedInput.limit, 'limit');
-            const marketplaceId = yield* optionalStringEffect(validatedInput.marketplaceId, 'marketplaceId');
-            const offset = yield* optionalNonNegativeNumberEffect(validatedInput.offset, 'offset');
-            const sku = yield* optionalStringEffect(validatedInput.sku, 'sku');
-            const params = buildEndpointParams({
-                format: { wireName: 'format', value: format },
-                limit: { wireName: 'limit', value: limit === undefined ? undefined : String(limit) },
-                marketplaceId: { wireName: 'marketplace_id', value: marketplaceId },
-                offset: { wireName: 'offset', value: offset === undefined ? undefined : String(offset) },
-                sku: { wireName: 'sku', value: sku },
-            });
-            return yield* requestGetEffect(client, path, params);
-        });
-    },
+    getOffers: (input) => getOffersEffect(client, input),
+    /**
+     * Retrieves offers for up to 25 SKUs, preserving first-occurrence order.
+     *
+     * Exact duplicates are requested once. At most three requests run concurrently, and request
+     * failures are returned beside their SKU instead of failing the whole batch.
+     */
+    getOffersBySkus: (input) => Effect.gen(function* () {
+        const validatedInput = yield* requireObjectEffect(input, 'input');
+        if (!Array.isArray(validatedInput.skus)) {
+            return yield* Effect.fail(new EndpointInputError({ parameter: 'skus', message: 'skus must be an array' }));
+        }
+        if (validatedInput.skus.length === 0 ||
+            validatedInput.skus.length > MAX_BATCH_GET_OFFERS_SKUS) {
+            return yield* Effect.fail(new EndpointInputError({
+                parameter: 'skus',
+                message: `skus must contain between 1 and ${MAX_BATCH_GET_OFFERS_SKUS} entries`,
+            }));
+        }
+        for (const sku of validatedInput.skus) {
+            if (typeof sku !== 'string' || sku.trim().length === 0 || sku.length > 50) {
+                return yield* Effect.fail(new EndpointInputError({
+                    parameter: 'skus',
+                    message: 'each SKU must be a non-empty string of at most 50 characters',
+                }));
+            }
+        }
+        const format = yield* optionalStringEffect(validatedInput.format, 'format');
+        const marketplaceId = yield* optionalStringEffect(validatedInput.marketplaceId, 'marketplaceId');
+        const uniqueSkus = [...new Set(validatedInput.skus)];
+        const results = yield* Effect.forEach(uniqueSkus, (sku) => Effect.map(Effect.either(getOffersEffect(client, {
+            sku,
+            format,
+            marketplaceId,
+        })), (outcome) => Either.isRight(outcome)
+            ? { sku, status: 'success', response: outcome.right }
+            : {
+                sku,
+                status: 'failure',
+                error: { type: outcome.left._tag, message: outcome.left.message },
+            }), { concurrency: BATCH_GET_OFFERS_CONCURRENCY });
+        const successCount = results.filter((result) => result.status === 'success').length;
+        return {
+            requestedSkuCount: validatedInput.skus.length,
+            uniqueSkuCount: uniqueSkus.length,
+            successCount,
+            failureCount: results.length - successCount,
+            results,
+        };
+    }),
     /**
      * Creates one offer.
      *

package/build/auth/credentialSession.js

@@ -1,9 +1,8 @@
 import dotenv from 'dotenv';
 import stringify from 'dotenv-stringify';
 import { closeSync, existsSync, fsyncSync, openSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { CREDENTIAL_ENV_PATH } from '../config/credentialFile.js';
 import { Data, Effect } from 'effect';
-import process from 'node:process';
 /**
  * Default lifetime for stored eBay user access tokens when eBay omits an expiry.
  */
@@ -42,7 +41,7 @@ const writeLockForEnvPath = (envPath) => {
  */
 export class DotEnvCredentialStore {
     getEnvPath;
-    constructor(getEnvPath = () => join(process.cwd(), '.env')) {
+    constructor(getEnvPath = () => CREDENTIAL_ENV_PATH) {
         this.getEnvPath = getEnvPath;
     }
     /**

package/build/auth/oauth.js

@@ -1,4 +1,4 @@
-import { createAppAccessTokenExpiry, createStoredUserTokens, createStoredUserTokensFromResponse, DotEnvCredentialStore, isTokenExpired, } from '../auth/credentialSession.js';
+import { createAppAccessTokenExpiry, createStoredUserTokens, createStoredUserTokensFromResponse, CredentialStoreError, DotEnvCredentialStore, isTokenExpired, } from '../auth/credentialSession.js';
 import { getBaseUrl, getDefaultScopes } from '../config/environment.js';
 import { LocaleEnum } from '../types/ebayEnums.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -13,6 +13,7 @@ const mapCredentialStoreError = (operation, message, cause) => new EbayOAuthErro
     message: `${message}: ${cause.message}`,
     cause,
 });
+const isCredentialPersistenceError = (error) => error.cause instanceof CredentialStoreError;
 /**
  * Manages eBay OAuth 2.0 authentication
  * Loads tokens exclusively from validated runtime config
@@ -70,12 +71,20 @@ export class EbayOAuthClient {
             }));
             if (Either.isLeft(refreshed)) {
                 const error = refreshed.left;
-                authLogger.error('Failed to refresh access token', {
-                    error: getErrorMessage(error, String(error)),
-                    hint: 'The configured EBAY_USER_REFRESH_TOKEN may be invalid or expired',
-                });
-                // Clear invalid tokens
-                this.userTokens = null;
+                if (isCredentialPersistenceError(error)) {
+                    authLogger.error('Access token refreshed but could not be persisted', {
+                        error: getErrorMessage(error, String(error)),
+                        hint: 'The refreshed token remains available for this process, but the credential file must be writable to survive a restart',
+                    });
+                }
+                else {
+                    authLogger.error('Failed to refresh access token', {
+                        error: getErrorMessage(error, String(error)),
+                        hint: 'The configured EBAY_USER_REFRESH_TOKEN may be invalid or expired',
+                    });
+                    // Clear tokens only when the refresh itself failed.
+                    this.userTokens = null;
+                }
             }
         }
     });
@@ -135,10 +144,19 @@ export class EbayOAuthClient {
             }
             const refreshed = yield* Effect.either(this.refreshUserToken());
             if (Either.isLeft(refreshed)) {
+                if (isCredentialPersistenceError(refreshed.left) &&
+                    this.userTokens &&
+                    !this.isUserAccessTokenExpired(this.userTokens)) {
+                    authLogger.error('User token refreshed but could not be persisted', {
+                        error: getErrorMessage(refreshed.left, String(refreshed.left)),
+                        hint: 'Using the valid refreshed token for this process only',
+                    });
+                    return this.userTokens.userAccessToken;
+                }
                 authLogger.error('Failed to refresh user token, falling back to app access token', {
                     error: getErrorMessage(refreshed.left, String(refreshed.left)),
                 });
-                // Clear invalid tokens
+                // Clear tokens only when no valid refreshed access token remains.
                 this.userTokens = null;
             }
             else if (this.userTokens) {

package/build/auth/scopeUtils.js

@@ -126,6 +126,11 @@ export const getRequiredScopesForTool = (toolName) => {
             minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.account',
             description: 'Requires write access to account settings',
         },
+        ebay_update_fulfillment_policy: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.account'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.account',
+            description: 'Requires write access to account settings',
+        },
         // Marketing Tools
         ebay_get_campaigns: {
             requiredScopes: [

package/build/config/credentialFile.js

@@ -0,0 +1,16 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the credential `.env` file from an installed source or build module URL.
+ *
+ * @param moduleUrl - URL of a module in `src/config` or `build/config`.
+ * @returns Absolute path to the package-root credential file.
+ *
+ * @example
+ * ```ts
+ * resolveCredentialEnvPath(import.meta.url);
+ * ```
+ */
+export const resolveCredentialEnvPath = (moduleUrl) => join(dirname(fileURLToPath(moduleUrl)), '../../.env');
+/** Package-root credential file used for both runtime reads and token writes. */
+export const CREDENTIAL_ENV_PATH = resolveCredentialEnvPath(import.meta.url);

package/build/config/environment.js

@@ -2,6 +2,7 @@ import { config } from 'dotenv';
 import { existsSync, readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { CREDENTIAL_ENV_PATH } from '../config/credentialFile.js';
 import { getToolGatingConfigError } from '../config/toolFamilies.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { getVersion } from '../utils/version.js';
@@ -13,7 +14,7 @@ const __dirname = dirname(__filename);
 // Load .env from the package root (two levels up from src/config/), not process.cwd().
 // MCP servers inherit cwd from the host (e.g. Claude Code's project dir), so
 // process.cwd() may point to an unrelated project with a different .env.
-config({ path: join(__dirname, '../../.env'), quiet: true });
+config({ path: CREDENTIAL_ENV_PATH, quiet: true });
 const writeConfigDiagnostic = (message) => {
     process.stderr.write(`[eBay MCP] ${message}\n`);
 };

package/build/mcp/runtime.js

@@ -6,7 +6,7 @@ import { isReadOnlyModeEnabled, isReadOnlyTool } from '../mcp/readOnlyFilter.js'
 import { createToolGatingController, DYNAMIC_MODE_INSTRUCTIONS, registerMetaTools, toolNamesInFamilies, } from '../mcp/toolGating.js';
 import { buildUiToolResult, createUiBridge } from '../mcp/uiBridge.js';
 import { getToolEntries } from '../tools/registry.js';
-import { getErrorMessage } from '../utils/errors.js';
+import { getEbayErrorDetails } from '../utils/errors.js';
 import { serverLogger, toolLogger } from '../utils/logger.js';
 import { Effect } from 'effect';
 function formatToolSuccess(result) {
@@ -23,12 +23,19 @@ function formatToolSuccess(result) {
     };
 }
 function formatToolFailure(error) {
-    const errorMessage = getErrorMessage(error);
+    const { message, status, errors } = getEbayErrorDetails(error);
+    const payload = { error: message };
+    if (status !== undefined) {
+        payload.status = status;
+    }
+    if (errors !== undefined) {
+        payload.details = errors;
+    }
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({ error: errorMessage }, null, 2),
+                text: JSON.stringify(payload, null, 2),
             },
         ],
         isError: true,
@@ -56,9 +63,10 @@ function registerTool(server, api, entry, logToolExecution, ui) {
                 ? buildUiToolResult(entry.ui, result)
                 : formatToolSuccess(result);
         }), Effect.catchAll((error) => {
-            const errorMessage = getErrorMessage(error);
             if (logToolExecution) {
-                toolLogger.error(`Tool ${definition.name} failed`, { error: errorMessage });
+                toolLogger.error(`Tool ${definition.name} failed`, {
+                    error: getEbayErrorDetails(error).message,
+                });
             }
             return Effect.succeed(formatToolFailure(error));
         })));

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/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

@@ -105,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',