### Deployment Build and Start Commands Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Commands for installing dependencies, building the project, and starting the HTTP server, suitable for deployment on platforms like Render. ```bash pnpm install && pnpm run build pnpm run start:http ``` -------------------------------- ### Environment Setup Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Copy the example environment file and edit it with your eBay credentials. ```bash cp .env.example .env # Edit .env with your eBay credentials ``` -------------------------------- ### Example .env File Configuration Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/CONFIGURATION.md This is an example of how to configure your .env file with the necessary eBay API credentials and settings. ```dotenv EBAY_CLIENT_ID=YourAppId-Prod-1234-5678-90ab-cdef EBAY_CLIENT_SECRET=YourAppId-Prod-1234-5678-90ab-cdef-YourSecretKey EBAY_RUNAME=YourAppId-YourAppId-PR-abc-def-ghi EBAY_REDIRECT_URI= PUBLIC_BASE_URL=https://your-server.com EBAY_ENVIRONMENT=production EBAY_MARKETPLACE_ID=EBAY_US EBAY_CONTENT_LANGUAGE=en-US EBAY_USER_REFRESH_TOKEN=v^1.1#r^1#i^1#p^3#I^3#f^0#t^H4sIAAAAAAAAAOVXa2... ``` -------------------------------- ### Install Dependencies Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Install project dependencies using npm or pnpm. ```bash npm install ``` ```bash pnpm install ``` -------------------------------- ### Configure eBay Credentials (.env Example) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Provides an example of how to configure eBay API credentials and environment settings using a .env file. This file should be created based on the provided .env.example and contains essential keys for authentication and environment selection. ```bash EBAY_CLIENT_ID=your_client_id EBAY_CLIENT_SECRET=your_client_secret EBAY_RUNAME=your_runame_string # eBay-generated RuName, not a URL EBAY_REDIRECT_URI= # legacy env name; do not set to the public callback URL EBAY_ENVIRONMENT=sandbox # or production EBAY_MARKETPLACE_ID=EBAY_US # optional, defaults to EBAY_US EBAY_CONTENT_LANGUAGE=en-US # optional, defaults to en-US EBAY_USER_REFRESH_TOKEN= # populated by setup wizard ``` -------------------------------- ### Install mkcert for local HTTPS Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Install mkcert and nss for local HTTPS development. This is required for setting up local OAuth callbacks. ```bash brew install mkcert nss ``` ```bash mkcert -install ``` ```bash mkcert ebay-local.test ``` -------------------------------- ### OAuth Start Endpoints for eBay MCP Remote Edition Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Example endpoints for initiating OAuth flows in sandbox and production environments. If `OAUTH_START_KEY` is set, requests require a key in the URL or header. ```http GET /sandbox/oauth/start # sandbox browser login GET /production/oauth/start # production browser login ``` -------------------------------- ### Run eBay MCP Remote Edition Setup Wizard Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Executes the setup wizard for the eBay MCP Remote Edition using pnpm. The wizard can be run interactively, with quick options to skip steps, or solely for diagnosing connectivity and token checks. ```bash pnpm run setup # interactive: env selection, credentials, OAuth, client config ``` ```bash pnpm run setup --quick # skip optional steps ``` ```bash pnpm run setup --diagnose # connectivity and token checks only ``` -------------------------------- ### Running the Application Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/AGENTS.md Commands to start the application in different modes: STDIO, HTTP, or with hot reloading for development. ```bash pnpm start pnpm run start:http pnpm run dev ``` -------------------------------- ### Install pnpm Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Install pnpm globally if you don't have it already. It is recommended for managing Node.js packages. ```bash npm install -g pnpm ``` -------------------------------- ### Minimal Configuration (Client Credentials) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/CONFIGURATION.md Configure your .env file with essential client credentials for basic API access. This setup is suitable for server-to-server authentication. ```bash # .env file EBAY_CLIENT_ID=YourAppId-Prod-1234-5678-90ab-cdef EBAY_CLIENT_SECRET=YourAppId-Prod-1234-5678-90ab-cdef-YourSecretKey EBAY_ENVIRONMENT=sandbox EBAY_MARKETPLACE_ID=EBAY_US EBAY_CONTENT_LANGUAGE=en-US ``` -------------------------------- ### OAuth Start URL for Production Environment Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/CONFIGURATION.md Initiate the OAuth flow for the production environment using this URL. ```http GET /production/oauth/start # always production ``` -------------------------------- ### Development Workflow Commands Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/AGENTS.md Standard commands for installing dependencies, building the project, type checking, and running tests. ```bash pnpm install && pnpm run build && pnpm run typecheck && pnpm test ``` -------------------------------- ### TypeScript API Client Example Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Example of an asynchronous TypeScript function to get an inventory item by SKU, including Zod validation and JSDoc comments. ```typescript import { z, } from 'zod'; import { MarketplaceId } from '@/types/ebay-enums.js'; import type { InventoryItem } from '@/types/sell_inventory.js'; /** * Get inventory item by SKU * @param sku - The seller-defined SKU * @returns The inventory item details */ async getInventoryItem(sku: string): Promise { const validated = getInventoryItemSchema.parse({ sku }); return this.client.get(`/sell/inventory/v1/inventory_item/${sku}`); } const getInventoryItemSchema = z.object({ sku: z.string().min(1).describe('The seller-defined SKU'), }); ``` -------------------------------- ### Tool Description Example Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md An example of a self-documenting tool description, including what the tool does, the required OAuth scope, and the minimum scope URL for fine-grained permissions. ```markdown Get a specific inventory item by SKU. Required OAuth Scope: sell.inventory.readonly or sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory.readonly ``` -------------------------------- ### OAuth Start URL for Sandbox Environment Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/CONFIGURATION.md Initiate the OAuth flow for the sandbox environment using this URL. ```http GET /sandbox/oauth/start # always sandbox ``` -------------------------------- ### Development Server Commands Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Commands to start the development server in different modes and for watching changes. ```bash # Start development server (STDIO mode) npm run dev ``` ```bash # Start development server (HTTP mode with OAuth) npm run dev:http ``` ```bash # Watch mode for TypeScript compilation npm run watch ``` -------------------------------- ### Example Consent Request Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt An example of an HTML redirect (consent request) targeting the Sandbox environment. ```APIDOC ## Example Consent Request URL redirects a user to the application's Grant Application Access page. GET https://auth.sandbox.ebay.com/oauth2/authorize? client_id=& locale=& // optional prompt=login // optional redirect_uri=& response_type=code& scope=& // a URL-encoded string of space-separated scopes state= // optional ``` -------------------------------- ### Install eBay MCP Remote Edition (Clone and Build) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Clones the ebay-mcp-remote-edition repository from GitHub and installs dependencies, followed by building the project. This method is intended for contributors or users who need to work with the source code. ```bash # Option B — clone and build (contributors): git clone https://github.com/mrnajiboy/ebay-mcp-remote-edition.git cd ebay-mcp-remote-edition pnpm install && pnpm run build ``` -------------------------------- ### Install Playwright and Run Research Checks Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md These commands are used to install Playwright, build the project, and run research checks. Expected outcomes after bootstrap include `authState = loaded`, `sessionStrategy = storage_state`, `sessionSource = kv`, and `authValidationSucceeded = true`. ```bash pnpm run playwright:install pnpm run build pnpm run research:check-browser pnpm run research:bootstrap ``` -------------------------------- ### Hosted Mode Setup Environment Variables Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Lists the required environment variables for hosted mode setup of the eBay MCP Remote Edition. This includes base URL, eBay credentials for both production and sandbox, and variables for token store backends like Upstash Redis or Cloudflare KV. ```bash # Required for hosted OAuth URLs and eBay callback registration PUBLIC_BASE_URL=https://your-server.com # Required eBay credentials unless EBAY_CONFIG_FILE provides them EBAY_CLIENT_ID= EBAY_CLIENT_SECRET= EBAY_RUNAME= EBAY_REDIRECT_URI= # legacy env name; not the public callback URL # Recommended when serving both environments from one host EBAY_PRODUCTION_CLIENT_ID= EBAY_PRODUCTION_CLIENT_SECRET= EBAY_PRODUCTION_RUNAME= EBAY_PRODUCTION_REDIRECT_URI= EBAY_SANDBOX_CLIENT_ID= EBAY_SANDBOX_CLIENT_SECRET= EBAY_SANDBOX_RUNAME= EBAY_SANDBOX_REDIRECT_URI= # Required for hosted multi-user token/session persistence EBAY_TOKEN_STORE_BACKEND=upstash-redis # cloudflare-kv | upstash-redis | memory UPSTASH_REDIS_REST_URL= # required when backend is upstash-redis UPSTASH_REDIS_REST_TOKEN= # required when backend is upstash-redis CLOUDFLARE_ACCOUNT_ID= # required when backend is cloudflare-kv CLOUDFLARE_KV_NAMESPACE_ID= # required when backend is cloudflare-kv CLOUDFLARE_API_TOKEN= # required when backend is cloudflare-kv ``` -------------------------------- ### Install eBay MCP Remote Edition (Global) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Installs the ebay-mcp-remote-edition package globally using pnpm. This is a convenient option for users who do not need to modify the package and want to use it directly without a build step. ```bash # Option A — global install (no build step): pnpm install -g ebay-mcp-remote-edition ``` -------------------------------- ### Conventional Commit Examples Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Examples of Git commit messages following the Conventional Commits specification. ```markdown Examples: ``` feat(inventory): add bulk update inventory items tool fix(auth): handle token refresh race condition docs(readme): update OAuth setup instructions test(marketing): add campaign status validation tests chore(deps): update @modelcontextprotocol/sdk to 1.21.1 ``` ``` -------------------------------- ### Tool Naming Convention Example Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Illustrates the standard naming convention for eBay MCP tools, which follows the pattern `ebay__` for predictable agent discoverability. ```markdown | Action | |--------| | `get` | | `create` | | `update` | | `delete` | | `publish` | | `withdraw` | | `revise` | | `bulk_` | ``` -------------------------------- ### Local Mode Command Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Use this command to start the local STDIO mode for a single-user AI client. It reads eBay credentials from environment variables. ```bash pnpm start ``` ```bash pnpm run dev ``` -------------------------------- ### Unit Test Example for EbayInventoryApi Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Demonstrates how to write unit tests for the EbayInventoryApi class using Vitest. Includes mocking external dependencies and testing both successful fetches and error conditions. ```typescript import { describe, it, expect, vi, beforeEach } from 'vitest'; import { EbayInventoryApi } from '@/api/listing-management/inventory.js'; describe('EbayInventoryApi', () => { let inventoryApi: EbayInventoryApi; beforeEach(() => { const mockClient = createMockClient(); inventoryApi = new EbayInventoryApi(mockClient); }); describe('getInventoryItem', () => { it('should fetch inventory item by SKU', async () => { const sku = 'TEST-SKU-123'; const mockItem = { sku, condition: 'NEW' }; mockClient.get.mockResolvedValue(mockItem); const result = await inventoryApi.getInventoryItem(sku); expect(result).toEqual(mockItem); expect(mockClient.get).toHaveBeenCalledWith( `/sell/inventory/v1/inventory_item/${sku}` ); }); it('should throw error for invalid SKU', async () => { await expect( inventoryApi.getInventoryItem('') ).rejects.toThrow('SKU is required'); }); }); }); ``` -------------------------------- ### Legacy OAuth Start URLs with Environment Parameter Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/CONFIGURATION.md These legacy URLs allow specifying the target environment via a query parameter. The callback URL is always at the root. ```http GET /oauth/start?env=sandbox # legacy ``` ```http GET /oauth/start?env=production # legacy ``` -------------------------------- ### MCP Authentication Behavior Examples Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Illustrates different authentication scenarios for MCP endpoints, including redirects, 401 responses, and various header-based authentication methods. ```http GET /mcp without token → redirects to oauth/start ``` ```http POST /mcp without token → 401 JSON with authorization_url, resource_metadata, and a WWW-Authenticate Bearer challenge ``` ```http Authorization: Bearer ``` ```http X-Ebay-Server-Request: true X-Ebay-Client-Id: X-Ebay-User-Id: X-Ebay-Environment: sandbox|production ``` ```http X-Ebay-Server-Request: true plus Authorization: Bearer ``` ```http Authorization: Bearer ``` -------------------------------- ### Multi-Scope Example for OAuth URL Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md When requesting multiple scopes, separate them with a plus sign (`+`) in the `scope` parameter. Do not use URL encoding like `%2B`. ```url scope=https://api.ebay.com/oauth/api_scope+https://api.ebay.com/oauth/api_scope/sell.inventory+https://api.ebay.com/oauth/api_scope/sell.inventory.readonly ``` -------------------------------- ### Constructing a Consent Request URL Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This example shows how to build the consent request URL, directing users to the Grant Application Access page. It includes required and optional query parameters for customizing the user experience. ```http GET https://auth.sandbox.ebay.com/oauth2/authorize? client_id=& locale=& // optional prompt=login // optional redirect_uri=& response_type=code& scope=& // a URL-encoded string of space-separated scopes state=& // optional ``` -------------------------------- ### Launch eBay Auth with HTML Form Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt An example of using an HTML form with JavaScript to open the eBay sign-in URL in a new window. This is useful for web applications. ```html ``` -------------------------------- ### Start OAuth in Browser (Sandbox) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md Initiates the OAuth 2.1 authorization flow in the sandbox environment. This URL is used to redirect users to eBay's authorization server to grant permissions. ```text https://your-server.com/sandbox/oauth/start ``` -------------------------------- ### Trading API Request with OAuth Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This example demonstrates how to make a Trading API request, like GetCategories, using an OAuth access token. It shows the necessary HTTP headers and the request payload. ```APIDOC ## Trading API Request with OAuth ### Description This example shows how to authenticate a Trading API request using an OAuth user access token. The `` field is removed, and the token is passed in the `X-EBAY-API-IAF-TOKEN` HTTP header. ### Method POST ### Endpoint (Trading API Endpoint) ### Headers - **X-EBAY-API-IAF-TOKEN** (string) - Required - The OAuth User access token. - **X-EBAY-API-CALL-NAME** (string) - Required - The name of the API call (e.g., `GetCategories`). - **X-EBAY-API-SITEID** (string) - Required - The eBay site ID (e.g., `0` for US). - **X-EBAY-API-COMPATIBILITY-LEVEL** (string) - Required - The API version. ### Request Body ```xml 0 ReturnAll ``` ### Request Example ```http POST (Trading API Endpoint) HTTP/1.1 Host: api.ebay.com X-EBAY-API-IAF-TOKEN: X-EBAY-API-CALL-NAME: GetCategories X-EBAY-API-SITEID: 0 X-EBAY-API-COMPATIBILITY-LEVEL: 1085 Content-Type: text/xml 0 ReturnAll ``` ### Response #### Success Response (200) (Standard API response structure for GetCategories) #### Response Example (Example XML response for GetCategories) ``` -------------------------------- ### Hosted Mode Commands Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Commands to start the hosted HTTP mode, suitable for multi-user server deployments. This mode uses browser-based OAuth 2.1 for user authorization. ```bash pnpm run start:http ``` ```bash pnpm run dev:http ``` -------------------------------- ### Start OAuth in Browser (Production) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md Initiates the OAuth 2.1 authorization flow in the production environment. This URL is used to redirect users to eBay's authorization server to grant permissions. ```text https://your-server.com/production/oauth/start ``` -------------------------------- ### Test Schema Validation with Vitest Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/src/schemas/README.md This example demonstrates how to test schema validation using Vitest. It shows how to import a schema and use `safeParse` to check for both valid and invalid input data. ```typescript import { describe, it, expect, } from 'vitest'; import { getInventoryItemInputSchema, } from '@/schemas'; describe('Inventory Schemas', () => { it('should validate correct input', () => { const result = getInventoryItemInputSchema.safeParse({ sku: 'TEST-SKU-123', }); expect(result.success).toBe(true); }); it('should reject invalid input', () => { const result = getInventoryItemInputSchema.safeParse({}); expect(result.success).toBe(false); }); }); ``` -------------------------------- ### Example cURL Request for Refresh Token Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This cURL command demonstrates how to make a refresh token request to the eBay Sandbox environment. Replace placeholders with your actual credentials and token. ```bash curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=' \ ``` -------------------------------- ### GET /whoami Response Example Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/CONFIGURATION.md The 'expiresAt' field is included in the session introspection response, indicating the session's expiration time. ```json { "userId": "...", "environment": "sandbox", "createdAt": "2026-03-23T08:00:00.000Z", "expiresAt": "2026-04-22T08:00:00.000Z", "lastUsedAt": "2026-03-23T09:30:00.000Z", "revokedAt": null } ``` -------------------------------- ### Build Project Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Build the project using npm. ```bash npm run build ``` -------------------------------- ### XML Seven-Day Warning Response Example Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt An example of an XML response containing the HardExpirationWarning element, signaling a token expiration within seven days. ```xml 2005-01-12T18:29:48.312Z Success 00000000-00000000-00000000-00000000-00000000-00000000-0000000000 393 20050110220901 2005-01-14 03:34:00 ``` -------------------------------- ### Full Configuration (OAuth User Tokens) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/CONFIGURATION.md Set up your .env file with both application credentials and user-specific OAuth tokens for user-authorized API access. This includes required fields for OAuth flow and user refresh tokens. ```bash # .env file # Required: eBay Application Credentials EBAY_CLIENT_ID=YourAppId-Prod-1234-5678-90ab-cdef EBAY_CLIENT_SECRET=YourAppId-Prod-1234-5678-90ab-cdef-YourSecretKey EBAY_RUNAME=YourAppId-YourAppId-SB-abc-def-ghi EBAY_REDIRECT_URI= PUBLIC_BASE_URL=https://ebay-local.test:3000 EBAY_ENVIRONMENT=sandbox EBAY_MARKETPLACE_ID=EBAY_US EBAY_CONTENT_LANGUAGE=en-US # Required: User Refresh Token (obtained through OAuth flow) EBAY_USER_REFRESH_TOKEN=v^1.1#r^1#p^3#I^3#f^0#t^H4sIAAAAAAAAAOVXa2... # Auto-generated (do not set manually - will be created automatically) # EBAY_USER_ACCESS_TOKEN= # EBAY_APP_ACCESS_TOKEN= ``` -------------------------------- ### Build and Test Project Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Execute this sequence to build the project, perform type checking, and run all tests. This is a comprehensive check for development. ```bash pnpm run build && pnpm run typecheck && pnpm test ``` -------------------------------- ### Configure OAuth 2.1 for Production Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/SECURITY.md Set up OAuth 2.1 with HTTPS, strong client secrets, JWT validation, and required scopes for secure authentication. ```bash # Always use HTTPS in production OAUTH_AUTH_SERVER_URL=https://auth.example.com # NOT http:// # Strong client secrets (32+ chars, random) OAUTH_CLIENT_SECRET="$(openssl rand -base64 32)" # Require JWT validation or introspection OAUTH_USE_INTROSPECTION=true # Enforce required scopes OAUTH_REQUIRED_SCOPES="mcp:tools" ``` -------------------------------- ### Clone Repository Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Clone the repository and navigate into the project directory. ```bash git clone https://github.com/YOUR_USERNAME/ebay-mcp-remote-server.git cd ebay-mcp-remote-server ``` -------------------------------- ### Run Tests Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Execute the project tests using npm. ```bash npm test ``` -------------------------------- ### SOAP GetUser Request with OAuth Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt Example of a SOAP request to the GetUser API using an OAuth token in the X-EBAY-API-IAF-TOKEN header. ```APIDOC ## POST https://api.sandbox.ebay.com/wsapi?callname=GetUser&version=1085&siteid=0 HTTP/1.1 ### Description This endpoint demonstrates how to make a SOAP request to the GetUser API, including an OAuth token for authentication. ### Method POST ### Endpoint https://api.sandbox.ebay.com/wsapi?callname=GETUSER&version=1085&siteid=0 ### Headers - **Content-Type**: text/xml;charset=UTF-8 - **X-EBAY-API-IAF-TOKEN**: v^1.1#i^1#I^3#p^3#f^...r^0#t^H4s - **Host**: api.sandbox.ebay.com ### Request Body ```xml 1209 Soap call - OAuth Token in trading ReturnAll ``` ``` -------------------------------- ### XML GetUser Request with OAuth Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt Example of a non-SOAP XML request to the GetUser API using an OAuth token in the X-EBAY-API-IAF-TOKEN header. ```APIDOC ## POST https://api.sandbox.ebay.com/ws/api.dll HTTP/1.1 ### Description This endpoint demonstrates how to make a non-SOAP XML request to the GetUser API, including an OAuth token for authentication. ### Method POST ### Endpoint https://api.sandbox.ebay.com/ws/api.dll ### Headers - **Content-Type**: text/xml;charset=UTF-8 - **X-EBAY-API-COMPATIBILITY-LEVEL**: 1209 - **X-EBAY-API-IAF-TOKEN**: v^1.1#i^1#I^3#p^3#f^...r^0#t^H4s - **X-EBAY-API-SITEID**: 0 - **X-EBAY-API-CALL-NAME**: GetUser - **Host**: api.ebay.com ### Request Body ```xml 1209 XML call: OAuth Token in trading ReturnAll ``` ``` -------------------------------- ### Non-SOAP XML Request with OAuth Token Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This example demonstrates a non-SOAP XML request. The OAuth token is passed via the X-EBAY-API-IAF-TOKEN header. ```http POST https://api.sandbox.ebay.com/ws/api.dll HTTP/1.1 Content-Type: text/xml;charset=UTF-8 X-EBAY-API-COMPATIBILITY-LEVEL : 1209 X-EBAY-API-IAF-TOKEN: v^1.1#i^1#I^3#p^3#f^...r^0#t^H4s X-EBAY-API-SITEID : 0 X-EBAY-API-CALL-NAME : GetUser Host: api.ebay.com 1209 XML call: OAuth Token in trading ReturnAll ``` -------------------------------- ### Configure Environment Variables for Sandbox and Production Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/SECURITY.md Use different environment variables for sandbox and production to ensure secure and isolated deployments. Never use production credentials in development. ```bash # Development/testing EBAY_ENVIRONMENT=sandbox EBAY_CLIENT_ID="sandbox_app_id" # Production (only after thorough testing) EBAY_ENVIRONMENT=production EBAY_CLIENT_ID="production_app_id" ``` -------------------------------- ### Display All Credentials Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md Useful for debugging authentication issues, this command displays all configured credentials, including masked secrets. Verify that all necessary tokens and keys are present and correctly set. ```bash ebay:ebay_display_credentials ``` -------------------------------- ### Taxonomy API Schemas Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/src/schemas/README.md Schemas for category navigation, suggestions, and product aspects. Includes getting category hierarchy, suggesting categories, and retrieving item aspects. ```APIDOC ## Category Tree API ### Description API for getting the category hierarchy. ### Schemas - `getCategoryTreeOutputSchema` ## Category Suggestions API ### Description APIs for finding appropriate categories for items. ### Schemas - `getCategorySuggestionsInputSchema` - `getCategorySuggestionsOutputSchema` ## Item Aspects API ### Description APIs for getting required and recommended aspects for categories. ### Schemas - `getItemAspectsForCategoryOutputSchema` ``` -------------------------------- ### List Business Policies via API Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/BUSINESS_POLICY_SETUP.md Retrieve a list of existing Business Policies (Fulfillment, Payment, or Return) by making a GET request to the respective endpoint. ```APIDOC ## GET /sell/fulfillment/v1/policy/{policyType} ### Description Retrieves a list of Business Policies of a specified type. ### Method GET ### Endpoint https://api.ebay.com/sell/fulfillment/v1/policy/fulfillment https://api.ebay.com/sell/fulfillment/v1/policy/payment https://api.ebay.com/sell/fulfillment/v1/policy/return ### Parameters #### Query Parameters (None explicitly documented for listing) ### Response #### Success Response (200) - **id** (string) - The unique identifier for the policy. (Other fields may be present depending on the policy type) ### Request Example ```bash # List fulfillment policies curl "https://api.ebay.com/sell/fulfillment/v1/policy/fulfillment" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # List payment policies curl "https://api.ebay.com/sell/fulfillment/v1/policy/payment" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # List return policies curl "https://api.ebay.com/sell/fulfillment/v1/policy/return" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ``` -------------------------------- ### Configure hosts file for local HTTPS Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Add an entry to your hosts file to map ebay-local.test to your local machine, enabling local HTTPS development. ```bash echo "127.0.0.1 ebay-local.test" | sudo tee -a /etc/hosts ``` -------------------------------- ### Access Token Refresh Response Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This is an example of the JSON response received after a successful access token refresh request. It contains the new access token and its expiration time. ```json { "access_token": "v^1.1#i ... AjRV4yNjA=", "expires_in": 7200, "token_type":"User Access Token" } ``` -------------------------------- ### Create eBay Return Policy via API Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/BUSINESS_POLICY_SETUP.md Use this bash command to create a return policy programmatically. Ensure you replace YOUR_ACCESS_TOKEN with your actual token. ```bash curl -X POST "https://api.ebay.com/sell/fulfillment/v1/policy/return" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Prefer: reply=minimal" \ -d '{ "name": "30-Day Returns", "returnsAcceptedOption": "Yes", "returnsWithinOption": "Days30", "returnShippingServicePaidBy": "Seller", "refundOption": "MoneyBack", "notReturnedHandlingFee": { "value": "0.00", "currencyCode": "USD" }, "description": "30-day money-back guarantee" }' ``` -------------------------------- ### List eBay Return Policies via API Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/BUSINESS_POLICY_SETUP.md Use this bash command to list all return policies associated with your account. Replace YOUR_ACCESS_TOKEN with your actual token. ```bash curl "https://api.ebay.com/sell/fulfillment/v1/policy/return" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### Authorization Code Grant Response Example Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This JSON object is returned by eBay upon a successful authorization code grant request, containing essential token information. ```json { "access_token": "v^1.1#i^1#p^3#r^1...XzMjRV4xMjg0", "expires_in": 7200, "refresh_token": "v^1.1#i^1#p^3#r^1...zYjRV4xMjg0", "refresh_token_expires_in": 47304000, "token_type": "User Access Token" } ``` -------------------------------- ### JSON Response for Application Access Token Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This is an example of the JSON response received after a successful client credentials grant request, containing the access token and its validity period. ```json { "access_token": "v^1.1#i^1#p^1#r^0#I^3#f^0#t^H4s ... wu67e3xAhskz4DAAA", "expires_in": 7200, "token_type": "Application Access Token" } ``` -------------------------------- ### Code Quality and Formatting Commands Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Commands for checking code quality and formatting. ```bash # Check code quality (type check + lint + format) npm run check ``` ```bash # Format code npm run format ``` -------------------------------- ### Testing Commands Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/AGENTS.md Commands for running unit tests and checking the health of a hosted server. ```bash pnpm test curl https://your-server.com/health ``` -------------------------------- ### FetchToken SOAP API Request Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt Example of a FetchToken SOAP API call including requester credentials in the SOAP header. This is used to retrieve user tokens after the sign-in and consent process. ```xml MyAppID MyDevID MyCertID ``` -------------------------------- ### Running Tests with npm Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/CONTRIBUTING.md Common npm commands for executing tests within the project. Use these to verify code changes and ensure project stability. ```bash # Run all tests npm test # Run with coverage npm run test:coverage # Run in watch mode npm run test:watch # Run with UI dashboard npm run test:ui ``` -------------------------------- ### Sync eBay OpenAPI Specs and Regenerate Types Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/README.md Run this command to download the latest eBay OpenAPI specifications and regenerate types. It's recommended to follow up with type checking and building. ```bash pnpm run sync && pnpm run typecheck && pnpm run build ``` -------------------------------- ### OAuth 2.1 Discovery Endpoint (Production) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md This GET request retrieves the OAuth 2.1 authorization server configuration for the production environment. It's used by clients to discover endpoints and capabilities. ```text GET https://your-server.com/production/.well-known/oauth-authorization-server ``` -------------------------------- ### List eBay Fulfillment Policies via API Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/BUSINESS_POLICY_SETUP.md Use this bash command to list all fulfillment policies associated with your account. Replace YOUR_ACCESS_TOKEN with your actual token. ```bash curl "https://api.ebay.com/sell/fulfillment/v1/policy/fulfillment" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### List eBay Payment Policies via API Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/BUSINESS_POLICY_SETUP.md Use this bash command to list all payment policies associated with your account. Replace YOUR_ACCESS_TOKEN with your actual token. ```bash curl "https://api.ebay.com/sell/fulfillment/v1/policy/payment" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### OAuth 2.1 Discovery Endpoint (Sandbox) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md This GET request retrieves the OAuth 2.1 authorization server configuration for the sandbox environment. It's used by clients to discover endpoints and capabilities. ```text GET https://your-server.com/sandbox/.well-known/oauth-authorization-server ``` -------------------------------- ### cURL Authorization Code Grant Request Example Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt This cURL command demonstrates how to construct the authorization code grant request. It includes the necessary headers and form-urlencoded data to obtain a User access token. ```curl curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=' \ -d 'grant_type=authorization_code&\ code=v%5E1.1%23i%5E1%23f% ... 3D%3D&\ redirect_uri=Davy_Developer-DavyDeve-DavysT-euiukxwt' ``` -------------------------------- ### Construct eBay Sign-in URL (Production) Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/oauth_custom.txt Use this URL to direct users to eBay for sign-in and consent. Ensure SessionID is URL-encoded. ```html https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName= RUName &SessID= SessionID ``` -------------------------------- ### Check Session Identity Source: https://github.com/mrnajiboy/ebay-mcp-remote-edition/blob/main/docs/auth/OAUTH_QUICK_REFERENCE.md This GET request retrieves information about the current user session, including user ID, environment, and token expiry details. It requires a valid session token in the Authorization header. ```text GET /whoami Authorization: Bearer ```