ebay-mcp 1.17.0 → 1.18.2

package/build/utils/schemaHelpers.js

@@ -1,10 +1,10 @@
-import { z } from '../utils/effectSchema.js';
+import { z } from 'zod';
 /**
  * Reusable schema builder for required string ID parameters.
  *
  * @param name - Human-readable parameter name used in validation messages.
  * @param description - Schema description exposed to MCP clients.
- * @returns Effect-backed string schema for a required ID parameter.
+ * @returns Zod string schema for a required ID parameter.
  *
  * @example
  * ```ts

package/build/utils/tokenUtils.js

@@ -1,6 +1,6 @@
-import { z } from '../utils/effectSchema.js';
+import { z } from 'zod';
 /**
- * Effect-backed schemas for token utility tools
+ * Zod schemas for token utility tools
  */
 /**
  * Input schema for converting date strings or timestamps into milliseconds.

package/build/utils/trading/trading.js

@@ -1,5 +1,5 @@
 import { FormatType } from '../../types/ebayEnums.js';
-import { z } from '../../utils/effectSchema.js';
+import { z } from 'zod';
 /** Listing format selector shared by the Trading listing tools. */
 const listingFormatSchema = z
     .nativeEnum(FormatType)

package/build/utils/version.js

@@ -132,7 +132,7 @@ export const getCachedUpdateNotice = () => {
  *
  * @example
  * ```ts
- * const info = await getUpdateInfo();
+ * const updateInfo = await getUpdateInfo();
  * ```
  */
 export const getUpdateInfo = async () => {

package/build/utils/zodIssues.js

@@ -0,0 +1,14 @@
+/**
+ * Formats Zod validation issues as one readable line for tool and endpoint errors.
+ *
+ * @param error - Zod error returned by a failed `safeParse`.
+ * @returns Issues joined by `; `, each prefixed with its dotted field path when it has one.
+ *
+ * @example
+ * ```ts
+ * formatZodIssues(schema.safeParse({}).error); // "sku: Required"
+ * ```
+ */
+export const formatZodIssues = (error) => error.issues
+    .map((issue) => issue.path.length > 0 ? `${issue.path.join('.')}: ${issue.message}` : issue.message)
+    .join('; ');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ebay-mcp",
-  "version": "1.17.0",
-  "description": "Model Context Protocol (MCP) server that exposes 100% of eBay's Sell APIs (313 tools across 283 endpoints) to AI assistants like Claude, Cursor, and Cline, covering inventory, order fulfillment, marketing, analytics, and developer tools with OAuth authentication and refresh-token support.",
+  "version": "1.18.2",
+  "description": "Model Context Protocol (MCP) server that exposes 100% of eBay's Sell APIs (384 tools across 360 endpoints) to AI assistants like Claude, Cursor, and Cline, covering inventory, order fulfillment, marketing, analytics, and developer tools with OAuth authentication and refresh-token support.",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -42,9 +42,7 @@
     "build/index.d.ts",
     "build/serverHttp.d.ts",
     "public/icons/*.png",
-    "README.md",
-    "docs/auth/production_scopes.json",
-    "docs/auth/sandbox_scopes.json"
+    "README.md"
   ],
   "repository": {
     "type": "git",
@@ -60,7 +58,6 @@
     "chalk": "^5.6.2",
     "cors": "^2.8.6",
     "dotenv": "^17.4.2",
-    "dotenv-stringify": "^3.0.1",
     "effect": "^3.21.4",
     "express": "^5.2.1",
     "fast-xml-builder": "1.2.0",
@@ -102,8 +99,8 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "tsc && tsc-alias && npm run build:ui",
-    "build:ui": "tsx src/scripts/buildUi.ts",
+    "build": "tsc && tsc-alias && pnpm run build:mcp-apps",
+    "build:mcp-apps": "tsx src/scripts/buildMcpApps.ts",
     "start": "node build/index.js",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
@@ -114,11 +111,11 @@
     "sync": "tsx src/scripts/devSync.ts",
     "diagnose": "node build/scripts/diagnostics.js",
     "typecheck": "tsc --noEmit",
-    "typecheck:ui": "tsc -p ui/tsconfig.json --noEmit",
-    "check": "tsc --noEmit && tsc -p ui/tsconfig.json --noEmit && biome check \"{src,ui}/**/*.{ts,tsx,js,json,md,css,html}\"",
+    "typecheck:mcp-apps": "tsc -p mcp-apps/tsconfig.json --noEmit",
+    "check": "tsc --noEmit && tsc -p mcp-apps/tsconfig.json --noEmit && biome check \"{src,mcp-apps}/**/*.{ts,tsx,js,json,md,css,html}\"",
     "check:ci": "biome ci .",
-    "verify": "npm run check:ci && npm run typecheck && npm run typecheck:ui && npm run test && npm run build",
-    "fix": "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true \"{src,ui}/**/*.{ts,tsx,js,json,md,css,html}\"",
+    "verify": "pnpm run check:ci && pnpm run typecheck && pnpm run typecheck:mcp-apps && pnpm run test && pnpm run build",
+    "fix": "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true \"{src,mcp-apps}/**/*.{ts,tsx,js,json,md,css,html}\"",
     "lint": "biome check .",
     "lint:fix": "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true .",
     "format": "biome format --write ."

package/README.de.md

@@ -1,422 +0,0 @@
-<!-- Keywords: eBay MCP-Server, Model Context Protocol für eBay, eBay-API für KI-Assistenten, eBay Sell API, eBay-Integration mit Claude, eBay mit Cursor, eBay-Bestandsautomatisierung, eBay-Auftragsverwaltung mit KI, eBay OAuth, eBay-Entwicklertools, MCP-Server für eBay -->
-
-<p align="center">
-  <a href="https://github.com/YosefHayim/ebay-mcp"><img src="public/ebay-mcp-hero.png" alt="eBay MCP-Server — verbinde Claude, Cursor und jeden KI-Assistenten mit einem einzigen Befehl mit den Sell-APIs von eBay (npm run setup)" width="820" /></a>
-</p>
-
-<p align="center">
-  <strong>Der eBay MCP-Server — gib Claude, Cursor und jedem KI-Assistenten vollen Zugriff auf die Sell-APIs von eBay. 313 Tools für Bestand, Bestellungen, Marketing und Analytik, lokal ausgeführt mit deinen eigenen Schlüsseln.</strong>
-</p>
-
-<p align="center"><sub>Inoffizielles Open-Source-Projekt — ohne Zugehörigkeit, Genehmigung oder Billigung durch eBay Inc.</sub></p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/ebay-mcp"><img src="https://img.shields.io/npm/v/ebay-mcp?logo=npm&color=cb3837" alt="npm-Version" /></a>
-  <a href="https://www.npmjs.com/package/ebay-mcp"><img src="https://img.shields.io/npm/dm/ebay-mcp?logo=npm&color=cb3837" alt="npm-Downloads pro Monat" /></a>
-  <a href="https://github.com/YosefHayim/ebay-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YosefHayim/ebay-mcp/ci.yml?branch=main&logo=github&label=CI" alt="CI-Status" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/npm/l/ebay-mcp?color=blue" alt="MIT-Lizenz" /></a>
-  <img src="https://img.shields.io/node/v/ebay-mcp?logo=node.js&color=339933" alt="erforderliche Node.js-Version" />
-  <img src="https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white" alt="TypeScript-Typen enthalten" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/tools-313-8957e5?logo=ebay&logoColor=white" alt="313 eBay-API-Tools" />
-  <img src="https://img.shields.io/badge/Sell%20API%20coverage-100%25-success" alt="100% Abdeckung der eBay Sell API" />
-  <img src="https://img.shields.io/badge/Model%20Context%20Protocol-compatible-000000" alt="Model Context Protocol kompatibel" />
-  <img src="https://img.shields.io/badge/tests-1%2C000%2B%20passing-3fb950?logo=vitest&logoColor=white" alt="über 1000 bestandene Tests" />
-  <img src="https://img.shields.io/badge/runs-100%25%20local-blue" alt="läuft vollständig auf deinem Rechner" />
-</p>
-
-<p align="center">
-  <a href="https://mseep.ai/app/yosefhayim-ebay-api-mcp-server"><img src="https://mseep.net/pr/yosefhayim-ebay-api-mcp-server-badge.png" alt="MseeP.ai-Sicherheitsbewertungs-Badge" height="40" /></a>
-</p>
-
-<p align="center">
-  <a href="README.md">English</a> ·
-  <a href="README.zh-CN.md">简体中文</a> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.pt-BR.md">Português (BR)</a> ·
-  <a href="README.ja.md">日本語</a> ·
-  <a href="README.ko.md">한국어</a> ·
-  <a href="README.fr.md">Français</a> ·
-  <strong>Deutsch</strong> ·
-  <a href="README.ru.md">Русский</a>
-</p>
-
----
-
-> **Hinweis:** Die englische [README.md](README.md) ist die Quelle der Wahrheit für aktuelle Produktangaben (Tool-Familien, API-Stilllegungen, Versionshinweise). Diese Übersetzung kann hinterherhinken.
-
-**eBay MCP** ist ein lokaler [Model-Context-Protocol](https://modelcontextprotocol.io)-Server, der KI-Assistenten —Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code und Amazon Q— direkt mit den **Sell-APIs von eBay** verbindet. Er stellt **313 Tools** bereit, die **100% der eBay-Sell-API-Oberfläche** (283 eindeutige Endpunkte) abdecken — für Bestandsverwaltung, Auftragsabwicklung, Marketing mit beworbenen Angeboten, Analytik und Entwicklerwerkzeuge. Alles läuft auf deinem Rechner über STDIO oder lokales HTTP — **kein Cloud-Relay**, und deine eBay-Zugangsdaten verlassen niemals deinen Computer.
-
-> **Haftungsausschluss:** Inoffizielles Drittanbieterprojekt — **ohne Zugehörigkeit zu oder Billigung durch eBay Inc.** Bereitgestellt „wie besehen“, ohne Gewährleistung. Du bist selbst dafür verantwortlich, die [eBay-API-Lizenzvereinbarung](https://developer.ebay.com/join/api-license-agreement) und die [Anforderungen an die Datenverarbeitung](https://developer.ebay.com/api-docs/static/data-handling-update.html) einzuhalten, deine Zugangsdaten zu schützen und die Ratenlimits einzuhalten. Teste im Sandbox-Modus vor dem Produktivbetrieb. Siehe [LICENSE](LICENSE), [SECURITY.md](SECURITY.md) und [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md).
-
-## Inhaltsverzeichnis
-
-- [Funktionen](#funktionen)
-- [eBay MCP im Vergleich zur reinen eBay-API](#ebay-mcp-im-vergleich-zur-reinen-ebay-api)
-- [KI-gestützte Einrichtung mit einem Klick](#ki-gestützte-einrichtung-mit-einem-klick)
-- [Schnellstart](#schnellstart)
-- [Demo](#demo)
-- [Konfiguration](#konfiguration)
-- [Verfügbare Tools](#verfügbare-tools)
-- [Interaktive Oberfläche (MCP Apps) — Beta](#interaktive-oberfläche-mcp-apps)
-- [Anwendungsbeispiele](#anwendungsbeispiele)
-- [Protokollierung und Fehlerbehebung](#protokollierung-und-fehlerbehebung)
-- [FAQ](#faq)
-- [Mitwirken](#mitwirken)
-- [Ressourcen](#ressourcen)
-- [Lizenz](#lizenz)
-- [Mitwirkende](#mitwirkende)
-
-## Funktionen
-
-- **313 eBay-API-Tools** — 100% Abdeckung der eBay-Sell-APIs für Bestand, Bestellungen, Marketing, Analytik, Metadaten, Taxonomie und Entwicklerwerkzeuge.
-- **9 KI-Clients, automatisch konfiguriert** — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI und Amazon Q Developer.
-- **OAuth 2.0 integriert** — vollständige Verwaltung von Benutzer-Tokens mit automatischer Erneuerung und intelligentem Rückfall von Benutzer-Tokens (10k–50k Anfragen/Tag) auf Client-Zugangsdaten (1k Anfragen/Tag).
-- **Standardmäßig robust** — automatischer Wiederholungsversuch mit exponentiellem Backoff bei `429`-Ratenlimits und konsistente, deutliche Fehlermeldungen.
-- **Typsicher** — durchgängig TypeScript, mit Effect validierte Tool-Eingaben und aus OpenAPI generierte Typen.
-- **Lokal und privat** — läuft über STDIO oder lokales HTTP; deine Zugangsdaten und Daten verlassen niemals deinen Rechner.
-- **Sandbox und Produktion** — wechsle die Umgebung mit einer einzigen Variablen.
-- **Einrichtung mit einem Befehl** — `npm run setup` konfiguriert Zugangsdaten, OAuth und deinen MCP-Client und öffnet automatisch den Browser für den OAuth-Ablauf.
-- **Gut getestet** — über 1000 automatisierte Tests laufen bei jeder Änderung in der CI.
-
-## eBay MCP im Vergleich zur reinen eBay-API
-
-Beide sprechen mit denselben eBay-Endpunkten — der Unterschied ist alles, was du sonst selbst bauen müsstest.
-
-| | **eBay MCP-Server** | **Reine eBay-REST-API** |
-| --- | --- | --- |
-| Schnittstelle | Natürliche Sprache über deinen KI-Assistenten | Handgeschriebene HTTP-Anfragen und JSON-Parsing |
-| OAuth & Token-Erneuerung | Integriert, mit automatischer Erneuerung | Du implementierst und pflegst sie |
-| Umgang mit Ratenlimits | Automatischer Wiederholungsversuch mit exponentiellem Backoff | Manuelle `429`-Behandlung und Backoff |
-| Eingabevalidierung | Effect-gestützte Schemata + TypeScript-Typen für jedes Tool | Keine — du validierst deine eigenen Payloads |
-| Einrichtung | Ein Assistent (`npm run setup`) | Auth, Header und Marketplace pro Aufruf |
-| Unterstützung von KI-Clients | 9 Clients automatisch konfiguriert | Nicht zutreffend |
-| API-Abdeckung | 313 Tools mit 100% Abdeckung der Sell-APIs, einsatzbereit | Du baust jede Anfrage anhand der Doku selbst |
-| Hosting | Läuft lokal, kein Cloud-Relay | Deine eigene Infrastruktur |
-
-## KI-gestützte Einrichtung mit einem Klick
-
-> **Lass deinen KI-Assistenten das für dich einrichten.** Kopiere den Prompt unten und füge ihn in Claude, ChatGPT oder einen beliebigen KI-Assistenten mit MCP-Unterstützung ein.
-
-<details>
-<summary><strong>Klicke, um den KI-Einrichtungs-Prompt zu kopieren</strong></summary>
-
-```
-I want to set up the eBay MCP Server for my AI assistant. Please help me:
-
-1. Install the eBay MCP server:
-   npm install -g ebay-mcp
-
-2. I need to configure it for [Claude Desktop / Cursor / Cline / Zed / Continue.dev / Windsurf / Claude Code CLI / Amazon Q] (choose one)
-
-3. My eBay credentials are:
-   - Client ID: [YOUR_CLIENT_ID]
-   - Client Secret: [YOUR_CLIENT_SECRET]
-   - Environment: [sandbox / production]
-   - Redirect URI (RuName): [YOUR_REDIRECT_URI]
-
-Please:
-- Create the appropriate config file for my MCP client
-- Set up the environment variables
-- Help me complete the OAuth flow to get a refresh token for higher rate limits
-- Test that the connection works
-
-If I don't have eBay credentials yet, guide me through creating a developer account at https://developer.ebay.com/
-```
-
-</details>
-
-## Schnellstart
-
-### 1. eBay-Zugangsdaten besorgen
-
-1. Erstelle ein kostenloses [eBay-Entwicklerkonto](https://developer.ebay.com/).
-2. Generiere App-Schlüssel im [Entwicklerportal](https://developer.ebay.com/my/keys).
-3. Speichere deine **Client ID** und dein **Client Secret**.
-
-### 2. Installieren
-
-```bash
-npm install -g ebay-mcp            # von npm (empfohlen)
-```
-
-Oder aus dem Quellcode:
-
-```bash
-git clone https://github.com/YosefHayim/ebay-mcp.git
-cd ebay-mcp && npm install && npm run build
-```
-
-### 3. Den Einrichtungsassistenten ausführen
-
-```bash
-npm run setup
-```
-
-Der Assistent konfiguriert deine eBay-Zugangsdaten, richtet OAuth ein (für höhere Ratenlimits), erkennt und konfiguriert deinen MCP-Client automatisch und speichert alles automatisch.
-
-### 4. Verwenden
-
-Starte deinen MCP-Client (Claude Desktop usw.) neu und beginne, eBay über deinen KI-Assistenten zu verwalten.
-
-<details>
-<summary><strong>📸 Visuelle Einrichtungsanleitung (eBay-Entwicklerportal)</strong></summary>
-
-<br />
-
-Der Einrichtungsassistent (`npm run setup`) übernimmt OAuth automatisch. Hier findest du deine Zugangsdaten im eBay-Entwicklerportal:
-
-**Schritt 1** — Kopiere im [Entwicklerportal](https://developer.ebay.com/my/keys) deine **App ID (Client ID)** und deine **Cert ID (Client Secret)**:
-
-![Schritt 1 - Client ID und Client Secret aus dem eBay-Entwicklerportal kopieren](public/screenshot-guides/STEP%20-%201%20-%20COPY%20CLIENT%20ID%20AND%20CLIENT%20SECRET%20TO%20ENV%20FILE.png)
-
-**Schritt 2** — Kopiere in den **User Tokens**-Einstellungen deiner App den **RuName** (eBay-Weiterleitungs-URL):
-
-![Schritt 2 - RuName-Weiterleitungs-URL aus den eBay-Anmeldeeinstellungen kopieren](public/screenshot-guides/STEP%20-%202%20-%20COPY%20REDIRECT%20URL.png)
-
-**Schritt 3** — Führe `npm run setup` aus. Es öffnet deinen Browser für die OAuth-Anmeldung und führt dich durch die eBay-Anmeldung:
-
-![Schritt 3 - Während des von npm run setup gestarteten OAuth-Ablaufs bei eBay anmelden](public/screenshot-guides/STEP%203%20-%20RUN%20COMMAND%20NPM%20RUN%20SETUP%20AND%20PREFORM%20OAUTH%20LOGIN.png)
-
-**Schritt 4** — Füge den Autorisierungscode aus der Callback-URL ein, wenn du dazu aufgefordert wirst:
-
-![Schritt 4 - Autorisierungscode in den eBay-MCP-Einrichtungsassistenten einfügen](public/screenshot-guides/STEP%20-%204%20-%20PASTE%20INTO%20THE%20SETUP%20WIZARD.png)
-
-Der Assistent tauscht den Code gegen Tokens, speichert sie und konfiguriert deinen MCP-Client. Du hast nun eine Authentifizierung mit Benutzer-Token (10k–50k Anfragen/Tag statt der standardmäßigen 1k/Tag).
-
-</details>
-
-## Demo
-
-Sieh dir den eBay MCP-Server in Aktion mit Claude Desktop an:
-
-https://github.com/user-attachments/assets/0173c8df-221c-4943-a4ce-cd20bce79f4b
-
-## Konfiguration
-
-> 📖 Die vollständige Referenz —jede Umgebungsvariable, jeder OAuth-Schritt und jeder Scope— steht im [Konfigurationsleitfaden](docs/auth/CONFIGURATION.md). `npm run setup` schreibt die `.env` für dich; die Variablen unten dienen nur als Referenz.
-
-```bash
-EBAY_CLIENT_ID=your_client_id
-EBAY_CLIENT_SECRET=your_client_secret
-EBAY_ENVIRONMENT=sandbox            # oder "production"
-EBAY_REDIRECT_URI=your_runame
-EBAY_MARKETPLACE_ID=EBAY_US         # Standard-Marketplace (pro Tool überschreibbar)
-EBAY_CONTENT_LANGUAGE=en-US         # Standard-Inhaltssprache der Anfragen
-EBAY_USER_REFRESH_TOKEN=your_token  # für höhere Ratenlimits
-EBAY_MCP_UI=on                      # interaktive MCP-Apps-Ansichten (Beta); auf "off" setzen, um reines JSON zu erzwingen
-```
-
-### Authentifizierung & Ratenlimits
-
-| Modus                                   | Tageslimit            | Am besten für           | Einrichtung                          |
-| --------------------------------------- | --------------------- | ----------------------- | ------------------------------------ |
-| **Client-Zugangsdaten** (Standard)      | 1000 Anfragen/Tag     | Entwicklung, Tests      | Automatisch mit Client ID + Secret   |
-| **Benutzer-Token** (empfohlen)          | 10k–50k Anfragen/Tag  | Produktion, hohe Last   | OAuth über `npm run setup`           |
-
-Die Limits des Benutzer-Tokens variieren je nach Kontostufe (Individual 10k · Commercial 25k · Enterprise 50k+). Bei einem `429` wiederholt der Server die Anfrage mit exponentiellem Backoff und meldet den Fehler. Details im [Konfigurationsleitfaden](docs/auth/CONFIGURATION.md) und in der [OAuth-Kurzreferenz](docs/auth/OAUTH_QUICK_REFERENCE.md); die Nutzung kannst du im [Entwicklerportal](https://developer.ebay.com/my/api_usage) überwachen.
-
-### MCP-Client-Kompatibilität
-
-Automatisch konfiguriert durch `npm run setup`. Erfordert Node.js ≥ 20 und das MCP-Protokoll 1.0+ über STDIO (Standard) oder HTTP.
-
-| Client                 | Plattform             | Konfigurationspfad                                                          |
-| ---------------------- | --------------------- | --------------------------------------------------------------------------- |
-| **Claude Desktop**     | macOS, Windows, Linux | `~/Library/Application Support/Claude/claude_desktop_config.json`            |
-| **Cursor IDE**         | macOS, Windows, Linux | `~/.cursor/mcp.json`                                                         |
-| **Zed Editor**         | macOS, Windows, Linux | `~/.config/zed/settings.json`                                               |
-| **Cline**              | VS-Code-Erweiterung   | `~/...globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
-| **Continue.dev**       | VS Code, JetBrains    | `~/.continue/config.json`                                                    |
-| **Windsurf (Codeium)** | macOS, Windows, Linux | `~/.codeium/windsurf/mcp_config.json`                                        |
-| **Roo Code**           | VS-Code-Erweiterung   | `~/...globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`   |
-| **Claude Code CLI**    | Terminal              | `~/.claude.json`                                                            |
-| **Amazon Q Developer** | AWS                   | `~/.aws/amazonq/mcp.json`                                                    |
-
-## Verfügbare Tools
-
-**313 Tools**, 100% Sell-API-Abdeckung, nach Kategorie geordnet. Jeder Link verweist auf die Tool-Definitionen und ihre Handler in [`src/tools/categories/`](src/tools/categories/):
-
-| Kategorie | Was du tun kannst |
-| --- | --- |
-| [Connector](src/tools/categories/connector.ts) | ChatGPT-Connector-Search/Fetch über den eBay-MCP-Katalog |
-| [Account](src/tools/categories/account.ts) | Geschäfts-, Versand-, Zahlungs- und Rückgaberichtlinien; Programme; Abonnements; Verkaufssteuer |
-| [Inventory](src/tools/categories/inventory.ts) | Bestandsartikel, Angebote, Standorte, Artikelgruppen, Massenvorgänge, SKU/Standort-Zuordnung sowie Upload lokaler Fotos/Videos ([`media.ts`](src/tools/categories/media.ts), Media API) |
-| [Fulfillment](src/tools/categories/fulfillment.ts) | Bestellungen, Versand, Rückerstattungen, Streitfälle, Nachweise zu Zahlungsstreitfällen |
-| [Marketing](src/tools/categories/marketing.ts) | Kampagnen für beworbene Angebote, Anzeigen, Aktionen, Gebote, Massenvorgänge |
-| [Analytics](src/tools/categories/analytics.ts) | Traffic-Berichte, Verkäuferstandards, Kundenservice-Kennzahlen |
-| [Communication](src/tools/categories/communication.ts) | Käufer-Verkäufer-Nachrichten, Verhandlungen, Benachrichtigungen, Bewertungen |
-| [Metadata](src/tools/categories/metadata.ts) | Rückgaberichtlinien, Verkaufssteuer-Zuständigkeiten, Fahrzeugkompatibilität |
-| [Taxonomy](src/tools/categories/taxonomy.ts) | Kategoriebäume, Artikelmerkmale, Artikelzustände |
-| [Browse](src/tools/categories/browse.ts) | Suche nach verkauften/abgeschlossenen Angeboten (Finding API) für Preisvergleiche |
-| [Other](src/tools/categories/other.ts) | Identity, VeRO, Übersetzung und internationale Versand-Support-APIs (Compliance-Tools melden eBays Stilllegung vom 2026-03-30) |
-| [Trading (Legacy-XML)](src/tools/categories/trading.ts) | Festpreisangebote und Auktionen erstellen, überarbeiten, neu einstellen und beenden |
-| [Developer](src/tools/categories/developer.ts) | Ratenlimits, Signaturschlüssel, Client-Registrierung |
-| [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`.
-
-Den vollständigen maschinenlesbaren Index findest du in [llms.txt](llms.txt).
-
-## Interaktive Oberfläche (MCP Apps)
-
-> **Beta** — diese Funktion ist neu und entwickelt sich gemeinsam mit der MCP-Apps-Spezifikation weiter, und die Host-Unterstützung wird gerade erst ausgerollt. Sie ist Opt-in und greift auf reines JSON zurück, sodass bestehende Clients niemals kaputtgehen. Schalte sie mit `EBAY_MCP_UI` um.
-
-Auf Hosts, die [MCP Apps](https://modelcontextprotocol.io) unterstützen, stellen gängige Lese-Tools ihre Ergebnisse als interaktive Ansichten statt als reines JSON dar — eine sortierbare **Tabelle**, eine Detail-**Karte** oder ein **Diagramm** — und nutzen dabei das eigene Theme des Hosts. Überall sonst liefern dieselben Tools weiterhin reines JSON, sodass nichts kaputtgeht. Sie basiert auf dem [MCP Apps SDK (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps), der Erweiterung, mit der MCP-Server interaktive Oberflächen an dialogorientierte Clients ausliefern können.
-
-- **Opt-in und Host-gesteuert.** Ansichten werden nur Clients angeboten, die die MCP-Apps-Fähigkeit ankündigen (z. B. Claude). Hosts ohne sie (z. B. Cursor) erhalten stillschweigend JSON.
-- **Notausschalter.** Setze `EBAY_MCP_UI=off`, um überall reines JSON zu erzwingen, selbst auf fähigen Hosts.
-- **Token-sparsam.** Das HTML jeder Ansicht wird vom Host einmalig außerhalb des Kontexts abgerufen (niemals in den Kontext des Modells); das Modell sieht nur eine einzeilige Zusammenfassung sowie die strukturierten Daten, die es ohnehin erhalten hätte.
-- **Schreibgeschützt.** Ansichten lösen ausschließlich Lese-Tools aus (in eine Zeile eintauchen, blättern, aktualisieren) — sie verändern deine eBay-Daten niemals.
-
-13 Tools für zentrale Arbeitsabläufe nehmen heute teil, über drei Archetypen hinweg:
-
-| Archetyp | Tools |
-| --- | --- |
-| **Tabelle** | `ebay_get_orders`, `ebay_get_shipping_fulfillments`, `ebay_get_offers`, `ebay_get_inventory_items`, `ebay_get_inventory_locations`, `ebay_get_payment_dispute_summaries` |
-| **Karte** | `ebay_get_order`, `ebay_get_offer`, `ebay_get_inventory_item`, `ebay_get_payment_dispute`, `ebay_get_seller_standards_profile` |
-| **Diagramm** | `ebay_get_traffic_report`, `ebay_get_customer_service_metric` |
-
-Die Ansichten werden mit `npm run build` (oder `npm run build:ui`) zu eigenständigem HTML gebaut; sie sind im veröffentlichten Paket enthalten und laden ohne eigenen Netzwerkzugriff.
-
-## Anwendungsbeispiele
-
-Häufige Aufgaben, formuliert wie du sie deinem KI-Assistenten stellen würdest:
-
-- **OAuth einrichten** — *„Hilf mir, OAuth für mein eBay-Konto einzurichten.“* → generiert eine Autorisierungs-URL über `ebay_get_oauth_url` und konfiguriert dann das Refresh-Token. Schaltet 10k–50k Anfragen/Tag frei.
-- **Bestand verwalten** — *„Zeig mir alle meine aktiven Angebote.“* → `ebay_get_inventory_items` liefert SKUs, Mengen und Status.
-- **Bestellungen bearbeiten** — *„Hol alle unerledigten Bestellungen der letzten 7 Tage.“* → `ebay_get_orders` mit Datums- und Versandstatus-Filtern.
-- **Kampagnen erstellen** — *„Erstelle eine Kampagne für beworbene Angebote für Elektronik.“* → `ebay_create_campaign` und zugehörige Marketing-Tools.
-- **Massenvorgänge** — *„Gewähre 10% Rabatt auf alle Artikel der Kategorie 'Vintage-Uhren'.“* → `ebay_get_inventory_items` + `ebay_update_offer` über die Treffer.
-
-## Protokollierung und Fehlerbehebung
-
-- **Protokollierung** — auf Winston basierend, nach stderr geschrieben (MCP-sicher), mit optionaler Dateiausgabe. Siehe [docs/logging.md](docs/logging.md).
-- **Fehlerbehebung** — Server erscheint nicht, Authentifizierungsfehler, Ratenlimits, leere Ergebnisse. Beginne mit `npm run diagnose` und siehe dann [docs/troubleshooting.md](docs/troubleshooting.md).
-
-## FAQ
-
-### Was ist der eBay MCP-Server?
-
-Ein lokaler [Model-Context-Protocol](https://modelcontextprotocol.io)-Server, der **313 Tools** bereitstellt, die **100% der Sell-APIs von eBay** (283 Endpunkte) für KI-Assistenten abdecken — Bestand, Auftragsabwicklung, Marketing, Analytik und Entwicklertools.
-
-### Ist das ein offizielles eBay-Produkt?
-
-Nein. Es ist ein inoffizielles Open-Source-Projekt eines Drittanbieters. Es ist **nicht mit eBay Inc. verbunden, von eBay autorisiert oder gebilligt.**
-
-### Welche KI-Assistenten und MCP-Clients werden unterstützt?
-
-`npm run setup` konfiguriert neun Clients automatisch: Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI und Amazon Q Developer. Jeder MCP-kompatible Client kann sich verbinden.
-
-### Kann ich es mit Claude, ChatGPT oder Cursor verwenden?
-
-Ja. Es funktioniert von Haus aus mit Claude Desktop und Claude Code, mit Cursor und anderen MCP-fähigen IDEs sowie mit jedem Assistenten, der das Model Context Protocol unterstützt. Der Ein-Klick-Einrichtungs-Prompt oben funktioniert auch mit ChatGPT und anderen Assistenten.
-
-### Warum sehe ich die interaktiven Tabellen und Diagramme nicht?
-
-Interaktive Ansichten via [MCP Apps](#interaktive-oberfläche-mcp-apps) erscheinen nur auf Hosts, die die Fähigkeit ankündigen (z. B. Claude); andere Clients erhalten dieselben Daten als reines JSON. Stelle außerdem sicher, dass du `EBAY_MCP_UI=off` nicht gesetzt hast und dass die Ansichten gebaut sind (`npm run build` führt `build:ui` aus).
-
-### Wie viele eBay-APIs und Tools deckt es ab?
-
-313 Tools über 283 eindeutige Endpunkte — 100% der Sell-APIs von eBay.
-
-### Ist es kostenlos und Open Source?
-
-Ja. Es wird unter der [MIT-Lizenz](LICENSE) veröffentlicht.
-
-### Läuft es lokal oder in der Cloud?
-
-Es läuft vollständig auf deinem Rechner über STDIO (oder lokales HTTP). Es gibt kein Cloud-Relay — deine eBay-Zugangsdaten verlassen niemals deinen Computer.
-
-### Was brauche ich, um loszulegen?
-
-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?
-
-Client-Zugangsdaten (Standard) erlauben etwa 1000 Anfragen/Tag. Die Authentifizierung mit einem Benutzer-Token über OAuth hebt dies je nach Kontostufe auf 10.000–50.000 Anfragen/Tag an.
-
-### Unterstützt es sowohl Sandbox als auch Produktion?
-
-Ja. Wechsle mit der Variablen `EBAY_ENVIRONMENT` (`sandbox` oder `production`).
-
-### Sind meine Zugangsdaten und Daten sicher?
-
-Zugangsdaten werden lokal in deiner `.env`-Datei gespeichert und nur verwendet, um eBay direkt aufzurufen. Siehe [SECURITY.md](SECURITY.md) und [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md).
-
-### Worin unterscheidet es sich vom direkten Aufruf der eBay-API?
-
-Du interagierst in natürlicher Sprache über deinen KI-Assistenten. OAuth-Token-Verwaltung, automatische Wiederholungen mit Backoff und typsichere Effect-gestützte Validierung sind integriert. Siehe die [Vergleichstabelle](#ebay-mcp-im-vergleich-zur-reinen-ebay-api) oben.
-
-### Kann es meine Fotos und Videos hochladen?
-
-Ja. `ebay_upload_images`, `ebay_upload_video` und `ebay_attach_media_to_inventory_item` lesen lokale Dateien (absolute Pfade oder `media://`-Referenzen) und laden sie über die Media API von eBay hoch. Zurück kommen EPS-Bild-URLs und Video-IDs für `product.imageUrls` / `product.videoIds`. Der Dateizugriff ist opt-in: Nichts ist lesbar, bis `EBAY_MCP_MEDIA_DIRS` oder `EBAY_MCP_MEDIA_ROOT` die Verzeichnisse benennt. Details: [Photos and videos from local files](README.md#photos-and-videos-from-local-files) (Englisch).
-
-### Unterstützt es Auktionen?
-
-Ja, über die REST-Inventory-Angebotstools: Erstelle das Angebot mit `format: "AUCTION"`, einem `auctionStartPrice`, einem optionalen `auctionReservePrice` und einer `listingDuration` in Tagen, und veröffentliche es dann. Details: [Auction offers](README.md#auction-offers) (Englisch). Die Trading-API-Tools nutzen denselben Schalter: `ebay_create_listing` mit `format: "AUCTION"` sendet `AddItem` mit `ListingType` Chinese, einem Startgebot `StartPrice` und einer `ListingDuration` in Tagen.
-
-### Unterstützt es die alte Trading-API von eBay (XML)?
-
-Ja. Das Erstellen, Überarbeiten, Neueinstellen und Beenden von Angeboten wird über die Trading-API-Tools unterstützt — für Festpreisangebote (`AddFixedPriceItem`-Familie, Standard) und für Auktionen (`format: "AUCTION"` → `AddItem`, `ReviseItem`, `EndItem`, `RelistItem`).
-
-### Wie bekomme ich höhere Ratenlimits?
-
-Schließe den OAuth-Ablauf mit `npm run setup` ab, um dich mit einem Benutzer-Token zu authentifizieren (10k–50k Anfragen/Tag statt der standardmäßigen 1k).
-
-### Womit ist es gebaut?
-
-TypeScript und Node.js (ESM), mit dem offiziellen MCP-SDK, Effect-gestützter Validierung mit einem Zod-kompatiblen MCP-Adapter und aus OpenAPI generierten Typen.
-
-### Wie aktualisiere ich auf die neueste Version?
-
-Führe `npm install -g ebay-mcp@latest` (oder `npm update -g ebay-mcp`) aus.
-
-### Funktioniert es offline?
-
-Nein. „Läuft lokal“ bedeutet, dass der Serverprozess auf deinem Rechner läuft — er benötigt dennoch eine Internetverbindung und gültige Zugangsdaten, um die Live-APIs von eBay zu erreichen.
-
-## Mitwirken
-
-Beiträge sind willkommen. Forken → Branch erstellen → Tests hinzufügen → `npm run check && npm test` → mit [Conventional Commits](https://www.conventionalcommits.org/) committen → PR öffnen.
-
-- Arbeitest du am Code oder mit einem Programmieragenten? Beginne mit **[AGENTS.md](AGENTS.md)** — Build-/Test-Befehle, Modulübersicht und der Ablauf zum Hinzufügen eines Endpunkts.
-- Vollständiger Leitfaden: **[CONTRIBUTING.md](CONTRIBUTING.md)**.
-
-## Ressourcen
-
-- [eBay-Entwicklerportal](https://developer.ebay.com/) — API-Dokumentation und Zugangsdaten
-- [eBay-API-Lizenzvereinbarung](https://developer.ebay.com/join/api-license-agreement) — Bedingungen und Compliance
-- [eBay-Anforderungen an die Datenverarbeitung](https://developer.ebay.com/api-docs/static/data-handling-update.html) — Datenschutz und Privatsphäre
-- [MCP-Dokumentation](https://modelcontextprotocol.io/) — Spezifikation des Model Context Protocol
-- [OAuth-Kurzreferenz](docs/auth/OAUTH_QUICK_REFERENCE.md) — Scopes, Fehlerbehebung, Beispiele
-- [eBay-API-Status](https://developer.ebay.com/support/api-status) — offizielle Statusseite (auch über das Tool `ebay_get_api_status` und den [Snapshot im Repository](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) — Fehlerberichte und Funktionswünsche
-
-## Lizenz
-
-MIT — siehe [LICENSE](LICENSE).
-
-## Mitwirkende
-
-Danke an alle, die geholfen haben, dieses Projekt zu verbessern! 🎉
-
-<a href="https://github.com/YosefHayim/ebay-mcp/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=YosefHayim/ebay-mcp" alt="eBay-MCP-Mitwirkende" />
-</a>
-
----
-
-<div align="center">
-
-<a href="https://www.buymeacoffee.com/yosefhayim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="48" /></a>
-
-<br /><br />
-
-**[Dieses Projekt unterstützen](https://www.buymeacoffee.com/yosefhayim)** · Erstellt von [Yosef Hayim Sabag](https://github.com/YosefHayim)
-
-<sub>eBay MCP-Server · Model Context Protocol für die eBay-Sell-APIs · verbinde Claude, Cursor und jeden KI-Assistenten mit eBay-Bestand, -Bestellungen, -Marketing und -Analytik.</sub>
-
-</div>