ebay-mcp-remote-edition 2.0.16 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +330 -490
  2. package/build/auth/kv-store.js +68 -2
  3. package/build/auth/multi-user-store.js +39 -6
  4. package/build/config/environment.js +34 -8
  5. package/build/scripts/auto-setup.js +0 -3
  6. package/build/scripts/interactive-setup.js +11 -8
  7. package/build/scripts/run-with-local-env.js +50 -0
  8. package/build/scripts/setup.js +13 -10
  9. package/build/server-http.js +340 -313
  10. package/build/utils/oauth-helper.js +264 -162
  11. package/package.json +21 -14
package/README.md CHANGED
@@ -1,9 +1,10 @@
1
- # eBay MCP (Remote Edition)
1
+ # eBay MCP — Remote Edition
2
+
2
3
  <div align="center">
3
4
 
4
- A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server providing AI assistants with comprehensive access to eBay's Sell APIs. Includes **325+ tools** for inventory management, order fulfillment, marketing campaigns, analytics, developer tools, and more.
5
+ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server providing AI assistants with comprehensive access to eBay's Sell APIs. **325+ tools** covering inventory management, order fulfillment, marketing campaigns, analytics, developer tools, and more.
5
6
 
6
- **API Coverage:** 100% (270+ unique eBay API endpoints)
7
+ **API Coverage:** 100% of eBay Sell APIs (270+ unique endpoints)
7
8
 
