Architecture

The eBay MCP Server is built with a layered, modular architecture that prioritizes type safety, maintainability, and extensibility. This guide provides a deep understanding of how the server is structured and how its components interact.

Overview

The server implements the Model Context Protocol (MCP) specification to expose eBay’s Sell APIs as tools that AI assistants can use. It follows a clean architecture pattern with clear separation of concerns.

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client Layer                         │
│         (Claude Desktop, Cursor, etc.)                       │
└──────────────────────┬──────────────────────────────────────┘
                       │ STDIO Transport
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   MCP Server Layer                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Tool Registration & Execution                       │   │
│  │  (230+ eBay API Tools)                              │   │
│  └────────────┬────────────────────────────────────────┘   │
└───────────────┼──────────────────────────────────────────────┘
                │
┌───────────────▼──────────────────────────────────────────────┐
│                 Business Logic Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │   Account    │  │  Inventory   │  │   Fulfillment   │   │
│  │     APIs     │  │     APIs     │  │      APIs       │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │  Marketing   │  │  Analytics   │  │   Metadata      │   │
│  │     APIs     │  │     APIs     │  │      APIs       │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
└───────────────┬──────────────────────────────────────────────┘
                │
┌───────────────▼──────────────────────────────────────────────┐
│              Infrastructure Layer                             │
│  ┌──────────────────────┐  ┌──────────────────────────┐     │
│  │   HTTP Client        │  │   OAuth Manager          │     │
│  │   - Interceptors     │  │   - Token Refresh        │     │
│  │   - Rate Limiting    │  │   - Client Credentials   │     │
│  │   - Retry Logic      │  │   - User Tokens          │     │
│  └──────────────────────┘  └──────────────────────────┘     │
└──────────────────────────────────────────────────────────────┘
                       │
                       ▼
            eBay Sell API Endpoints

Core Layers

1. MCP Server Layer

The server layer implements the Model Context Protocol specification using the @modelcontextprotocol/sdk package. Key Components:

McpServer (src/index.ts:16) - Main MCP server instance that handles tool registration and execution
StdioServerTransport (src/index.ts:104) - STDIO transport for communication with MCP clients
Tool Registry - Dynamic registration of all 230+ eBay API tools

Responsibilities:

Accept incoming tool requests from MCP clients
Route requests to appropriate API implementations
Format responses according to MCP specification
Handle server lifecycle (startup, shutdown, error handling)

// Example: Server initialization
class EbayMcpServer {
  private server: McpServer;
  private api: EbaySellerApi;

  constructor() {
    this.server = new McpServer(mcpConfig);
    this.api = new EbaySellerApi(getEbayConfig());
    this.setupHandlers();
    this.setupErrorHandling();
  }

  private setupHandlers(): void {
    const tools = getToolDefinitions();

    for (const toolDef of tools) {
      this.server.registerTool(
        toolDef.name,
        {
          description: toolDef.description,
          inputSchema: toolDef.inputSchema,
        },
        async (args: Record<string, unknown>) => {
          const result = await executeTool(this.api, toolDef.name, args);
          return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
        }
      );
    }
  }
}

2. Business Logic Layer

The business logic layer contains domain-specific implementations of eBay APIs, organized by functional category. Directory Structure:

src/api/
├── account-management/
│   ├── fulfillment-policy.ts
│   ├── payment-policy.ts
│   ├── return-policy.ts
│   └── program.ts
├── listing-management/
│   ├── inventory.ts
│   ├── offer.ts
│   └── location.ts
├── order-management/
│   ├── fulfillment.ts
│   └── order.ts
├── marketing-and-promotions/
│   ├── campaign.ts
│   ├── ad.ts
│   └── promotion.ts
├── analytics-and-reporting/
│   └── analytics.ts
├── metadata/
│   └── metadata.ts
└── index.ts  # API facade

Key Principles:

Each API category is self-contained with clear boundaries
All methods use Zod schemas for input validation
OpenAPI-generated types ensure type safety
Consistent error handling across all APIs

3. Infrastructure Layer

The infrastructure layer provides cross-cutting concerns like HTTP communication, authentication, and rate limiting.

HTTP Client (src/api/client.ts)

The EbayApiClient class handles all HTTP communication with eBay APIs. Features:

Request/response interceptors for authentication
Automatic token refresh on 401 errors
Client-side rate limiting
Exponential backoff retry logic for server errors
Rate limit header tracking

