ebay-mcp 1.11.1 → 1.12.0

package/README.de.md

@@ -58,6 +58,7 @@
 - [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)
@@ -203,6 +204,7 @@ 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
@@ -252,6 +254,27 @@ Automatisch konfiguriert durch `npm run setup`. Erfordert Node.js ≥ 18 und das
 
 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:
@@ -285,6 +308,10 @@ Nein. Es ist ein inoffizielles Open-Source-Projekt eines Drittanbieters. Es ist
 
 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?
 
 322 Tools über 270 eindeutige Endpunkte — 100% der Sell-APIs von eBay.

package/README.es.md

@@ -58,6 +58,7 @@
 - [Demostración](#demostración)
 - [Configuración](#configuración)
 - [Herramientas disponibles](#herramientas-disponibles)
+- [Interfaz interactiva (MCP Apps) — beta](#interfaz-interactiva-mcp-apps)
 - [Ejemplos de uso](#ejemplos-de-uso)
 - [Registro y solución de problemas](#registro-y-solución-de-problemas)
 - [Preguntas frecuentes](#preguntas-frecuentes)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # mercado predeterminado (anulable por herramienta)
 EBAY_CONTENT_LANGUAGE=en-US         # idioma de contenido predeterminado de las solicitudes
 EBAY_USER_REFRESH_TOKEN=your_token  # para límites de tasa más altos
+EBAY_MCP_UI=on                      # vistas interactivas MCP Apps (beta); pon "off" para forzar JSON simple
 ```
 
 ### Autenticación y límites de tasa
@@ -252,6 +254,27 @@ Autoconfigurados por `npm run setup`. Requiere Node.js ≥ 18 y el protocolo MCP
 
 Para el índice completo legible por máquina, consulta [llms.txt](llms.txt).
 
+## Interfaz interactiva (MCP Apps)
+
+> **Beta** — esta función es nueva y evoluciona junto con la especificación de MCP Apps, y la compatibilidad de los hosts aún se está desplegando. Es opcional y recurre a JSON simple, así que nunca rompe los clientes existentes. Actívala o desactívala con `EBAY_MCP_UI`.
+
+En los hosts compatibles con [MCP Apps](https://modelcontextprotocol.io), las herramientas de lectura más habituales muestran sus resultados como vistas interactivas en lugar de JSON sin procesar —una **tabla** ordenable, una **ficha** de detalle o un **gráfico**— usando el propio tema del host. En cualquier otro lugar, esas mismas herramientas devuelven JSON simple, así que nada se rompe. Está construido sobre el [SDK de MCP Apps (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps), la extensión que permite a los servidores MCP ofrecer interfaces interactivas a los clientes conversacionales.
+
+- **Opcional y supeditado al host.** Las vistas solo se anuncian a los clientes que declaran la capacidad de MCP Apps (p. ej. Claude). Los hosts que no la tienen (p. ej. Cursor) reciben JSON sin más.
+- **Interruptor de emergencia.** Define `EBAY_MCP_UI=off` para forzar JSON simple en todas partes, incluso en hosts compatibles.
+- **Eficiente en tokens.** El host obtiene el HTML de cada vista una sola vez y de forma externa (nunca entra en el contexto del modelo); el modelo solo ve un resumen de una línea más los datos estructurados que habría recibido de todos modos.
+- **Solo lectura.** Las vistas únicamente activan herramientas de lectura (profundizar en una fila, paginar, actualizar): nunca modifican tus datos de eBay.
+
+Hoy se acogen 13 herramientas de flujos de trabajo esenciales, repartidas en tres arquetipos:
+
+| Arquetipo | Herramientas |
+| --- | --- |
+| **Tabla** | `ebay_get_orders`, `ebay_get_shipping_fulfillments`, `ebay_get_offers`, `ebay_get_inventory_items`, `ebay_get_inventory_locations`, `ebay_get_payment_dispute_summaries` |
+| **Ficha** | `ebay_get_order`, `ebay_get_offer`, `ebay_get_inventory_item`, `ebay_get_payment_dispute`, `ebay_get_seller_standards_profile` |
+| **Gráfico** | `ebay_get_traffic_report`, `ebay_get_customer_service_metric` |
+
+Las vistas se compilan en HTML autónomo con `npm run build` (o `npm run build:ui`); se incluyen en el paquete publicado y se cargan sin acceso de red propio.
+
 ## Ejemplos de uso
 
 Tareas comunes, formuladas como se las pedirías a tu asistente de IA:
@@ -285,6 +308,10 @@ No. Es un proyecto de código abierto de terceros no oficial. **No está afiliad
 
 Sí. Funciona con Claude Desktop y Claude Code de forma nativa, con Cursor y otros IDE con MCP, y con cualquier asistente que soporte el Model Context Protocol. El mensaje de configuración con un clic de arriba también funciona con ChatGPT y otros asistentes.
 
+### ¿Por qué no veo las tablas y los gráficos interactivos?
+
+Las vistas interactivas de [MCP Apps](#interfaz-interactiva-mcp-apps) solo aparecen en los hosts que declaran la capacidad (p. ej. Claude); los demás clientes reciben los mismos datos como JSON simple. Comprueba también que no hayas definido `EBAY_MCP_UI=off` y que las vistas estén compiladas (`npm run build` ejecuta `build:ui`).
+
 ### ¿Cuántas APIs y herramientas de eBay cubre?
 
 322 herramientas en 270 endpoints únicos: el 100% de las Sell APIs de eBay.

package/README.fr.md

@@ -58,6 +58,7 @@
 - [Démonstration](#démonstration)
 - [Configuration](#configuration)
 - [Outils disponibles](#outils-disponibles)
+- [Interface interactive (MCP Apps) — bêta](#interface-interactive-mcp-apps)
 - [Exemples d'utilisation](#exemples-dutilisation)
 - [Journalisation et dépannage](#journalisation-et-dépannage)
 - [FAQ](#faq)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # marketplace par défaut (modifiable par outil)
 EBAY_CONTENT_LANGUAGE=en-US         # langue de contenu par défaut des requêtes
 EBAY_USER_REFRESH_TOKEN=your_token  # pour des limites de débit plus élevées
+EBAY_MCP_UI=on                      # vues interactives MCP Apps (bêta) ; mettez "off" pour forcer le JSON brut
 ```
 
 ### Authentification et limites de débit
@@ -252,6 +254,27 @@ Configurés automatiquement par `npm run setup`. Nécessite Node.js ≥ 18 et le
 
 Pour l'index complet lisible par machine, consultez [llms.txt](llms.txt).
 
+## Interface interactive (MCP Apps)
+
+> **Bêta** — cette fonctionnalité est récente et évolue en parallèle de la spécification MCP Apps, et la prise en charge par les hôtes se déploie encore. Elle est optionnelle et se replie sur du JSON brut, donc elle ne casse jamais les clients existants. Activez-la ou désactivez-la avec `EBAY_MCP_UI`.
+
+Sur les hôtes qui prennent en charge [MCP Apps](https://modelcontextprotocol.io), les outils de lecture courants affichent leurs résultats sous forme de vues interactives plutôt qu'en JSON brut — un **tableau** triable, une **fiche** détaillée ou un **graphique** — en utilisant le thème de l'hôte lui-même. Partout ailleurs, ces mêmes outils renvoient du JSON brut, donc rien ne casse. Elle s'appuie sur le [SDK MCP Apps (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps), l'extension qui permet aux serveurs MCP de fournir une interface interactive aux clients conversationnels.
+
+- **Optionnel et conditionné par l'hôte.** Les vues ne sont proposées qu'aux clients qui annoncent la capacité MCP Apps (par ex. Claude). Les hôtes qui ne la prennent pas en charge (par ex. Cursor) reçoivent silencieusement du JSON.
+- **Interrupteur d'arrêt.** Mettez `EBAY_MCP_UI=off` pour forcer le JSON brut partout, même sur les hôtes compatibles.
+- **Économe en jetons.** Le HTML de chaque vue est récupéré une seule fois par l'hôte, hors bande (jamais dans le contexte du modèle) ; le modèle ne voit qu'un résumé d'une ligne, en plus des données structurées qu'il aurait reçues de toute façon.
+- **En lecture seule.** Les vues ne déclenchent jamais que des outils de lecture (explorer une ligne, paginer, actualiser) — elles ne modifient jamais vos données eBay.
+
+13 outils de flux de travail essentiels y adhèrent aujourd'hui, répartis en trois archétypes :
+
+| Archétype | Outils |
+| --- | --- |
+| **Tableau** | `ebay_get_orders`, `ebay_get_shipping_fulfillments`, `ebay_get_offers`, `ebay_get_inventory_items`, `ebay_get_inventory_locations`, `ebay_get_payment_dispute_summaries` |
+| **Fiche** | `ebay_get_order`, `ebay_get_offer`, `ebay_get_inventory_item`, `ebay_get_payment_dispute`, `ebay_get_seller_standards_profile` |
+| **Graphique** | `ebay_get_traffic_report`, `ebay_get_customer_service_metric` |
+
+Les vues se compilent en HTML autonome avec `npm run build` (ou `npm run build:ui`) ; elles sont incluses dans le paquet publié et se chargent sans aucun accès réseau propre.
+
 ## Exemples d'utilisation
 
 Tâches courantes, formulées comme vous les demanderiez à votre assistant IA :
@@ -285,6 +308,10 @@ Non. C'est un projet open source tiers non officiel. Il n'est **ni affilié, ni
 
 Oui. Il fonctionne nativement avec Claude Desktop et Claude Code, avec Cursor et d'autres IDE compatibles MCP, et avec tout assistant prenant en charge le Model Context Protocol. L'invite de configuration en un clic ci-dessus fonctionne aussi avec ChatGPT et d'autres assistants.
 
+### Pourquoi ne vois-je pas les tableaux et graphiques interactifs ?
+
+Les vues interactives [MCP Apps](#interface-interactive-mcp-apps) n'apparaissent que sur les hôtes qui annoncent la capacité (par ex. Claude) ; les autres clients reçoivent les mêmes données en JSON brut. Vérifiez aussi que vous n'avez pas défini `EBAY_MCP_UI=off` et que les vues sont compilées (`npm run build` exécute `build:ui`).
+
 ### Combien d'API et d'outils eBay couvre-t-il ?
 
 322 outils sur 270 endpoints uniques — 100% des Sell APIs d'eBay.

package/README.ja.md

@@ -58,6 +58,7 @@
 - [デモ](#デモ)
 - [設定](#設定)
 - [利用可能なツール](#利用可能なツール)
+- [インタラクティブ UI（MCP Apps・ベータ）](#インタラクティブ-ui-mcp-apps)
 - [使用例](#使用例)
 - [ログとトラブルシューティング](#ログとトラブルシューティング)
 - [よくある質問](#よくある質問)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # 既定のマーケットプレイス（ツールごとに上書き可能）
 EBAY_CONTENT_LANGUAGE=en-US         # リクエストの既定コンテンツ言語
 EBAY_USER_REFRESH_TOKEN=your_token  # より高いレート制限のため
+EBAY_MCP_UI=on                      # インタラクティブな MCP Apps 表示（ベータ）。プレーンな JSON を強制するには "off" に設定
 ```
 
 ### 認証とレート制限
@@ -252,6 +254,27 @@ EBAY_USER_REFRESH_TOKEN=your_token  # より高いレート制限のため
 
 完全な機械可読インデックスは [llms.txt](llms.txt) を参照してください。
 
+## インタラクティブ UI（MCP Apps）
+
+> **ベータ版** — この機能は新しく、MCP Apps の仕様とともに進化を続けており、ホスト側の対応もまだ広がっている段階です。オプトイン方式で、対応していない場合はプレーンな JSON にフォールバックするため、既存のクライアントを壊すことは決してありません。`EBAY_MCP_UI` で切り替えられます。
+
+[MCP Apps](https://modelcontextprotocol.io) に対応するホストでは、よく使う読み取り系ツールが結果を生の JSON ではなくインタラクティブな表示として描画します — 並べ替え可能な **テーブル**、詳細を示す **カード**、または **チャート** — ホスト自身のテーマを用いて。それ以外の環境では、まったく同じツールがプレーンな JSON を返すため、何も壊れません。これは、MCP サーバーが会話型クライアントにインタラクティブな UI を提供できるようにする公式の拡張機能、[MCP Apps SDK (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps) を基盤に構築されています。
+
+- **オプトインかつホスト依存。** 表示は、MCP Apps 機能を通知するクライアント（例：Claude）にのみ提供されます。それを持たないホスト（例：Cursor）には何も告知されず、JSON が返されます。
+- **キルスイッチ。** `EBAY_MCP_UI=off` を設定すると、対応ホストであってもどこでもプレーンな JSON を強制できます。
+- **トークン効率。** 各表示の HTML はホストが帯域外で一度だけ取得し（モデルのコンテキストに入ることは決してありません）、モデルが目にするのは 1 行の要約と、いずれにせよ受け取っていた構造化データだけです。
+- **読み取り専用。** 表示が呼び出すのは読み取り系ツールのみです（行の詳細表示、ページング、更新） — あなたの eBay データを変更することは決してありません。
+
+現在、3 つの基本タイプにわたり 13 個のコアワークフローツールがオプトインしています：
+
+| タイプ | ツール |
+| --- | --- |
+| **テーブル** | `ebay_get_orders`、`ebay_get_shipping_fulfillments`、`ebay_get_offers`、`ebay_get_inventory_items`、`ebay_get_inventory_locations`、`ebay_get_payment_dispute_summaries` |
+| **カード** | `ebay_get_order`、`ebay_get_offer`、`ebay_get_inventory_item`、`ebay_get_payment_dispute`、`ebay_get_seller_standards_profile` |
+| **チャート** | `ebay_get_traffic_report`、`ebay_get_customer_service_metric` |
+
+これらの表示は `npm run build`（または `npm run build:ui`）で自己完結型の HTML にビルドされ、公開パッケージに同梱されて、それ自体は一切のネットワークアクセスなしで読み込まれます。
+
 ## 使用例
 
 AI アシスタントに尋ねるように表現した一般的なタスク：
@@ -285,6 +308,10 @@ AI アシスタントに **eBay Sell API の 100%**（270 エンドポイント
 
 はい。Claude Desktop と Claude Code でそのまま動作し、Cursor やその他の MCP 対応 IDE、そして Model Context Protocol に対応するあらゆるアシスタントで利用できます。上のワンクリック設定プロンプトは ChatGPT や他のアシスタントでも機能します。
 
+### インタラクティブなテーブルやチャートが表示されないのはなぜですか？
+
+インタラクティブな [MCP Apps](#インタラクティブ-ui-mcp-apps) の表示は、その機能を通知するホスト（例：Claude）でのみ現れます。他のクライアントには同じデータがプレーンな JSON として返されます。あわせて、`EBAY_MCP_UI=off` を設定していないこと、そして表示がビルドされていること（`npm run build` が `build:ui` を実行します）を確認してください。
+
 ### eBay の API とツールはどれくらいカバーしていますか？
 
 270 の固有エンドポイントにわたる 322 ツール — eBay Sell API の 100% です。

package/README.ko.md

@@ -58,6 +58,7 @@
 - [데모](#데모)
 - [구성](#구성)
 - [사용 가능한 도구](#사용-가능한-도구)
+- [대화형 UI (MCP Apps) — 베타](#대화형-ui-mcp-apps)
 - [사용 예시](#사용-예시)
 - [로깅 및 문제 해결](#로깅-및-문제-해결)
 - [자주 묻는 질문](#자주-묻는-질문)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # 기본 마켓플레이스 (도구별 재정의 가능)
 EBAY_CONTENT_LANGUAGE=en-US         # 요청의 기본 콘텐츠 언어
 EBAY_USER_REFRESH_TOKEN=your_token  # 더 높은 속도 제한용
+EBAY_MCP_UI=on                      # 대화형 MCP Apps 보기(베타); 일반 JSON을 강제하려면 "off"로 설정
 ```
 
 ### 인증 및 속도 제한
@@ -252,6 +254,27 @@ EBAY_USER_REFRESH_TOKEN=your_token  # 더 높은 속도 제한용
 
 전체 기계 판독 인덱스는 [llms.txt](llms.txt)를 참조하세요.
 
+## 대화형 UI (MCP Apps)
+
+> **베타** — 이 기능은 새로 추가되었으며 MCP Apps 사양과 함께 발전하고 있고, 호스트 지원도 아직 확대되는 중입니다. 옵트인 방식이며 일반 JSON으로 폴백하므로 기존 클라이언트를 절대 깨뜨리지 않습니다. `EBAY_MCP_UI`로 켜고 끌 수 있습니다.
+
+[MCP Apps](https://modelcontextprotocol.io)를 지원하는 호스트에서는 일반적인 읽기 도구가 결과를 원시 JSON 대신 대화형 보기로 — 정렬 가능한 **테이블**, 상세 **카드**, 또는 **차트** — 호스트 자체 테마를 사용해 렌더링합니다. 그 외 모든 곳에서는 완전히 동일한 도구가 일반 JSON을 반환하므로 아무것도 깨지지 않습니다. 이 기능은 MCP 서버가 대화형 클라이언트에 대화형 UI를 제공할 수 있게 해주는 공식 확장인 [MCP Apps SDK (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps) 위에 구축되었습니다.
+
+- **옵트인이며 호스트에 따라 제한됨.** 보기는 MCP Apps 기능을 알리는 클라이언트(예: Claude)에만 광고됩니다. 이를 지원하지 않는 호스트(예: Cursor)는 조용히 JSON을 받습니다.
+- **킬 스위치.** `EBAY_MCP_UI=off`로 설정하면 지원하는 호스트에서도 모든 곳에서 일반 JSON을 강제합니다.
+- **토큰 절약.** 각 보기의 HTML은 호스트가 한 번만 별도 경로로 가져오며(모델의 컨텍스트로는 절대 들어가지 않음), 모델은 한 줄 요약과 어차피 받았을 구조화된 데이터만 보게 됩니다.
+- **읽기 전용.** 보기는 읽기 도구만 트리거하며(행 상세 보기, 페이지 이동, 새로 고침) — eBay 데이터를 절대 변경하지 않습니다.
+
+오늘 기준 13개의 핵심 워크플로 도구가 세 가지 원형에 걸쳐 옵트인되어 있습니다:
+
+| 원형 | 도구 |
+| --- | --- |
+| **테이블** | `ebay_get_orders`, `ebay_get_shipping_fulfillments`, `ebay_get_offers`, `ebay_get_inventory_items`, `ebay_get_inventory_locations`, `ebay_get_payment_dispute_summaries` |
+| **카드** | `ebay_get_order`, `ebay_get_offer`, `ebay_get_inventory_item`, `ebay_get_payment_dispute`, `ebay_get_seller_standards_profile` |
+| **차트** | `ebay_get_traffic_report`, `ebay_get_customer_service_metric` |
+
+보기는 `npm run build`(또는 `npm run build:ui`)로 자체 완결형 HTML로 빌드되며, 게시된 패키지에 포함되어 자체적인 네트워크 접근 없이 로드됩니다.
+
 ## 사용 예시
 
 AI 어시스턴트에게 묻듯이 표현한 일반적인 작업:
@@ -285,6 +308,10 @@ AI 어시스턴트에 **eBay Sell API의 100%**(270개 엔드포인트)를 포
 
 네. Claude Desktop과 Claude Code에서 기본 지원되고, Cursor 및 기타 MCP 지원 IDE, 그리고 Model Context Protocol을 지원하는 모든 어시스턴트에서 작동합니다. 위의 원클릭 설정 프롬프트는 ChatGPT 및 다른 어시스턴트에서도 작동합니다.
 
+### 대화형 테이블과 차트가 보이지 않는 이유는 무엇인가요?
+
+대화형 [MCP Apps](#대화형-ui-mcp-apps) 보기는 해당 기능을 알리는 호스트(예: Claude)에서만 나타나며, 다른 클라이언트는 동일한 데이터를 일반 JSON으로 받습니다. 또한 `EBAY_MCP_UI=off`로 설정하지 않았는지, 그리고 보기가 빌드되어 있는지(`npm run build`가 `build:ui`를 실행함) 확인하세요.
+
 ### eBay API와 도구를 얼마나 커버하나요?
 
 270개 고유 엔드포인트에 걸친 322개 도구 — eBay Sell API의 100%입니다.

package/README.md

@@ -58,6 +58,7 @@
 - [Demo](#demo)
 - [Configuration](#configuration)
 - [Available tools](#available-tools)
+- [Interactive UI (MCP Apps) — beta](#interactive-ui-mcp-apps)
 - [Usage examples](#usage-examples)
 - [Logging & troubleshooting](#logging--troubleshooting)
 - [FAQ](#faq)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # default marketplace (overridable per tool)
 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
 ```
 
 ### Authentication & rate limits
@@ -252,6 +254,27 @@ 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).
 
+## Interactive UI (MCP Apps)
+
+> **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.
+
+- **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:
+
+| 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` |
+
+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.
+
 ## Usage examples
 
 Common tasks, phrased as you'd ask your AI assistant:
@@ -285,6 +308,10 @@ Nine clients are auto-configured by `npm run setup`: Claude Desktop, Cursor, Zed
 
 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?
+
+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?
 
 322 tools across 270 unique endpoints — 100% of eBay's Sell APIs.

package/README.pt-BR.md

@@ -58,6 +58,7 @@
 - [Demonstração](#demonstração)
 - [Configuração](#configuração)
 - [Ferramentas disponíveis](#ferramentas-disponíveis)
+- [Interface interativa (MCP Apps) — beta](#interface-interativa-mcp-apps)
 - [Exemplos de uso](#exemplos-de-uso)
 - [Logs e solução de problemas](#logs-e-solução-de-problemas)
 - [Perguntas frequentes](#perguntas-frequentes)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # marketplace padrão (substituível por ferramenta)
 EBAY_CONTENT_LANGUAGE=en-US         # idioma de conteúdo padrão das requisições
 EBAY_USER_REFRESH_TOKEN=your_token  # para limites de taxa mais altos
+EBAY_MCP_UI=on                      # visualizações interativas MCP Apps (beta); defina "off" para forçar JSON puro
 ```
 
 ### Autenticação e limites de taxa
@@ -252,6 +254,27 @@ Autoconfigurados pelo `npm run setup`. Requer Node.js ≥ 18 e o protocolo MCP 1
 
 Para o índice completo legível por máquina, consulte [llms.txt](llms.txt).
 
+## Interface interativa (MCP Apps)
+
+> **Beta** — este recurso é novo e evolui junto com a especificação do MCP Apps, e o suporte dos hosts ainda está sendo lançado. É opcional (opt-in) e tem fallback para JSON puro, então nunca quebra clientes existentes. Ative ou desative com `EBAY_MCP_UI`.
+
+Em hosts compatíveis com [MCP Apps](https://modelcontextprotocol.io), as ferramentas de leitura mais comuns exibem seus resultados como visualizações interativas em vez de JSON bruto — uma **tabela** ordenável, um **cartão** de detalhes ou um **gráfico** — usando o próprio tema do host. Em qualquer outro lugar, exatamente as mesmas ferramentas retornam JSON puro, então nada quebra. É construída sobre o [SDK oficial do MCP Apps (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps), a extensão que permite que servidores MCP entreguem interfaces interativas a clientes conversacionais.
+
+- **Opt-in e condicionado ao host.** As visualizações só são anunciadas aos clientes que declaram a capacidade MCP Apps (por exemplo, o Claude). Hosts sem ela (por exemplo, o Cursor) recebem JSON silenciosamente.
+- **Interruptor de desligamento.** Defina `EBAY_MCP_UI=off` para forçar JSON puro em todos os lugares, mesmo em hosts compatíveis.
+- **Econômico em tokens.** O HTML de cada visualização é buscado uma única vez pelo host fora de banda (nunca entra no contexto do modelo); o modelo só vê um resumo de uma linha mais os dados estruturados que receberia de qualquer forma.
+- **Somente leitura.** As visualizações só acionam ferramentas de leitura (detalhar uma linha, paginar, atualizar) — elas nunca alteram seus dados do eBay.
+
+13 ferramentas de fluxos de trabalho essenciais adotam isso hoje, em três arquétipos:
+
+| Arquétipo | Ferramentas |
+| --- | --- |
+| **Tabela** | `ebay_get_orders`, `ebay_get_shipping_fulfillments`, `ebay_get_offers`, `ebay_get_inventory_items`, `ebay_get_inventory_locations`, `ebay_get_payment_dispute_summaries` |
+| **Cartão** | `ebay_get_order`, `ebay_get_offer`, `ebay_get_inventory_item`, `ebay_get_payment_dispute`, `ebay_get_seller_standards_profile` |
+| **Gráfico** | `ebay_get_traffic_report`, `ebay_get_customer_service_metric` |
+
+As visualizações são compiladas em HTML autocontido com `npm run build` (ou `npm run build:ui`); elas são distribuídas no pacote publicado e carregam sem nenhum acesso à rede próprio.
+
 ## Exemplos de uso
 
 Tarefas comuns, formuladas como você pediria ao seu assistente de IA:
@@ -285,6 +308,10 @@ Não. É um projeto de código aberto de terceiros não oficial. **Não tem afil
 
 Sim. Funciona com Claude Desktop e Claude Code de forma nativa, com Cursor e outros IDEs com MCP, e com qualquer assistente que suporte o Model Context Protocol. O prompt de configuração em um clique acima também funciona com ChatGPT e outros assistentes.
 
+### Por que não vejo as tabelas e os gráficos interativos?
+
+As visualizações interativas do [MCP Apps](#interface-interativa-mcp-apps) só aparecem em hosts que declaram a capacidade (por exemplo, o Claude); outros clientes recebem os mesmos dados como JSON puro. Confirme também que você não definiu `EBAY_MCP_UI=off` e que as visualizações foram compiladas (`npm run build` executa `build:ui`).
+
 ### Quantas APIs e ferramentas do eBay ele cobre?
 
 322 ferramentas em 270 endpoints únicos — 100% das Sell APIs do eBay.

package/README.ru.md

@@ -58,6 +58,7 @@
 - [Демонстрация](#демонстрация)
 - [Конфигурация](#конфигурация)
 - [Доступные инструменты](#доступные-инструменты)
+- [Интерактивный интерфейс (MCP Apps) — бета](#интерактивный-интерфейс-mcp-apps)
 - [Примеры использования](#примеры-использования)
 - [Логирование и устранение неполадок](#логирование-и-устранение-неполадок)
 - [Часто задаваемые вопросы](#часто-задаваемые-вопросы)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # маркетплейс по умолчанию (переопределяется на уровне инструмента)
 EBAY_CONTENT_LANGUAGE=en-US         # язык содержимого запросов по умолчанию
 EBAY_USER_REFRESH_TOKEN=your_token  # для более высоких лимитов
+EBAY_MCP_UI=on                      # интерактивные представления MCP Apps (бета); установите "off", чтобы принудительно выводить обычный JSON
 ```
 
 ### Аутентификация и лимиты запросов
@@ -252,6 +254,27 @@ EBAY_USER_REFRESH_TOKEN=your_token  # для более высоких лими
 
 Полный машиночитаемый индекс см. в [llms.txt](llms.txt).
 
+## Интерактивный интерфейс (MCP Apps)
+
+> **Бета** — это новая возможность, которая развивается вместе со спецификацией MCP Apps, а поддержка на стороне хостов всё ещё внедряется. Она подключается по выбору и откатывается к обычному JSON, поэтому никогда не ломает существующих клиентов. Переключается переменной `EBAY_MCP_UI`.
+
+На хостах с поддержкой [MCP Apps](https://modelcontextprotocol.io) распространённые инструменты чтения отображают свои результаты как интерактивные представления вместо «сырого» JSON — сортируемую **таблицу**, **карточку** с деталями или **график** — используя собственную тему хоста. Везде в остальных случаях те же самые инструменты возвращают обычный JSON, так что ничего не ломается. Он построен на официальном [MCP Apps SDK (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps) — расширении, которое позволяет MCP-серверам предоставлять интерактивный интерфейс диалоговым клиентам.
+
+- **Подключение по выбору и контроль на стороне хоста.** Представления объявляются только тем клиентам, которые сообщают о поддержке возможности MCP Apps (например, Claude). Хосты без неё (например, Cursor) без лишних слов получают JSON.
+- **Аварийный выключатель.** Установите `EBAY_MCP_UI=off`, чтобы принудительно выводить обычный JSON везде, даже на поддерживающих хостах.
+- **Экономия токенов.** HTML каждого представления хост загружает один раз вне основного канала (никогда не в контекст модели); модель всегда видит только однострочное резюме и те же структурированные данные, которые она получила бы в любом случае.
+- **Только для чтения.** Представления всегда запускают только инструменты чтения (углубиться в строку, перелистнуть страницу, обновить) — они никогда не изменяют ваши данные на eBay.
+
+Сегодня подключены 13 инструментов основных рабочих процессов, разделённых на три архетипа:
+
+| Архетип | Инструменты |
+| --- | --- |
+| **Таблица** | `ebay_get_orders`, `ebay_get_shipping_fulfillments`, `ebay_get_offers`, `ebay_get_inventory_items`, `ebay_get_inventory_locations`, `ebay_get_payment_dispute_summaries` |
+| **Карточка** | `ebay_get_order`, `ebay_get_offer`, `ebay_get_inventory_item`, `ebay_get_payment_dispute`, `ebay_get_seller_standards_profile` |
+| **График** | `ebay_get_traffic_report`, `ebay_get_customer_service_metric` |
+
+Представления собираются в самодостаточный HTML командой `npm run build` (или `npm run build:ui`); они входят в опубликованный пакет и загружаются без собственного доступа к сети.
+
 ## Примеры использования
 
 Типичные задачи, сформулированные так, как вы попросили бы ИИ-ассистента:
@@ -285,6 +308,10 @@ EBAY_USER_REFRESH_TOKEN=your_token  # для более высоких лими
 
 Да. Он работает с Claude Desktop и Claude Code «из коробки», с Cursor и другими IDE с поддержкой MCP, а также с любым ассистентом, поддерживающим Model Context Protocol. Промпт настройки в один клик выше также работает с ChatGPT и другими ассистентами.
 
+### Почему я не вижу интерактивные таблицы и графики?
+
+Интерактивные представления [MCP Apps](#интерактивный-интерфейс-mcp-apps) появляются только на хостах, которые сообщают о поддержке этой возможности (например, Claude); другие клиенты получают те же данные в виде обычного JSON. Также убедитесь, что вы не установили `EBAY_MCP_UI=off` и что представления собраны (`npm run build` запускает `build:ui`).
+
 ### Сколько API и инструментов eBay он охватывает?
 
 322 инструмента на 270 уникальных эндпоинтах — 100% Sell API eBay.

package/README.zh-CN.md

@@ -58,6 +58,7 @@
 - [演示](#演示)
 - [配置](#配置)
 - [可用工具](#可用工具)
+- [交互式界面（MCP Apps · 测试版）](#交互式界面mcp-apps)
 - [使用示例](#使用示例)
 - [日志与故障排查](#日志与故障排查)
 - [常见问题](#常见问题)
@@ -203,6 +204,7 @@ EBAY_REDIRECT_URI=your_runame
 EBAY_MARKETPLACE_ID=EBAY_US         # 默认站点（可按工具覆盖）
 EBAY_CONTENT_LANGUAGE=en-US         # 请求的默认内容语言
 EBAY_USER_REFRESH_TOKEN=your_token  # 用于更高的速率限制
+EBAY_MCP_UI=on                      # 交互式 MCP Apps 视图（测试版）；设为 "off" 可强制返回纯 JSON
 ```
 
 ### 认证与速率限制
@@ -252,6 +254,27 @@ EBAY_USER_REFRESH_TOKEN=your_token  # 用于更高的速率限制
 
 完整的机器可读索引见 [llms.txt](llms.txt)。
 
+## 交互式界面（MCP Apps）
+
+> **测试版** —— 此功能是全新的，会随 MCP Apps 规范一同演进，宿主端的支持仍在逐步推出。它需要主动启用，并会回退到纯 JSON，因此绝不会破坏现有客户端。可通过 `EBAY_MCP_UI` 开启或关闭。
+
+在支持 [MCP Apps](https://modelcontextprotocol.io) 的宿主上，常用的读取类工具会将结果渲染为交互式视图，而非原始 JSON —— 可排序的**表格**、详情**卡片**或**图表** —— 并采用宿主自身的主题。在其他任何环境中，同样的这些工具都会返回纯 JSON，因此不会出现任何问题。它基于官方的 [MCP Apps SDK (`@modelcontextprotocol/ext-apps`)](https://github.com/modelcontextprotocol/ext-apps) 构建 —— 这个扩展让 MCP 服务器能够向对话式客户端交付交互式界面。
+
+- **可选启用且受宿主限制。** 视图仅向声明了 MCP Apps 能力的客户端（例如 Claude）公布。不具备该能力的宿主（例如 Cursor）会静默地获得 JSON。
+- **紧急开关。** 设置 `EBAY_MCP_UI=off` 即可在所有环境强制返回纯 JSON，即使在具备能力的宿主上也是如此。
+- **节省 token。** 每个视图的 HTML 由宿主在带外只获取一次（绝不进入模型的上下文）；模型始终只看到一行摘要，外加它本就会收到的结构化数据。
+- **只读。** 视图只会触发读取类工具（深入查看某一行、翻页、刷新）—— 它们绝不会改动你的 eBay 数据。
+
+目前有 13 个核心工作流工具选择了启用，分为三种类型：
+
+| 类型 | 工具 |
+| --- | --- |
+| **表格** | `ebay_get_orders`、`ebay_get_shipping_fulfillments`、`ebay_get_offers`、`ebay_get_inventory_items`、`ebay_get_inventory_locations`、`ebay_get_payment_dispute_summaries` |
+| **卡片** | `ebay_get_order`、`ebay_get_offer`、`ebay_get_inventory_item`、`ebay_get_payment_dispute`、`ebay_get_seller_standards_profile` |
+| **图表** | `ebay_get_traffic_report`、`ebay_get_customer_service_metric` |
+
+这些视图通过 `npm run build`（或 `npm run build:ui`）构建为自包含的 HTML；它们随发布的包一同分发，加载时无需自身的任何网络访问。
+
 ## 使用示例
 
 常见任务，按你向 AI 助手提问的方式表述：
@@ -285,6 +308,10 @@ EBAY_USER_REFRESH_TOKEN=your_token  # 用于更高的速率限制
 
 可以。它开箱即用地支持 Claude Desktop 和 Claude Code，支持 Cursor 和其他支持 MCP 的 IDE，以及任何支持 Model Context Protocol 的助手。上面的一键配置提示词也适用于 ChatGPT 和其他助手。
 
+### 为什么我看不到交互式表格和图表？
+
+交互式 [MCP Apps](#交互式界面mcp-apps) 视图仅出现在声明了该能力的宿主上（例如 Claude）；其他客户端会以纯 JSON 的形式获得相同的数据。另外请确认你没有设置 `EBAY_MCP_UI=off`，并且这些视图已经构建（`npm run build` 会运行 `build:ui`）。
+
 ### 它覆盖多少 eBay API 和工具？
 
 322 个工具，覆盖 270 个唯一端点 —— eBay Sell API 的 100%。

package/build/mcp/runtime.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { EbaySellerApi } from '../api/index.js';
 import { getEbayConfig, mcpConfig } from '../config/environment.js';
+import { buildUiToolResult, createUiBridge } from '../mcp/ui-bridge.js';
 import { getToolEntries } from '../tools/registry.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { serverLogger, toolLogger } from '../utils/logger.js';
@@ -26,9 +27,11 @@ function formatToolFailure(error) {
         isError: true,
     };
 }
-function registerTool(server, api, entry, logToolExecution) {
+function registerTool(server, api, entry, logToolExecution, ui) {
     const { definition, handler } = entry;
-    server.registerTool(definition.name, {
+    // Registered plainly (no UI `_meta`) so every host gets a working text tool by
+    // default; the capability gate later flips `_meta.ui` on for UI-capable clients.
+    const registered = server.registerTool(definition.name, {
         description: definition.description,
         inputSchema: definition.inputSchema,
     }, async (args) => {
@@ -40,7 +43,9 @@ function registerTool(server, api, entry, logToolExecution) {
             if (logToolExecution) {
                 toolLogger.debug(`Tool ${definition.name} completed successfully`);
             }
-            return formatToolSuccess(result);
+            return ui.shouldRender(entry)
+                ? buildUiToolResult(entry.ui, result)
+                : formatToolSuccess(result);
         }
         catch (error) {
             const errorMessage = getErrorMessage(error);
@@ -50,6 +55,7 @@ function registerTool(server, api, entry, logToolExecution) {
             return formatToolFailure(error);
         }
     });
+    ui.register(entry, registered);
 }
 /**
  * Create an MCP server runtime and register all eBay tool handlers.
@@ -58,10 +64,14 @@ export function createEbayMcpRuntime(options = {}) {
     const api = options.api ?? new EbaySellerApi(getEbayConfig());
     const server = new McpServer(options.serverConfig ?? mcpConfig);
     const entries = getToolEntries();
+    const ui = createUiBridge(server, import.meta.url);
     serverLogger.info(`Registering ${entries.length} tools`);
     for (const entry of entries) {
-        registerTool(server, api, entry, options.logToolExecution ?? false);
+        registerTool(server, api, entry, options.logToolExecution ?? false, ui);
     }
+    // Install after registration so every UI-eligible tool is captured before the
+    // gate can flip their metadata on a UI-capable client's `initialize`.
+    ui.installCapabilityGate();
     return {
         api,
         server,