ebay-mcp 1.4.3

package/build/server-http.d.ts

@@ -0,0 +1,11 @@
+/**
+ * eBay API MCP Server with HTTP Transport and OAuth 2.1 Authorization
+ *
+ *
+ * This server implements:
+ * - HTTP transport using Express
+ * - OAuth 2.1 authorization (RFC 8414, RFC 9728)
+ * - Bearer token authentication (RFC 6750)
+ * - Token verification via introspection (RFC 7662) or JWT validation
+ */
+export {};

package/build/server-http.js

@@ -0,0 +1,361 @@
+/**
+ * eBay API MCP Server with HTTP Transport and OAuth 2.1 Authorization
+ *
+ *
+ * This server implements:
+ * - HTTP transport using Express
+ * - OAuth 2.1 authorization (RFC 8414, RFC 9728)
+ * - Bearer token authentication (RFC 6750)
+ * - Token verification via introspection (RFC 7662) or JWT validation
+ */
+import express from 'express';
+import helmet from 'helmet';
+import cors from 'cors';
+import { randomUUID } from 'crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { EbaySellerApi } from './api/index.js';
+import { getEbayConfig, getDefaultScopes, validateEnvironmentConfig, } from './config/environment.js';
+import { getToolDefinitions, executeTool } from './tools/index.js';
+import { TokenVerifier } from './auth/token-verifier.js';
+import { createBearerAuthMiddleware } from './auth/oauth-middleware.js';
+import { createMetadataRouter, getProtectedResourceMetadataUrl } from './auth/oauth-metadata.js';
+// Configuration from environment
+const CONFIG = {
+    // Server settings
+    host: process.env.MCP_HOST || 'localhost',
+    port: Number(process.env.MCP_PORT) || 3000,
+    // OAuth settings
+    oauth: {
+        // Authorization server metadata URL or custom metadata
+        authServerUrl: process.env.OAUTH_AUTH_SERVER_URL ?? 'http://localhost:8080/realms/master',
+        // Client credentials for token introspection
+        clientId: process.env.OAUTH_CLIENT_ID,
+        clientSecret: process.env.OAUTH_CLIENT_SECRET,
+        // Scopes required for this server
+        requiredScopes: (process.env.OAUTH_REQUIRED_SCOPES || 'mcp:tools')
+            .split(',')
+            .map((s) => s.trim()),
+        // Whether to use token introspection (true) or JWT validation (false)
+        useIntrospection: process.env.OAUTH_USE_INTROSPECTION !== 'false',
+    },
+    // Whether OAuth is enabled (disable for local development)
+    authEnabled: process.env.OAUTH_ENABLED !== 'false',
+};
+/**
+ * Create OAuth server metadata URL
+ */
+function getAuthServerMetadataUrl() {
+    // Support both OIDC Discovery and OAuth Server Metadata
+    const baseUrl = CONFIG.oauth.authServerUrl;
+    // Try OIDC Discovery first
+    if (baseUrl.includes('/realms/')) {
+        // Keycloak-style URL
+        return `${baseUrl}/.well-known/openid-configuration`;
+    }
+    // Fall back to OAuth 2.0 Authorization Server Metadata
+    return `${baseUrl}/.well-known/oauth-authorization-server`;
+}
+/**
+ * Create Express app with OAuth support
+ */
+async function createApp() {
+    const app = express();
+    // Enable CORS
+    app.use(cors({
+        // TODO: Restrict origin to known clients in production
+        // For development, allow all origins
+        origin: '*',
+        exposedHeaders: ['Mcp-Session-Id'],
+    }));
+    // Parse JSON bodies
+    app.use(express.json());
+    // Add security best practices (disable X-Powered-By header)
+    app.use(helmet({ xPoweredBy: false }));
+    // Request logging
+    app.use((req, res, next) => {
+        const start = Date.now();
+        res.on('finish', () => {
+            const duration = Date.now() - start;
+            console.log(`${req.method} ${req.path} -> ${res.statusCode} (${duration}ms)`);
+        });
+        next();
+    });
+    // Server URL
+    const serverUrl = `http://${CONFIG.host}:${CONFIG.port}`;
+    // Get eBay configuration for metadata
+    const ebayConfig = getEbayConfig();
+    // Add OAuth metadata endpoints
+    const metadataRouter = createMetadataRouter({
+        resourceServerUrl: serverUrl,
+        authServerMetadata: getAuthServerMetadataUrl(),
+        scopesSupported: CONFIG.oauth.requiredScopes,
+        resourceDocumentation: 'https://github.com/YosefHayim/ebay-mcp',
+        resourceName: 'eBay API MCP Server',
+        ebayEnvironment: ebayConfig.environment,
+        ebayScopes: getDefaultScopes(ebayConfig.environment),
+    });
+    app.use(metadataRouter);
+    // Health check endpoint (no auth required)
+    app.get('/health', (req, res) => {
+        res.json({
+            status: 'healthy',
+            timestamp: new Date().toISOString(),
+            oauth_enabled: CONFIG.authEnabled,
+        });
+    });
+    // Initialize token verifier if OAuth is enabled
+    let tokenVerifier;
+    let authMiddleware;
+    if (CONFIG.authEnabled) {
+        console.log('Initializing OAuth token verifier...');
+        tokenVerifier = new TokenVerifier({
+            authServerMetadata: getAuthServerMetadataUrl(),
+            clientId: CONFIG.oauth.clientId,
+            clientSecret: CONFIG.oauth.clientSecret,
+            expectedAudience: serverUrl,
+            requiredScopes: CONFIG.oauth.requiredScopes,
+            useIntrospection: CONFIG.oauth.useIntrospection,
+        });
+        try {
+            await tokenVerifier.initialize();
+            console.log('Token verifier initialized');
+            authMiddleware = createBearerAuthMiddleware({
+                verifier: tokenVerifier,
+                resourceMetadataUrl: getProtectedResourceMetadataUrl(serverUrl),
+                realm: 'ebay-mcp',
+            });
+        }
+        catch (error) {
+            console.error('Failed to initialize token verifier:', error);
+            throw error;
+        }
+    }
+    else {
+        console.error('OAuth is disabled. Server running in unauthenticated mode.');
+    }
+    // MCP session storage
+    const transports = new Map();
+    /**
+     * Create a new MCP server instance
+     */
+    function createMcpServer() {
+        const ebayConfig = getEbayConfig();
+        const api = new EbaySellerApi(ebayConfig);
+        const server = new McpServer({
+            name: 'ebay-mcp',
+            version: '1.4.0',
+            title: 'eBay API MCP Server',
+            websiteUrl: 'https://coming-soon.com',
+            icons: [
+                {
+                    src: './icons/16x16.png',
+                    mimeType: 'image/png',
+                    sizes: ['16x16'],
+                },
+                {
+                    src: './icons/32x32.png',
+                    mimeType: 'image/png',
+                    sizes: ['32x32'],
+                },
+                {
+                    src: './icons/48x48.png',
+                    mimeType: 'image/png',
+                    sizes: ['48x48'],
+                },
+                {
+                    src: './icons/128x128.png',
+                    mimeType: 'image/png',
+                    sizes: ['128x128'],
+                },
+                {
+                    src: './icons/256x256.png',
+                    mimeType: 'image/png',
+                    sizes: ['256x256'],
+                },
+                {
+                    src: './icons/512x512.png',
+                    mimeType: 'image/png',
+                    sizes: ['512x512'],
+                },
+                {
+                    src: './icons/1024x1024.png',
+                    mimeType: 'image/png',
+                    sizes: ['1024x1024'],
+                }
+            ],
+        });
+        // Register tools
+        const tools = getToolDefinitions();
+        for (const toolDef of tools) {
+            server.registerTool(toolDef.name, {
+                description: toolDef.description,
+                // ToolDefinition uses Zod schemas internally, but MCP SDK expects Zod schemas
+                // This is a safe cast since both are Zod-based schema types
+                inputSchema: toolDef.inputSchema,
+            }, async (args) => {
+                try {
+                    const result = await executeTool(api, toolDef.name, args);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({ error: errorMessage }, null, 2),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            });
+        }
+        return server;
+    }
+    /**
+     * MCP POST handler
+     */
+    const mcpPostHandler = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        let transport;
+        if (sessionId && transports.has(sessionId)) {
+            transport = transports.get(sessionId);
+        }
+        else if (!sessionId && isInitializeRequest(req.body)) {
+            // Create new session
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sessionId) => {
+                    transports.set(sessionId, transport);
+                    console.log(`New MCP session initialized: ${sessionId}`);
+                },
+            });
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    transports.delete(transport.sessionId);
+                    console.log(`MCP session closed: ${transport.sessionId}`);
+                }
+            };
+            const server = createMcpServer();
+            await server.connect(transport);
+        }
+        else {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Bad Request: No valid session ID provided',
+                },
+                id: null,
+            });
+            return;
+        }
+        await transport.handleRequest(req, res, req.body);
+    };
+    /**
+     * MCP session request handler (GET/DELETE)
+     */
+    const handleSessionRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (!sessionId || !transports.has(sessionId)) {
+            res.status(400).json({
+                error: 'invalid_session',
+                error_description: 'Invalid or missing session ID',
+            });
+            return;
+        }
+        const transport = transports.get(sessionId);
+        await transport.handleRequest(req, res);
+    };
+    // Apply auth middleware to MCP endpoints if enabled
+    const mcpMiddleware = authMiddleware ? [authMiddleware, mcpPostHandler] : [mcpPostHandler];
+    const sessionMiddleware = authMiddleware
+        ? [authMiddleware, handleSessionRequest]
+        : [handleSessionRequest];
+    // MCP endpoints
+    app.post('/', ...mcpMiddleware);
+    app.get('/', ...sessionMiddleware);
+    app.delete('/', ...sessionMiddleware);
+    return app;
+}
+/**
+ * Start the server
+ */
+async function main() {
+    try {
+        console.log('Starting eBay API MCP Server (HTTP + OAuth)...');
+        console.log();
+        // Validate environment configuration
+        const validation = validateEnvironmentConfig();
+        // Display warnings
+        if (validation.warnings.length > 0) {
+            console.log('Environment Configuration Warnings:');
+            validation.warnings.forEach((warning) => {
+                console.log(`  • ${warning}`);
+            });
+            console.log();
+        }
+        // Display errors and exit if configuration is invalid
+        if (!validation.isValid) {
+            console.error('Environment Configuration Errors:');
+            validation.errors.forEach((error) => {
+                console.error(`  • ${error}`);
+            });
+            console.error('\nPlease fix the configuration errors and restart the server.\n');
+            process.exit(1);
+        }
+        console.log('Configuration:');
+        console.log(`Host: ${CONFIG.host}`);
+        console.log(`Port: ${CONFIG.port}`);
+        console.log(`OAuth Enabled: ${CONFIG.authEnabled}`);
+        if (CONFIG.authEnabled) {
+            console.log(`Auth Server: ${CONFIG.oauth.authServerUrl}`);
+            console.log(`Required Scopes: ${CONFIG.oauth.requiredScopes.join(', ')}`);
+            console.log(`Verification Method: ${CONFIG.oauth.useIntrospection ? 'Introspection' : 'JWT'}`);
+        }
+        const app = await createApp();
+        const server = app.listen(CONFIG.port, CONFIG.host, () => {
+            const serverUrl = `http://${CONFIG.host}:${CONFIG.port}`;
+            console.log('Server is running!');
+            console.log();
+            console.log(`MCP endpoint: ${serverUrl}/`);
+            console.log(`Protected Resource Metadata: ${serverUrl}/.well-known/oauth-protected-resource`);
+            console.log(`Health check: ${serverUrl}/health`);
+            console.log();
+            if (CONFIG.authEnabled) {
+                console.log('Authorization is ENABLED');
+                console.log('Clients must provide valid Bearer tokens to access MCP endpoints');
+            }
+            else {
+                console.log('Authorization is DISABLED');
+                console.log('Set OAUTH_ENABLED=true to enable OAuth protection');
+            }
+        });
+        // Graceful shutdown
+        process.on('SIGINT', () => {
+            console.log('\n Shutting down...');
+            server.close(() => {
+                console.log('✓ Server closed');
+                process.exit(0);
+            });
+        });
+    }
+    catch (error) {
+        console.error('Fatal error starting server:', error);
+        process.exit(1);
+    }
+}
+// Start server if run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    await main();
+}