class EbayApiClient {
  private httpClient: AxiosInstance;
  private authClient: EbayOAuthClient;
  private rateLimitTracker: RateLimitTracker;

  constructor(config: EbayConfig) {
    this.httpClient = axios.create({
      baseURL: this.baseUrl,
      timeout: 30000,
      headers: {
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
    });

    // Request interceptor: inject auth token + check rate limits
    this.httpClient.interceptors.request.use(async (config) => {
      if (!this.rateLimitTracker.canMakeRequest()) {
        throw new Error('Rate limit exceeded');
      }

      const token = await this.authClient.getAccessToken();
      config.headers.Authorization = `Bearer ${token}`;
      this.rateLimitTracker.recordRequest();

      return config;
    });

    // Response interceptor: handle errors + retry logic
    this.httpClient.interceptors.response.use(
      (response) => response,
      async (error) => {
        // Handle 401: refresh token and retry
        // Handle 429: rate limit exceeded
        // Handle 5xx: exponential backoff retry
      }
    );
  }
}

OAuth Client (src/auth/oauth.ts)

The EbayOAuthClient class manages OAuth 2.0 authentication with automatic token refresh. Features:

User token management with automatic refresh
Client credentials flow (app tokens) as fallback
Token expiry tracking
Environment variable integration

Token Priority:

Valid user access token (if available)
Refresh user token (if access token expired)
App access token from client credentials (fallback)

class EbayOAuthClient {
  private appAccessToken: string | null = null;
  private userTokens: StoredTokenData | null = null;

  async getAccessToken(): Promise<string> {
    // Priority 1: User token
    if (this.userTokens && !this.isUserAccessTokenExpired(this.userTokens)) {
      return this.userTokens.userAccessToken;
    }

    // Priority 2: Refresh user token
    if (this.userTokens && !this.isUserRefreshTokenExpired(this.userTokens)) {
      await this.refreshUserToken();
      return this.userTokens.userAccessToken;
    }

    // Priority 3: App access token (fallback)
    await this.getOrRefreshAppAccessToken();
    return this.appAccessToken!;
  }
}

Project Structure

ebay-mcp-server/
├── src/
│   ├── index.ts                # STDIO MCP server entry point
│   ├── server-http.ts          # HTTP MCP server (OAuth 2.1)
│   ├── api/                    # Business logic layer
│   │   ├── client.ts           # HTTP client with interceptors
│   │   ├── index.ts            # API facade (EbaySellerApi)
│   │   ├── account-management/
│   │   ├── listing-management/
│   │   ├── order-management/
│   │   ├── marketing-and-promotions/
│   │   ├── analytics-and-reporting/
│   │   └── metadata/
│   ├── auth/                   # OAuth & token management
│   │   └── oauth.ts            # OAuth client with auto-refresh
│   ├── tools/                  # MCP tool definitions
│   │   ├── definitions/        # Modular tool schemas by category
│   │   │   ├── account-tools.ts
│   │   │   ├── inventory-tools.ts
│   │   │   ├── order-tools.ts
│   │   │   ├── marketing-tools.ts
│   │   │   └── ...
│   │   ├── index.ts            # Tool registry & dispatcher
│   │   └── token-template.ts   # Token management tools
│   ├── types/                  # TypeScript types
│   │   ├── ebay.ts             # Core types
│   │   ├── ebay-enums.ts       # 33+ native TypeScript enums
│   │   └── sell_*.ts           # OpenAPI-generated types
│   ├── utils/                  # Zod validation schemas
│   │   ├── account-schemas.ts
│   │   ├── inventory-schemas.ts
│   │   └── ...
│   └── config/                 # Environment configuration
│       └── environment.ts
├── tests/                      # Test suite
│   ├── unit/                   # Unit tests
│   │   ├── api/
│   │   ├── auth/
│   │   └── tools/
│   ├── integration/            # Integration tests
│   │   └── mcp-server/
│   └── helpers/                # Test utilities
├── docs/                       # OpenAPI specifications
│   └── sell-apps/
├── scripts/                    # Build and setup scripts
├── build/                      # Compiled JavaScript
├── .env.example                # Environment template
├── package.json                # Dependencies & scripts
├── tsconfig.json               # TypeScript configuration
└── vitest.config.ts            # Test configuration

Design Patterns

1. Facade Pattern

The EbaySellerApi class (src/api/index.ts) acts as a facade, providing a unified interface to all eBay API categories.

export class EbaySellerApi {
  private client: EbayApiClient;

