ebay-mcp 1.13.2 → 1.14.0

package/README.de.md

@@ -218,7 +218,7 @@ Die Limits des Benutzer-Tokens variieren je nach Kontostufe (Individual 10k · C
 
 ### MCP-Client-Kompatibilität
 
-Automatisch konfiguriert durch `npm run setup`. Erfordert Node.js ≥ 18 und das MCP-Protokoll 1.0+ über STDIO (Standard) oder HTTP.
+Automatisch konfiguriert durch `npm run setup`. Erfordert Node.js ≥ 20 und das MCP-Protokoll 1.0+ über STDIO (Standard) oder HTTP.
 
 | Client                 | Plattform             | Konfigurationspfad                                                          |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ Automatisch konfiguriert durch `npm run setup`. Erfordert Node.js ≥ 18 und das
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Kategoriebäume, Artikelmerkmale, Artikelzustände |
 | [Trading (Legacy-XML)](src/tools/categories/trading.ts) | Festpreisangebote erstellen, überarbeiten, neu einstellen und beenden |
 | [Developer](src/tools/categories/developer.ts) | Ratenlimits, Signaturschlüssel, Client-Registrierung |
-| [Token Management](src/tools/categories/token-management.ts) | OAuth-URL-Generierung und Token-Verwaltung |
+| [Token Management](src/tools/categories/tokenManagement.ts) | OAuth-URL-Generierung und Token-Verwaltung |
 
 **Beispiel-Tools:** `ebay_get_inventory_items`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
@@ -326,7 +326,7 @@ Es läuft vollständig auf deinem Rechner über STDIO (oder lokales HTTP). Es gi
 
 ### Was brauche ich, um loszulegen?
 
-Node.js ≥ 18, ein kostenloses [eBay-Entwicklerkonto](https://developer.ebay.com/) (Client ID + Client Secret) und dann `npm run setup`.
+Node.js ≥ 20, ein kostenloses [eBay-Entwicklerkonto](https://developer.ebay.com/) (Client ID + Client Secret) und dann `npm run setup`.
 
 ### Wie hoch sind die Ratenlimits der eBay-API?
 

package/README.es.md

@@ -218,7 +218,7 @@ Los límites del token de usuario varían según el nivel de cuenta (Individual
 
 ### Compatibilidad de clientes MCP
 
-Autoconfigurados por `npm run setup`. Requiere Node.js ≥ 18 y el protocolo MCP 1.0+ mediante STDIO (predeterminado) o HTTP.
+Autoconfigurados por `npm run setup`. Requiere Node.js ≥ 20 y el protocolo MCP 1.0+ mediante STDIO (predeterminado) o HTTP.
 
 | Cliente                | Plataforma            | Ruta de configuración                                                       |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ Autoconfigurados por `npm run setup`. Requiere Node.js ≥ 18 y el protocolo MCP
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Árboles de categorías, aspectos de artículos, condiciones de artículos |
 | [Trading (XML heredado)](src/tools/categories/trading.ts) | Crear, revisar, volver a publicar y finalizar anuncios de precio fijo |
 | [Developer](src/tools/categories/developer.ts) | Límites de tasa, claves de firma, registro de clientes |
-| [Token Management](src/tools/categories/token-management.ts) | Generación de URL de OAuth y gestión de tokens |
+| [Token Management](src/tools/categories/tokenManagement.ts) | Generación de URL de OAuth y gestión de tokens |
 
 **Herramientas de ejemplo:** `ebay_get_inventory_items`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
@@ -326,7 +326,7 @@ Se ejecuta íntegramente en tu máquina mediante STDIO (o HTTP local). No hay re
 
 ### ¿Qué necesito para empezar?
 
-Node.js ≥ 18, una [cuenta de desarrollador de eBay](https://developer.ebay.com/) gratuita (Client ID + Client Secret) y luego ejecutar `npm run setup`.
+Node.js ≥ 20, una [cuenta de desarrollador de eBay](https://developer.ebay.com/) gratuita (Client ID + Client Secret) y luego ejecutar `npm run setup`.
 
 ### ¿Cuáles son los límites de tasa de la API de eBay?
 

package/README.fr.md

@@ -218,7 +218,7 @@ Les limites du jeton utilisateur varient selon le niveau de compte (Individuel 1
 
 ### Compatibilité des clients MCP
 
-Configurés automatiquement par `npm run setup`. Nécessite Node.js ≥ 18 et le protocole MCP 1.0+ via STDIO (par défaut) ou HTTP.
+Configurés automatiquement par `npm run setup`. Nécessite Node.js ≥ 20 et le protocole MCP 1.0+ via STDIO (par défaut) ou HTTP.
 
 | Client                 | Plateforme            | Chemin de configuration                                                     |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ Configurés automatiquement par `npm run setup`. Nécessite Node.js ≥ 18 et le
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Arbres de catégories, aspects d'articles, états d'articles |
 | [Trading (XML hérité)](src/tools/categories/trading.ts) | Créer, réviser, remettre en vente et clôturer des annonces à prix fixe |
 | [Developer](src/tools/categories/developer.ts) | Limites de débit, clés de signature, enregistrement de clients |
-| [Token Management](src/tools/categories/token-management.ts) | Génération d'URL OAuth et gestion des jetons |
+| [Token Management](src/tools/categories/tokenManagement.ts) | Génération d'URL OAuth et gestion des jetons |
 
 **Outils d'exemple :** `ebay_get_inventory_items`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
@@ -326,7 +326,7 @@ Il s'exécute entièrement sur votre machine via STDIO (ou HTTP local). Il n'y a
 
 ### De quoi ai-je besoin pour commencer ?
 
-Node.js ≥ 18, un [compte développeur eBay](https://developer.ebay.com/) gratuit (Client ID + Client Secret), puis lancez `npm run setup`.
+Node.js ≥ 20, un [compte développeur eBay](https://developer.ebay.com/) gratuit (Client ID + Client Secret), puis lancez `npm run setup`.
 
 ### Quelles sont les limites de débit de l'API eBay ?
 

package/README.ja.md

@@ -218,7 +218,7 @@ EBAY_MCP_UI=on                      # インタラクティブな MCP Apps 表
 
 ### MCP クライアント互換性
 
-`npm run setup` により自動設定されます。Node.js ≥ 18 と、STDIO（既定）または HTTP 経由の MCP プロトコル 1.0+ が必要です。
+`npm run setup` により自動設定されます。Node.js ≥ 20 と、STDIO（既定）または HTTP 経由の MCP プロトコル 1.0+ が必要です。
 
 | クライアント           | プラットフォーム      | 設定パス                                                                    |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ EBAY_MCP_UI=on                      # インタラクティブな MCP Apps 表
 | [Taxonomy](src/tools/categories/taxonomy.ts) | カテゴリツリー、アイテムの特性、アイテムのコンディション |
 | [Trading（レガシー XML）](src/tools/categories/trading.ts) | 固定価格出品の作成・修正・再出品・終了 |
 | [Developer](src/tools/categories/developer.ts) | レート制限、署名キー、クライアント登録 |
-| [Token Management](src/tools/categories/token-management.ts) | OAuth URL の生成とトークン管理 |
+| [Token Management](src/tools/categories/tokenManagement.ts) | OAuth URL の生成とトークン管理 |
 
 **ツール例：** `ebay_get_inventory_items`、`ebay_get_orders`、`ebay_create_offer`、`ebay_get_campaigns`、`ebay_get_oauth_url`。
 
@@ -326,7 +326,7 @@ STDIO（またはローカル HTTP）経由で完全にあなたのマシン上
 
 ### 始めるには何が必要ですか？
 
-Node.js ≥ 18、無料の [eBay 開発者アカウント](https://developer.ebay.com/)（Client ID + Client Secret）、そして `npm run setup` の実行です。
+Node.js ≥ 20、無料の [eBay 開発者アカウント](https://developer.ebay.com/)（Client ID + Client Secret）、そして `npm run setup` の実行です。
 
 ### eBay API のレート制限はどれくらいですか？
 

package/README.ko.md

@@ -218,7 +218,7 @@ EBAY_MCP_UI=on                      # 대화형 MCP Apps 보기(베타); 일반
 
 ### MCP 클라이언트 호환성
 
-`npm run setup`으로 자동 구성됩니다. Node.js ≥ 18과 STDIO(기본) 또는 HTTP를 통한 MCP 프로토콜 1.0+가 필요합니다.
+`npm run setup`으로 자동 구성됩니다. Node.js ≥ 20과 STDIO(기본) 또는 HTTP를 통한 MCP 프로토콜 1.0+가 필요합니다.
 
 | 클라이언트             | 플랫폼                | 구성 경로                                                                   |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ EBAY_MCP_UI=on                      # 대화형 MCP Apps 보기(베타); 일반
 | [Taxonomy](src/tools/categories/taxonomy.ts) | 카테고리 트리, 항목 속성, 항목 상태 |
 | [Trading(레거시 XML)](src/tools/categories/trading.ts) | 고정 가격 리스팅 생성, 수정, 재등록, 종료 |
 | [Developer](src/tools/categories/developer.ts) | 속도 제한, 서명 키, 클라이언트 등록 |
-| [Token Management](src/tools/categories/token-management.ts) | OAuth URL 생성 및 토큰 관리 |
+| [Token Management](src/tools/categories/tokenManagement.ts) | OAuth URL 생성 및 토큰 관리 |
 
 **예시 도구:** `ebay_get_inventory_items`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
@@ -326,7 +326,7 @@ STDIO(또는 로컬 HTTP)를 통해 전적으로 사용자의 컴퓨터에서
 
 ### 시작하려면 무엇이 필요한가요?
 
-Node.js ≥ 18, 무료 [eBay 개발자 계정](https://developer.ebay.com/)(Client ID + Client Secret), 그리고 `npm run setup` 실행입니다.
+Node.js ≥ 20, 무료 [eBay 개발자 계정](https://developer.ebay.com/)(Client ID + Client Secret), 그리고 `npm run setup` 실행입니다.
 
 ### eBay API 속도 제한은 어떻게 되나요?
 

package/README.md

@@ -45,13 +45,14 @@
 
 ---
 
-**eBay MCP** is a local [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI assistants — Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code, and Amazon Q — directly to **eBay's Sell APIs**. It exposes **322 tools** spanning **100% of eBay's Sell API surface** (270 unique endpoints) for inventory management, order fulfillment, promoted-listings marketing, analytics, and developer tooling. Everything runs on your machine over STDIO or local HTTP — **no cloud relay**, and your eBay credentials never leave your computer.
+**eBay MCP** is a local [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI assistants — [Claude Desktop](https://claude.ai/download), [Claude Code](https://code.claude.com/docs/en/overview), [Cursor](https://cursor.com/), [Cline](https://cline.bot/), [Windsurf](https://windsurf.com/), [Zed](https://zed.dev/), [Continue.dev](https://docs.continue.dev/), [Roo Code](https://roocode.com/), and [Amazon Q Developer](https://aws.amazon.com/q/developer/) — directly to **[eBay's Sell APIs](https://developer.ebay.com/api-docs/sell/static/overview.html)**. It exposes **322 tools** spanning **100% of eBay's Sell API surface** (270 unique endpoints) for inventory management, order fulfillment, promoted-listings marketing, analytics, and developer tooling. Everything runs on your machine over STDIO or local HTTP — **no cloud relay**, and your eBay credentials never leave your computer.
 
 > **Disclaimer:** Unofficial, third-party project — **not affiliated with or endorsed by eBay Inc.** Provided "as is" without warranty. You are responsible for complying with [eBay's API License Agreement](https://developer.ebay.com/join/api-license-agreement) and [data-handling requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html), keeping your credentials secure, and staying within rate limits. Test in sandbox before production. See [LICENSE](LICENSE), [SECURITY.md](SECURITY.md), and [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md).
 
 ## Table of contents
 
 - [Features](#features)
+- [Capability map](#capability-map)
 - [eBay MCP vs. the raw eBay API](#ebay-mcp-vs-the-raw-ebay-api)
 - [One-click AI setup](#one-click-ai-setup)
 - [Quick start](#quick-start)
@@ -60,6 +61,7 @@
 - [Available tools](#available-tools)
 - [Interactive UI (MCP Apps) — beta](#interactive-ui-mcp-apps)
 - [Usage examples](#usage-examples)
+- [Scope and safety](#scope-and-safety)
 - [Logging & troubleshooting](#logging--troubleshooting)
 - [FAQ](#faq)
 - [Contributing](#contributing)
@@ -73,11 +75,30 @@
 - **9 AI clients, auto-configured** — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, and Amazon Q Developer.
 - **OAuth 2.0 built in** — full user-token management with automatic refresh, and smart fallback from user tokens (10k–50k req/day) to client credentials (1k req/day).
 - **Resilient by default** — automatic retry with exponential backoff on `429` rate limits, and consistent, loud error surfacing.
-- **Type-safe** — TypeScript end to end, Zod-validated tool inputs, and OpenAPI-generated types.
+- **Type-safe** — [TypeScript](https://www.typescriptlang.org/) end to end, [Effect](https://effect.website/docs)-backed tool input validation, and [OpenAPI](https://www.openapis.org/)-generated types.
 - **Local-first & private** — runs over STDIO or local HTTP; your credentials and data never leave your machine.
 - **Sandbox and production** — switch environments with a single variable.
 - **One-command setup** — `npm run setup` configures credentials, OAuth, and your MCP client, with a browser auto-opened for the OAuth flow.
-- **Well tested** — 1,000+ automated tests run in CI on every change.
+- **Well tested** — 1,000+ automated tests run in CI on every change through [GitHub Actions](https://docs.github.com/en/actions).
+
+## Capability map
+
+Use this map when deciding which tool family to expose, or when asking an assistant what it can do. The family names match `EBAY_MCP_TOOLS`, so you can run with all tools, dynamic discovery, or only the families needed for a specific workflow.
+
+| Family | What it unlocks | Good first request |
+| --- | --- | --- |
+| `account` | Business policies, fulfillment policies, payment policies, return policies, sales tax, subscriptions, and programs | "Show my eBay fulfillment policies." |
+| `inventory` | Inventory items, offers, inventory locations, item groups, bulk offer flows, and SKU/location mapping | "List my active inventory items and their available quantity." |
+| `fulfillment` | Orders, shipping fulfillments, refunds, payment disputes, and dispute evidence | "Show unfulfilled orders from the last 7 days." |
+| `browse` | Sold/completed listing search (Finding API) for pricing comps | "What have similar items sold for recently?" |
+| `marketing` | Promoted Listings campaigns, ads, promotions, bidding, and marketing reports | "List my active promoted listing campaigns." |
+| `analytics` | Traffic reports, seller standards, and customer-service metrics | "Show my seller standards profile." |
+| `communication` | Buyer-seller messaging, negotiations, notifications, and feedback | "Show recent buyer messages that need a response." |
+| `metadata` / `taxonomy` | Category trees, aspects, item conditions, return-policy metadata, tax jurisdictions, and vehicle compatibility | "Find required item aspects for this category." |
+| `other` | Identity, VeRO, translation, and international shipping support APIs (Compliance tools remain but report eBay's 2026-03-30 decommission) | "Show my current seller identity details." |
+| `developer` / `token-management` | Rate limits, signing keys, OAuth URLs, token refresh, and diagnostics | "Check my eBay API rate limits." |
+| `trading` | Legacy XML fixed-price listing create, revise, relist, and end operations | "Create a fixed-price listing draft from this SKU." |
+| `connector` | ChatGPT connector search/fetch tools over the eBay MCP catalogue | "Search the eBay tool catalogue for order tools." |
 
 ## eBay MCP vs. the raw eBay API
 
@@ -88,7 +109,7 @@ Both talk to the same eBay endpoints — the difference is everything you'd othe
 | Interface | Natural language through your AI assistant | Hand-written HTTP requests and JSON parsing |
 | OAuth & token refresh | Built in, with automatic refresh | You implement and maintain it |
 | Rate-limit handling | Automatic retry with exponential backoff | Manual `429` handling and backoff |
-| Input validation | Zod schemas + TypeScript types on every tool | None — you validate your own payloads |
+| Input validation | Effect-backed schemas + TypeScript types on every tool | None — you validate your own payloads |
 | Setup | One wizard (`npm run setup`) | Per-call auth, headers, and marketplace wiring |
 | AI client support | 9 clients auto-configured | Not applicable |
 | API coverage | 322 tools across 100% of the Sell APIs, ready to call | Build each request from the docs |
@@ -155,9 +176,17 @@ npm run setup
 
 The wizard configures your eBay credentials, sets up OAuth (for higher rate limits), auto-detects and configures your MCP client, and saves everything automatically.
 
-### 4. Use
+### 4. Verify with a read-only request
+
+Restart your MCP client and ask:
 
-Restart your MCP client (Claude Desktop, etc.) and start managing eBay through your AI assistant.
+> "Check my eBay API rate limits."
+
+That should call `ebay_get_rate_limits` or `ebay_get_user_rate_limits` and confirms the server, credentials, and MCP client wiring without changing seller data.
+
+### 5. Use
+
+Start managing eBay through your AI assistant. Begin with read-only questions, then move to mutating inventory, order, or campaign tools after you have confirmed the target environment is sandbox or production.
 
 <details>
 <summary><strong>📸 Visual setup walkthrough (eBay Developer Portal)</strong></summary>
@@ -194,6 +223,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
@@ -206,6 +238,11 @@ EBAY_CONTENT_LANGUAGE=en-US         # default request content language
 EBAY_USER_REFRESH_TOKEN=your_token  # for higher rate limits
 EBAY_MCP_UI=on                      # interactive MCP Apps views (beta); "off" forces plain JSON
 EBAY_MCP_TOOLS=all                  # tool exposure: "all", "dynamic", or a family list (see below)
+EBAY_READ_ONLY=false                # when true, only register read-only tools (gets/lists/searches)
+# HTTP deploy (optional — Docker / Railway / self-hosted):
+# MCP_HOST=0.0.0.0                  # default is 0.0.0.0 when PORT is set
+# MCP_PORT=3000                     # preferred over platform PORT
+# MCP_AUTH_TOKEN=secret             # static Bearer for HTTP MCP (skips OAuth verifier)
 ```
 
 ### Tool exposure (`EBAY_MCP_TOOLS`)
@@ -218,7 +255,7 @@ By default all tools are advertised to the agent at once. On a long conversation
 | `dynamic`                   | Only three discovery tools are visible (`list_ebay_tools`, `enable_ebay_tools`, `disable_ebay_tools`). The agent searches the catalogue and loads only the tools it needs; they then appear natively. | hosts that honor `tools/listChanged` (e.g. Claude) |
 | `inventory,fulfillment,…`   | Registers **only** the named families (listed below), frozen for the session.                                                                          | every host (incl. ChatGPT, Cursor)      |
 
-The family list is literal — you get exactly what you name. ChatGPT connectors need the `connector` family (its `search`/`fetch` tools); add it explicitly, e.g. `EBAY_MCP_TOOLS=connector,inventory`. An unknown family name fails fast at startup with the valid list. Valid families: `connector`, `token-management`, `account`, `inventory`, `fulfillment`, `marketing`, `analytics`, `metadata`, `taxonomy`, `communication`, `other`, `developer`, `trading`.
+The family list is literal — you get exactly what you name. ChatGPT connectors need the `connector` family (its `search`/`fetch` tools); add it explicitly, e.g. `EBAY_MCP_TOOLS=connector,inventory`. An unknown family name fails fast at startup with the valid list. Valid families: `connector`, `token-management`, `account`, `inventory`, `fulfillment`, `marketing`, `analytics`, `metadata`, `taxonomy`, `communication`, `browse`, `other`, `developer`, `trading`.
 
 ### Authentication & rate limits
 
@@ -231,7 +268,7 @@ User-token limits vary by account tier (Individual 10k · Commercial 25k · Ente
 
 ### MCP client compatibility
 
-Auto-configured by `npm run setup`. Requires Node.js ≥ 18 and MCP protocol 1.0+ over STDIO (default) or HTTP.
+Auto-configured by `npm run setup`. Requires [Node.js](https://nodejs.org/en) ≥ 20 and MCP protocol 1.0+ over STDIO (default) or HTTP.
 
 | Client                 | Platform              | Config path                                                                  |
 | ---------------------- | --------------------- | ---------------------------------------------------------------------------- |
@@ -245,12 +282,18 @@ 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 |
 | --- | --- |
+| [Connector](src/tools/categories/connector.ts) | ChatGPT connector search/fetch tools over the eBay MCP catalogue |
 | [Account](src/tools/categories/account.ts) | Business, fulfillment, payment, and return policies; programs; subscriptions; sales tax |
 | [Inventory](src/tools/categories/inventory.ts) | Inventory items, offers, locations, item groups, bulk operations, SKU/location mapping |
 | [Fulfillment](src/tools/categories/fulfillment.ts) | Orders, shipping, refunds, disputes, payment-dispute evidence |
@@ -259,35 +302,44 @@ Auto-configured by `npm run setup`. Requires Node.js ≥ 18 and MCP protocol 1.0
 | [Communication](src/tools/categories/communication.ts) | Buyer–seller messaging, negotiations, notifications, feedback |
 | [Metadata](src/tools/categories/metadata.ts) | Return policies, sales-tax jurisdictions, automotive compatibility |
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Category trees, item aspects, item conditions |
+| [Other](src/tools/categories/other.ts) | Identity, VeRO, translation, and international shipping support APIs (Compliance tools report eBay decommission) |
 | [Trading (legacy XML)](src/tools/categories/trading.ts) | Fixed-price listing create, revise, relist, end |
 | [Developer](src/tools/categories/developer.ts) | Rate limits, signing keys, client registration |
-| [Token Management](src/tools/categories/token-management.ts) | OAuth URL generation and token management |
+| [Token Management](src/tools/categories/tokenManagement.ts) | OAuth URL generation and token management |
 
 **Example tools:** `ebay_get_inventory_items`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
 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:
@@ -298,6 +350,15 @@ Common tasks, phrased as you'd ask your AI assistant:
 - **Create campaigns** — *"Create a promoted-listing campaign for electronics."* → `ebay_create_campaign` and related marketing tools.
 - **Bulk operations** — *"Apply a 10% discount to all 'Vintage Watches' items."* → `ebay_get_inventory_items` + `ebay_update_offer` across matches.
 
+## Scope and safety
+
+- **Unofficial project.** This is not an eBay product and does not grant any additional API rights beyond your own eBay Developer account.
+- **Local server, live APIs.** The MCP server runs on your machine, but tools still call eBay's sandbox or production APIs over the internet.
+- **Mutating tools can change seller data.** Inventory, fulfillment, marketing, and Trading tools may create, revise, refund, end, or otherwise update eBay records. Test in sandbox first.
+- **Tool exposure is configurable.** Use `EBAY_MCP_TOOLS=dynamic` or a family list when you want a smaller, workflow-specific tool surface.
+- **Interactive views are read-only.** MCP Apps views can page, refresh, and drill into read tools, but they do not mutate eBay data.
+- **Compliance remains yours.** Keep credentials secure, monitor rate limits, and follow eBay's API terms and data-handling rules.
+
 ## Logging & troubleshooting
 
 - **Logging** — Winston-based, written to stderr (MCP-safe) with optional file output. See [docs/logging.md](docs/logging.md).
@@ -305,95 +366,156 @@ 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`.
+Node.js ≥ 20, 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 Effect-backed validation are built in. See the [comparison table](#ebay-mcp-vs-the-raw-ebay-api) above.
 
-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.
+</details>
 
-### Does it support eBay's legacy Trading API (XML)?
+<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>
 
-TypeScript and Node.js (ESM), using the official MCP SDK, Zod for validation, and OpenAPI-generated types.
+<details>
+<summary><strong>What is it built with?</strong></summary>
 
-### How do I update to the latest version?
+TypeScript and Node.js (ESM), using the official MCP SDK, Effect-backed validation with a Zod-compatible MCP adapter, and OpenAPI-generated types.
+
+</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.
 
 - Working on the codebase or with a coding agent? Start with **[AGENTS.md](AGENTS.md)** — build/test commands, module map, and the add-an-endpoint workflow.
-- Full guidelines: **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+- Code style lives in **[CODE-STYLE.md](CODE-STYLE.md)**. Architecture and decision context live in **[ARCHITECTURE.md](ARCHITECTURE.md)** and [ADRs](docs/adr/current/).
+- Full contribution guidelines: **[CONTRIBUTING.md](CONTRIBUTING.md)**.
 
 ## Resources
 
-- [eBay Developer Portal](https://developer.ebay.com/) — API docs and credentials
-- [eBay API License Agreement](https://developer.ebay.com/join/api-license-agreement) — terms and compliance
-- [eBay Data Handling Requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html) — data protection and privacy
-- [MCP Documentation](https://modelcontextprotocol.io/) — Model Context Protocol spec
-- [OAuth Quick Reference](docs/auth/OAUTH_QUICK_REFERENCE.md) — scopes, troubleshooting, examples
-- [eBay API Status](https://developer.ebay.com/support/api-status) — official status page (also via the `ebay_get_api_status` tool and the [in-repo snapshot](docs/API_STATUS.md))
-- [CHANGELOG.md](CHANGELOG.md) · [SECURITY.md](SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
-- [Issue Tracker](https://github.com/YosefHayim/ebay-mcp/issues) — bug reports and feature requests
+Project docs:
+
+- [Configuration Guide](docs/auth/CONFIGURATION.md) — every environment variable, OAuth step, and eBay scope.
+- [OAuth Quick Reference](docs/auth/OAUTH_QUICK_REFERENCE.md) — scopes, troubleshooting, and examples.
+- [Logging Guide](docs/logging.md) and [Troubleshooting Guide](docs/troubleshooting.md) — operational help after setup.
+- [Architecture](ARCHITECTURE.md), [CODE-STYLE.md](CODE-STYLE.md), [AGENTS.md](AGENTS.md), and [llms.txt](llms.txt) — contributor and agent entry points.
+- [CHANGELOG.md](CHANGELOG.md), [SECURITY.md](SECURITY.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and the [Issue Tracker](https://github.com/YosefHayim/ebay-mcp/issues).
+
+Official specs and tooling:
+
+- [eBay Developer Portal](https://developer.ebay.com/), [Sell API docs](https://developer.ebay.com/api-docs/sell/static/overview.html), [API License Agreement](https://developer.ebay.com/join/api-license-agreement), [Data Handling Requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html), and [API Status](https://developer.ebay.com/support/api-status).
+- [Model Context Protocol](https://modelcontextprotocol.io/) and the [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps).
+- [Node.js](https://nodejs.org/en), [npm package](https://www.npmjs.com/package/ebay-mcp), [TypeScript](https://www.typescriptlang.org/), [Effect](https://effect.website/docs), [Biome](https://biomejs.dev/), [Vitest](https://vitest.dev/), and [GitHub Actions](https://docs.github.com/en/actions).
+- [AGENTS.md convention](https://agents.md/), [Claude Code](https://code.claude.com/docs/en/overview), [GitHub Copilot repository instructions](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions), and [llms.txt](https://llmstxt.org/).
 
 ## License
 

package/README.pt-BR.md

@@ -218,7 +218,7 @@ Os limites do token de usuário variam conforme o nível da conta (Individual 10
 
 ### Compatibilidade de clientes MCP
 
-Autoconfigurados pelo `npm run setup`. Requer Node.js ≥ 18 e o protocolo MCP 1.0+ via STDIO (padrão) ou HTTP.
+Autoconfigurados pelo `npm run setup`. Requer Node.js ≥ 20 e o protocolo MCP 1.0+ via STDIO (padrão) ou HTTP.
 
 | Cliente                | Plataforma            | Caminho de configuração                                                     |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ Autoconfigurados pelo `npm run setup`. Requer Node.js ≥ 18 e o protocolo MCP 1
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Árvores de categorias, aspectos de itens, condições de itens |
 | [Trading (XML legado)](src/tools/categories/trading.ts) | Criar, revisar, republicar e encerrar anúncios de preço fixo |
 | [Developer](src/tools/categories/developer.ts) | Limites de taxa, chaves de assinatura, registro de clientes |
-| [Token Management](src/tools/categories/token-management.ts) | Geração de URL de OAuth e gestão de tokens |
+| [Token Management](src/tools/categories/tokenManagement.ts) | Geração de URL de OAuth e gestão de tokens |
 
 **Ferramentas de exemplo:** `ebay_get_inventory_items`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
@@ -326,7 +326,7 @@ Roda inteiramente na sua máquina via STDIO (ou HTTP local). Não há relay na n
 
 ### O que preciso para começar?
 
-Node.js ≥ 18, uma [conta de desenvolvedor do eBay](https://developer.ebay.com/) gratuita (Client ID + Client Secret) e então rodar `npm run setup`.
+Node.js ≥ 20, uma [conta de desenvolvedor do eBay](https://developer.ebay.com/) gratuita (Client ID + Client Secret) e então rodar `npm run setup`.
 
 ### Quais são os limites de taxa da API do eBay?
 

package/README.ru.md

@@ -218,7 +218,7 @@ EBAY_MCP_UI=on                      # интерактивные предста
 
 ### Совместимость MCP-клиентов
 
-Автоматически настраиваются `npm run setup`. Требуется Node.js ≥ 18 и протокол MCP 1.0+ через STDIO (по умолчанию) или HTTP.
+Автоматически настраиваются `npm run setup`. Требуется Node.js ≥ 20 и протокол MCP 1.0+ через STDIO (по умолчанию) или HTTP.
 
 | Клиент                 | Платформа             | Путь к конфигурации                                                         |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ EBAY_MCP_UI=on                      # интерактивные предста
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Деревья категорий, характеристики товаров, состояния товаров |
 | [Trading (устаревший XML)](src/tools/categories/trading.ts) | Создание, изменение, повторное размещение и завершение объявлений с фиксированной ценой |
 | [Developer](src/tools/categories/developer.ts) | Лимиты запросов, ключи подписи, регистрация клиентов |
-| [Token Management](src/tools/categories/token-management.ts) | Генерация URL OAuth и управление токенами |
+| [Token Management](src/tools/categories/tokenManagement.ts) | Генерация URL OAuth и управление токенами |
 
 **Примеры инструментов:** `ebay_get_inventory_items`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
@@ -326,7 +326,7 @@ EBAY_MCP_UI=on                      # интерактивные предста
 
 ### Что нужно для начала работы?
 
-Node.js ≥ 18, бесплатный [аккаунт разработчика eBay](https://developer.ebay.com/) (Client ID + Client Secret), затем запустите `npm run setup`.
+Node.js ≥ 20, бесплатный [аккаунт разработчика eBay](https://developer.ebay.com/) (Client ID + Client Secret), затем запустите `npm run setup`.
 
 ### Каковы лимиты запросов API eBay?
 

package/README.zh-CN.md

@@ -218,7 +218,7 @@ EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）
 
 ### MCP 客户端兼容性
 
-由 `npm run setup` 自动配置。需要 Node.js ≥ 18 以及通过 STDIO（默认）或 HTTP 的 MCP 协议 1.0+。
+由 `npm run setup` 自动配置。需要 Node.js ≥ 20 以及通过 STDIO（默认）或 HTTP 的 MCP 协议 1.0+。
 
 | 客户端                 | 平台                  | 配置路径                                                                    |
 | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
@@ -248,7 +248,7 @@ EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）
 | [Taxonomy](src/tools/categories/taxonomy.ts) | 类目树、商品属性、商品成色 |
 | [Trading（旧版 XML）](src/tools/categories/trading.ts) | 固定价格刊登的创建、修改、重新刊登和结束 |
 | [Developer](src/tools/categories/developer.ts) | 速率限制、签名密钥、客户端注册 |
-| [Token Management](src/tools/categories/token-management.ts) | OAuth URL 生成与令牌管理 |
+| [Token Management](src/tools/categories/tokenManagement.ts) | OAuth URL 生成与令牌管理 |
 
 **示例工具：** `ebay_get_inventory_items`、`ebay_get_orders`、`ebay_create_offer`、`ebay_get_campaigns`、`ebay_get_oauth_url`。
 
@@ -326,7 +326,7 @@ EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）
 
 ### 我需要什么才能开始？
 
-Node.js ≥ 18、一个免费的 [eBay 开发者账号](https://developer.ebay.com/)（Client ID + Client Secret），然后运行 `npm run setup`。
+Node.js ≥ 20、一个免费的 [eBay 开发者账号](https://developer.ebay.com/)（Client ID + Client Secret），然后运行 `npm run setup`。
 
 ### eBay API 的速率限制是多少？