ebay-mcp 1.13.2 → 1.13.3

package/README.md

@@ -194,6 +194,9 @@ https://github.com/user-attachments/assets/0173c8df-221c-4943-a4ce-cd20bce79f4b
 
 ## Configuration
 
+<details open>
+<summary><strong>Environment variables, tool exposure, auth &amp; client compatibility</strong></summary>
+
 > 📖 Full reference — every environment variable, OAuth step, and scope — is in the [Configuration Guide](docs/auth/CONFIGURATION.md). `npm run setup` writes the `.env` for you; the variables below are for reference.
 
 ```bash
@@ -245,8 +248,13 @@ Auto-configured by `npm run setup`. Requires Node.js ≥ 18 and MCP protocol 1.0
 | **Claude Code CLI**    | Terminal              | `~/.claude.json`                                                             |
 | **Amazon Q Developer** | AWS                   | `~/.aws/amazonq/mcp.json`                                                     |
 
+</details>
+
 ## Available tools
 
+<details open>
+<summary><strong>322 tools by category (100% Sell API coverage)</strong></summary>
+
 **322 tools**, 100% Sell API coverage, organized by category. Each link points to the tool definitions and handlers in [`src/tools/categories/`](src/tools/categories/):
 
 | Category | What you can do |
@@ -267,27 +275,35 @@ Auto-configured by `npm run setup`. Requires Node.js ≥ 18 and MCP protocol 1.0
 
 For the complete machine-readable index, see [llms.txt](llms.txt).
 
+</details>
+
 ## Interactive UI (MCP Apps)
 
+<details open>
+<summary><strong>Interactive table, card, chart &amp; stat views (beta)</strong></summary>
+
 > **Beta** — this feature is new and evolving alongside the MCP Apps spec, and host support is still rolling out. It is opt-in and falls back to plain JSON, so it never breaks existing clients. Toggle it with `EBAY_MCP_UI` (see [Configuration](#configuration)).
 
-On hosts that support [MCP Apps](https://modelcontextprotocol.io), common read tools render their results as interactive views instead of raw JSON — a sortable **table**, a detail **card**, or a **chart** — using the host's own theme. Everywhere else, the exact same tools return plain JSON, so nothing breaks. It is built on the official [MCP Apps SDK (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps), the extension that lets MCP servers ship interactive UI to conversational clients.
+On hosts that support [MCP Apps](https://modelcontextprotocol.io), common read tools render their results as interactive views instead of raw JSON — a sortable **table**, a detail **card**, a **chart**, or a **stat grid** — using the host's own theme. Everywhere else, the exact same tools return plain JSON, so nothing breaks. It is built on the official [MCP Apps SDK (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps), the extension that lets MCP servers ship interactive UI to conversational clients.
 
 - **Opt-in and host-gated.** Views are advertised only to clients that announce the MCP Apps capability (e.g. Claude). Hosts without it (e.g. Cursor) silently get JSON.
 - **Kill-switch.** Set `EBAY_MCP_UI=off` to force plain JSON everywhere, even on capable hosts.
 - **Token-cheap.** Each view's HTML is fetched once by the host out of band (never into the model's context); the model only ever sees a one-line summary plus the structured data it would have received anyway.
 - **Read-only.** Views only ever trigger read tools (drill into a row, page, refresh) — they never mutate your eBay data.
 
-13 core-workflow tools opt in today, across three archetypes:
+15 core-workflow tools opt in today, across four archetypes:
 
 | Archetype | Tools |
 | --- | --- |
 | **Table** | `ebay_get_orders`, `ebay_get_shipping_fulfillments`, `ebay_get_offers`, `ebay_get_inventory_items`, `ebay_get_inventory_locations`, `ebay_get_payment_dispute_summaries` |
 | **Card** | `ebay_get_order`, `ebay_get_offer`, `ebay_get_inventory_item`, `ebay_get_payment_dispute`, `ebay_get_seller_standards_profile` |
 | **Chart** | `ebay_get_traffic_report`, `ebay_get_customer_service_metric` |
+| **Stat** | `ebay_get_rate_limits`, `ebay_get_user_rate_limits` |
 
 The views build into self-contained HTML with `npm run build` (or `npm run build:ui`); they ship in the published package and load with no network access of their own.
 
+</details>
+
 ## Usage examples
 
 Common tasks, phrased as you'd ask your AI assistant:
@@ -305,78 +321,132 @@ Common tasks, phrased as you'd ask your AI assistant:
 
 ## FAQ
 
-### What is the eBay MCP server?
+<details>
+<summary><strong>What is the eBay MCP server?</strong></summary>
 
 A local [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **322 tools** covering **100% of eBay's Sell APIs** (270 endpoints) to AI assistants — inventory, order fulfillment, marketing, analytics, and developer tools.
 
-### Is this an official eBay product?
+</details>
+
+<details>
+<summary><strong>Is this an official eBay product?</strong></summary>
 
 No. This is an unofficial, third-party open-source project. It is **not affiliated with, authorized, or endorsed by eBay Inc.**
 
-### Which AI assistants and MCP clients are supported?
+</details>
+
+<details>
+<summary><strong>Which AI assistants and MCP clients are supported?</strong></summary>
 
 Nine clients are auto-configured by `npm run setup`: Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, and Amazon Q Developer. Any MCP-compatible client can connect.
 
-### Can I use it with Claude, ChatGPT, or Cursor?
+</details>
+
+<details>
+<summary><strong>Can I use it with Claude, ChatGPT, or Cursor?</strong></summary>
 
 Yes. It works with Claude Desktop and Claude Code out of the box, with Cursor and other MCP-enabled IDEs, and with any assistant that supports the Model Context Protocol. The one-click setup prompt above works with ChatGPT and other assistants too.
 
-### Why don't I see the interactive tables and charts?
+</details>
+
+<details>
+<summary><strong>Why don't I see the interactive tables and charts?</strong></summary>
 
 Interactive [MCP Apps](#interactive-ui-mcp-apps) views only appear on hosts that announce the capability (e.g. Claude); other clients get the same data as plain JSON. Also confirm you have not set `EBAY_MCP_UI=off` and that the views are built (`npm run build` runs `build:ui`).
 
-### How many eBay APIs and tools does it cover?
+</details>
+
+<details>
+<summary><strong>How many eBay APIs and tools does it cover?</strong></summary>
 
 322 tools across 270 unique endpoints — 100% of eBay's Sell APIs.
 
-### Is it free and open source?
+</details>
+
+<details>
+<summary><strong>Is it free and open source?</strong></summary>
 
 Yes. It is released under the [MIT license](LICENSE).
 
-### Does it run locally or in the cloud?
+</details>
+
+<details>
+<summary><strong>Does it run locally or in the cloud?</strong></summary>
 
 It runs entirely on your machine over STDIO (or local HTTP). There is no cloud relay — your eBay credentials never leave your computer.
 
-### What do I need to get started?
+</details>
+
+<details>
+<summary><strong>What do I need to get started?</strong></summary>
 
 Node.js ≥ 18, a free [eBay Developer Account](https://developer.ebay.com/) (Client ID + Client Secret), then run `npm run setup`.
 
-### What are the eBay API rate limits?
+</details>
+
+<details>
+<summary><strong>What are the eBay API rate limits?</strong></summary>
 
 Client credentials (the default) allow about 1,000 requests/day. Authenticating with a user token via OAuth raises this to 10,000–50,000 requests/day depending on your account tier.
 
-### Does it support both sandbox and production?
+</details>
+
+<details>
+<summary><strong>Does it support both sandbox and production?</strong></summary>
 
 Yes. Switch with the `EBAY_ENVIRONMENT` variable (`sandbox` or `production`).
 
-### Are my credentials and data secure?
+</details>
+
+<details>
+<summary><strong>Are my credentials and data secure?</strong></summary>
 
 Credentials are stored locally in your `.env` file and used only to call eBay directly. See [SECURITY.md](SECURITY.md) and [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md).
 
-### How is this different from calling the eBay API directly?
+</details>
+
+<details>
+<summary><strong>How is this different from calling the eBay API directly?</strong></summary>
 
 You interact in natural language through your AI assistant. OAuth token management, automatic retries with backoff, and type-safe Zod validation are built in. See the [comparison table](#ebay-mcp-vs-the-raw-ebay-api) above.
 
-### Does it support eBay's legacy Trading API (XML)?
+</details>
+
+<details>
+<summary><strong>Does it support eBay's legacy Trading API (XML)?</strong></summary>
 
 Yes. Fixed-price listing create, revise, relist, and end operations are supported through the Trading API tools.
 
-### How do I get higher rate limits?
+</details>
+
+<details>
+<summary><strong>How do I get higher rate limits?</strong></summary>
 
 Complete the OAuth flow with `npm run setup` to authenticate with a user token (10k–50k requests/day instead of the default 1k).
 
-### What is it built with?
+</details>
+
+<details>
+<summary><strong>What is it built with?</strong></summary>
 
 TypeScript and Node.js (ESM), using the official MCP SDK, Zod for validation, and OpenAPI-generated types.
 
-### How do I update to the latest version?
+</details>
+
+<details>
+<summary><strong>How do I update to the latest version?</strong></summary>
 
 Run `npm install -g ebay-mcp@latest` (or `npm update -g ebay-mcp`).
 
-### Does it work offline?
+</details>
+
+<details>
+<summary><strong>Does it work offline?</strong></summary>
 
 No. "Runs locally" means the server process runs on your machine — it still needs an internet connection and valid credentials to reach eBay's live APIs.
 
+</details>
+
 ## Contributing
 
 Contributions welcome. Fork → branch → add tests → `npm run check && npm test` → commit with [Conventional Commits](https://www.conventionalcommits.org/) → open a PR.

package/build/api/communication/negotiation.js

@@ -1,5 +1,5 @@
 import { assertRequiredString, buildPaginatedQueryParams, getPathWithContextError, getWithContextError, } from './shared.js';
-import { buildTruthyPaginatedParams } from '../shared/query-params.js';
+import { buildTruthyPaginatedParams } from '../../api/shared/query-params.js';
 import { withApiError } from '../../api/shared/request.js';
 /**
  * Negotiation API - Buyer-seller negotiations and offers

package/build/api/communication/notification.js

@@ -1,4 +1,4 @@
-import { buildContinuationParams, deleteWithApiError, getWithApiError, postWithApiError, putWithApiError, requireObject, requireString, } from '../shared/request.js';
+import { buildContinuationParams, deleteWithApiError, getWithApiError, postWithApiError, putWithApiError, requireObject, requireString, } from '../../api/shared/request.js';
 /**
  * Notification API - Event notifications and subscriptions
  * Based on: docs/sell-apps/communication/commerce_notification_v1_oas3.json

package/build/api/communication/shared.js

@@ -1,4 +1,4 @@
-import { buildValidatedPaginatedParams, getWithApiError, requireString, } from '../shared/request.js';
+import { buildValidatedPaginatedParams, getWithApiError, requireString, } from '../../api/shared/request.js';
 /**
  * Build validated pagination query params.
  *

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

@@ -1,4 +1,4 @@
-import { buildOptionalStringParams, buildValidatedPaginatedParams, optionalStringParam, requireObject, requireString, withApiError, } from '../shared/request.js';
+import { buildOptionalStringParams, buildValidatedPaginatedParams, optionalStringParam, requireObject, requireString, withApiError, } from '../../api/shared/request.js';
 /**
  * Inventory API - Manage listings and inventory
  * Based on: docs/sell-apps/listing-management/sell_inventory_v1_oas3.json

package/build/api/listing-metadata/metadata.js

@@ -1,4 +1,4 @@
-import { buildOptionalStringParams, requireObject, requireString, withApiError, } from '../shared/request.js';
+import { buildOptionalStringParams, requireObject, requireString, withApiError, } from '../../api/shared/request.js';
 /**
  * Metadata API - Marketplace policies and configurations
  * Based on: docs/sell-apps/listing-metadata/sell_metadata_v1_oas3.json

package/build/api/other/vero.js

@@ -1,4 +1,4 @@
-import { buildTruthyPaginatedParams } from '../shared/query-params.js';
+import { buildTruthyPaginatedParams } from '../../api/shared/query-params.js';
 import { withApiError } from '../../api/shared/request.js';
 /**
  * VERO API - Verified Rights Owner program

package/build/mcp/ui-bridge.js

@@ -43,6 +43,10 @@ export function summarizeView(view) {
             const pointCount = view.series.reduce((total, series) => total + series.points.length, 0);
             return `${view.title ?? 'Chart'} (${view.kind}): ${view.series.length} series, ${pointCount} ${pointCount === 1 ? 'point' : 'points'}. Rendered as an interactive chart.`;
         }
+        case 'stat': {
+            const count = view.tiles.length;
+            return `${view.title ?? 'Metrics'}: ${count} ${count === 1 ? 'metric' : 'metrics'}. Rendered as an interactive stat grid.`;
+        }
     }
 }
 /**

package/build/tools/categories/account.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { MarketplaceId } from '../../types/ebay-enums.js';
 import { defineTool } from '../../tools/define-tool.js';
-import { bulkSalesTaxRequestSchema, customPolicySchema, fulfillmentPolicySchema, paymentPolicySchema, programRequestSchema, returnPolicySchema, salesTaxBaseSchema, } from '../schemas.js';
+import { bulkSalesTaxRequestSchema, customPolicySchema, fulfillmentPolicySchema, paymentPolicySchema, programRequestSchema, returnPolicySchema, salesTaxBaseSchema, } from '../../tools/schemas.js';
 import { customPolicyResponseSchema, getFulfillmentPoliciesOutputSchema, createFulfillmentPolicyOutputSchema, fulfillmentPolicyResponseSchema, getPaymentPoliciesOutputSchema, createPaymentPolicyOutputSchema, paymentPolicyResponseSchema, getReturnPoliciesOutputSchema, createReturnPolicyOutputSchema, returnPolicyResponseSchema, createCustomPolicyOutputSchema, getSalesTaxesOutputSchema, salesTaxSchema, kycOutputSchema, privilegesOutputSchema, programsOutputSchema, } from '../../schemas/account-management/account.js';
 /** Account Management API tools for seller policies, tax, KYC, privileges, and programs. */
 export const accountEntries = [

package/build/tools/categories/developer.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { defineTool } from '../../tools/define-tool.js';
+import { mapRateLimitsToStat, mapUserRateLimitsToStat } from '../../tools/ui/maps.js';
 import { getApiStatusFeed } from '../../utils/api-status-feed.js';
 /** Developer API tools for eBay application and keyset management. */
 export const developerEntries = [
@@ -86,6 +87,7 @@ export const developerEntries = [
             description: 'Rate limit data for application APIs',
         },
         handler: (api, args) => api.developer.getRateLimits(args.apiContext, args.apiName),
+        ui: { archetype: 'stat', map: mapRateLimitsToStat },
     }),
     defineTool({
         name: 'ebay_get_user_rate_limits',
@@ -108,6 +110,7 @@ export const developerEntries = [
             description: 'Rate limit data for user APIs',
         },
         handler: (api, args) => api.developer.getUserRateLimits(args.apiContext, args.apiName),
+        ui: { archetype: 'stat', map: mapUserRateLimitsToStat },
     }),
     defineTool({
         name: 'ebay_register_client',

package/build/tools/categories/fulfillment.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { defineTool } from '../../tools/define-tool.js';
 import { mapDisputeSummariesToTable, mapDisputeToCard, mapFulfillmentsToTable, mapOrdersToTable, mapOrderToCard, } from '../../tools/ui/maps.js';
-import { shippingFulfillmentSchema } from '../schemas.js';
+import { shippingFulfillmentSchema } from '../../tools/schemas.js';
 import { getOrdersOutputSchema, getOrderOutputSchema, createShippingFulfillmentOutputSchema, getShippingFulfillmentsOutputSchema, issueRefundOutputSchema, getPaymentDisputesOutputSchema, } from '../../schemas/fulfillment/orders.js';
 /** Fulfillment API tools for orders, shipping fulfillments, refunds, and cancellations. */
 export const fulfillmentEntries = [

package/build/tools/categories/inventory.js

@@ -3,7 +3,7 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
 import { MarketplaceId } from '../../types/ebay-enums.js';
 import { defineTool } from '../../tools/define-tool.js';
 import { mapInventoryItemsToTable, mapInventoryItemToCard, mapLocationsToTable, mapOffersToTable, mapOfferToCard, } from '../../tools/ui/maps.js';
-import { bulkInventoryItemRequestSchema, bulkMigrateRequestSchema, bulkOfferRequestSchema, bulkPriceQuantityRequestSchema, bulkPublishRequestSchema, inventoryItemGroupSchema, inventoryItemSchema, listingFeesRequestSchema, locationSchema, offerSchema, productCompatibilitySchema, } from '../schemas.js';
+import { bulkInventoryItemRequestSchema, bulkMigrateRequestSchema, bulkOfferRequestSchema, bulkPriceQuantityRequestSchema, bulkPublishRequestSchema, inventoryItemGroupSchema, inventoryItemSchema, listingFeesRequestSchema, locationSchema, offerSchema, productCompatibilitySchema, } from '../../tools/schemas.js';
 import { getInventoryItemsOutputSchema, getInventoryItemOutputSchema, createInventoryItemOutputSchema, getOffersOutputSchema, createOfferOutputSchema, publishOfferOutputSchema, offerResponseSchema, getInventoryLocationsOutputSchema, createInventoryLocationOutputSchema, getProductCompatibilityOutputSchema, getInventoryItemGroupOutputSchema, bulkInventoryItemResponseSchema, bulkOfferResponseSchema, bulkPublishResponseSchema, } from '../../schemas/inventory-management/inventory.js';
 /** Inventory API tools for seller inventory items, offers, locations, and bulk operations. */
 export const inventoryEntries = [

package/build/tools/categories/metadata.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { MarketplaceId } from '../../types/ebay-enums.js';
 import { defineTool } from '../../tools/define-tool.js';
-import { compatibilityDataSchema, compatibilitySpecificationSchema } from '../schemas.js';
+import { compatibilityDataSchema, compatibilitySpecificationSchema } from '../../tools/schemas.js';
 /** Metadata API tools for marketplace, business policy, and sales tax metadata. */
 export const metadataEntries = [
     defineTool({

package/build/tools/categories/other.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { defineTool } from '../../tools/define-tool.js';
-import { shippingQuoteRequestSchema, veroReportDataSchema } from '../schemas.js';
+import { shippingQuoteRequestSchema, veroReportDataSchema } from '../../tools/schemas.js';
 /** Miscellaneous eBay API tools that do not fit the primary seller API categories. */
 export const otherEntries = [
     // Identity API

package/build/tools/ui/archetypes.js

@@ -8,4 +8,5 @@ export const uiArchetypes = {
     table: { uri: 'ui://ebay/table.html', name: 'eBay table view', htmlFile: 'table.html' },
     card: { uri: 'ui://ebay/card.html', name: 'eBay detail card view', htmlFile: 'card.html' },
     chart: { uri: 'ui://ebay/chart.html', name: 'eBay chart view', htmlFile: 'chart.html' },
+    stat: { uri: 'ui://ebay/stat.html', name: 'eBay stat grid view', htmlFile: 'stat.html' },
 };

package/build/tools/ui/maps.js

@@ -417,3 +417,63 @@ export function mapCustomerServiceMetricToChart(result) {
         series,
     };
 }
+/**
+ * Buckets remaining API headroom into a tile tone: healthy above a quarter of
+ * the quota, warning as it drains, danger near exhaustion. A missing or zero
+ * limit is neutral — there is no meaningful ratio to colour.
+ */
+function headroomTone(remaining, limit) {
+    if (limit <= 0) {
+        return 'neutral';
+    }
+    const ratio = remaining / limit;
+    if (ratio <= 0.1) {
+        return 'danger';
+    }
+    if (ratio <= 0.25) {
+        return 'warning';
+    }
+    return 'success';
+}
+/**
+ * Flattens a rate-limit response into one tile per API resource, showing calls
+ * remaining against the quota with a tone that reflects headroom. Shared by the
+ * application- and user-scoped rate-limit tools, which return the same shape.
+ */
+function rateLimitTiles(result) {
+    const tiles = [];
+    for (const rateLimit of result.rateLimits ?? []) {
+        for (const resource of rateLimit.resources ?? []) {
+            const rate = resource.rates?.[0];
+            if (!rate) {
+                continue;
+            }
+            const remaining = rate.remaining ?? 0;
+            const limit = rate.limit ?? 0;
+            const parts = [rateLimit.apiContext, rateLimit.apiName, resource.name].filter(Boolean);
+            tiles.push({
+                label: parts.length > 0 ? parts.join(' · ') : 'Resource',
+                value: remaining.toLocaleString('en-US'),
+                sub: `of ${limit.toLocaleString('en-US')}`,
+                tone: headroomTone(remaining, limit),
+            });
+        }
+    }
+    return tiles;
+}
+/** Projects application rate limits into a stat grid (calls remaining per resource). */
+export function mapRateLimitsToStat(result) {
+    return {
+        archetype: 'stat',
+        title: 'Application rate limits',
+        tiles: rateLimitTiles(result),
+    };
+}
+/** Projects user rate limits into a stat grid (per-user calls remaining per resource). */
+export function mapUserRateLimitsToStat(result) {
+    return {
+        archetype: 'stat',
+        title: 'User rate limits',
+        tiles: rateLimitTiles(result),
+    };
+}