  // API categories
  public readonly account: {
    fulfillmentPolicy: EbayFulfillmentPolicyApi;
    paymentPolicy: EbayPaymentPolicyApi;
    returnPolicy: EbayReturnPolicyApi;
    program: EbayProgramApi;
  };

  public readonly inventory: EbayInventoryApi;
  public readonly fulfillment: EbayFulfillmentApi;
  public readonly marketing: EbayMarketingApi;
  public readonly analytics: EbayAnalyticsApi;

  constructor(config: EbayConfig) {
    this.client = new EbayApiClient(config);

    // Initialize all API categories
    this.account = {
      fulfillmentPolicy: new EbayFulfillmentPolicyApi(this.client),
      paymentPolicy: new EbayPaymentPolicyApi(this.client),
      // ...
    };
  }
}

Benefits:

Single entry point for all eBay APIs
Simplified dependency injection
Easy to mock for testing

2. Interceptor Pattern

Axios interceptors handle cross-cutting concerns like authentication and error handling. Request Interceptor:

Inject authentication token
Check rate limits before request
Record request timestamp

Response Interceptor:

Extract rate limit headers
Handle authentication errors (401)
Implement retry logic for server errors (5xx)
Transform eBay-specific errors

3. Strategy Pattern

The OAuth client uses a strategy pattern for token management, automatically selecting the best authentication method. Strategies:

User Token Strategy - Use valid user access token
Token Refresh Strategy - Refresh expired user token
Client Credentials Strategy - Fallback to app token

4. Repository Pattern

Each API category acts as a repository for its domain entities.

class EbayInventoryApi {
  constructor(private client: EbayApiClient) {}

  async getInventoryItem(sku: string): Promise<InventoryItem> {
    return this.client.get(`/sell/inventory/v1/inventory_item/${sku}`);
  }

  async createOrReplaceInventoryItem(
    sku: string,
    item: InventoryItemInput
  ): Promise<void> {
    return this.client.put(`/sell/inventory/v1/inventory_item/${sku}`, item);
  }
}

Type Safety

The server implements multiple layers of type safety:

1. OpenAPI-Generated Types

All eBay API request/response types are generated from OpenAPI specifications.

npm run generate:types

This generates TypeScript types in src/types/sell_*.ts files.

2. Native TypeScript Enums

33+ native TypeScript enums provide compile-time type checking for eBay constants.

export enum MarketplaceId {
  EBAY_US = 'EBAY_US',
  EBAY_GB = 'EBAY_GB',
  EBAY_DE = 'EBAY_DE',
  // ... 20+ more marketplaces
}

export enum ListingDuration {
  DAYS_1 = 'DAYS_1',
  DAYS_3 = 'DAYS_3',
  DAYS_5 = 'DAYS_5',
  DAYS_7 = 'DAYS_7',
  DAYS_10 = 'DAYS_10',
  DAYS_30 = 'DAYS_30',
  GTC = 'GTC', // Good 'Til Cancelled
}

3. Zod Runtime Validation

All external inputs (tool arguments, environment variables) are validated using Zod schemas.

const createOfferSchema = z.object({
  sku: z.string().min(1).describe('The seller-defined SKU'),
  marketplaceId: z.nativeEnum(MarketplaceId),
  format: z.nativeEnum(FormatType),
  price: z.object({
    value: z.string().regex(/^\d+(\.\d{1,2})?$/),
    currency: z.string().length(3),
  }),
});

Benefits:

Catch invalid inputs at runtime
Automatic type inference
Clear error messages
Self-documenting code

Data Flow

Tool Execution Flow

1. MCP Client sends tool request
   ↓
2. MCP Server validates tool name
   ↓
3. Tool executor looks up tool definition
   ↓
4. Zod schema validates input arguments
   ↓
5. Business logic method is called
   ↓
6. HTTP Client checks rate limits
   ↓
7. OAuth Client provides access token
   ↓
8. HTTP request sent to eBay API
   ↓
9. Response interceptor handles errors
   ↓
10. Response data returned to MCP Client

Authentication Flow

1. Client makes API request
   ↓
2. Request interceptor triggered
   ↓
3. OAuth Client checks token status
   ↓
4. If expired → Refresh token
   ↓
5. If refresh fails → Get app token
   ↓
6. Inject token in Authorization header
   ↓
7. If 401 response → Retry with refreshed token

Configuration Management

The server uses a centralized configuration system in src/config/environment.ts.

export interface EbayConfig {
  clientId: string;
  clientSecret: string;
  environment: 'sandbox' | 'production';
  redirectUri: string;
  scopes?: string[];
}

export function getEbayConfig(): EbayConfig {
  const validation = validateEnvironmentConfig();

  if (!validation.isValid) {
    throw new Error('Invalid environment configuration');
  }

  return {
    clientId: process.env.EBAY_CLIENT_ID!,
    clientSecret: process.env.EBAY_CLIENT_SECRET!,
    environment: (process.env.EBAY_ENVIRONMENT || 'sandbox') as 'sandbox' | 'production',
    redirectUri: process.env.EBAY_REDIRECT_URI!,
    scopes: process.env.EBAY_SCOPES?.split(' '),
  };
}

Environment Variables:

EBAY_CLIENT_ID - eBay application Client ID
EBAY_CLIENT_SECRET - eBay application Client Secret
EBAY_ENVIRONMENT - sandbox or production
EBAY_REDIRECT_URI - OAuth redirect URI (RuName)
EBAY_USER_ACCESS_TOKEN - Optional user access token
EBAY_USER_REFRESH_TOKEN - Optional user refresh token

Extensibility

The architecture is designed for easy extensibility:

Adding New eBay APIs

Create API implementation in appropriate category directory
Define Zod schemas for input validation
Add TypeScript types (or generate from OpenAPI)
Create tool definitions in src/tools/definitions/
Register tools in tool registry
Write tests for new functionality

Adding New Tool Categories

// 1. Create tool definitions
export const newCategoryTools: ToolDefinition[] = [
  {
    name: 'ebay_new_operation',
    description: 'Performs new operation',
    inputSchema: newOperationSchema,
    handler: 'newCategory.operation',
  },
];

// 2. Add to tool registry
export function getToolDefinitions(): ToolDefinition[] {
  return [
    ...accountTools,
    ...inventoryTools,
    ...newCategoryTools,  // Add new tools
  ];
}

Performance Considerations

Rate Limit Management

The server implements client-side rate limiting to prevent exceeding eBay’s API limits:

class RateLimitTracker {
  private requestTimestamps: number[] = [];
  private readonly windowMs = 60000; // 1 minute window
  private readonly maxRequests = 5000; // Conservative limit

