ebay-mcp 1.14.2 → 1.15.0

package/README.ru.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>MCP-сервер eBay — дайте Claude, Cursor и любому ИИ-ассистенту полный доступ к Sell API eBay. 322 инструмента для инвентаря, заказов, маркетинга и аналитики, работающих локально с вашими собственными ключами.</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-322-8957e5?logo=ebay&logoColor=white" alt="322 инструмента 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**. Он предоставляет **322 инструмента**, охватывающих **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 @@
 
 ## Возможности
 
-- **322 инструмента 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 | 322 инструмента на 100% Sell API, готовы к вызову | Вы строите каждый запрос по документации |
+| Покрытие API | 299 инструмента на 100% Sell API, готовы к вызову | Вы строите каждый запрос по документации |
 | Размещение | Работает локально, без облачного ретранслятора | Ваша собственная инфраструктура |
 
 ## Настройка с помощью ИИ в один клик
@@ -236,7 +236,7 @@ EBAY_MCP_UI=on                      # интерактивные предста
 
 ## Доступные инструменты
 
-**322 инструмента**, 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), предоставляющий **322 инструмента**, охватывающих **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 он охватывает?
 
-322 инструмента на 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。322 个工具覆盖库存、订单、营销与分析，使用你自己的密钥在本地运行。</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-322-8957e5?logo=ebay&logoColor=white" alt="322 个 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**。它提供 **322 个工具**，覆盖 **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 @@
 
 ## 功能特性
 
-- **322 个 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 覆盖 | 322 个工具覆盖 100% Sell API，开箱即用 | 你需根据文档构建每个请求 |
+| API 覆盖 | 299 个工具覆盖 100% Sell API，开箱即用 | 你需根据文档构建每个请求 |
 | 托管 | 本地运行，无云端中继 | 你自己的基础设施 |
 
 ## AI 一键配置
@@ -236,7 +236,7 @@ EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）
 
 ## 可用工具
 
-**322 个工具**，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 助手提供 **322 个工具**，覆盖 **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 和工具？
 
-322 个工具，覆盖 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 { existsSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, writeFileSync } from 'fs';
+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.
  */
@@ -19,17 +18,39 @@ export const APP_ACCESS_TOKEN_EXPIRY_BUFFER_SECONDS = 60;
 /** Tagged failure returned when credential persistence cannot write to disk. */
 export class CredentialStoreError extends Data.TaggedError('CredentialStoreError') {
 }