package/build/tools/definitions/account-with-schemas.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Example: Account Management Tools with Full Schema Integration
+ *
+ * This file demonstrates how to integrate the new Zod schemas
+ * for both input and output validation with MCP tools.
+ */
+import type { ToolDefinition } from './account.js';
+/**
+ * Account Management Tools with Output Schema Validation
+ *
+ * These tool definitions include both inputSchema and outputSchema
+ * for complete request/response validation.
+ */
+export declare const accountToolsWithSchemas: ToolDefinition[];
+/**
+ * Example: Using the schemas for runtime validation
+ *
+ * ```typescript
+ * import { accountToolsWithSchemas } from '../../tools/definitions/account-with-schemas';
+ * import { EbaySellerApi } from '../../api';
+ *
+ * async function validateToolExecution() {
+ *   const api = new EbaySellerApi();
+ *   const tool = accountToolsWithSchemas.find(t => t.name === 'ebay_get_fulfillment_policies');
+ *
+ *   // Validate input
+ *   const input = { marketplaceId: 'EBAY_US' };
+ *   const validatedInput = tool.inputSchema.parse(input); // Throws if invalid
+ *
+ *   // Execute API call
+ *   const response = await api.account.getFulfillmentPolicies(validatedInput.marketplaceId);
+ *
+ *   // Validate output
+ *   const validatedOutput = tool.outputSchema?.parse(response); // Throws if invalid
+ *
+ *   return validatedOutput;
+ * }
+ * ```
+ */

