ebay-mcp-remote-edition 3.1.2 → 3.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Kenyatta Naji Johnson-Adams
+Copyright (c) 2026 Kenyatta Naji Johnson-Adams
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -154,10 +154,10 @@ For hosted deployments, register your server's public HTTPS URL instead (e.g. `h
 
 ### Install
 
-**Option A — npm global install (no build step):**
+**Option A — pnpm global install (no build step):**
 
 ```bash
-npm install -g ebay-mcp-remote-edition
+pnpm install -g ebay-mcp-remote-edition
 ```
 
 **Option B — clone and build (for contributors or self-hosting):**

package/build/auth/multi-user-store.js

@@ -44,7 +44,7 @@ export class MultiUserAuthStore {
      * `lastUsedAt` once per TOUCH_THROTTLE_MS (default: 1 hour).
      */
     sessionTouchCache = new Map();
-    static TOUCH_THROTTLE_MS = 60 * 60 * 1_000; // 1 hour
+    static touchThrottleMs = 60 * 60 * 1_000; // 1 hour
     stateKey(state) {
         return `oauth_state:${state}`;
     }
@@ -67,6 +67,12 @@ export class MultiUserAuthStore {
         await this.kv.put(this.stateKey(state), record, OAUTH_STATE_TTL_S);
         return record;
     }
+    async getOAuthState(state) {
+        return await this.kv.get(this.stateKey(state));
+    }
+    async deleteOAuthState(state) {
+        await this.kv.delete(this.stateKey(state));
+    }
     async consumeOAuthState(state) {
         const key = this.stateKey(state);
         const record = await this.kv.get(key);
@@ -122,7 +128,7 @@ export class MultiUserAuthStore {
         // Skip the KV write entirely if we touched this session recently.
         // The in-memory cache in CloudflareKVStore already keeps reads free,
         // so the only cost we're avoiding here is the unnecessary KV PUT.
-        if (lastTouched !== undefined && now - lastTouched < MultiUserAuthStore.TOUCH_THROTTLE_MS) {
+        if (lastTouched !== undefined && now - lastTouched < MultiUserAuthStore.touchThrottleMs) {
             return;
         }
         const record = await this.getSession(sessionToken);

package/build/auth/oauth.js

@@ -1,5 +1,5 @@
 import axios from 'axios';
-import { getBaseUrl } from '../config/environment.js';
+import { getOAuthTokenBaseUrl } from '../config/environment.js';
 import { MultiUserAuthStore } from '../auth/multi-user-store.js';
 export class EbayOAuthClient {
     config;
@@ -8,15 +8,20 @@ export class EbayOAuthClient {
     appAccessTokenExpiry = 0;
     userTokens = null;
     authStore = new MultiUserAuthStore();
+    authSource = null;
     constructor(config, context) {
         this.config = config;
         this.context = context;
     }
+    getTokenEndpoint() {
+        return `${getOAuthTokenBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+    }
     async initialize() {
         if (this.context?.userId && this.context.environment) {
             const stored = await this.authStore.getUserTokens(this.context.userId, this.context.environment);
             if (stored?.tokenData) {
                 this.userTokens = stored.tokenData;
+                this.authSource = 'stored_user_tokens';
                 return;
             }
         }
@@ -24,7 +29,7 @@ export class EbayOAuthClient {
         const envRefreshToken = process.env.EBAY_USER_REFRESH_TOKEN;
         if (envRefreshToken) {
             try {
-                const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+                const authUrl = this.getTokenEndpoint();
                 const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
                 const response = await axios.post(authUrl, new URLSearchParams({
                     grant_type: 'refresh_token',
@@ -50,6 +55,7 @@ export class EbayOAuthClient {
                         : now + 18 * 30 * 24 * 60 * 60 * 1000,
                     scope: tokenData.scope,
                 };
+                this.authSource = 'env_refresh_token_fallback';
             }
             catch {
                 // If refresh fails, leave userTokens as null
@@ -99,13 +105,14 @@ export class EbayOAuthClient {
             userAccessTokenExpiry: accessTokenExpiry ?? now + 7200 * 1000,
             userRefreshTokenExpiry: refreshTokenExpiry ?? now + 18 * 30 * 24 * 60 * 60 * 1000,
         };
+        this.authSource = 'manual_set_user_tokens';
         await this.persistUserTokens();
     }
     async getOrRefreshAppAccessToken() {
         if (this.appAccessToken && Date.now() < this.appAccessTokenExpiry) {
             return this.appAccessToken;
         }
-        const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const authUrl = this.getTokenEndpoint();
         const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
         const response = await axios.post(authUrl, new URLSearchParams({
             grant_type: 'client_credentials',
@@ -124,7 +131,7 @@ export class EbayOAuthClient {
         if (!this.config.redirectUri) {
             throw new Error('Redirect URI is required for authorization code exchange');
         }
-        const tokenUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const tokenUrl = this.getTokenEndpoint();
         const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
         try {
             const response = await axios.post(tokenUrl, new URLSearchParams({
@@ -150,6 +157,7 @@ export class EbayOAuthClient {
                 userRefreshTokenExpiry: now + tokenData.refresh_token_expires_in * 1000,
                 scope: tokenData.scope,
             };
+            this.authSource = 'authorization_code_exchange';
             await this.persistUserTokens();
             return tokenData;
         }
@@ -170,7 +178,7 @@ export class EbayOAuthClient {
         if (!this.userTokens) {
             throw new Error('No user tokens available to refresh');
         }
-        const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const authUrl = this.getTokenEndpoint();
         const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
         const response = await axios.post(authUrl, new URLSearchParams({
             grant_type: 'refresh_token',
@@ -198,6 +206,24 @@ export class EbayOAuthClient {
         };
         await this.persistUserTokens();
     }
+    getAuthDebugInfo() {
+        return {
+            tokenEndpoint: this.getTokenEndpoint(),
+            environment: this.config.environment,
+            hasClientId: this.config.clientId.trim().length > 0,
+            hasClientSecret: this.config.clientSecret.trim().length > 0,
+            hasRefreshToken: !!this.userTokens?.userRefreshToken,
+            hasAccessToken: !!this.userTokens?.userAccessToken,
+            hasRedirectUri: !!this.config.redirectUri,
+            ...(this.userTokens?.userRefreshTokenExpiry
+                ? { refreshTokenExpiry: this.userTokens.userRefreshTokenExpiry }
+                : {}),
+            ...(this.userTokens?.userAccessTokenExpiry
+                ? { accessTokenExpiry: this.userTokens.userAccessTokenExpiry }
+                : {}),
+            ...(this.authSource ? { source: this.authSource } : {}),
+        };
+    }
     isAuthenticated() {
         if (this.userTokens && !this.isUserAccessTokenExpired(this.userTokens)) {
             return true;

package/build/config/environment.js

@@ -289,9 +289,19 @@ export function getEbayConfig(environmentOverride) {
         appAccessToken: process.env.EBAY_APP_ACCESS_TOKEN ?? '',
     };
 }
+export function getValidationRunnerUserId(environment) {
+    const envSpecific = environment === 'production'
+        ? process.env.VALIDATION_RUNNER_USER_ID_PRODUCTION
+        : process.env.VALIDATION_RUNNER_USER_ID_SANDBOX;
+    const resolved = (envSpecific ?? process.env.VALIDATION_RUNNER_USER_ID ?? '').trim();
+    return resolved || null;
+}
 export function getBaseUrl(environment) {
     return environment === 'production' ? 'https://api.ebay.com' : 'https://api.sandbox.ebay.com';
 }
+export function getOAuthTokenBaseUrl(environment) {
+    return environment === 'production' ? 'https://api.ebay.com' : 'https://api.sandbox.ebay.com';
+}
 export function getIdentityBaseUrl(environment) {
     return environment === 'production' ? 'https://apiz.ebay.com' : 'https://apiz.sandbox.ebay.com';
 }

package/build/scripts/{run-with-local-env.js → env-check.js}

@@ -11,7 +11,7 @@ function isHostedEnvironment() {
 function main() {
     const args = process.argv.slice(2);
     if (args.length === 0) {
-        throw new Error('Usage: tsx src/scripts/run-with-local-env.ts <command> [args...]');
+        throw new Error('Usage: tsx src/scripts/env-check.ts <command> [args...]');
     }
     const hosted = isHostedEnvironment();
     const [command, ...commandArgs] = args;

package/build/server-http.js

@@ -1,6 +1,7 @@
 import express from 'express';
 import helmet from 'helmet';
 import cors from 'cors';
+import axios from 'axios';
 import { createServer as createHttpsServer } from 'https';
 import { readFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
@@ -10,8 +11,7 @@ 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 { getConfiguredEnvironment, getHostedOauthScopes, getEbayConfig, getOAuthAuthorizationUrl, validateCredentialsForEnvironment, ruNameToEnvironment, } from './config/environment.js';
-import { getToolDefinitions, executeTool } from './tools/index.js';
+import { getBaseUrl, getConfiguredEnvironment, getHostedOauthScopes, getEbayConfig, getOAuthAuthorizationUrl, getValidationRunnerUserId, validateCredentialsForEnvironment, ruNameToEnvironment, } from './config/environment.js';
 import { getVersion } from './utils/version.js';
 import { serverLogger } from './utils/logger.js';
 import { MultiUserAuthStore } from './auth/multi-user-store.js';
@@ -38,6 +38,48 @@ function htmlEscape(value) {
         .replace(/"/g, '"')
         .replace(/'/g, ''');
 }
+function getValidationIdFromBody(body) {
+    if (typeof body === 'object' &&
+        body !== null &&
+        'validationId' in body &&
+        typeof body.validationId === 'string') {
+        return body.validationId;
+    }
+    return '';
+}
+function getRetryTimestampFromBody(body) {
+    if (typeof body === 'object' &&
+        body !== null &&
+        'timestamp' in body &&
+        typeof body.timestamp === 'string') {
+        const parsed = new Date(body.timestamp);
+        if (Number.isFinite(parsed.getTime())) {
+            return new Date(parsed.getTime() + 30 * 60 * 1000).toISOString();
+        }
+    }
+    return new Date(Date.now() + 30 * 60 * 1000).toISOString();
+}
+function getAxiosFailureDebug(error) {
+    if (!axios.isAxiosError(error)) {
+        return {
+            responseStatus: null,
+            responseBodyExcerpt: null,
+        };
+    }
+    const responseStatus = error.response?.status ?? null;
+    const rawBody = error.response?.data;
+    if (rawBody === undefined) {
+        return {
+            responseStatus,
+            responseBodyExcerpt: null,
+        };
+    }
+    const bodyText = typeof rawBody === 'string' ? rawBody : JSON.stringify(rawBody, null, 2);
+    return {
+        responseStatus,
+        responseBodyExcerpt: bodyText.slice(0, 500),
+    };
+}
 function requireAdmin(req, res, next) {
     if (!CONFIG.adminApiKey) {
         res.status(500).json({ error: 'ADMIN_API_KEY is not configured' });
@@ -107,6 +149,7 @@ function createApp() {
     app.use(express.urlencoded({ extended: false }));
     app.use(helmet({ xPoweredBy: false }));
     app.use('/icons', express.static(join(projectRoot, 'public', 'icons')));
+    app.use('/callback-copy.js', express.static(join(projectRoot, 'public', 'callback-copy.js')));
     app.use((req, res, next) => {
         const start = Date.now();
         res.on('finish', () => {
@@ -317,9 +360,9 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
             }
         }
         // Step 2: per-env RuName detection.
-        const sandboxRuName = process.env.EBAY_SANDBOX_RUNAME || process.env.EBAY_SANDBOX_REDIRECT_URI;
-        const productionRuName = process.env.EBAY_PRODUCTION_RUNAME || process.env.EBAY_PRODUCTION_REDIRECT_URI;
-        const genericRuName = process.env.EBAY_RUNAME || process.env.EBAY_REDIRECT_URI;
+        const sandboxRuName = process.env.EBAY_SANDBOX_RUNAME ?? process.env.EBAY_SANDBOX_REDIRECT_URI;
+        const productionRuName = process.env.EBAY_PRODUCTION_RUNAME ?? process.env.EBAY_PRODUCTION_REDIRECT_URI;
+        const genericRuName = process.env.EBAY_RUNAME ?? process.env.EBAY_REDIRECT_URI;
         const sandboxDetected = ruNameToEnvironment(sandboxRuName);
         const productionDetected = ruNameToEnvironment(productionRuName);
         if (sandboxDetected && !productionDetected)
@@ -333,6 +376,113 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
         // Step 4: final fallback.
         return getConfiguredEnvironment();
     }
+    router.post('/validation/run', requireAdmin, async (req, res) => {
+        const environment = resolveEnv(req);
+        const validationRunnerUserId = getValidationRunnerUserId(environment);
+        if (!validationRunnerUserId) {
+            res.status(500).json({
+                status: 'error',
+                validationId: getValidationIdFromBody(req.body),
+                errorCode: 'VALIDATION_USER_NOT_CONFIGURED',
+                message: `No validation runner user is configured for ${environment}`,
+                retryable: false,
+                nextCheckAt: null,
+            });
+            return;
+        }
+        const storedTokens = await authStore.getUserTokens(validationRunnerUserId, environment);
+        if (!storedTokens?.tokenData) {
+            res.status(500).json({
+                status: 'error',
+                validationId: getValidationIdFromBody(req.body),
+                errorCode: 'VALIDATION_USER_TOKENS_MISSING',
+                message: `Stored refresh-token-backed credentials were not found for validation user ${validationRunnerUserId} in ${environment}`,
+                retryable: false,
+                nextCheckAt: null,
+            });
+            return;
+        }
+        try {
+            const api = await createUserScopedApi(validationRunnerUserId, environment);
+            const { runValidation } = await import('./validation/run-validation.js');
+            const result = await runValidation(api, req.body);
+            if (result.status === 'error') {
+                res.status(500).json(result);
+                return;
+            }
+            res.json(result);
+        }
+        catch (error) {
+            res.status(500).json({
+                status: 'error',
+                validationId: getValidationIdFromBody(req.body),
+                errorCode: 'VALIDATION_ROUTE_ERROR',
+                message: error instanceof Error ? error.message : String(error),
+                retryable: true,
+                nextCheckAt: getRetryTimestampFromBody(req.body),
+            });
+        }
+    });
+    router.get('/validation/health', requireAdmin, async (req, res) => {
+        const environment = resolveEnv(req);
+        const validationRunnerUserId = getValidationRunnerUserId(environment);
+        const storedTokens = validationRunnerUserId
+            ? await authStore.getUserTokens(validationRunnerUserId, environment)
+            : null;
+        let authenticated = false;
+        let authError = null;
+        let tokenStatus = null;
+        let authDebug = null;
+        if (validationRunnerUserId && storedTokens?.tokenData) {
+            try {
+                const api = await createUserScopedApi(validationRunnerUserId, environment);
+                const oauthClient = api.getAuthClient().getOAuthClient();
+                const config = api.getAuthClient().getConfig();
+                authDebug = {
+                    ...oauthClient.getAuthDebugInfo(),
+                    configuredMarketplaceId: config.marketplaceId ?? '',
+                    configuredContentLanguage: config.contentLanguage ?? '',
+                };
+                await api.getAuthClient().getOAuthClient().getAccessToken();
+                authenticated = true;
+                tokenStatus = api.getTokenInfo();
+            }
+            catch (error) {
+                authError = error instanceof Error ? error.message : String(error);
+                const failureDebug = getAxiosFailureDebug(error);
+                authDebug = authDebug
+                    ? {
+                        ...authDebug,
+                        responseStatus: failureDebug.responseStatus,
+                        responseBodyExcerpt: failureDebug.responseBodyExcerpt,
+                    }
+                    : null;
+                serverLogger.error('Validation health auth check failed', {
+                    environment,
+                    validationRunnerUserId,
+                    tokenEndpoint: authDebug?.tokenEndpoint ?? null,
+                    responseStatus: failureDebug.responseStatus,
+                    responseBodyExcerpt: failureDebug.responseBodyExcerpt,
+                    authError,
+                });
+            }
+        }
+        res.json({
+            status: authenticated ? 'ok' : 'degraded',
+            environment,
+            validationRunnerUserId,
+            hasStoredTokens: !!storedTokens?.tokenData,
+            authenticated,
+            tokenStatus,
+            authDebug,
+            providers: {
+                ebay: { available: true, implemented: true, confidence: 'medium' },
+                social: { available: false, implemented: false, confidence: 'low' },
+                chart: { available: false, implemented: false, confidence: 'low' },
+            },
+            ...(authError ? { authError } : {}),
+        });
+    });
     // ── RFC 8414 – Authorization Server Metadata ──────────────────────────
     // For env-scoped routers: endpoints are relative to the env base URL.
     // For the ROOT router: endpoints are relative to the DEFAULT environment's
@@ -671,6 +821,19 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
         next();
     };
     async function createMcpServer(userId, environment) {
+        let getToolDefinitions;
+        let executeTool;
+        try {
+            ({ getToolDefinitions, executeTool } = await import('./tools/index.js'));
+        }
+        catch (error) {
+            serverLogger.error('Failed to import MCP tool registry', {
+                userId,
+                environment,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
         const api = await createUserScopedApi(userId, environment);
         const server = new McpServer({
             name: 'ebay-mcp-remote-edition',
@@ -685,23 +848,36 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
         });
         const tools = getToolDefinitions();
         for (const toolDef of tools) {
-            server.registerTool(toolDef.name, { description: toolDef.description, 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) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2),
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-            });
+            try {
+                server.registerTool(toolDef.name, { description: toolDef.description, 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) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                });
+            }
+            catch (error) {
+                serverLogger.error('Failed to register MCP tool', {
+                    toolName: toolDef.name,
+                    userId,
+                    environment,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
         }
         return server;
     }
@@ -717,26 +893,51 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
             transport = transports.get(sessionId);
         }
         else if (!sessionId && isInitializeRequest(req.body)) {
-            transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => randomUUID(),
-                onsessioninitialized: (newSessionId) => {
-                    transports.set(newSessionId, transport);
-                    serverLogger.info('New MCP session initialized', {
-                        sessionId: newSessionId,
-                        userId: userContext.userId,
-                        environment: userContext.environment,
-                    });
-                },
-            });
-            transport.onclose = () => {
-                if (transport.sessionId) {
-                    transports.delete(transport.sessionId);
-                }
-            };
-            const server = await createMcpServer(userContext.userId, userContext.environment);
-            await server.connect(transport);
+            try {
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (newSessionId) => {
+                        transports.set(newSessionId, transport);
+                        serverLogger.info('New MCP session initialized', {
+                            sessionId: newSessionId,
+                            userId: userContext.userId,
+                            environment: userContext.environment,
+                        });
+                    },
+                });
+                transport.onclose = () => {
+                    if (transport.sessionId) {
+                        transports.delete(transport.sessionId);
+                    }
+                };
+                const server = await createMcpServer(userContext.userId, userContext.environment);
+                await server.connect(transport);
+            }
+            catch (error) {
+                serverLogger.error('Failed to initialize MCP session', {
+                    userId: userContext.userId,
+                    environment: userContext.environment,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32603,
+                        message: error instanceof Error ? error.message : 'Failed to initialize MCP session',
+                    },
+                    id: null,
+                });
+                return;
+            }
         }
         else {
+            serverLogger.warn('Rejected MCP request without valid transport session', {
+                hasSessionId: !!sessionId,
+                sessionId,
+                isInitialize: isInitializeRequest(req.body),
+                userId: userContext.userId,
+                environment: userContext.environment,
+            });
             res.status(400).json({
                 jsonrpc: '2.0',
                 error: { code: -32000, message: 'Bad Request: No valid session ID provided' },
@@ -769,7 +970,6 @@ async function handleOAuthCallback(req, res, serverUrl) {
     try {
         const code = typeof req.query.code === 'string' ? req.query.code : undefined;
         const state = typeof req.query.state === 'string' ? req.query.state : undefined;
-        const envFromQuery = typeof req.query.env === 'string' ? req.query.env : undefined;
         const oauthError = typeof req.query.error === 'string' ? req.query.error : undefined;
         const errorDescription = typeof req.query.error_description === 'string' ? req.query.error_description : undefined;
         serverLogger.info('[oauth/callback] Received', {
@@ -787,33 +987,37 @@ async function handleOAuthCallback(req, res, serverUrl) {
             res.status(400).send('<h1>Missing authorization code</h1>');
             return;
         }
-        let environment;
-        let stateRecord = null;
-        if (state) {
-            stateRecord = await authStore.consumeOAuthState(state);
-            if (!stateRecord) {
-                serverLogger.warn('[oauth/callback] OAuth state not found or expired', { state });
-                res.status(400).send('<h1>Invalid or expired OAuth state</h1>');
-                return;
-            }
-            environment = stateRecord.environment;
-            serverLogger.info('[oauth/callback] State resolved', {
-                environment,
-                isMcpFlow: !!(stateRecord.mcpClientId && stateRecord.mcpRedirectUri),
-            });
+        if (!state) {
+            serverLogger.warn('[oauth/callback] Missing OAuth state in callback');
+            res
+                .status(400)
+                .send("<h1>Missing OAuth state</h1><p>Restart the OAuth flow from this server's /oauth/start or /authorize endpoint.</p>");
+            return;
         }
-        else {
-            environment =
-                envFromQuery === 'sandbox' || envFromQuery === 'production'
-                    ? envFromQuery
-                    : getConfiguredEnvironment();
-            serverLogger.warn('OAuth callback received without state; falling back to configured/query environment', { environment });
+        const stateRecord = await authStore.getOAuthState(state);
+        if (!stateRecord) {
+            serverLogger.warn('[oauth/callback] OAuth state not found or expired', { state });
+            res.status(400).send('<h1>Invalid or expired OAuth state</h1>');
+            return;
         }
+        const environment = stateRecord.environment;
+        serverLogger.info('[oauth/callback] State resolved', {
+            environment,
+            isMcpFlow: !!(stateRecord.mcpClientId && stateRecord.mcpRedirectUri),
+        });
+        const ebayConfig = getEbayConfig(environment);
+        serverLogger.info('[oauth/callback] Prepared eBay token exchange', {
+            environment,
+            tokenBaseUrl: getBaseUrl(environment),
+            clientIdPrefix: ebayConfig.clientId ? `${ebayConfig.clientId.slice(0, 12)}...` : '(missing)',
+            ruName: ebayConfig.redirectUri ?? '(missing)',
+        });
         const userId = randomUUID();
         const api = await createUserScopedApi(userId, environment);
         const oauthClient = api.getAuthClient().getOAuthClient();
         serverLogger.info('[oauth/callback] Exchanging code for eBay tokens', { userId });
         const tokenData = await oauthClient.exchangeCodeForToken(code);
+        await authStore.deleteOAuthState(state);
         serverLogger.info('[oauth/callback] eBay token exchange successful', {
             userId,
             hasScope: !!tokenData.scope,
@@ -901,32 +1105,7 @@ async function handleOAuthCallback(req, res, serverUrl) {
       .muted { color: #6b7280; }
       a { color: #2563eb; }
     </style>
-    <script>
-      async function copyText(elementId, statusId) {
-        const token = document.getElementById(elementId).innerText;
-        const status = document.getElementById(statusId);
-        try {
-          if (navigator.clipboard && window.isSecureContext) {
-            await navigator.clipboard.writeText(token);
-          } else {
-            const temp = document.createElement('textarea');
-            temp.value = token;
-            temp.setAttribute('readonly', '');
-            temp.style.position = 'absolute';
-            temp.style.left = '-9999px';
-            document.body.appendChild(temp);
-            temp.select();
-            document.execCommand('copy');
-            document.body.removeChild(temp);
-          }
-          status.textContent = 'Copied!';
-          setTimeout(() => { status.textContent = ''; }, 1800);
-        } catch (err) {
-          status.textContent = 'Copy failed — select manually';
-          setTimeout(() => { status.textContent = ''; }, 2500);
-        }
-      }
-    </script>
+    <script src="/callback-copy.js" defer></script>
   </head>
   <body>
     <h1>eBay account connected ✓</h1>
@@ -936,21 +1115,21 @@ async function handleOAuthCallback(req, res, serverUrl) {
     <h2>① Session token — paste as Bearer token in your MCP client</h2>
     <div class="card">
       <pre id="session-token">${htmlEscape(session.sessionToken)}</pre>
-      <button class="copy-btn" onclick="copyText('session-token','st-status')">Copy</button><span id="st-status" class="copy-status"></span>
+      <button class="copy-btn" data-copy-source="session-token" data-copy-status="st-status">Copy</button><span id="st-status" class="copy-status"></span>
       <p class="muted">Set as <code>EBAY_SESSION_TOKEN</code> in your server env to survive restarts.</p>
     </div>
 
     <h2>② eBay user access token</h2>
     <div class="card">
       <pre id="access-token">${htmlEscape(tokenData.access_token)}</pre>
-      <button class="copy-btn" onclick="copyText('access-token','at-status')">Copy</button><span id="at-status" class="copy-status"></span>
+      <button class="copy-btn" data-copy-source="access-token" data-copy-status="at-status">Copy</button><span id="at-status" class="copy-status"></span>
       <p class="muted">Set as <code>EBAY_USER_ACCESS_TOKEN</code> in your server env (optional — auto-refreshed from refresh token).</p>
     </div>
 
     <h2>③ eBay user refresh token</h2>
     <div class="card">
       <pre id="refresh-token">${htmlEscape(tokenData.refresh_token ?? '')}</pre>
-      <button class="copy-btn" onclick="copyText('refresh-token','rt-status')">Copy</button><span id="rt-status" class="copy-status"></span>
+      <button class="copy-btn" data-copy-source="refresh-token" data-copy-status="rt-status">Copy</button><span id="rt-status" class="copy-status"></span>
       <p class="muted">Set as <code>EBAY_USER_REFRESH_TOKEN</code> in your server env. The server uses this to keep the access token fresh automatically.</p>
     </div>