  canMakeRequest(): boolean {
    const now = Date.now();
    this.requestTimestamps = this.requestTimestamps.filter(
      timestamp => now - timestamp < this.windowMs
    );
    return this.requestTimestamps.length < this.maxRequests;
  }
}

Connection Pooling

Axios automatically manages HTTP connection pooling for improved performance.

Caching

Currently, the server does not implement response caching, as eBay data can change frequently. Consider implementing caching for specific use cases:

Metadata API responses (category trees, policies)
Fulfillment/payment/return policies
Rate limit headers

Security

Credential Management

Credentials loaded from environment variables only
Never logged or exposed in error messages
Token storage in memory only (not persisted to disk)

Input Validation

All inputs validated with Zod schemas
SQL injection not applicable (REST API client)
No user-generated code execution

HTTPS Only

All communication with eBay APIs uses HTTPS.

Monitoring and Observability

Logging

The server uses console.error for logging to stderr:

Server startup/shutdown events
Authentication events (token refresh, expiry)
Rate limit warnings
Error conditions

Error Context

All errors include context for debugging:

Original eBay API error messages
Suggested remediation steps
Request/response details (in development)

Next Steps

Error Handling

Learn how errors are handled and recovered

Rate Limits

Understand rate limiting strategies

Testing

Explore the testing strategy and tools

Contributing

Contribute to the project

​Architecture

​Overview

​Core Layers

​1. MCP Server Layer

​2. Business Logic Layer

​3. Infrastructure Layer

​HTTP Client (src/api/client.ts)

​OAuth Client (src/auth/oauth.ts)

​Project Structure

​Design Patterns

​1. Facade Pattern

​2. Interceptor Pattern

​3. Strategy Pattern

​4. Repository Pattern

​Type Safety

​1. OpenAPI-Generated Types

​2. Native TypeScript Enums

​3. Zod Runtime Validation

​Data Flow

​Tool Execution Flow

​Authentication Flow

​Configuration Management

​Extensibility

​Adding New eBay APIs

​Adding New Tool Categories

​Performance Considerations

​Rate Limit Management

​Connection Pooling

​Caching

​Security

​Credential Management

​Input Validation

​HTTPS Only

​Monitoring and Observability

​Logging

​Error Context

​Next Steps