ebay-mcp-remote-edition: Instructions file for Codex

Agent Guide for eBay MCP — Remote Edition

Purpose: Orients AI agents on project structure, conventions, and work queue. Read before making changes.

---

1. Project Overview

A Model Context Protocol (MCP) server exposing 325+ tools covering eBay's Sell APIs.

Mode	Transport	Use Case
Local STDIO	stdin/stdout	Single-user local AI clients
Hosted HTTP	Streamable HTTP	Multi-user deployments (Render, Railway, Coolify)

Key capabilities: 270+ unique endpoints, OAuth 2.1 auth, Cloudflare KV / Upstash Redis storage, validation pipeline (browse, sold, Terapeak, social signals), eBay Research session with QStash-triggered Telegram alerts.

---

2. Architecture

src/
├── index.ts                    # STDIO entry point
├── server-http.ts              # HTTP entry point (Express + MCP Streamable HTTP)
├── api/
│   ├── client.ts               # REST client for eBay Sell APIs
│   ├── client-trading.ts       # XML/SOAP client for Trading API
│   └── */                      # Domain-specific modules
├── tools/
│   ├── definitions/            # MCP tool definitions (Zod schemas)
│   ├── tool-definitions.ts     # Tool registration + routing
│   └── schemas.ts              # Shared Zod schemas
├── validation/
│   ├── run-validation.ts       # Validation orchestration
│   ├── recommendation.ts       # Buy/track decision logic
│   ├── types.ts                # Request/response contracts
│   └── providers/              # Providers (ebay, ebay-sold, terapeak, social, research, chart)
├── config/environment.ts       # Environment variable resolution
├── auth/oauth.ts               # OAuth 2.1 flows, token refresh, sessions
├── scripts/                    # Research session scripts + Playwright check
└── utils/                      # Logging, security, date conversion

Conventions: TypeScript strict mode, Zod for validation, fast-xml-parser for Trading API XML, Playwright for research sessions, all records carry expiresAt + backend TTL.