+/**
+ * Process-wide write mutexes keyed by absolute `.env` path so concurrent
+ * DotEnvCredentialStore instances cannot interleave read-modify-write on the
+ * same file (e.g. user-token write racing app-token write).
+ */
+const writeLocksByEnvPath = new Map();
+const writeLockForEnvPath = (envPath) => {
+    const existing = writeLocksByEnvPath.get(envPath);
+    if (existing) {
+        return existing;
+    }
+    const created = Effect.runSync(Effect.makeSemaphore(1));
+    writeLocksByEnvPath.set(envPath, created);
+    return created;
+};
 /**
  * Credential store that merges token updates into the project .env file.
+ *
+ * Writes are serialized through a one-permit semaphore so concurrent Effect
+ * callers cannot interleave read-modify-write on the same `.env` path.
  */
 export class DotEnvCredentialStore {
     getEnvPath;
-    constructor(getEnvPath = () => join(process.cwd(), '.env')) {
+    constructor(getEnvPath = () => CREDENTIAL_ENV_PATH) {
         this.getEnvPath = getEnvPath;
     }
     /**
      * Merges credential updates into the project `.env` file.
      *
+     * Concurrent writes are serialized so one call cannot overwrite another
+     * caller's keys. After the file is written, the store fsyncs the file
+     * descriptor when the path exists so crash/kill is less likely to drop tokens.
+     *
      * @param updates - Environment variable names and values to persist.
      * @returns An Effect that succeeds after `.env` is written.
      *
@@ -40,18 +61,44 @@ export class DotEnvCredentialStore {
      */
     write(updates) {
         const envPath = this.getEnvPath();
-        return Effect.try({
+        const writeLock = writeLockForEnvPath(envPath);
+        return writeLock.withPermits(1)(Effect.try({
             try: () => {
-                const existingEnv = existsSync(envPath) ? dotenv.parse(readFileSync(envPath, 'utf-8')) : {};
-                const safeEnvContent = stringify({ ...existingEnv, ...updates });
+                // Drop non-string values so a missing refresh_token cannot persist as empty.
+                const sanitizedUpdates = {};
+                for (const [key, value] of Object.entries(updates)) {
+                    if (typeof value === 'string') {
+                        sanitizedUpdates[key] = value;
+                    }
+                }
+                const existingEnv = existsSync(envPath)
+                    ? dotenv.parse(readFileSync(envPath, 'utf-8'))
+                    : {};
+                const safeEnvContent = stringify({ ...existingEnv, ...sanitizedUpdates });
                 writeFileSync(envPath, safeEnvContent, 'utf-8');
+                // Durability: best-effort fsync. Windows and mocked FS may reject fsync
+                // on a read-only open; never fail the write after a successful writeFileSync.
+                if (existsSync(envPath)) {
+                    try {
+                        const fd = openSync(envPath, 'r+');
+                        try {
+                            fsyncSync(fd);
+                        }
+                        finally {
+                            closeSync(fd);
+                        }
+                    }
+                    catch {
+                        // Ignore fsync failures — tokens are already on disk for the write path.
+                    }
+                }
             },
             catch: (cause) => new CredentialStoreError({
                 envPath,
                 message: `Failed to write credential updates to ${envPath}`,
                 cause,
             }),
-        });
+        }));
     }
 }
 /**

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) {
@@ -265,6 +283,15 @@ export class EbayOAuthClient {
                 Authorization: `Basic ${credentials}`,
             },
         });
+        // Authorization-code exchange must return a refresh token; without it we
+        // cannot persist durable user credentials and must not claim success.
+        const refreshToken = tokenData.refresh_token;
+        if (typeof refreshToken !== 'string' || refreshToken.length === 0) {
+            return yield* Effect.fail(new EbayOAuthError({
+                operation: 'exchangeCodeForToken',
+                message: 'eBay token response did not include a non-empty refresh_token; cannot complete authorization code exchange',
+            }));
+        }
         this.userTokens = createStoredUserTokensFromResponse({
             config: this.config,
             tokenData,
@@ -273,13 +300,13 @@ export class EbayOAuthClient {
         yield* this.credentialStore
             .write({
             EBAY_USER_ACCESS_TOKEN: tokenData.access_token,
-            EBAY_USER_REFRESH_TOKEN: tokenData.refresh_token,
+            EBAY_USER_REFRESH_TOKEN: refreshToken,
         })
             .pipe(Effect.mapError((cause) => mapCredentialStoreError('exchangeCodeForToken', 'Failed to persist exchanged user tokens', cause)));
         this.config = {
             ...this.config,
             accessToken: tokenData.access_token,
-            refreshToken: tokenData.refresh_token,
+            refreshToken: refreshToken,
         };
         return tokenData;
     });

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/index.js

@@ -2,6 +2,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { validateEnvironmentConfig } from './config/environment.js';
 import { createEbayMcpRuntime } from './mcp/runtime.js';
+import { runDiagnostics } from './scripts/diagnostics.js';
 import { runSetup } from './scripts/setup.js';
 import { runSkillsWizard } from './scripts/skills.js';
 import { getErrorMessage } from './utils/errors.js';
@@ -29,6 +30,10 @@ if (args.includes('setup')) {
 if (args.includes('skills')) {
     await runCliCommand('Skills install', runSkillsWizard);
 }
+if (args.includes('diagnose')) {
+    const exportReport = args.includes('--export') || args.includes('-e');
+    await runCliCommand('Diagnostics', () => runDiagnostics(exportReport));
+}
 /**
  * eBay API MCP Server
  * Provides access to eBay APIs through Model Context Protocol

package/build/mcp/runtime.js

@@ -6,26 +6,36 @@ 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) {
+    // JSON.stringify(undefined) returns undefined (not a string), which produces an
+    // invalid MCP content block and triggers client -32602 on empty-body 201/204s.
+    const successDocument = result === undefined || result === null ? { status: 'success' } : result;
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(result, null, 2),
+                text: JSON.stringify(successDocument, null, 2),
             },
         ],
     };
 }
 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,
@@ -53,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));
         })));