ebay-mcp 1.14.3 → 1.16.0

package/README.ko.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>eBay MCP 서버 — Claude, Cursor 및 모든 AI 어시스턴트에 eBay Sell API에 대한 완전한 접근 권한을. 재고, 주문, 마케팅, 분석을 위한 298개 도구를 자신의 키로 로컬에서 실행합니다.</strong>
+  <strong>eBay MCP 서버 — Claude, Cursor 및 모든 AI 어시스턴트에 eBay Sell API에 대한 완전한 접근 권한을 제공합니다. 재고, 주문, 마케팅, 분석을 위한 305개 도구를 자신의 키로 로컬에서 실행합니다.</strong>
 </p>
 
 <p align="center"><sub>비공식 오픈소스 프로젝트 — eBay Inc.와 제휴, 승인 또는 보증 관계가 없습니다.</sub></p>
@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tools-298-8957e5?logo=ebay&logoColor=white" alt="298개 eBay API 도구" />
+  <img src="https://img.shields.io/badge/tools-305-8957e5?logo=ebay&logoColor=white" alt="305개 eBay API 도구" />
   <img src="https://img.shields.io/badge/Sell%20API%20coverage-100%25-success" alt="eBay Sell API 100% 커버리지" />
   <img src="https://img.shields.io/badge/Model%20Context%20Protocol-compatible-000000" alt="Model Context Protocol 호환" />
   <img src="https://img.shields.io/badge/tests-1%2C000%2B%20passing-3fb950?logo=vitest&logoColor=white" alt="1,000개 이상의 테스트 통과" />
@@ -47,7 +47,7 @@
 
 > **참고:** 최신 제품 설명(도구 패밀리, API 폐기, 버전 노트)의 기준 문서는 영어 [README.md](README.md)입니다. 이 번역은 뒤처질 수 있습니다.
 