8
9
  [![npm version](https://img.shields.io/npm/v/ebay-mcp-remote-edition.svg)](https://www.npmjs.com/package/ebay-mcp-remote-edition)
9
10
  [![Socket Badge](https://socket.dev/api/badge/npm/package/ebay-mcp-remote-edition)](https://socket.dev/npm/package/ebay-mcp-remote-edition)
@@ -11,138 +12,110 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server providi
11
12
 
12
13
  </div>
13
14
 
14
- ----
15
-
16
- ## Fork differences
15
+ ---
17
16
 
18
- This fork of [Yosef Hayim's eBay MCP](https://github.com/YosefHayim/ebay-mcp) preserves the original local/STDIO workflow up to v1.7.5, while expanding and focusing on adding hosted multi-user support for both ephemeral and persistant remote server instances. For all intents and purposes, any changes made to the original project from that version on is completely independent of any changes made here, and may be considered a wholly separate project.
17
+ ## Overview
19
18
 
20
- ### Added in this fork
19
+ This project extends [Yosef Hayim's eBay MCP](https://github.com/YosefHayim/ebay-mcp) with a full hosted, multi-user deployment mode while keeping the original local STDIO mode intact. The key additions are:
21
20
 
22
- - Hosted Streamable HTTP MCP deployment mode for remote server deployment
23
- - Multi-user server-side eBay OAuth for both production and sandbox
24
- - Cloudflare KV-backed storage for:
25
- - OAuth state
26
- - user token records
27
- - session records
28
- - Session-token based MCP auth:
29
- - `Authorization: Bearer <session-token>`
30
- - Render Secret File support for environment-specific credentials
31
- - Admin session inspection/revocation endpoints
32
- - `GET /whoami` endpoint for session-bound identity lookup
33
- - Optional `OAUTH_START_KEY` protection for `/oauth/start`
34
- - **MCP OAuth 2.1 authorization server** — Cline and other MCP clients that support OAuth discovery (`/.well-known/oauth-authorization-server`, `POST /register`, `GET /authorize`, `POST /token`) can authenticate fully automatically via browser eBay OAuth with no manual token pasting
21
+ - **Hosted Streamable HTTP mode** — deploy to Render (or any Node.js host) and serve multiple users from one instance
22
+ - **MCP OAuth 2.1 authorization server** — full browser-based eBay login with automatic token management; Cline and other OAuth-aware clients connect with zero manual token pasting
23
+ - **Environment-scoped route trees** — `/sandbox/mcp` and `/production/mcp` hard-bind their eBay environment; no query param needed
24
+ - **Cloudflare KV / Upstash Redis** token and session storage for persistent multi-user auth
25
+ - **Admin session management** — inspect, revoke, or delete sessions via authenticated endpoints
26
+ - **TTL-aligned records** — every stored record (OAuth state, auth code, session, user token) carries an `expiresAt` timestamp and a matching KV/Redis TTL so storage and application expiry are always in sync
35
27
 
36
28
  ---
37
29
 
38
- ## One-Click AI Setup
39
-
40
- > **Let your AI assistant set this up for you!** Copy the prompt below and paste it into Claude, ChatGPT, or any AI assistant with MCP support.
30
+ ## ⚠️ Disclaimer
41
31
 
42
- <details>
43
- <summary><strong>Click to copy the AI setup prompt</strong></summary>
32
+ This is an open-source project provided "as is" without warranty of any kind. The authors accept **no responsibility or liability** for any damages arising from use of this software. This project is **not affiliated with, endorsed by, or sponsored by eBay Inc.** Test thoroughly in eBay's sandbox before using in production.
44
33
 
45
- ```text
46
- I want to set up the eBay MCP Server for my AI assistant. Please help me:
34
+ ---
47
35
 
48
- 1. Install the eBay MCP server:
49
- git clone https://github.com/mrnajiboy/ebay-mcp-remote-edition.git
50
- cd ebay-mcp-remote-edition
51
- pnpm install
52
- pnpm run build
36
+ ## Table of Contents
53
37
 
54
- 2. I need to configure it for [Claude Desktop / Cursor / Cline / Zed / Continue.dev / Windsurf / Claude Code CLI / Amazon Q] (choose one)
38
+ - [Choose a runtime mode](#choose-a-runtime-mode)
39
+ - [Prerequisites](#prerequisites)
40
+ - [Local mode setup](#local-mode-setup)
41
+ - [Install](#install)
42
+ - [Configure credentials](#configure-credentials)
43
+ - [Run the setup wizard](#run-the-setup-wizard)
44
+ - [Local client configuration](#local-client-configuration)
45
+ - [Hosted mode setup](#hosted-mode-setup)
46
+ - [Environment variables](#hosted-environment-variables)
47
+ - [Secret file](#secret-file)
48
+ - [Deploy to Render](#deploy-to-render)
49
+ - [OAuth flows](#oauth-flows)
50
+ - [MCP endpoints](#mcp-endpoints)
51
+ - [Remote client configuration](#remote-client-configuration)
52
+ - [Available tools](#available-tools)
53
+ - [Development](#development)
54
+ - [Testing & validation](#testing--validation)
55
+ - [Troubleshooting](#troubleshooting)
56
+ - [Resources](#resources)
55
57
 
56
- 3. My eBay credentials are:
57
- - Client ID: [YOUR_CLIENT_ID]
58
- - Client Secret: [YOUR_CLIENT_SECRET]
59
- - Environment: [sandbox / production]
60
- - Redirect URI (RuName): [YOUR_REDIRECT_URI]
58
+ ---
61
59
 
62
- Please:
63
- - Create the appropriate config file for my MCP client
64
- - Set up the environment variables
65
- - Help me complete the OAuth flow to get a refresh token for higher rate limits
66
- - Test that the connection works
60
+ ## Choose a runtime mode
67
61
 
68
- If I don't have eBay credentials yet, guide me through creating a developer account at https://developer.ebay.com/
69
- ```
62
+ | Mode | Transport | Best for |
63
+ |------|-----------|----------|
64
+ | **Local STDIO** | stdin/stdout | Single-user local AI client (Claude Desktop, Cline, Cursor, etc.) |
65
+ | **Hosted HTTP** | Streamable HTTP | Multi-user server deployment; remote MCP clients |
70
66
 
71
- </details>
67
+ Both modes use the same eBay tools. The local mode reads credentials from environment variables or a `.env` file. The hosted mode handles multi-user OAuth server-side and authenticates clients with session tokens.
72
68
 
73
69
  ---
74
70
 
75
- ## ⚠️ Disclaimer
76
-
77
- **IMPORTANT: Please read this disclaimer carefully before using this software.**
71
+ ## Prerequisites
78
72
 
79
- This is an **open-source project** provided "as is" without warranty of any kind, either express or implied. By using this software, you acknowledge and agree to the following:
73
+ **All modes:**
74
+ - Node.js ≥ 18.0.0
75
+ - [pnpm](https://pnpm.io/) (or npm — `npm install -g pnpm`)
76
+ - An [eBay Developer Account](https://developer.ebay.com/)
80
77
 
81
- - **No Liability:** The authors, contributors, and maintainers of this project accept **NO responsibility or liability** for any damages, losses, or issues that may arise from using this software.
82
- - **eBay API Usage:** This project is an unofficial third-party implementation and is **NOT affiliated with, endorsed by, or sponsored by eBay Inc.**
83
- - **Use at Your Own Risk:** Test thoroughly in eBay's sandbox before production use.
84
- - **Security:** You are responsible for securing API credentials, session tokens, and hosted endpoints.
78
+ **Getting eBay credentials:**
79
+ 1. Log in to the [eBay Developer Portal](https://developer.ebay.com/my/keys)
80
+ 2. Create an application and copy your **App ID (Client ID)** and **Cert ID (Client Secret)**
81
+ 3. Under **User Tokens → Add RuName**, register your OAuth callback URL and copy the generated **RuName** string
85
82
 
86
- For official eBay API support, please refer to the [eBay Developer Program](https://developer.ebay.com/).
83
+ > **`EBAY_RUNAME` is the RuName string eBay generates, not the callback URL itself.** It looks like `YourApp-YourApp-SBX-abcdefghi`. The callback URL is set separately (see below).
87
84
 
88
- ---
85
+ ### HTTPS callback URL (required by eBay)
89
86
 
90
- ## Table of Contents
87
+ eBay requires an HTTPS callback URL for OAuth. For local development, use [mkcert](https://github.com/FiloSottile/mkcert):
91
88
 
92
- - [Fork additions in this deployment-focused version](#fork-additions-in-this-deployment-focused-version)
93
- - [⚠️ Disclaimer](#️-disclaimer)
94
- - [Features](#features)
95
- - [Quick Start](#quick-start)
96
- - [Local MCP Client Configuration](#local-mcp-client-configuration)
97
- - [Hosted Render Deployment](#hosted-render-deployment)
98
- - [Hosted MCP Client Configuration](#hosted-mcp-client-configuration)
99
- - [Configuration](#configuration)
100
- - [Available Tools](#available-tools)
101
- - [Development](#development)
102
- - [Logging](#logging)
103
- - [Troubleshooting](#troubleshooting)
104
- - [Resources](#resources)
105
- - [License](#license)
89
+ ```bash
90
+ brew install mkcert nss
91
+ mkcert -install
92
+ mkcert ebay-local.test
93
+ echo "127.0.0.1 ebay-local.test" | sudo tee -a /etc/hosts
94
+ ```
106
95
 
107
- ## Features
96
+ Register `https://ebay-local.test:3000/oauth/callback` in the eBay Developer Portal as your Accept URL. Then add to `.env`:
108
97
 
109
- - **325+ eBay API Tools** - 100% coverage of eBay Sell APIs across inventory, orders, marketing, analytics, developer tools, and more
110
- - **9 AI Clients Supported** - Auto-configuration for Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, and Amazon Q
111
- - **OAuth 2.0 Support** - Full user token management with automatic refresh
112
- - **Type Safety** - Built with TypeScript, Zod validation, and OpenAPI-generated types
113
- - **MCP Integration** - STDIO transport for local integration and HTTP transport for hosted deployment
114
- - **Smart Authentication** - Automatic fallback from user tokens to client credentials where applicable
115
- - **Hosted Multi-User Mode** - Server-side OAuth + session-token auth for hosted MCP access
116
- - **Well Tested** - Comprehensive typecheck/build/deploy validation
117
- - **Interactive Setup Wizard** - Run `pnpm run setup` for guided local configuration
118
- - **Developer Analytics** - Rate limit monitoring and signing key management
98
+ ```bash
99
+ PUBLIC_BASE_URL=https://ebay-local.test:3000
100
+ EBAY_LOCAL_TLS_CERT_PATH=/path/to/ebay-local.test.pem
101
+ EBAY_LOCAL_TLS_KEY_PATH=/path/to/ebay-local.test-key.pem
102
+ ```
119
103
 
120
- ## Quick Start
104
+ For hosted deployments, register your server's public HTTPS URL instead (e.g. `https://your-server.com/oauth/callback`).
121
105
 
122
- ### 1. Get eBay Credentials
106
+ ---
123
107
 
124
- 1. Create a free [eBay Developer Account](https://developer.ebay.com/)
125
- 2. Generate application keys in the [Developer Portal](https://developer.ebay.com/my/keys)
126
- 3. Save your **Client ID** and **Client Secret**
127
- 4. Configure environment-specific RuNames for production and sandbox as needed
108
+ ## Local mode setup
128
109
 
129
- ### 2. Install
110
+ ### Install
130
111
 
131
- **Option A — npm (easiest, no build step required):**
112
+ **Option A — npm global install (no build step):**
132
113
 
133
114
  ```bash
134
115
  npm install -g ebay-mcp-remote-edition
135
- # or
136
- pnpm add -g ebay-mcp-remote-edition
137
- ```
138
-
139
- Then run the setup wizard:
140
-
141
- ```bash
142
- ebay-mcp-remote-edition --setup
143
116
  ```
144
117
 
145
- **Option B — clone and build (for contributors or if you want to self-host the HTTP server):**
118
+ **Option B — clone and build (for contributors or self-hosting):**
146
119
 
147
120
  ```bash
148
121
  git clone https://github.com/mrnajiboy/ebay-mcp-remote-edition.git
@@ -151,83 +124,48 @@ pnpm install
151
124
  pnpm run build
152
125
  ```
153
126
 
154
- ### 3. Run Local Setup Wizard
127
+ ### Configure credentials
155
128
 
156
- For local/STDIO usage after cloning:
129
+ Create a `.env` file in the project root (see `.env.example`):
157
130
 
158
131
  ```bash
159
- pnpm run setup
160
- ```
161
-
162
- ### 4. Hosted Mode
163
-
164
- For hosted Render usage, see the next section.
165
-
166
- ---
167
-
168
- ## Local MCP Client Configuration
169
-
170
- Two ways to configure your MCP client for local (STDIO) usage:
171
-
172
- - **Option A — `npx` (no clone needed):** Use `npx -y ebay-mcp-remote-edition` as the command. npm downloads and runs the latest published version automatically.
173
- - **Option B — local build:** Clone the repo, run `pnpm run build` and `pnpm run setup`, then point at `/absolute/path/to/ebay-mcp-remote-edition/build/index.js`.
132
+ EBAY_CLIENT_ID=your_client_id
133
+ EBAY_CLIENT_SECRET=your_client_secret
134
+ EBAY_RUNAME=your_runame_string
135
+ EBAY_ENVIRONMENT=sandbox # or production
136
+ EBAY_MARKETPLACE_ID=EBAY_US # optional, defaults to EBAY_US
137
+ EBAY_CONTENT_LANGUAGE=en-US # optional, defaults to en-US
174
138
 
175
- The configs below show both. Supply your eBay credentials either as `env` fields in the config or via a `.env` file in the working directory.
139
+ # Populated by the setup wizard:
140
+ EBAY_USER_REFRESH_TOKEN=
141
+ ```
176
142
 
177
- > **Getting your credentials:** Run `pnpm run setup` in the cloned repo — it completes the OAuth flow and writes `EBAY_USER_REFRESH_TOKEN` to `.env`.
143
+ **Authentication tiers:**
178
144
 
179
- ### Cline
145
+ | Method | Rate limit | How |
146
+ |--------|-----------|-----|
147
+ | Client credentials (default) | 1,000 req/day | Just set `EBAY_CLIENT_ID` + `EBAY_CLIENT_SECRET` |
148
+ | User tokens (recommended) | 10,000–50,000 req/day | Run the setup wizard to complete OAuth and populate `EBAY_USER_REFRESH_TOKEN` |
180
149
 
181
- Config file location:
182
- `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
150
+ ### Run the setup wizard
183
151
 
184
- **Using npx (no clone needed):**
152
+ The interactive wizard guides you through environment selection, credential entry, OAuth login, and MCP client configuration:
185
153
 
186
- ```json
187
- {
188
- "mcpServers": {
189
- "ebay": {
190
- "command": "npx",
191
- "args": ["-y", "ebay-mcp-remote-edition"],
192
- "env": {
193
- "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
194
- "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
195
- "EBAY_ENVIRONMENT": "sandbox",
196
- "EBAY_REDIRECT_URI": "YOUR_RUNAME",
197
- "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
198
- }
199
- }
200
- }
201
- }
154
+ ```bash
155
+ pnpm run setup
202
156
  ```
203
157
 
204
- **Using local build:**
158
+ Options:
159
+ - `--quick` — skip optional steps
160
+ - `--diagnose` — run connectivity and token checks only
205
161
 
206
- ```json
207
- {
208
- "mcpServers": {
209
- "ebay": {
210
- "command": "node",
211
- "args": ["/absolute/path/to/ebay-mcp-remote-edition/build/index.js"],
212
- "env": {
213
- "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
214
- "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
215
- "EBAY_ENVIRONMENT": "sandbox",
216
- "EBAY_REDIRECT_URI": "YOUR_RUNAME",
217
- "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
218
- }
219
- }
220
- }
221
- }
222
- ```
162
+ After completing OAuth, the wizard writes `EBAY_USER_REFRESH_TOKEN` to `.env` and optionally configures Claude Desktop automatically.
223
163
 
224
- ### Claude Desktop
164
+ ### Local client configuration
225
165
 
226
- Config file location:
227
- - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
228
- - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
166
+ For direct STDIO usage, configure your MCP client to launch the server as a subprocess. All clients use the same JSON pattern:
229
167
 
230
- **Using npx:**
168
+ **Using npm (no clone needed):**
231
169
 
232
170
  ```json
233
171
  {
@@ -239,7 +177,7 @@ Config file location:
239
177
  "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
240
178
  "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
241
179
  "EBAY_ENVIRONMENT": "sandbox",
242
- "EBAY_REDIRECT_URI": "YOUR_RUNAME",
180
+ "EBAY_RUNAME": "YOUR_RUNAME",
243
181
  "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
244
182
  }
245
183
  }
@@ -247,7 +185,7 @@ Config file location:
247
185
  }
248
186
  ```
249
187
 
250
- **Using local build:**
188
+ **Using a local build:**
251
189
 
252
190
  ```json
253
191
  {
@@ -259,7 +197,7 @@ Config file location:
259
197
  "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
260
198
  "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
261
199
  "EBAY_ENVIRONMENT": "sandbox",
262
- "EBAY_REDIRECT_URI": "YOUR_RUNAME",
200
+ "EBAY_RUNAME": "YOUR_RUNAME",
263
201
  "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
264
202
  }
265
203
  }
@@ -267,119 +205,68 @@ Config file location:
267
205
  }
268
206
  ```
269
207
 
270
- ### Cursor
208
+ **Config file locations by client:**
271
209
 
272
- Global config: `~/.cursor/mcp.json`
273
- Project config: `.cursor/mcp.json` (in your project root)
210
+ | Client | Config file |
211
+ |--------|-------------|
212
+ | Cline | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
213
+ | Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
214
+ | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
215
+ | Cursor (global) | `~/.cursor/mcp.json` |
216
+ | Cursor (project) | `.cursor/mcp.json` |
274
217
 
275
- **Using npx:**
218
+ Zed, Windsurf, Continue.dev, Roo Code, and Amazon Q follow the same `mcpServers` JSON shape.
276
219
 
277
- ```json
278
- {
279
- "mcpServers": {
280
- "ebay": {
281
- "command": "npx",
282
- "args": ["-y", "ebay-mcp-remote-edition"],
283
- "env": {
284
- "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
285
- "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
286
- "EBAY_ENVIRONMENT": "sandbox",
287
- "EBAY_REDIRECT_URI": "YOUR_RUNAME",
288
- "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
289
- }
290
- }
291
- }
292
- }
293
- ```
294
-
295
- **Using local build:**
296
-
297
- ```json
298
- {
299
- "mcpServers": {
300
- "ebay": {
301
- "command": "node",
302
- "args": ["/absolute/path/to/ebay-mcp-remote-edition/build/index.js"],
303
- "env": {
304
- "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
305
- "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
306
- "EBAY_ENVIRONMENT": "sandbox",
307
- "EBAY_REDIRECT_URI": "YOUR_RUNAME",
308
- "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
309
- }
310
- }
311
- }
312
- }
313
- ```
220
+ ---
314
221
 
315
- ### Other STDIO clients (Zed, Windsurf, Continue.dev, Roo Code, Amazon Q)
222
+ ## Hosted mode setup
316
223
 
317
- All STDIO-based clients use the same pattern. Use `npx -y ebay-mcp-remote-edition` for zero-install, or point `command` at `node` with `build/index.js` for a local build.
224
+ The hosted HTTP server exposes environment-scoped MCP and OAuth endpoints, handles eBay OAuth server-side, and issues session tokens to MCP clients.
318
225
 
319
- **Using npx:**
226
+ ### Hosted environment variables
320
227
 
321
- ```json
322
- {
323
- "mcpServers": {
324
- "ebay": {
325
- "command": "npx",
326
- "args": ["-y", "ebay-mcp-remote-edition"],
327
- "env": {
328
- "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
329
- "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
330
- "EBAY_ENVIRONMENT": "sandbox",
331
- "EBAY_REDIRECT_URI": "YOUR_RUNAME",
332
- "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
333
- }
334
- }
335
- }
336
- }
337
- ```
228
+ ```bash
229
+ # Server
230
+ PORT=3000
231
+ MCP_HOST=0.0.0.0
232
+ PUBLIC_BASE_URL=https://your-server.com
338
233
 
339
- ---
234
+ # eBay credentials (prefer secret file below instead of raw env)
235
+ EBAY_DEFAULT_ENVIRONMENT=production # sandbox or production
340
236
 
341
- ## Hosted Render Deployment
237
+ # Persistent token/session storage backend (required for multi-user hosted mode)
238
+ EBAY_TOKEN_STORE_BACKEND=cloudflare-kv # cloudflare-kv | upstash-redis | memory
342
239
 
343
- ### Build command
240
+ # Cloudflare KV (when EBAY_TOKEN_STORE_BACKEND=cloudflare-kv)
241
+ CLOUDFLARE_ACCOUNT_ID=
242
+ CLOUDFLARE_KV_NAMESPACE_ID=
243
+ CLOUDFLARE_API_TOKEN=
344
244
 
345
- ```bash
346
- pnpm install && pnpm run build
347
- ```
245
+ # Upstash Redis (when EBAY_TOKEN_STORE_BACKEND=upstash-redis)
246
+ UPSTASH_REDIS_REST_URL=
247
+ UPSTASH_REDIS_REST_TOKEN=
348
248
 
349
- ### Start command
249
+ # Security
250
+ ADMIN_API_KEY= # required for admin session endpoints
251
+ OAUTH_START_KEY= # optional; protects /oauth/start with a shared secret
350
252
 
351
- ```bash
352
- pnpm run start:http
353
- ```
253
+ # Session TTL (optional; default 30 days)
254
+ SESSION_TTL_SECONDS=2592000
354
255
 
355
- ### Recommended Render environment variables
256
+ # Logging
257
+ EBAY_LOG_LEVEL=info
258
+ EBAY_MARKETPLACE_ID=EBAY_US
259
+ EBAY_CONTENT_LANGUAGE=en-US
356
260
 
357
- ```bash
358
- PORT=
359
- NODE_VERSION=
360
- PUBLIC_BASE_URL=https://your-server.com
261
+ # Path to secret file (see below)
361
262
  EBAY_CONFIG_FILE=/etc/secrets/ebay-config.json
362
- EBAY_DEFAULT_ENVIRONMENT=sandbox|production
363
- EBAY_TOKEN_STORE_BACKEND=cloudflare-kv
364
- CLOUDFLARE_ACCOUNT_ID=ID
365
- CLOUDFLARE_KV_NAMESPACE_ID=ID
366
- CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
367
- ADMIN_API_KEY=your-admin-api-key
368
- OAUTH_START_KEY=optional-shared-secret-for-oauth-start
369
- EBAY_MARKETPLACE_ID=EBAY_COUNTRY
370
- EBAY_CONTENT_LANGUAGE=lang-COUNTRY
371
- EBAY_LOG_LEVEL=info
372
263
  ```
373
264
 
374
- ### Render secret file
265
+ > Use `EBAY_TOKEN_STORE_BACKEND=memory` only for local development or tests. All OAuth state, session tokens, and user tokens are lost on restart.
375
266
 
376
- Filename:
267
+ ### Secret file
377
268
 
378
- ```text
379
- ebay-config.json
380
- ```
381
-
382
- Example contents:
269
+ Store eBay credentials in a mounted secret file rather than raw environment variables. On Render, create a **Secret File** named `ebay-config.json` mounted at `/etc/secrets/ebay-config.json`:
383
270
 
384
271
  ```json
385
272
  {
@@ -396,160 +283,141 @@ Example contents:
396
283
  }
397
284
  ```
398
285
 
399
- Render mounts it at:
286
+ ### Deploy to Render
400
287
 
401
- ```text
402
- /etc/secrets/ebay-config.json
403
- ```
288
+ 1. Connect your repo to Render as a **Web Service**
289
+ 2. Set **Build command:**
290
+ ```bash
291
+ pnpm install && pnpm run build
292
+ ```
293
+ 3. Set **Start command:**
294
+ ```bash
295
+ pnpm run start:http
296
+ ```
297
+ 4. Add the environment variables listed above
298
+ 5. Add the `ebay-config.json` secret file
404
299
 
405
- ### OAuth flows
300
+ The server starts on the port Render assigns via `$PORT` and logs the active KV backend on startup.
406
301
 
407
- Start production OAuth:
302
+ ### OAuth flows
408
303
 
409
- ```text
410
- /oauth/start?env=production
411
- ```
304
+ eBay requires a single registered callback URL per application. The hosted server registers `/oauth/callback` at the root and recovers the environment from the stored OAuth state record.
412
305
 
413
- Start sandbox OAuth:
306
+ **Start an OAuth flow (browser):**
414
307
 
415
- ```text
416
- /oauth/start?env=sandbox
417
308
  ```
418
-
419
- If `OAUTH_START_KEY` is configured, include either:
420
-
421
- ```text
422
- /oauth/start?env=production&key=YOUR_OAUTH_START_KEY
309
+ GET /sandbox/oauth/start # always sandbox
310
+ GET /production/oauth/start # always production
423
311
  ```
424
312
 
425
- or send:
426
-
427
- ```text
428
- X-OAuth-Start-Key: YOUR_OAUTH_START_KEY
313
+ If `OAUTH_START_KEY` is set, include it as a query parameter or header:
429
314
  ```
430
-
431
- ### Hosted session token usage
432
-
433
- After successful callback, the app issues a session token and displays it in a copy-friendly callback page.
434
-
435
- Use it in your MCP client:
436
-
437
- ```text
438
- Authorization: Bearer <session-token>
315
+ GET /sandbox/oauth/start?key=YOUR_OAUTH_START_KEY
316
+ # or header: X-OAuth-Start-Key: YOUR_OAUTH_START_KEY
439
317
  ```
440
318
 
441
- For Make/Zapier/TypingMind anywhere where Remote MCP is accepted, the practical supported flow is:
319
+ After a successful login, the callback page displays your **session token**, **eBay access token**, and **eBay refresh token** with one-click copy buttons.
442
320
 
443
- 1. complete browser OAuth via the hosted server
444
- 2. copy the returned session token from the callback page
445
- 3. paste it into the platform's API Key / Access token field
321
+ **Session token TTL schedule:**
446
322
 
447
- Normal MCP usage should not open a browser window once a valid hosted session token already exists.
323
+ | Record | `expiresAt` field | Backend TTL |
324
+ |--------|-------------------|-------------|
325
+ | OAuth state | 15 minutes | 15 minutes |
326
+ | MCP auth code | 10 minutes | 10 minutes |
327
+ | Session | 30 days (configurable) | Matches `SESSION_TTL_SECONDS` |
328
+ | User token record | eBay refresh token expiry (fallback: 18 months) | Matches token expiry |
448
329
 
449
- ### Admin endpoints
330
+ ### MCP endpoints
450
331
 
451
- Require:
332
+ **Environment-scoped (recommended):**
452
333
 
453
- ```text
454
- X-Admin-API-Key: <ADMIN_API_KEY>
455
334
  ```
456
-
457
- Endpoints:
458
-
459
- - `GET /admin/session/:sessionToken`
460
- - `POST /admin/session/:sessionToken/revoke`
461
- - `DELETE /admin/session/:sessionToken`
462
-
463
- ### Session introspection
464
-
465
- ```text
466
- GET /whoami
467
- Authorization: Bearer <session-token>
335
+ POST/GET/DELETE /sandbox/mcp
336
+ POST/GET/DELETE /production/mcp
468
337
  ```
469
338
 
470
- ### MCP endpoint
471
-
472
- ```text
473
- POST /mcp
474
- GET /mcp
475
- DELETE /mcp
339
+ Each scoped path includes its own OAuth 2.1 discovery document:
340
+ ```
341
+ GET /sandbox/.well-known/oauth-authorization-server
342
+ GET /production/.well-known/oauth-authorization-server
476
343
  ```
477
344
 
478
- #### Initial auth behavior
479
-
480
- - `GET /mcp` without a valid Bearer token redirects into browser OAuth
481
- - default environment is production
482
- - sandbox can be requested with `?env=sandbox`
483
- - `POST /mcp` without a valid Bearer token returns an auth-required JSON response
484
-
485
- This means browser-driven onboarding works cleanly, while protocol clients can still receive a structured auth response.
486
-
487
- ### Privacy recommendations
345
+ **Legacy auto-detect (backward-compatible):**
346
+ ```
347
+ POST/GET/DELETE /mcp # resolves environment from ?env= or EBAY_DEFAULT_ENVIRONMENT
348
+ ```
488
349
 
489
- If you want the service URL to be less exposed:
350
+ **Authentication behavior:**
351
+ - `GET /mcp` (or scoped variant) without a valid Bearer token redirects the browser to the matching `oauth/start` URL
352
+ - `POST /mcp` without a valid Bearer token returns a structured `401` JSON with an `authorization_url` field
353
+ - All requests supply a session token via `Authorization: Bearer <session-token>`
490
354
 
491
- - protect `/oauth/start` with `OAUTH_START_KEY`
492
- - protect `/admin/*` with `ADMIN_API_KEY`
493
- - keep `/oauth/callback` reachable by eBay
494
- - optionally place `/`, `/oauth/start`, and `/admin/*` behind Cloudflare Access
495
- - keep `/health` available if needed by Render health checks
355
+ **Other utility endpoints:**
496
356
 
497
- ---
357
+ ```
358
+ GET /health # Server health check (no auth required)
359
+ GET /whoami # Session identity; requires Bearer token
360
+ GET /admin/session/:sessionToken # View session; requires X-Admin-API-Key
361
+ POST /admin/session/:sessionToken/revoke # Revoke session
362
+ DELETE /admin/session/:sessionToken # Delete session
363
+ ```
498
364
 
499
- ## Hosted MCP Client Configuration
365
+ `/whoami` response:
366
+ ```json
367
+ {
368
+ "userId": "...",
369
+ "environment": "sandbox",
370
+ "createdAt": "2026-03-23T08:00:00.000Z",
371
+ "expiresAt": "2026-04-22T08:00:00.000Z",
372
+ "lastUsedAt": "2026-03-23T09:30:00.000Z",
373
+ "revokedAt": null
374
+ }
375
+ ```
500
376
 
501
- The hosted server implements a full **MCP OAuth 2.1 authorization server** (RFC 8414 / RFC 7591 / RFC 6749 + PKCE). MCP clients that support OAuth discovery — such as Cline — will handle the full browser-based eBay login flow automatically with no manual token pasting required.
377
+ ### Remote client configuration
502
378
 
503
379
  Replace `https://your-server.com` with your actual `PUBLIC_BASE_URL`.
504
380
 
505
- ### Cline (recommended — full OAuth auto-discovery)
381
+ #### Cline (automatic OAuth — no manual token needed)
506
382
 
507
- Cline supports OAuth 2.1 discovery natively. Just point it at the MCP endpoint and it handles everything:
383
+ Cline supports MCP OAuth 2.1 discovery natively. It fetches the discovery document, registers itself, opens the eBay browser login, exchanges the auth code for a session token, and stores it — all automatically.
508
384
 
509
385
  ```json
510
386
  {
511
387
  "mcpServers": {
512
- "ebay": {
513
- "url": "https://your-server.com/mcp"
388
+ "ebay-sandbox": {
389
+ "url": "https://your-server.com/sandbox/mcp"
390
+ },
391
+ "ebay-production": {
392
+ "url": "https://your-server.com/production/mcp"
514
393
  }
515
394
  }
516
395
  }
517
396
  ```
518
397
 
519
- **What happens automatically:**
520
- 1. Cline fetches `/.well-known/oauth-authorization-server` to discover the auth server.
521
- 2. It registers itself at `POST /register` (Dynamic Client Registration).
522
- 3. Your browser opens `GET /authorize`, which redirects to eBay's login page.
523
- 4. After you grant access, eBay redirects to `/oauth/callback`, which issues an MCP auth code and sends it back to Cline.
524
- 5. Cline exchanges the code at `POST /token` for a session token and stores it.
525
- 6. All subsequent `/mcp` requests are authenticated automatically.
398
+ What Cline does automatically:
399
+ 1. Fetches `/.well-known/oauth-authorization-server` for the scoped path
400
+ 2. Registers at `POST /sandbox/register` (or `/production/register`)
401
+ 3. Your browser opens `GET /sandbox/authorize`, which redirects to eBay login
402
+ 4. After you grant access, eBay redirects to `/oauth/callback`, which issues an auth code
403
+ 5. Cline exchanges the code at `POST /sandbox/token` for a session token and stores it
404
+ 6. All subsequent `/sandbox/mcp` requests authenticate automatically
526
405
 
527
- > **`OAUTH_START_KEY` note:** If your server has `OAUTH_START_KEY` set, the `/authorize` endpoint also requires it. You can temporarily disable it for first-time client setup, or consult your server operator for the key.
406
+ #### Claude Desktop and Cursor (Bearer token)
528
407
 
529
- ### Claude Desktop (HTTP remote with pre-obtained session token)
408
+ Claude Desktop and most other remote MCP clients require a pre-obtained session token. Complete the browser OAuth flow first:
530
409
 
531
- Claude Desktop's remote MCP support requires an explicit `Authorization` header. Complete the browser OAuth flow at `https://your-server.com/oauth/start` first to get your session token, then configure:
410
+ 1. Open `https://your-server.com/sandbox/oauth/start` (or `/production/oauth/start`) in a browser
411
+ 2. Log in with your eBay account
412
+ 3. Copy the session token from the confirmation page
532
413
 
533
- ```json
534
- {
535
- "mcpServers": {
536
- "ebay": {
537
- "url": "https://your-server.com/mcp",
538
- "headers": {
539
- "Authorization": "Bearer YOUR_SESSION_TOKEN"
540
- }
541
- }
542
- }
543
- }
544
- ```
545
-
546
- ### Cursor (HTTP remote with pre-obtained session token)
414
+ Then configure your client:
547
415
 
548
416
  ```json
549
417
  {
550
418
  "mcpServers": {
551
- "ebay": {
552
- "url": "https://your-server.com/mcp",
419
+ "ebay-sandbox": {
420
+ "url": "https://your-server.com/sandbox/mcp",
553
421
  "headers": {
554
422
  "Authorization": "Bearer YOUR_SESSION_TOKEN"
555
423
  }
@@ -558,197 +426,169 @@ Claude Desktop's remote MCP support requires an explicit `Authorization` header.
558
426
  }
559
427
  ```
560
428
 
561
- ### Make / Zapier / TypingMind and similar platforms
429
+ #### Make / Zapier / TypingMind and similar platforms
562
430
 
563
- These platforms use a fixed token field. To connect:
564
-
565
- 1. Open `https://your-server.com/oauth/start?env=production` in a browser.
566
- 2. Complete the eBay login flow.
567
- 3. Copy the session token from the confirmation page.
568
- 4. Paste it as your **API Key / Bearer token** in the platform's MCP connector settings.
569
- 5. Set the MCP endpoint URL to `https://your-server.com/mcp`.
431
+ 1. Open `https://your-server.com/sandbox/oauth/start` in a browser and complete eBay login
432
+ 2. Copy the session token from the confirmation page
433
+ 3. Paste it as the **API Key / Bearer token** in the platform's MCP connector settings
434
+ 4. Set the MCP endpoint URL to `https://your-server.com/sandbox/mcp`
570
435
 
571
436
  ---
572
437
 
573
- ## Configuration
574
-
575
- ### Environment Variables
576
-
577
- Local mode still supports the classic environment-variable model:
578
-
579
- ```bash
580
- EBAY_CLIENT_ID=your_client_id
581
- EBAY_CLIENT_SECRET=your_client_secret
582
- EBAY_ENVIRONMENT=sandbox|production
583
- EBAY_REDIRECT_URI=your_runame
584
- EBAY_MARKETPLACE_ID=EBAY_COUNTRY
585
- EBAY_CONTENT_LANGUAGE=lang_COUNTRY
586
- EBAY_USER_REFRESH_TOKEN=your_refresh_token
587
- ```
588
-
589
- ### OAuth Authentication
590
-
591
- **Client Credentials:** lower-rate, application-level access.
592
-
593
- **User Tokens:** higher-rate access for seller/member-specific operations.
594
-
595
- For hosted mode, OAuth is handled server-side by the Render deployment.
438
+ ## Available tools
596
439
 
597
- ## Available Tools
598
-
599
- The server provides **325+ tools** across:
440
+ 325+ tools across all eBay Sell API categories:
600
441
 
601
442
  - Account Management
602
443
  - Inventory Management
603
444
  - Order Fulfillment
604
445
  - Marketing & Promotions
605
- - Analytics
606
- - Communication
446
+ - Analytics & Reporting
447
+ - Communication (messages, feedback, notifications, negotiation)
607
448
  - Metadata & Taxonomy
608
- - Developer Tools
609
- - Token / Auth-related helper tools
449
+ - Developer Tools (key management, analytics)
450
+ - Auth / Token helper tools
451
+
452
+ Full tool source: [`src/tools/definitions/`](src/tools/definitions/)
610
453
 
611
- For the complete tool list, see [src/tools/definitions/](src/tools/definitions/).
454
+ ---
612
455
 
613
456
  ## Development
614
457
 
615
- ### Prerequisites
458
+ ### Commands reference
459
+
460
+ | Command | Description |
461
+ |---------|-------------|
462
+ | `pnpm run build` | Compile TypeScript to JavaScript |
463
+ | `pnpm start` | Run local STDIO MCP server |
464
+ | `pnpm run start:http` | Run hosted HTTP MCP server |
465
+ | `pnpm run dev` | Local STDIO server with hot reload |
466
+ | `pnpm run dev:http` | Hosted HTTP server with hot reload |
467
+ | `pnpm test` | Run test suite |
468
+ | `pnpm run setup` | Interactive local setup wizard |
469
+ | `pnpm run sync` | Download latest eBay OpenAPI specs and regenerate types |
470
+ | `pnpm run diagnose` | Check configuration and connectivity |
471
+ | `pnpm run typecheck` | Run TypeScript type checking |
472
+ | `pnpm run check` | Typecheck + lint + format check |
473
+ | `pnpm run fix` | Auto-fix lint and format issues |
616
474
 
617
- - Node.js >= 24.0.0
618
- - [pnpm](https://pnpm.io/) (`npm install -g pnpm`)
619
- - eBay Developer Account
475
+ ### `pnpm run sync`
620
476
 
621
- ### Quick Start for Contributors
477
+ Downloads the latest eBay OpenAPI specs, regenerates TypeScript types, and reports implemented vs missing endpoints. Run this when you want to pick up new eBay API surface:
622
478
 
623
479
  ```bash
624
- git clone https://github.com/mrnajiboy/ebay-mcp-remote-edition.git
625
- cd ebay-mcp-remote-edition
626
- pnpm install
627
- pnpm run build
480
+ pnpm run sync
628
481
  pnpm run typecheck
629
- pnpm test
482
+ pnpm run build
630
483
  ```
631
484
 
632
- ### Commands Reference
633
-
634
- | Command | Description |
635
- | ------------------------ | -------------------------------------------------- |
636
- | `pnpm run build` | Compile TypeScript to JavaScript |
637
- | `pnpm start` | Run local STDIO MCP server |
638
- | `pnpm run start:http` | Run hosted HTTP MCP server |
639
- | `pnpm run dev` | Run local server with hot reload |
640
- | `pnpm run dev:http` | Run hosted HTTP server with hot reload |
641
- | `pnpm test` | Run test suite |
642
- | `pnpm run setup` | Interactive setup wizard |
643
- | `pnpm run sync` | Sync specs, generate types, find missing endpoints |
644
- | `pnpm run diagnose` | Check configuration and connectivity |
645
- | `pnpm run check` | Run typecheck + lint + format check |
646
- | `pnpm run fix` | Auto-fix lint and format issues |
485
+ Review the diff, commit the generated changes you want to keep, and deploy.
647
486
 
648
- ### About `pnpm run sync`
487
+ ### Local env management
649
488
 
650
- This command is a spec/type regeneration workflow. It is **not** an upstream git sync.
651
-
652
- It will:
653
-
654
- 1. Download latest OpenAPI specs from eBay
655
- 2. Generate TypeScript types from specs
656
- 3. Analyze implemented vs missing endpoints
657
- 4. Produce a sync report
658
-
659
- Run it intentionally when you want to refresh generated artifacts.
660
-
661
- ### Manual sync workflow
662
-
663
- This fork treats sync as a repo-side maintenance workflow, not a live server feature.
664
-
665
- Recommended manual flow:
489
+ For local development, standard runtime scripts automatically load `.env` via dotenvx. Hosted platforms should provide environment variables directly — the server detects hosted environments (e.g. `RENDER=true`) and skips local file loading.
666
490
 
667
491
  ```bash
668
- pnpm install
669
- pnpm run sync
670
- pnpm run typecheck
671
- pnpm run build
492
+ pnpm run env:encrypt # encrypt .env for safe sharing
493
+ pnpm run env:decrypt # decrypt
672
494
  ```
673
495
 
674
- Then review the diff, commit the generated changes you want to keep, and deploy from Git.
496
+ ### Logging
675
497
 
676
- ## Dependency policy
498
+ ```bash
499
+ EBAY_LOG_LEVEL=debug # error | warn | info | debug
500
+ EBAY_ENABLE_FILE_LOGGING=true # write logs to files
501
+ ```
677
502
 
678
- This fork uses normal semver-compatible dependency ranges so fresh installs can pick up newer compatible versions automatically. The MCP SDK dependency has been bumped to a newer range so patched transitive dependencies can be resolved during install rather than requiring users to perform a manual update after cloning.
503
+ ---
679
504
 
680
- After dependency changes, validate with:
505
+ ## Testing & validation
681
506
 
682
507
  ```bash
683
- pnpm run typecheck
508
+ # Build and type check
684
509
  pnpm run build
685
- ```
510
+ pnpm run typecheck
686
511
 
687
- ## Logging
512
+ # Run the test suite
513
+ pnpm test
688
514
 
689
- The server includes Winston-based logging for easier debugging.
515
+ # Check connectivity and token status
516
+ pnpm run diagnose
690
517
 
691
- ### Log Levels
518
+ # Verify hosted server health
519
+ curl https://your-server.com/health
692
520
 
693
- ```bash
694
- EBAY_LOG_LEVEL=debug
695
- ```
521
+ # Verify a session token
522
+ curl -H "Authorization: Bearer <session-token>" https://your-server.com/whoami
696
523
 
697
- ### File Logging
698
-
699
- ```bash
700
- EBAY_ENABLE_FILE_LOGGING=true
524
+ # Test MCP endpoint returns auth challenge when no token is provided
525
+ curl -X POST https://your-server.com/sandbox/mcp \
526
+ -H "Content-Type: application/json" \
527
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
528
+ # → should return 401 with authorization_url
701
529
  ```
702
530
 
531
+ ---
532
+
703
533
  ## Troubleshooting
704
534
 
705
535
  ### Hosted MCP returns 406
706
536
 
707
- If your MCP test client gets `406 Not Acceptable`, include:
708
-
709
- ```text
537
+ Include the correct `Accept` header in your MCP client:
538
+ ```
710
539
  Accept: application/json, text/event-stream
711
540
  ```
712
541
 
713
- ### OAuth browser flow
542
+ ### OAuth callback: "Invalid or expired OAuth state"
714
543
 
715
- In hosted mode, browser OAuth is needed for:
544
+ OAuth state records expire in 15 minutes. If you see this error, restart the browser OAuth flow.
716
545
 
717
- - first-time account connection
718
- - re-authorization after token expiry/revocation
546
+ ### Token verification fails on existing refresh token
719
547
 
720
- For Make and TypingMind, the server currently expects users to complete browser OAuth first and then paste the issued session token into the platform's token field. The server then takes over token refresh and ongoing eBay access.
548
+ Refresh tokens expire after ~18 months or can be revoked by eBay (password changes, etc.). Run the setup wizard again to obtain a new one:
549
+ ```bash
550
+ pnpm run setup
551
+ ```
721
552
 
722
- Normal MCP usage should rely on the issued session token.
553
+ In hosted mode, start a new browser OAuth flow at `/sandbox/oauth/start` or `/production/oauth/start`.
723
554
 
724
- ### Security reminders
555
+ ### Session token no longer works in hosted mode
725
556
 
726
- - Do not paste session tokens publicly
727
- - Revoke any exposed session tokens with the admin endpoint
728
- - Rotate exposed eBay client secrets and update your Render secret file
557
+ Check whether the session was revoked or expired:
558
+ ```bash
559
+ curl -H "Authorization: Bearer <token>" https://your-server.com/whoami
560
+ ```
729
561
 
730
- ## Cloudflare Access recommendation
562
+ Revoke exposed session tokens via the admin endpoint:
563
+ ```bash
564
+ curl -X POST https://your-server.com/admin/session/<token>/revoke \
565
+ -H "X-Admin-API-Key: YOUR_ADMIN_API_KEY"
566
+ ```
731
567
 
732
- If you want browser/admin surfaces to be private to only you:
568
+ ### Security checklist
733
569
 
734
- - protect `/`
735
- - protect `/oauth/start`
736
- - protect `/admin/*`
737
- - keep `/oauth/callback` reachable by eBay
738
- - keep `/mcp` outside Cloudflare Access unless your MCP client is verified to work through Cloudflare Access
739
- - keep `/health` reachable if Render uses it for health checks
570
+ - Do not commit `.env` or session tokens to version control
571
+ - Protect `/oauth/start` and `/admin/*` with `OAUTH_START_KEY` and `ADMIN_API_KEY`
572
+ - Keep `/oauth/callback` publicly reachable (eBay redirects to it after login)
573
+ - Keep `/health` reachable if Render uses it for health checks
574
+ - For production-grade isolation, optionally place `/`, `/oauth/start`, and `/admin/*` behind Cloudflare Access
575
+ - Rotate exposed eBay client secrets and update your secret file
740
576
 
741
- This is the recommended way to make the hosted URL effectively private without breaking OAuth callback or MCP compatibility.
577
+ ---
742
578
 
743
579
  ## Resources
744
580
 
745
581
  - [eBay Developer Portal](https://developer.ebay.com/)
746
582
  - [MCP Documentation](https://modelcontextprotocol.io/)
747
- - [OAuth Setup Guide](docs/auth/)
583
+ - [Auth Configuration Guide](docs/auth/CONFIGURATION.md)
584
+ - [OAuth Quick Reference](docs/auth/OAUTH_QUICK_REFERENCE.md)
585
+ - [API Status](docs/API_STATUS.md)
586
+ - [Changelog](CHANGELOG.md)
748
587
  - [Contributing Guidelines](CONTRIBUTING.md)
749
588
  - [Security Policy](SECURITY.md)
750
- - [Changelog](CHANGELOG.md)
589
+
590
+ ---
751
591
 
752
592
  ## License
753
593
 
754
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
594
+ MIT — see [LICENSE](LICENSE)