package/build/tools/definitions/account-with-schemas.js

@@ -0,0 +1,170 @@
+/**
+ * Example: Account Management Tools with Full Schema Integration
+ *
+ * This file demonstrates how to integrate the new Zod schemas
+ * for both input and output validation with MCP tools.
+ */
+import { MarketplaceId } from '../../types/ebay-enums.js';
+import { z } from 'zod';
+// Import schemas from the new schemas folder
+import { getCustomPoliciesInputSchema, getFulfillmentPoliciesInputSchema, createFulfillmentPolicyInputSchema, getPaymentPoliciesInputSchema, createPaymentPolicyInputSchema, getReturnPoliciesInputSchema, createReturnPolicyInputSchema, } from '../../schemas/account-management/account.js';
+/**
+ * Account Management Tools with Output Schema Validation
+ *
+ * These tool definitions include both inputSchema and outputSchema
+ * for complete request/response validation.
+ */
+export const accountToolsWithSchemas = [
+    // ============================================================================
+    // Custom Policies
+    // ============================================================================
+    {
+        name: 'ebay_get_custom_policies',
+        description: 'Retrieve custom policies defined for the seller account',
+        inputSchema: {
+            policyTypes: getCustomPoliciesInputSchema.shape.policyTypes,
+        },
+    },
+    // ============================================================================
+    // Fulfillment Policies
+    // ============================================================================
+    {
+        name: 'ebay_get_fulfillment_policies',
+        description: 'Get fulfillment policies for the seller.\n\nRequired OAuth Scope: sell.account.readonly or sell.account\nMinimum Scope: https://api.ebay.com/oauth/api_scope/sell.account.readonly',
+        inputSchema: {
+            marketplaceId: getFulfillmentPoliciesInputSchema.shape.marketplaceId,
+        },
+    },
+    {
+        name: 'ebay_create_fulfillment_policy',
+        description: 'Create a new fulfillment policy.\n\nRequired OAuth Scope: sell.account\nMinimum Scope: https://api.ebay.com/oauth/api_scope/sell.account',
+        inputSchema: {
+            policy: createFulfillmentPolicyInputSchema.shape.policy,
+        },
+    },
+    {
+        name: 'ebay_get_fulfillment_policy',
+        description: 'Get a specific fulfillment policy by ID',
+        inputSchema: {
+            fulfillmentPolicyId: z.string().describe('The fulfillment policy ID'),
+        },
+    },
+    {
+        name: 'ebay_get_fulfillment_policy_by_name',
+        description: 'Get a fulfillment policy by name',
+        inputSchema: {
+            marketplaceId: z.nativeEnum(MarketplaceId).describe('eBay marketplace ID'),
+            name: z.string().describe('Policy name'),
+        },
+    },
+    {
+        name: 'ebay_update_fulfillment_policy',
+        description: 'Update an existing fulfillment policy',
+        inputSchema: {
+            fulfillmentPolicyId: z.string().describe('The fulfillment policy ID'),
+            policy: createFulfillmentPolicyInputSchema.shape.policy,
+        },
+    },
+    {
+        name: 'ebay_delete_fulfillment_policy',
+        description: 'Delete a fulfillment policy',
+        inputSchema: {
+            fulfillmentPolicyId: z.string().describe('The fulfillment policy ID'),
+        },
+    },
+    // ============================================================================
+    // Payment Policies
+    // ============================================================================
+    {
+        name: 'ebay_get_payment_policies',
+        description: 'Get payment policies for the seller',
+        inputSchema: {
+            marketplaceId: getPaymentPoliciesInputSchema.shape.marketplaceId,
+        },
+    },
+    {
+        name: 'ebay_create_payment_policy',
+        description: 'Create a new payment policy',
+        inputSchema: {
+            policy: createPaymentPolicyInputSchema.shape.policy,
+        },
+    },
+    // ============================================================================
+    // Return Policies
+    // ============================================================================
+    {
+        name: 'ebay_get_return_policies',
+        description: 'Get return policies for the seller',
+        inputSchema: {
+            marketplaceId: getReturnPoliciesInputSchema.shape.marketplaceId,
+        },
+    },
+    {
+        name: 'ebay_create_return_policy',
+        description: 'Create a new return policy',
+        inputSchema: {
+            policy: createReturnPolicyInputSchema.shape.policy,
+        },
+    },
+    // ============================================================================
+    // Sales Tax
+    // ============================================================================
+    {
+        name: 'ebay_get_sales_taxes',
+        description: 'Get all sales tax tables for a country',
+        inputSchema: {
+            countryCode: z.string().describe('Required: Two-letter ISO 3166-1 country code'),
+        },
+    },
+    {
+        name: 'ebay_get_sales_tax',
+        description: 'Get sales tax table for a jurisdiction',
+        inputSchema: {
+            countryCode: z.string().describe('Two-letter ISO 3166 country code'),
+            jurisdictionId: z.string().describe('Tax jurisdiction ID'),
+        },
+    },
+    // ============================================================================
+    // KYC & Programs
+    // ============================================================================
+    {
+        name: 'ebay_get_kyc',
+        description: 'Get seller KYC (Know Your Customer) status',
+        inputSchema: {},
+    },
+    {
+        name: 'ebay_get_opted_in_programs',
+        description: 'Get seller programs the account is opted into',
+        inputSchema: {},
+    },
+    {
+        name: 'ebay_get_privileges',
+        description: "Get seller's current set of privileges, including whether or not the seller's eBay registration has been completed, as well as the details of their site-wide sellingLimit (the maximum dollar value and quantity of items a seller can sell per day).\n\nRequired OAuth Scope: sell.account.readonly or sell.account",
+        inputSchema: {},
+    },
+];
+/**
+ * Example: Using the schemas for runtime validation
+ *
+ * ```typescript
+ * import { accountToolsWithSchemas } from '../../tools/definitions/account-with-schemas';
+ * import { EbaySellerApi } from '../../api';
+ *
+ * async function validateToolExecution() {
+ *   const api = new EbaySellerApi();
+ *   const tool = accountToolsWithSchemas.find(t => t.name === 'ebay_get_fulfillment_policies');
+ *
+ *   // Validate input
+ *   const input = { marketplaceId: 'EBAY_US' };
+ *   const validatedInput = tool.inputSchema.parse(input); // Throws if invalid
+ *
+ *   // Execute API call
+ *   const response = await api.account.getFulfillmentPolicies(validatedInput.marketplaceId);
+ *
+ *   // Validate output
+ *   const validatedOutput = tool.outputSchema?.parse(response); // Throws if invalid
+ *
+ *   return validatedOutput;
+ * }
+ * ```
+ */

package/build/tools/definitions/account.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { OutputArgs, ToolAnnotations } from '../tool-definitions.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, z.ZodTypeAny>;
+    title?: string;
+    outputSchema?: OutputArgs;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+}
+export declare const accountTools: ToolDefinition[];