-**eBay MCP**는 AI 어시스턴트 —Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code, Amazon Q— 를 **eBay의 Sell API**에 직접 연결하는 로컬 [Model Context Protocol](https://modelcontextprotocol.io) 서버입니다. **eBay Sell API 전체(고유 엔드포인트 270개)의 100%**를 포괄하는 **298개 도구**를 제공하여 재고 관리, 주문 처리, 프로모션 광고 마케팅, 분석, 개발자 도구를 다룹니다. 모든 것은 STDIO 또는 로컬 HTTP를 통해 사용자의 컴퓨터에서 실행되며 — **클라우드 중계가 없고** — eBay 자격 증명은 절대 사용자의 컴퓨터를 벗어나지 않습니다.
+**eBay MCP**는 AI 어시스턴트 —Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code, Amazon Q— 를 **eBay의 Sell API**에 직접 연결하는 로컬 [Model Context Protocol](https://modelcontextprotocol.io) 서버입니다. **eBay Sell API 전체(고유 엔드포인트 274개)의 100%**를 포괄하는 **305개 도구**를 제공하여 재고 관리, 주문 처리, 프로모션 광고 마케팅, 분석, 개발자 도구를 다룹니다. 모든 것은 STDIO 또는 로컬 HTTP를 통해 사용자의 컴퓨터에서 실행되며 — **클라우드 중계가 없고** — eBay 자격 증명은 절대 사용자의 컴퓨터를 벗어나지 않습니다.
 
 > **면책 조항:** 비공식 서드파티 프로젝트로서 **eBay Inc.와 제휴하거나 보증받지 않습니다.** "있는 그대로" 제공되며 어떠한 보증도 없습니다. [eBay API 라이선스 계약](https://developer.ebay.com/join/api-license-agreement) 및 [데이터 처리 요건](https://developer.ebay.com/api-docs/static/data-handling-update.html) 준수, 자격 증명의 안전한 보관, 속도 제한 준수는 사용자의 책임입니다. 프로덕션 전에 샌드박스에서 테스트하세요. [LICENSE](LICENSE), [SECURITY.md](SECURITY.md), [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md)를 참조하세요.
 
@@ -71,11 +71,11 @@
 
 ## 기능
 
-- **298개 eBay API 도구** — 재고, 주문, 마케팅, 분석, 메타데이터, 분류체계, 개발자 도구 전반에서 eBay Sell API를 100% 커버.
+- **305개 eBay API 도구** — 재고, 주문, 마케팅, 분석, 메타데이터, 분류체계, 개발자 도구 전반에서 eBay Sell API를 100% 커버.
 - **9개 AI 클라이언트 자동 구성** — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, Amazon Q Developer.
 - **OAuth 2.0 내장** — 사용자 토큰의 완전한 관리와 자동 갱신, 그리고 사용자 토큰(일 1만~5만 요청)에서 클라이언트 자격 증명(일 1천 요청)으로의 스마트 폴백.
 - **기본적으로 견고함** — `429` 속도 제한 시 지수 백오프로 자동 재시도하고, 일관되고 명확하게 오류를 표시합니다.
-- **타입 안전** — 엔드투엔드 TypeScript, Zod로 검증되는 도구 입력, OpenAPI에서 생성된 타입.
+- **타입 안전** — 엔드투엔드 TypeScript, Effect로 검증되는 도구 입력, OpenAPI에서 생성된 타입.
 - **로컬 및 프라이빗** — STDIO 또는 로컬 HTTP로 실행되며, 자격 증명과 데이터가 컴퓨터를 벗어나지 않습니다.
 - **샌드박스와 프로덕션** — 변수 하나로 환경을 전환합니다.
 - **한 번의 명령으로 설정** — `npm run setup`이 자격 증명, OAuth, MCP 클라이언트를 구성하고 OAuth 플로우를 위해 브라우저를 자동으로 엽니다.
@@ -90,10 +90,10 @@
 | 인터페이스 | AI 어시스턴트를 통한 자연어 | 직접 작성한 HTTP 요청과 JSON 파싱 |
 | OAuth 및 토큰 갱신 | 내장, 자동 갱신 | 직접 구현하고 유지보수 |
 | 속도 제한 처리 | 지수 백오프로 자동 재시도 | `429`와 백오프 수동 처리 |
-| 입력 검증 | 모든 도구에 Zod 스키마 + TypeScript 타입 | 없음 — 페이로드를 직접 검증 |
+| 입력 검증 | 모든 도구에 Effect 기반 스키마 + TypeScript 타입 | 없음 — 페이로드를 직접 검증 |
 | 설정 | 단일 마법사(`npm run setup`) | 호출마다 인증, 헤더, 마켓플레이스 |
 | AI 클라이언트 지원 | 9개 클라이언트 자동 구성 | 해당 없음 |
-| API 커버리지 | Sell API 100%에 걸친 298개 도구, 바로 호출 가능 | 문서를 보고 각 요청을 직접 구성 |
+| API 커버리지 | Sell API 100%에 걸친 305개 도구, 바로 호출 가능 | 문서를 보고 각 요청을 직접 구성 |
 | 호스팅 | 로컬 실행, 클라우드 중계 없음 | 자체 인프라 |
 
 ## AI 원클릭 설정
@@ -236,13 +236,13 @@ EBAY_MCP_UI=on                      # 대화형 MCP Apps 보기(베타); 일반
 
 ## 사용 가능한 도구
 
-**298개 도구**, Sell API 100% 커버리지, 카테고리별로 구성. 각 링크는 [`src/tools/categories/`](src/tools/categories/)의 도구 정의와 핸들러를 가리킵니다:
+**305개 도구**, Sell API 100% 커버리지, 카테고리별로 구성. 각 링크는 [`src/tools/categories/`](src/tools/categories/)의 도구 정의와 핸들러를 가리킵니다:
 
 | 카테고리 | 할 수 있는 일 |
 | --- | --- |
 | [Connector](src/tools/categories/connector.ts) | eBay MCP 카탈로그용 ChatGPT 커넥터 search/fetch 도구 |
 | [Account](src/tools/categories/account.ts) | 비즈니스·배송·결제·반품 정책, 프로그램, 구독, 판매세 |
-| [Inventory](src/tools/categories/inventory.ts) | 재고 항목, 오퍼, 위치, 항목 그룹, 일괄 작업, SKU/위치 매핑 |
+| [Inventory](src/tools/categories/inventory.ts) | 재고 항목, 오퍼, 위치, 항목 그룹, 일괄 작업, SKU/위치 매핑, 로컬 사진/동영상 업로드([`media.ts`](src/tools/categories/media.ts), Media API) |
 | [Fulfillment](src/tools/categories/fulfillment.ts) | 주문, 배송, 환불, 분쟁, 결제 분쟁 증거 |
 | [Marketing](src/tools/categories/marketing.ts) | 프로모션 광고 캠페인, 광고, 프로모션, 입찰, 일괄 작업 |
 | [Analytics](src/tools/categories/analytics.ts) | 트래픽 보고서, 판매자 기준, 고객 서비스 지표 |
@@ -251,7 +251,7 @@ EBAY_MCP_UI=on                      # 대화형 MCP Apps 보기(베타); 일반
 | [Taxonomy](src/tools/categories/taxonomy.ts) | 카테고리 트리, 항목 속성, 항목 상태 |
 | [Browse](src/tools/categories/browse.ts) | 가격 비교용 판매/완료 리스팅 검색(Finding API) |
 | [Other](src/tools/categories/other.ts) | Identity, VeRO, 번역 및 국제 배송 지원 API(Compliance 도구는 eBay 2026-03-30 폐기를 보고) |
-| [Trading(레거시 XML)](src/tools/categories/trading.ts) | 고정 가격 리스팅 생성, 수정, 재등록, 종료 |
+| [Trading(레거시 XML)](src/tools/categories/trading.ts) | 고정 가격 리스팅과 경매의 생성, 수정, 재등록, 종료 |
 | [Developer](src/tools/categories/developer.ts) | 속도 제한, 서명 키, 클라이언트 등록 |
 | [Token Management](src/tools/categories/tokenManagement.ts) | OAuth URL 생성 및 토큰 관리 |
 
@@ -299,7 +299,7 @@ AI 어시스턴트에게 묻듯이 표현한 일반적인 작업:
 
 ### eBay MCP 서버란 무엇인가요?
 
-AI 어시스턴트에 **eBay Sell API의 100%**(270개 엔드포인트)를 포괄하는 **298개 도구**를 제공하는 로컬 [Model Context Protocol](https://modelcontextprotocol.io) 서버입니다 — 재고, 주문 처리, 마케팅, 분석, 개발자 도구.
+AI 어시스턴트에 **eBay Sell API의 100%**(274개 엔드포인트)를 포괄하는 **305개 도구**를 제공하는 로컬 [Model Context Protocol](https://modelcontextprotocol.io) 서버입니다 — 재고, 주문 처리, 마케팅, 분석, 개발자 도구.
 
 ### 이것은 eBay 공식 제품인가요?
 
@@ -319,7 +319,7 @@ AI 어시스턴트에 **eBay Sell API의 100%**(270개 엔드포인트)를 포
 
 ### eBay API와 도구를 얼마나 커버하나요?
 
-270개 고유 엔드포인트에 걸친 298개 도구 — eBay Sell API의 100%입니다.
+274개 고유 엔드포인트에 걸친 305개 도구 — eBay Sell API의 100%입니다.
 
 ### 무료이고 오픈소스인가요?
 
@@ -347,11 +347,19 @@ Node.js ≥ 20, 무료 [eBay 개발자 계정](https://developer.ebay.com/)(Clie
 
 ### eBay API를 직접 호출하는 것과 무엇이 다른가요?
 
-AI 어시스턴트를 통해 자연어로 상호작용합니다. OAuth 토큰 관리, 백오프가 적용된 자동 재시도, Zod를 통한 타입 안전 검증이 내장되어 있습니다. 위의 [비교 표](#ebay-mcp-vs-순수-ebay-api)를 참조하세요.
+AI 어시스턴트를 통해 자연어로 상호작용합니다. OAuth 토큰 관리, 백오프가 적용된 자동 재시도, Effect를 통한 타입 안전 검증이 내장되어 있습니다. 위의 [비교 표](#ebay-mcp-vs-순수-ebay-api)를 참조하세요.
+
+### 사진과 동영상을 업로드할 수 있나요?
+
+네. `ebay_upload_images`, `ebay_upload_video`, `ebay_attach_media_to_inventory_item`은 로컬 파일(절대 경로 또는 `media://` 참조)을 읽어 eBay의 Media API를 통해 업로드하고, `product.imageUrls` / `product.videoIds`에 쓸 EPS 이미지 URL과 동영상 ID를 반환합니다. 파일 시스템 접근은 옵트인입니다. `EBAY_MCP_MEDIA_DIRS` 또는 `EBAY_MCP_MEDIA_ROOT`로 디렉터리를 지정하기 전까지는 아무것도 읽을 수 없습니다. 자세한 내용은 [Photos and videos from local files](README.md#photos-and-videos-from-local-files)(영어)를 참조하세요.
+
+### 경매 리스팅을 지원하나요?
+
+네. REST Inventory 오퍼 도구로 `format: "AUCTION"`, `auctionStartPrice`, 선택적 `auctionReservePrice`, 일 단위 `listingDuration`을 지정해 오퍼를 만든 뒤 게시하면 됩니다. 자세한 내용은 [Auction offers](README.md#auction-offers)(영어)를 참조하세요. 레거시 Trading API 도구도 같은 스위치를 사용합니다. `format: "AUCTION"`을 지정한 `ebay_create_listing`은 `ListingType` Chinese, 시작가 `StartPrice`, 일 단위 `ListingDuration`을 담은 `AddItem`을 보냅니다.
 
 ### eBay의 레거시 Trading API(XML)를 지원하나요?
 
-네. 고정 가격 리스팅의 생성, 수정, 재등록, 종료 작업이 Trading API 도구를 통해 지원됩니다.
+네. 리스팅의 생성, 수정, 재등록, 종료 작업이 Trading API 도구를 통해 지원됩니다. 고정 가격 리스팅(`AddFixedPriceItem` 계열, 기본값)과 경매(`format: "AUCTION"` → `AddItem`, `ReviseItem`, `EndItem`, `RelistItem`) 모두 가능합니다.
 
 ### 더 높은 속도 제한은 어떻게 얻나요?
 
@@ -359,7 +367,7 @@ AI 어시스턴트를 통해 자연어로 상호작용합니다. OAuth 토큰
 
 ### 무엇으로 만들어졌나요?
 
-TypeScript와 Node.js(ESM), 공식 MCP SDK, 검증용 Zod, OpenAPI에서 생성된 타입을 사용합니다.
+TypeScript와 Node.js(ESM), 공식 MCP SDK, Zod 호환 MCP 어댑터를 갖춘 Effect 기반 검증, OpenAPI에서 생성된 타입을 사용합니다.
 
 ### 최신 버전으로 어떻게 업데이트하나요?
 

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>The eBay MCP server — give Claude, Cursor, and any AI assistant full access to eBay's Sell APIs. 298 tools for inventory, orders, marketing, and analytics, running locally with your own keys.</strong>
+  <strong>The eBay MCP server — give Claude, Cursor, and any AI assistant full access to eBay's Sell APIs. 305 tools for inventory, orders, marketing, and analytics, running locally with your own keys.</strong>
 </p>
 
 <p align="center"><sub>Unofficial, open-source project — not affiliated with, authorized, or endorsed by eBay Inc.</sub></p>
@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tools-298-8957e5?logo=ebay&logoColor=white" alt="298 eBay API tools" />
+  <img src="https://img.shields.io/badge/tools-305-8957e5?logo=ebay&logoColor=white" alt="305 eBay API tools" />
   <img src="https://img.shields.io/badge/Sell%20API%20coverage-100%25-success" alt="100% eBay Sell API coverage" />
   <img src="https://img.shields.io/badge/Model%20Context%20Protocol-compatible-000000" alt="Model Context Protocol compatible" />
   <img src="https://img.shields.io/badge/tests-1%2C000%2B%20passing-3fb950?logo=vitest&logoColor=white" alt="Over 1,000 passing tests" />
@@ -45,7 +45,7 @@
 
 ---
 
-**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 **298 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 **305 tools** spanning **100% of eBay's Sell API surface** (274 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).
 
@@ -71,7 +71,7 @@
 
 ## Features
 
-- **298 eBay API tools** — 100% coverage of the eBay Sell APIs across inventory, orders, marketing, analytics, metadata, taxonomy, and developer tooling.
+- **305 eBay API tools** — 100% coverage of the eBay Sell APIs across inventory, orders, marketing, analytics, metadata, taxonomy, and developer tooling.
 - **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.
@@ -97,9 +97,82 @@ Use this map when deciding which tool family to expose, or when asking an assist
 | `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." |
+| `trading` | Legacy XML listing create, revise, relist, and end operations for fixed-price listings and auctions | "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." |
 
+### Listing preflight: required item specifics
+
+Before calling `ebay_create_or_replace_inventory_item`, `ebay_create_offer`, or
+`ebay_get_listing_fees`, fetch the live requirements for the selected category:
+
+`ebay_get_default_category_tree_id` → `ebay_get_category_suggestions` →
+`ebay_get_item_aspects_for_category`
+
+The aspects response identifies required and recommended item specifics. Put every
+required aspect on the inventory item before creating its offer. Requirements vary by
+category and marketplace, so re-run the lookup when either changes; do not rely on
+examples or a fixed global fallback value.
+
+### Auction offers
+
+`ebay_create_offer`, `ebay_update_offer`, and `ebay_bulk_create_offer` accept both
+listing formats through the same Inventory model:
+
+| Field | `FIXED_PRICE` | `AUCTION` |
+| --- | --- | --- |
+| `pricingSummary.price` | Listing price | Optional Buy It Now price, at least 30% above the opening bid |
+| `pricingSummary.auctionStartPrice` | — | Opening bid |
+| `pricingSummary.auctionReservePrice` | — | Optional; must exceed the opening bid and carries an eBay fee |
+| `listingDuration` | `GTC` | Day count such as `DAYS_7` (never `GTC`) |
+| `availableQuantity` | Any | Omit or `1` — an auction sells a single unit |
+| Best Offer | Allowed | Allowed where the category supports it, but not together with a Buy It Now price |
+| `quantityLimitPerBuyer` / `eBayPlusIfEligible` | Allowed | Not allowed |
+| `listingStartDate` | Only when a scheduled start was explicitly requested (eBay may charge a fee) | Same |
+
+Check `ebay_get_listing_type_policies` for the formats and durations a category allows,
+then `ebay_get_listing_fees` before `ebay_publish_offer`. Bodies that mix the two formats
+are rejected locally, before any request reaches eBay.
+
+#### Auctions on the Trading (XML) path
+
+The legacy tools take the same switch as a top-level `format` argument (`FIXED_PRICE` by
+default). `ebay_create_listing`, `ebay_revise_listing`, `ebay_end_listing`, and
+`ebay_relist_item` with `format: "AUCTION"` use the auction-capable calls (`AddItem`,
+`ReviseItem`, `EndItem`, `RelistItem`) instead of the `*FixedPriceItem` family, and
+`ebay_create_listing` adds `ListingType: "Chinese"` to the `Item` for you:
+
+| Trading `Item` field | `FIXED_PRICE` | `AUCTION` |
+| --- | --- | --- |
+| `StartPrice` | Listing price | Opening bid (required on create) |
+| `ReservePrice` | Not allowed | Optional; must exceed `StartPrice` (a reserve carries an eBay fee) |
+| `BuyItNowPrice` | Not allowed | Optional; at least 30% above `StartPrice` |
+| `ListingDuration` | `GTC` (the only fixed-price duration eBay accepts) | Day count such as `Days_7` (required on create; never `GTC`) |
+| `Quantity` | Any | Omit or `1` |
+| `BestOfferDetails.BestOfferEnabled` | Allowed | Allowed where the category supports it, but not together with `BuyItNowPrice` |
+| `ebay_end_listing` reason `SellToHighBidder` | Not allowed | Ends an auction with bids |
+
+Mixed payloads are rejected locally. When the format of an existing item is unknown, read
+its `ListingType` with `ebay_get_listing` first (`Chinese` = auction).
+
+### Photos and videos from local files
+
+An offer cannot be published without at least one picture. The media tools upload local
+files through eBay's Media API and return what the Inventory API needs:
+
+| Tool | What it does |
+| --- | --- |
+| `ebay_upload_images` | Uploads pictures to eBay Picture Services (`createImageFromFile`) and returns the EPS URLs in order for `product.imageUrls` |
+| `ebay_upload_video` | Runs the video lifecycle (`createVideo` → `uploadVideo` → `getVideo`) and returns the `videoId` for `product.videoIds` |
+| `ebay_get_video` | Re-checks a video that was still `PROCESSING` |
+| `ebay_attach_media_to_inventory_item` | Reads the item, uploads the files, and rewrites only `product.imageUrls` / `product.videoIds` — never publishes, and leaves the item untouched if any upload fails unless `allowPartial` is set |
+
+Local file access is off until you allow it: set `EBAY_MCP_MEDIA_DIRS` (path-delimited
+directories) and/or `EBAY_MCP_MEDIA_ROOT` (one directory that also resolves
+`media://<relative-path>` references). Symlinks are resolved before the containment
+check; anything outside the allowed directories is refused before any upload. Supported:
+JPG, PNG, GIF, BMP, TIFF, WEBP, AVIF, HEIC up to 12 MB; MP4/MOV up to 150 MB. Unused
+uploads expire on eBay's side; they become permanent once a listing uses them.
+
 ## eBay MCP vs. the raw eBay API
 
 Both talk to the same eBay endpoints — the difference is everything you'd otherwise build yourself.
@@ -112,7 +185,7 @@ Both talk to the same eBay endpoints — the difference is everything you'd othe
 | 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 | 298 tools across 100% of the Sell APIs, ready to call | Build each request from the docs |
+| API coverage | 305 tools across 100% of the Sell APIs, ready to call | Build each request from the docs |
 | Hosting | Runs locally, no cloud relay | Your own infrastructure |
 
 ## One-click AI setup
@@ -240,6 +313,9 @@ 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)
+# Local photo/video upload (optional — off until a directory is allowed):
+# EBAY_MCP_MEDIA_DIRS=/srv/media    # path-delimited directories the media tools may read
+# EBAY_MCP_MEDIA_ROOT=/srv/media    # root for media://<relative-path> references (also allowed)
 # 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
@@ -288,15 +364,15 @@ Auto-configured by `npm run setup`. Requires [Node.js](https://nodejs.org/en)
 ## Available tools
 
 <details open>
-<summary><strong>298 tools by category (100% Sell API coverage)</strong></summary>
+<summary><strong>305 tools by category (100% Sell API coverage)</strong></summary>
 
-**298 tools**, 100% Sell API coverage, organized by category. Each link points to the tool definitions and handlers in [`src/tools/categories/`](src/tools/categories/):
+**305 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 |
+| [Inventory](src/tools/categories/inventory.ts) | Inventory items, offers, locations, item groups, bulk operations, SKU/location mapping, and local photo/video upload ([`media.ts`](src/tools/categories/media.ts), Media API) |
 | [Fulfillment](src/tools/categories/fulfillment.ts) | Orders, shipping, refunds, disputes, payment-dispute evidence |
 | [Marketing](src/tools/categories/marketing.ts) | Promoted-listings campaigns, ads, promotions, bidding, bulk operations |
 | [Analytics](src/tools/categories/analytics.ts) | Traffic reports, seller standards, customer-service metrics |
@@ -304,11 +380,11 @@ Auto-configured by `npm run setup`. Requires [Node.js](https://nodejs.org/en)
 | [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 |
+| [Trading (legacy XML)](src/tools/categories/trading.ts) | Fixed-price and auction listing create, revise, relist, end |
 | [Developer](src/tools/categories/developer.ts) | Rate limits, signing keys, client registration |
 | [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`.
+**Example tools:** `ebay_get_inventory_items`, `ebay_get_offers_by_skus`, `ebay_get_orders`, `ebay_create_offer`, `ebay_get_campaigns`, `ebay_get_oauth_url`.
 
 For the complete machine-readable index, see [llms.txt](llms.txt).
 
@@ -347,6 +423,10 @@ Common tasks, phrased as you'd ask your AI assistant:
 
 - **Set up OAuth** — *"Help me set up OAuth for my eBay account."* → generates an authorization URL via `ebay_get_oauth_url`, then configures the refresh token. Unlocks 10k–50k req/day.
 - **Manage inventory** — *"Show me all my active listings."* → `ebay_get_inventory_items` returns SKUs, quantities, and status.
+- **Add photos to a listing** — *"Attach the three photos in ~/listings/megadrive to SKU MD-001."* → `ebay_attach_media_to_inventory_item` uploads them to eBay Picture Services and updates `product.imageUrls` (with `EBAY_MCP_MEDIA_DIRS` allowing that folder).
+- **Run an auction** — *"List this SKU as a 7-day auction starting at $9.99 with a $25 reserve."* → `ebay_create_offer` with `format: "AUCTION"`, `auctionStartPrice`, `auctionReservePrice`, and `listingDuration: "DAYS_7"`, then `ebay_publish_offer`. On the legacy path, `ebay_create_listing` with `format: "AUCTION"` and a Trading `Item` (`StartPrice`, `ReservePrice`, `ListingDuration: "Days_7"`).
+- **Look up offers** — `ebay_get_offers` returns offers for one required SKU. To enumerate offers across the inventory, call `ebay_get_inventory_items` first, then call `ebay_get_offers` once per SKU.
+- **Manage fulfillment policies** — *"Create a shipping policy, then update its handling time."* → `ebay_create_fulfillment_policy` creates the reusable policy ID and `ebay_update_fulfillment_policy` replaces its settings.
 - **Process orders** — *"Get all unfulfilled orders from the last 7 days."* → `ebay_get_orders` with date and fulfillment-status filters.
 - **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.
@@ -370,7 +450,7 @@ Common tasks, phrased as you'd ask your AI assistant:
 <details>
 <summary><strong>What is the eBay MCP server?</strong></summary>
 
-A local [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **298 tools** covering **100% of eBay's Sell APIs** (270 endpoints) to AI assistants — inventory, order fulfillment, marketing, analytics, and developer tools.
+A local [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **305 tools** covering **100% of eBay's Sell APIs** (274 endpoints) to AI assistants — inventory, order fulfillment, marketing, analytics, and developer tools.
 
 </details>
 
@@ -405,7 +485,7 @@ Interactive [MCP Apps](#interactive-ui-mcp-apps) views only appear on hosts that
 <details>
 <summary><strong>How many eBay APIs and tools does it cover?</strong></summary>
 
-298 tools across 270 unique endpoints — 100% of eBay's Sell APIs.
+305 tools across 274 unique endpoints — 100% of eBay's Sell APIs.
 
 </details>
 
@@ -458,10 +538,24 @@ You interact in natural language through your AI assistant. OAuth token manageme
 
 </details>
 
+<details>
+<summary><strong>Can it upload my photos and videos?</strong></summary>
+
+Yes. `ebay_upload_images`, `ebay_upload_video`, and `ebay_attach_media_to_inventory_item` read local files (absolute paths or `media://` references) and upload them through eBay's Media API, returning EPS image URLs and video IDs for `product.imageUrls` / `product.videoIds`. Filesystem access is opt-in: nothing is readable until `EBAY_MCP_MEDIA_DIRS` or `EBAY_MCP_MEDIA_ROOT` names the directories. See [Photos and videos from local files](#photos-and-videos-from-local-files).
+
+</details>
+
+<details>
+<summary><strong>Does it support auction listings?</strong></summary>
+
+Yes, through the REST Inventory offer tools: create the offer with `format: "AUCTION"`, an `auctionStartPrice`, an optional `auctionReservePrice`, and a day-count `listingDuration`, then publish it. See [Auction offers](#auction-offers). The legacy Trading API tools take the same switch: `ebay_create_listing` with `format: "AUCTION"` sends `AddItem` with `ListingType` Chinese, an opening-bid `StartPrice`, and a day-count `ListingDuration`.
+
+</details>
+
 <details>
 <summary><strong>Does it support eBay's legacy Trading API (XML)?</strong></summary>
 
-Yes. Fixed-price listing create, revise, relist, and end operations are supported through the Trading API tools.
+Yes. Listing create, revise, relist, and end operations are supported through the Trading API tools, for fixed-price listings (`AddFixedPriceItem` family, the default) and for auctions (`format: "AUCTION"` → `AddItem`, `ReviseItem`, `EndItem`, `RelistItem`).
 
 </details>
 

package/README.pt-BR.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>O servidor MCP do eBay — dê ao Claude, ao Cursor e a qualquer assistente de IA acesso completo às Sell APIs do eBay. 298 ferramentas para estoque, pedidos, marketing e analytics, rodando localmente com suas próprias chaves.</strong>
+  <strong>O servidor MCP do eBay — dê ao Claude, ao Cursor e a qualquer assistente de IA acesso completo às Sell APIs do eBay. 305 ferramentas para estoque, pedidos, marketing e analytics, rodando localmente com suas próprias chaves.</strong>
 </p>
 
 <p align="center"><sub>Projeto de código aberto não oficial — sem afiliação, autorização ou endosso da eBay Inc.</sub></p>
@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tools-298-8957e5?logo=ebay&logoColor=white" alt="298 ferramentas da API do eBay" />
+  <img src="https://img.shields.io/badge/tools-305-8957e5?logo=ebay&logoColor=white" alt="305 ferramentas da API do eBay" />
   <img src="https://img.shields.io/badge/Sell%20API%20coverage-100%25-success" alt="100% de cobertura da Sell API do eBay" />
   <img src="https://img.shields.io/badge/Model%20Context%20Protocol-compatible-000000" alt="compatível com o Model Context Protocol" />
   <img src="https://img.shields.io/badge/tests-1%2C000%2B%20passing-3fb950?logo=vitest&logoColor=white" alt="mais de 1000 testes passando" />
@@ -47,7 +47,7 @@
 
 > **Nota:** o [README.md](README.md) em inglês é a fonte da verdade para claims de produto atuais (famílias de ferramentas, APIs descontinuadas, notas de versão). Esta tradução pode estar atrasada.
 
-**eBay MCP** é um servidor local do [Model Context Protocol](https://modelcontextprotocol.io) que conecta assistentes de IA —Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code e Amazon Q— diretamente às **Sell APIs do eBay**. Ele expõe **298 ferramentas** abrangendo **100% da superfície da Sell API do eBay** (270 endpoints únicos) para gestão de estoque, processamento de pedidos, marketing de anúncios patrocinados, analytics e ferramentas para desenvolvedores. Tudo roda na sua máquina via STDIO ou HTTP local — **sem relay na nuvem**, e suas credenciais do eBay nunca saem do seu computador.
+**eBay MCP** é um servidor local do [Model Context Protocol](https://modelcontextprotocol.io) que conecta assistentes de IA —Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed, Continue.dev, Roo Code e Amazon Q— diretamente às **Sell APIs do eBay**. Ele expõe **305 ferramentas** abrangendo **100% da superfície da Sell API do eBay** (274 endpoints únicos) para gestão de estoque, processamento de pedidos, marketing de anúncios patrocinados, analytics e ferramentas para desenvolvedores. Tudo roda na sua máquina via STDIO ou HTTP local — **sem relay na nuvem**, e suas credenciais do eBay nunca saem do seu computador.
 
 > **Aviso legal:** Projeto não oficial de terceiros — **sem afiliação ou endosso da eBay Inc.** Fornecido "como está", sem garantia. Você é responsável por cumprir o [Contrato de licença da API do eBay](https://developer.ebay.com/join/api-license-agreement) e os [requisitos de tratamento de dados](https://developer.ebay.com/api-docs/static/data-handling-update.html), por manter suas credenciais seguras e por respeitar os limites de taxa. Teste no sandbox antes de ir para produção. Consulte [LICENSE](LICENSE), [SECURITY.md](SECURITY.md) e [EBAY_COMPLIANCE.md](EBAY_COMPLIANCE.md).
 
@@ -71,11 +71,11 @@
 
 ## Recursos
 
-- **298 ferramentas da API do eBay** — 100% de cobertura das Sell APIs do eBay em estoque, pedidos, marketing, analytics, metadados, taxonomia e ferramentas para desenvolvedores.
+- **305 ferramentas da API do eBay** — 100% de cobertura das Sell APIs do eBay em estoque, pedidos, marketing, analytics, metadados, taxonomia e ferramentas para desenvolvedores.
 - **9 clientes de IA, autoconfigurados** — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI e Amazon Q Developer.
 - **OAuth 2.0 integrado** — gestão completa de tokens de usuário com renovação automática e fallback inteligente de tokens de usuário (10k–50k req/dia) para credenciais de cliente (1k req/dia).
 - **Resiliente por padrão** — nova tentativa automática com recuo exponencial em limites de taxa `429` e exibição de erros clara e consistente.
-- **Com segurança de tipos** — TypeScript de ponta a ponta, entradas de ferramentas validadas com Zod e tipos gerados a partir do OpenAPI.
+- **Com segurança de tipos** — TypeScript de ponta a ponta, entradas de ferramentas validadas com Effect e tipos gerados a partir do OpenAPI.
 - **Local e privado** — roda via STDIO ou HTTP local; suas credenciais e dados nunca saem da sua máquina.
 - **Sandbox e produção** — troque de ambiente com uma única variável.
 - **Configuração em um comando** — `npm run setup` configura credenciais, OAuth e seu cliente MCP, abrindo o navegador automaticamente para o fluxo OAuth.
@@ -90,10 +90,10 @@ Ambos falam com os mesmos endpoints do eBay — a diferença é tudo o que você
 | Interface | Linguagem natural pelo seu assistente de IA | Requisições HTTP escritas à mão e parsing de JSON |
 | OAuth e renovação de tokens | Integrados, com renovação automática | Você implementa e mantém |
 | Tratamento de limites de taxa | Nova tentativa automática com recuo exponencial | Tratamento manual de `429` e recuo |
-| Validação de entradas | Esquemas Zod + tipos TypeScript em cada ferramenta | Nenhuma — você valida seus próprios payloads |
+| Validação de entradas | Esquemas baseados em Effect + tipos TypeScript em cada ferramenta | Nenhuma — você valida seus próprios payloads |
 | Configuração | Um assistente (`npm run setup`) | Auth, cabeçalhos e marketplace por chamada |
 | Suporte a clientes de IA | 9 clientes autoconfigurados | Não se aplica |
-| Cobertura da API | 298 ferramentas em 100% das Sell APIs, prontas para usar | Você constrói cada requisição a partir da documentação |
+| Cobertura da API | 305 ferramentas em 100% das Sell APIs, prontas para usar | Você constrói cada requisição a partir da documentação |
 | Hospedagem | Roda localmente, sem relay na nuvem | Sua própria infraestrutura |
 
 ## Configuração com IA em um clique
@@ -236,13 +236,13 @@ Autoconfigurados pelo `npm run setup`. Requer Node.js ≥ 20 e o protocolo MCP 1
 
 ## Ferramentas disponíveis
 
-**298 ferramentas**, 100% de cobertura da Sell API, organizadas por categoria. Cada link aponta para as definições de ferramentas e seus handlers em [`src/tools/categories/`](src/tools/categories/):
+**305 ferramentas**, 100% de cobertura da Sell API, organizadas por categoria. Cada link aponta para as definições de ferramentas e seus handlers em [`src/tools/categories/`](src/tools/categories/):
 
 | Categoria | O que você pode fazer |
 | --- | --- |
 | [Connector](src/tools/categories/connector.ts) | Ferramentas search/fetch do conector ChatGPT sobre o catálogo eBay MCP |
 | [Account](src/tools/categories/account.ts) | Políticas de negócio, envio, pagamento e devolução; programas; assinaturas; imposto sobre vendas |
-| [Inventory](src/tools/categories/inventory.ts) | Itens de estoque, ofertas, locais, grupos de itens, operações em massa, mapeamento SKU/local |
+| [Inventory](src/tools/categories/inventory.ts) | Itens de estoque, ofertas, locais, grupos de itens, operações em massa, mapeamento SKU/local e upload de fotos/vídeos locais ([`media.ts`](src/tools/categories/media.ts), Media API) |
 | [Fulfillment](src/tools/categories/fulfillment.ts) | Pedidos, envio, reembolsos, disputas, evidências de disputas de pagamento |
 | [Marketing](src/tools/categories/marketing.ts) | Campanhas de anúncios patrocinados, anúncios, promoções, lances, operações em massa |
 | [Analytics](src/tools/categories/analytics.ts) | Relatórios de tráfego, padrões do vendedor, métricas de atendimento ao cliente |
@@ -251,7 +251,7 @@ Autoconfigurados pelo `npm run setup`. Requer Node.js ≥ 20 e o protocolo MCP 1
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Árvores de categorias, aspectos de itens, condições de itens |
 | [Browse](src/tools/categories/browse.ts) | Busca de anúncios vendidos/concluídos (Finding API) para comparáveis de preço |
 | [Other](src/tools/categories/other.ts) | Identity, VeRO, tradução e APIs de suporte a envio internacional (ferramentas de Compliance reportam a desativação da eBay em 2026-03-30) |
-| [Trading (XML legado)](src/tools/categories/trading.ts) | Criar, revisar, republicar e encerrar anúncios de preço fixo |
+| [Trading (XML legado)](src/tools/categories/trading.ts) | Criar, revisar, republicar e encerrar anúncios de preço fixo e leilões |
 | [Developer](src/tools/categories/developer.ts) | Limites de taxa, chaves de assinatura, registro de clientes |
 | [Token Management](src/tools/categories/tokenManagement.ts) | Geração de URL de OAuth e gestão de tokens |
 
@@ -299,7 +299,7 @@ Tarefas comuns, formuladas como você pediria ao seu assistente de IA:
 
 ### O que é o servidor MCP do eBay?
 
-Um servidor local do [Model Context Protocol](https://modelcontextprotocol.io) que expõe **298 ferramentas** cobrindo **100% das Sell APIs do eBay** (270 endpoints) para assistentes de IA — estoque, processamento de pedidos, marketing, analytics e ferramentas para desenvolvedores.
+Um servidor local do [Model Context Protocol](https://modelcontextprotocol.io) que expõe **305 ferramentas** cobrindo **100% das Sell APIs do eBay** (274 endpoints) para assistentes de IA — estoque, processamento de pedidos, marketing, analytics e ferramentas para desenvolvedores.
 
 ### Este é um produto oficial do eBay?
 
@@ -319,7 +319,7 @@ As visualizações interativas do [MCP Apps](#interface-interativa-mcp-apps) só
 
 ### Quantas APIs e ferramentas do eBay ele cobre?
 
-298 ferramentas em 270 endpoints únicos — 100% das Sell APIs do eBay.
+305 ferramentas em 274 endpoints únicos — 100% das Sell APIs do eBay.
 
 ### É gratuito e de código aberto?
 
@@ -347,11 +347,19 @@ As credenciais são armazenadas localmente no seu arquivo `.env` e usadas apenas
 
 ### Qual a diferença em relação a chamar a API do eBay diretamente?
 
-Você interage em linguagem natural pelo seu assistente de IA. Gestão de tokens OAuth, novas tentativas automáticas com recuo e validação com segurança de tipos via Zod já vêm integradas. Consulte a [tabela comparativa](#ebay-mcp-vs-a-api-bruta-do-ebay) acima.
+Você interage em linguagem natural pelo seu assistente de IA. Gestão de tokens OAuth, novas tentativas automáticas com recuo e validação com segurança de tipos baseada em Effect já vêm integradas. Consulte a [tabela comparativa](#ebay-mcp-vs-a-api-bruta-do-ebay) acima.
+
+### Ele consegue enviar minhas fotos e vídeos?
+
+Sim. `ebay_upload_images`, `ebay_upload_video` e `ebay_attach_media_to_inventory_item` leem arquivos locais (caminhos absolutos ou referências `media://`) e os enviam pela Media API do eBay, devolvendo URLs de imagem EPS e IDs de vídeo para `product.imageUrls` / `product.videoIds`. O acesso ao sistema de arquivos é opcional: nada pode ser lido até que `EBAY_MCP_MEDIA_DIRS` ou `EBAY_MCP_MEDIA_ROOT` indique os diretórios. Veja [Photos and videos from local files](README.md#photos-and-videos-from-local-files) (em inglês).
+
+### Ele suporta anúncios em leilão?
+
+Sim, pelas ferramentas de ofertas da Inventory API (REST): crie a oferta com `format: "AUCTION"`, um `auctionStartPrice`, um `auctionReservePrice` opcional e uma `listingDuration` em dias, e depois publique. Veja [Auction offers](README.md#auction-offers) (em inglês). As ferramentas da Trading API usam a mesma chave: `ebay_create_listing` com `format: "AUCTION"` envia `AddItem` com `ListingType` Chinese, um lance inicial `StartPrice` e uma `ListingDuration` em dias.
 
 ### Ele suporta a antiga Trading API do eBay (XML)?
 
-Sim. As operações de criar, revisar, republicar e encerrar anúncios de preço fixo são suportadas pelas ferramentas da Trading API.
+Sim. As operações de criar, revisar, republicar e encerrar anúncios são suportadas pelas ferramentas da Trading API, tanto para anúncios de preço fixo (família `AddFixedPriceItem`, o padrão) quanto para leilões (`format: "AUCTION"` → `AddItem`, `ReviseItem`, `EndItem`, `RelistItem`).
 
 ### Como obtenho limites de taxa mais altos?
 
@@ -359,7 +367,7 @@ Conclua o fluxo OAuth com `npm run setup` para autenticar com um token de usuár
 
 ### Com o que ele é construído?
 
-TypeScript e Node.js (ESM), usando o SDK oficial do MCP, Zod para validação e tipos gerados a partir do OpenAPI.
+TypeScript e Node.js (ESM), usando o SDK oficial do MCP, validação baseada em Effect com um adaptador MCP compatível com Zod e tipos gerados a partir do OpenAPI.
 
 ### Como atualizo para a versão mais recente?