ebay-mcp-remote-edition 3.3.0 → 3.3.1

package/README.md

@@ -458,6 +458,7 @@ The hosted backend now includes a deployment-oriented validation pipeline for no
 Current module layout:
 
 - [`src/validation/types.ts`](src/validation/types.ts) — request/response contracts for validation runs, decision payloads, debug payloads, and provider signal types
+- [`src/validation/effective-context.ts`](src/validation/effective-context.ts) — source-aware normalization layer that converts raw request payloads into a first-class effective validation context for item and event runs
 - [`src/validation/run-validation.ts`](src/validation/run-validation.ts) — orchestration entrypoint that validates input, queries providers, merges signals, and returns writes/decision/debug output
 - [`src/validation/recommendation.ts`](src/validation/recommendation.ts) — recommendation and automation decision logic
 - [`src/validation/providers/ebay.ts`](src/validation/providers/ebay.ts) — live eBay browse-market snapshot provider using the server's existing user-scoped eBay API client
@@ -489,8 +490,26 @@ Operationally, validation works like this:
 3. The route looks up the configured validation runner user ID for that environment.
 4. The server loads that user's stored refresh-token-backed credentials from the existing hosted auth store.
 5. The validation orchestrator calls all six provider domains and gathers browse/current-market, sold enrichment, Terapeak/research contract data, social support signals, chart stub output, and previous-comeback research output.
-6. [`runValidation()`](src/validation/run-validation.ts:106) deterministically merges the provider outputs into normalized field writes.
-7. The response returns those writes, a conservative buy/track decision block, and provider debug metadata for downstream systems.
+6. Before provider execution, [`runValidation()`](src/validation/run-validation.ts) builds a normalized `effectiveContext` so downstream logic consumes a source-aware model (`item` or `event`) instead of relying on empty item placeholders.
+7. [`runValidation()`](src/validation/run-validation.ts) deterministically merges the provider outputs into normalized field writes.
+8. The response returns those writes, a conservative buy/track decision block, and provider debug metadata for downstream systems.
+
+#### Effective validation context
+
+Validation runs now normalize incoming request data into an internal effective context before provider query planning and recommendation logic execute.
+
+- **Item-scope runs** normalize to an item-oriented context with the resolved artist, album/item phrase, location, and resolved search query.
+- **Event-scope runs** normalize to an event-oriented context with `searchArtist`, `searchEvent`, `searchItem`, `searchLocation`, timing metadata, and a derived `effectiveSearchQuery` when no direct resolved query is present.
+- Providers and recommendation logic consume that normalized context rather than reasoning about blank `item.recordId` or `item.name` fields.
+- Debug output now exposes `effectiveSourceType`, `effectiveContextMode`, `effectiveSearchQuery`, `hasItem`, and `hasEvent` so operators can confirm whether an event run was normalized correctly.
+
+The request schema also now accepts source-aware query-context fields for hosted validation runs:
+
+- `resolvedSearchArtist`
+- `resolvedSearchItem`
+- `resolvedSearchEvent`
+- `resolvedSearchLocation`
+- `resolvedSearchQuery`
 
 The validation contract is intentionally split between stable route orchestration and swappable providers. That is why the current sold-data source can be replaced later without changing downstream orchestration or the hosted route contract implemented in [`src/validation/run-validation.ts`](src/validation/run-validation.ts).
 
@@ -595,10 +614,11 @@ Current backend status:
 - Social support signals are implemented in phase 1.
 - Chart data remains a stub.
 - Validation is currently an **admin-operated hosted backend workflow**, not an MCP tool surface.
+- Event-scope validations are now handled as first-class normalized runs instead of as item-shaped requests with null item identity tolerated for compatibility.
 
 Provider behavior:
 
-- **Browse/eBay provider:** [`src/validation/providers/ebay.ts`](src/validation/providers/ebay.ts) uses the eBay Browse API plus shared query fallback logic from [`src/validation/providers/query-utils.ts`](src/validation/providers/query-utils.ts). It walks multiple query candidates, records the selected query and tier in debug output, and uses heuristic matching rather than a strict catalog identity join.
+- **Browse/eBay provider:** [`src/validation/providers/ebay.ts`](src/validation/providers/ebay.ts) uses the eBay Browse API plus shared query fallback logic from [`src/validation/providers/query-utils.ts`](src/validation/providers/query-utils.ts). It walks multiple query candidates, records the selected query and tier in debug output, and uses heuristic matching rather than a strict catalog identity join. Event-driven runs now build those fallback queries from normalized event context instead of raw item title assumptions.
 - **Browse debug semantics:** validation debug now keeps browse candidate generation, selected query/tier, browse-specific sample size, and per-candidate result counts separate from sold-provider result counts so operators can tell whether the browse layer contributed a field, fell back to a weaker query, or returned no usable match.
 - **Sold provider:** [`src/validation/providers/ebay-sold.ts`](src/validation/providers/ebay-sold.ts) uses a temporary external sold-data source configured by `SOLD_ITEMS_API_URL` and `SOLD_ITEMS_API_KEY`. It uses the same query-fallback strategy as the browse provider and returns sold-price ranges, sample sold items, and recent sold-velocity buckets when available.
 - **Terapeak / eBay research provider:** [`src/validation/providers/terapeak.ts`](src/validation/providers/terapeak.ts) is currently a stable placeholder contract. It already defines the query/debug shape and output fields used by orchestration, including `previousPobAvgPriceUsd` and `previousPobSellThroughPct`, but live authenticated Terapeak/eBay research retrieval is not implemented yet.
@@ -609,6 +629,7 @@ Provider behavior:
 Recommendation behavior:
 
 - [`src/validation/recommendation.ts`](src/validation/recommendation.ts) now accepts Terapeak and research inputs alongside browse, sold, social, and chart signals.
+- Recommendation generation also consumes the normalized effective context so event runs can carry source-aware monitoring notes and avoid item-only assumptions when no usable item identity exists.
 - The decisioning remains intentionally conservative: Terapeak and research data can improve monitoring notes and confidence context, but the system still avoids aggressive automatic buy-state changes from partial or proxy signals alone.
 
 Known limitations in the current implementation:

package/build/validation/effective-context.js

@@ -0,0 +1,77 @@
+function sanitizeText(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function buildCompactText(...parts) {
+    const compact = parts
+        .map((part) => sanitizeText(part))
+        .filter((part) => part !== null)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return compact.length > 0 ? compact : null;
+}
+function getQueryContext(request) {
+    return request.validation.queryContext;
+}
+function getFallbackArtist(request) {
+    return sanitizeText(request.item.canonicalArtists[0]);
+}
+function getFallbackAlbum(request) {
+    return sanitizeText(request.item.relatedAlbums[0]);
+}
+function getFallbackItem(request) {
+    return sanitizeText(request.item.name);
+}
+export function buildValidationEffectiveContext(request) {
+    const queryContext = getQueryContext(request);
+    const sourceType = request.sourceContext?.sourceType ?? 'item';
+    const searchArtist = sanitizeText(queryContext?.resolvedSearchArtist) ?? getFallbackArtist(request);
+    const searchAlbum = sanitizeText(getFallbackAlbum(request));
+    const searchItem = sanitizeText(queryContext?.resolvedSearchItem) ??
+        (sourceType === 'item' ? getFallbackItem(request) : null);
+    const searchEvent = sanitizeText(queryContext?.resolvedSearchEvent);
+    const searchLocation = sanitizeText(queryContext?.resolvedSearchLocation);
+    const resolvedSearchQuery = sanitizeText(queryContext?.resolvedSearchQuery);
+    const itemRecordId = sanitizeText(request.item.recordId);
+    const eventRecordId = sanitizeText(request.sourceContext?.eventRecordId);
+    const itemName = getFallbackItem(request);
+    const hasItem = sourceType === 'item'
+        ? (request.sourceContext?.hasItem ?? itemRecordId !== null) || itemName !== null
+        : request.sourceContext?.hasItem === true || itemRecordId !== null;
+    const hasEvent = sourceType === 'event'
+        ? true
+        : request.sourceContext?.hasEvent === true || searchEvent !== null || eventRecordId !== null;
+    const effectiveSearchQuery = resolvedSearchQuery ??
+        (sourceType === 'event'
+            ? buildCompactText(searchArtist, searchEvent, searchItem, searchLocation)
+            : buildCompactText(searchArtist, searchAlbum ?? searchItem, searchLocation));
+    return {
+        sourceType,
+        mode: sourceType,
+        validationScope: sanitizeText(queryContext?.validationScope),
+        queryScope: sanitizeText(queryContext?.queryScope),
+        directQueryActive: queryContext?.directQueryActive === true,
+        resolvedSearchQuery,
+        effectiveSearchQuery,
+        searchArtist,
+        searchAlbum,
+        searchItem,
+        searchEvent,
+        searchLocation,
+        hasItem,
+        hasEvent,
+        itemRecordId,
+        eventRecordId,
+        itemName,
+        eventDate: sanitizeText(request.item.releaseDate),
+        dDay: request.validation.dDay,
+        requestTimestamp: request.timestamp,
+    };
+}
+export function getValidationEffectiveContext(request) {
+    return request.effectiveContext ?? buildValidationEffectiveContext(request);
+}

package/build/validation/providers/query-utils.js

@@ -1,3 +1,4 @@
+import { getValidationEffectiveContext } from '../effective-context.js';
 const NOISY_VERSION_PATTERNS = [
     /\((?:weverse albums?|weverse|digipack|platform|photobook|poca|poca album|kit)\s+ver\.?\)/gi,
     /\((?:weverse albums?|weverse|digipack|platform|photobook|poca|poca album|kit)\s+version\)/gi,
@@ -107,14 +108,28 @@ function dedupeQueries(candidates) {
     return result;
 }
 function getPrimaryArtist(request) {
-    return request.item.canonicalArtists[0]?.trim() ?? '';
+    return (getValidationEffectiveContext(request).searchArtist ??
+        request.item.canonicalArtists[0]?.trim() ??
+        '');
 }
 export function getPrimaryAlbumPhrase(request) {
-    const relatedAlbum = sanitizeQueryCandidate(request.item.relatedAlbums[0]?.trim() ?? '');
+    const effectiveContext = getValidationEffectiveContext(request);
+    if (effectiveContext.sourceType === 'event') {
+        const eventPhrase = sanitizeQueryCandidate(effectiveContext.searchEvent ?? '');
+        if (eventPhrase && extractSemanticTokens(eventPhrase).length > 0) {
+            return eventPhrase;
+        }
+        const itemPhrase = sanitizeQueryCandidate(effectiveContext.searchItem ?? '');
+        if (itemPhrase && extractSemanticTokens(itemPhrase).length > 0) {
+            return itemPhrase;
+        }
+        return sanitizeQueryCandidate(effectiveContext.searchLocation ?? '');
+    }
+    const relatedAlbum = sanitizeQueryCandidate(effectiveContext.searchAlbum ?? request.item.relatedAlbums[0]?.trim() ?? '');
     if (relatedAlbum && extractSemanticTokens(relatedAlbum).length > 0) {
         return relatedAlbum;
     }
-    const simplifiedTitle = simplifyItemTitle(request.item.name);
+    const simplifiedTitle = simplifyItemTitle(effectiveContext.searchItem ?? request.item.name);
     const withoutArtist = stripArtistsFromText(simplifiedTitle, request.item.canonicalArtists);
     const cleanedWithoutArtist = sanitizeQueryCandidate(removeBracketedContent(withoutArtist));
     if (extractSemanticTokens(cleanedWithoutArtist).length > 0) {
@@ -124,6 +139,13 @@ export function getPrimaryAlbumPhrase(request) {
     return extractSemanticTokens(cleanedTitle).length > 0 ? cleanedTitle : relatedAlbum;
 }
 export function getPrimarySocialAlbumPhrase(request) {
+    const effectiveContext = getValidationEffectiveContext(request);
+    if (effectiveContext.sourceType === 'event') {
+        const eventPhrase = buildConversationAlbumPhrase(buildCompactPhrase(effectiveContext.searchEvent ?? '', effectiveContext.searchItem ?? '', effectiveContext.searchLocation ?? ''));
+        if (extractSemanticTokens(eventPhrase).length > 0) {
+            return eventPhrase;
+        }
+    }
     for (const relatedAlbum of request.item.relatedAlbums) {
         const sanitizedRelatedAlbum = sanitizeQueryCandidate(relatedAlbum?.trim() ?? '');
         if (!sanitizedRelatedAlbum) {
@@ -204,6 +226,18 @@ function normalizeDescriptorPhrase(value) {
         .replace(/\b(?:sealed|new|official)\b/gi, ' '));
 }
 function collectDescriptorPhrases(request, options) {
+    const effectiveContext = getValidationEffectiveContext(request);
+    if (effectiveContext.sourceType === 'event') {
+        const eventDescriptors = [
+            effectiveContext.searchItem,
+            effectiveContext.searchLocation,
+            options.includeValidationType ? request.validation.validationType : null,
+        ]
+            .map((value) => normalizeDescriptorPhrase(value ?? ''))
+            .filter(Boolean)
+            .filter((value) => !GENERIC_DESCRIPTOR_PATTERN.test(value.toLowerCase()));
+        return dedupeQueries(eventDescriptors).slice(0, 3);
+    }
     const rawValues = [
         ...request.item.variation,
         ...request.item.itemType,
@@ -263,6 +297,93 @@ export function getQueryContext(request) {
 export function getResolvedSearchQuery(request) {
     return sanitizeQueryContextValue(getQueryContext(request)?.resolvedSearchQuery);
 }
+function getUsableResolvedSearchQuery(request) {
+    const resolvedSearchQuery = getResolvedSearchQuery(request);
+    return resolvedSearchQuery && !isRejectedResolvedQuery(resolvedSearchQuery)
+        ? resolvedSearchQuery
+        : null;
+}
+function getNormalizedQueryScope(request) {
+    return sanitizeQueryContextValue(getQueryContext(request)?.queryScope)?.toLowerCase() ?? null;
+}
+function resolveDeclaredQueryScope(request) {
+    const normalizedQueryScope = getNormalizedQueryScope(request);
+    if (!normalizedQueryScope) {
+        return 'unknown';
+    }
+    if (normalizedQueryScope.includes('direct query')) {
+        return 'direct_query';
+    }
+    const hasArtist = normalizedQueryScope.includes('artist');
+    const hasItem = normalizedQueryScope.includes('item');
+    const hasAlbum = normalizedQueryScope.includes('album');
+    const hasEvent = normalizedQueryScope.includes('event');
+    const hasLocation = normalizedQueryScope.includes('city') ||
+        normalizedQueryScope.includes('country') ||
+        normalizedQueryScope.includes('state') ||
+        normalizedQueryScope.includes('province') ||
+        normalizedQueryScope.includes('location');
+    if (hasArtist && hasItem && hasLocation) {
+        return 'artist_item_location';
+    }
+    if (hasArtist && hasLocation) {
+        return 'artist_location';
+    }
+    if (hasArtist && hasEvent) {
+        return 'artist_event';
+    }
+    if (hasArtist && hasAlbum) {
+        return 'artist_album';
+    }
+    if (hasArtist && hasItem) {
+        return 'artist_item';
+    }
+    if (normalizedQueryScope === 'artist only' || normalizedQueryScope === 'artist') {
+        return 'artist_only';
+    }
+    return 'unknown';
+}
+function hasExclusiveDirectQueryOverride(request) {
+    const queryContext = getQueryContext(request);
+    return (queryContext?.directQueryActive === true && getNormalizedQueryScope(request) === 'direct query');
+}
+function finalizeLooseQueryPlan(candidates) {
+    return dedupeQueryPlan(candidates).filter((candidate) => isValidConversationQuery(candidate.query));
+}
+function buildArtistOnlyCommerceFallbackPlan(request) {
+    return finalizeLooseQueryPlan([
+        {
+            family: 'artist_only_fallback',
+            query: getPrimaryArtist(request),
+        },
+    ]);
+}
+function buildArtistOnlySocialFallbackPlan(request) {
+    return finalizeLooseQueryPlan([
+        {
+            family: 'artist_only_fallback',
+            query: normalizeSocialSearchPhrase(getPrimaryArtist(request)),
+        },
+    ]);
+}
+function constrainFallbackPlanForScope(request, fallbackPlan, scopeSpecificFallbackPlan) {
+    if (getUsableResolvedSearchQuery(request) === null) {
+        return fallbackPlan;
+    }
+    switch (resolveDeclaredQueryScope(request)) {
+        case 'artist_only':
+            return scopeSpecificFallbackPlan;
+        case 'artist_item':
+        case 'artist_album':
+        case 'unknown':
+            return fallbackPlan;
+        case 'artist_event':
+        case 'artist_location':
+        case 'artist_item_location':
+        case 'direct_query':
+            return [];
+    }
+}
 export function buildProviderQueryResolutionDebug(request, queryContextUsed) {
     const queryContext = getQueryContext(request);
     const resolvedSearchQuery = getResolvedSearchQuery(request);
@@ -275,15 +396,14 @@ export function buildProviderQueryResolutionDebug(request, queryContextUsed) {
     };
 }
 export function prependResolvedQueryCandidate(request, fallbackPlan) {
-    const resolvedSearchQuery = getResolvedSearchQuery(request);
-    const usableResolvedQuery = resolvedSearchQuery && !isRejectedResolvedQuery(resolvedSearchQuery)
-        ? resolvedSearchQuery
-        : null;
+    const usableResolvedQuery = getUsableResolvedSearchQuery(request);
     const queryPlan = usableResolvedQuery
-        ? dedupeQueryPlan([
-            { family: 'resolved_query_context', query: usableResolvedQuery },
-            ...fallbackPlan,
-        ])
+        ? hasExclusiveDirectQueryOverride(request)
+            ? [{ family: 'resolved_query_context', query: usableResolvedQuery }]
+            : dedupeQueryPlan([
+                { family: 'resolved_query_context', query: usableResolvedQuery },
+                ...fallbackPlan,
+            ])
         : fallbackPlan;
     return {
         queryPlan,
@@ -308,9 +428,12 @@ function finalizeQueryPlan(candidates, primaryArtist, albumPhrase) {
     return dedupeQueryPlan(candidates).filter((candidate) => isValidCandidate(candidate.query, primaryArtist, albumPhrase));
 }
 function buildCorePhrases(request) {
+    const effectiveContext = getValidationEffectiveContext(request);
     const primaryArtist = getPrimaryArtist(request);
     const albumPhrase = getPrimaryAlbumPhrase(request);
-    const simplifiedTitle = sanitizeQueryCandidate(removeBracketedContent(simplifyItemTitle(request.item.name)));
+    const simplifiedTitle = effectiveContext.sourceType === 'event'
+        ? sanitizeQueryCandidate(buildCompactPhrase(primaryArtist, effectiveContext.searchEvent ?? '', effectiveContext.searchItem ?? '', effectiveContext.searchLocation ?? ''))
+        : sanitizeQueryCandidate(removeBracketedContent(simplifyItemTitle(request.item.name)));
     const artistAlbumPhrase = ensureArtistRetention(buildCompactPhrase(primaryArtist, albumPhrase), primaryArtist);
     const titleWithArtist = ensureArtistRetention(simplifiedTitle, primaryArtist);
     return {
@@ -344,7 +467,7 @@ export function buildBrowseQueryPlan(request) {
     ], primaryArtist, albumPhrase);
 }
 export function buildResolvedBrowseQueryPlan(request) {
-    return prependResolvedQueryCandidate(request, buildBrowseQueryPlan(request));
+    return prependResolvedQueryCandidate(request, constrainFallbackPlanForScope(request, buildBrowseQueryPlan(request), buildArtistOnlyCommerceFallbackPlan(request)));
 }
 export function buildBrowseQueryCandidates(request) {
     return buildBrowseQueryPlan(request).map((candidate) => candidate.query);
@@ -372,7 +495,7 @@ export function buildSoldQueryPlan(request) {
     ], primaryArtist, albumPhrase);
 }
 export function buildResolvedSoldQueryPlan(request) {
-    return prependResolvedQueryCandidate(request, buildSoldQueryPlan(request));
+    return prependResolvedQueryCandidate(request, constrainFallbackPlanForScope(request, buildSoldQueryPlan(request), buildArtistOnlyCommerceFallbackPlan(request)));
 }
 export function buildSoldQueryCandidates(request) {
     return buildSoldQueryPlan(request).map((candidate) => candidate.query);
@@ -398,7 +521,7 @@ export function buildTwitterQueryPlan(request) {
     return finalizeConversationQueryPlan(candidates);
 }
 export function buildResolvedTwitterQueryPlan(request) {
-    return prependResolvedQueryCandidate(request, buildTwitterQueryPlan(request));
+    return prependResolvedQueryCandidate(request, constrainFallbackPlanForScope(request, buildTwitterQueryPlan(request), buildArtistOnlySocialFallbackPlan(request)));
 }
 export function buildTwitterQueryCandidates(request) {
     return buildTwitterQueryPlan(request).map((candidate) => candidate.query);
@@ -422,7 +545,7 @@ export function buildYouTubeQueryPlan(request) {
         : [{ family: 'artist_only_media_fallback', query: compactArtist }]);
 }
 export function buildResolvedYouTubeQueryPlan(request) {
-    return prependResolvedQueryCandidate(request, buildYouTubeQueryPlan(request));
+    return prependResolvedQueryCandidate(request, constrainFallbackPlanForScope(request, buildYouTubeQueryPlan(request), buildArtistOnlySocialFallbackPlan(request)));
 }
 export function buildYouTubeQueryCandidates(request) {
     return buildYouTubeQueryPlan(request).map((candidate) => candidate.query);
@@ -441,7 +564,7 @@ export function buildRedditQueryPlan(request) {
     ], primaryArtist, compactAlbum);
 }
 export function buildResolvedRedditQueryPlan(request) {
-    return prependResolvedQueryCandidate(request, buildRedditQueryPlan(request));
+    return prependResolvedQueryCandidate(request, constrainFallbackPlanForScope(request, buildRedditQueryPlan(request), buildArtistOnlySocialFallbackPlan(request)));
 }
 export function buildRedditQueryCandidates(request) {
     return buildRedditQueryPlan(request).map((candidate) => candidate.query);
@@ -450,5 +573,5 @@ export function buildValidationQueryCandidates(request) {
     return buildSoldQueryCandidates(request);
 }
 export function buildResolvedValidationQueryPlan(request) {
-    return prependResolvedQueryCandidate(request, buildSoldQueryPlan(request));
+    return prependResolvedQueryCandidate(request, constrainFallbackPlanForScope(request, buildSoldQueryPlan(request), buildArtistOnlyCommerceFallbackPlan(request)));
 }

package/build/validation/providers/research.js

@@ -1,7 +1,9 @@
+import { getValidationEffectiveContext } from '../effective-context.js';
 export async function getPreviousComebackResearchSignals(request) {
     await Promise.resolve();
     const hasPerplexityKey = (process.env.PERPLEXITY_API_KEY ?? '').trim().length > 0;
-    const primaryAlbum = request.item.relatedAlbums[0] ?? null;
+    const effectiveContext = getValidationEffectiveContext(request);
+    const primaryAlbum = effectiveContext.searchAlbum ?? effectiveContext.searchEvent ?? effectiveContext.searchItem;
     return {
         previousAlbumTitle: null,
         previousComebackFirstWeekSales: null,

package/build/validation/providers/social.js

@@ -1,5 +1,6 @@
 import axios from 'axios';
 import { buildConversationAlbumPhrase, buildResolvedRedditQueryPlan, buildResolvedTwitterQueryPlan, buildResolvedYouTubeQueryPlan, extractSemanticTokens, getPrimaryAlbumPhrase, getPrimarySocialAlbumPhrase, normalizeWhitespace, } from './query-utils.js';
+import { getValidationEffectiveContext } from '../effective-context.js';
 const buildResolvedTwitterQueryPlanSafe = buildResolvedTwitterQueryPlan;
 const buildResolvedYouTubeQueryPlanSafe = buildResolvedYouTubeQueryPlan;
 const buildResolvedRedditQueryPlanSafe = buildResolvedRedditQueryPlan;
@@ -20,7 +21,9 @@ const YOUTUBE_OFFICIAL_CHANNEL_PATTERN = /\bofficial\b|\btopic\b/;
 const YOUTUBE_BRANDED_CHANNEL_PATTERN = /entertainment|music|records|labels?|media|studio|vevo/;
 const YOUTUBE_DEMOTED_CHANNEL_PATTERN = /shop\b|store\b|merch|reseller|resale|unboxing|fan\b|collector|trading|market/;
 function getPrimaryArtist(request) {
-    return request.item.canonicalArtists[0]?.trim() ?? '';
+    return (getValidationEffectiveContext(request).searchArtist ??
+        request.item.canonicalArtists[0]?.trim() ??
+        '');
 }
 function buildTwitterCountsUrl(query) {
     return `https://api.x.com/2/tweets/counts/recent?query=${encodeURIComponent(query)}`;

package/build/validation/providers/terapeak.js

@@ -4,7 +4,7 @@ export async function getTerapeakValidationSignals(_api, request) {
     const { queryPlan, queryResolution } = buildResolvedValidationQueryPlan(request);
     const queryCandidates = queryPlan.map((candidate) => candidate.query);
     const currentQuery = queryCandidates[0] ?? null;
-    const previousPobQuery = queryCandidates[1] ?? currentQuery;
+    const previousPobQuery = queryCandidates[1] ?? null;
     return {
         avgWatchersPerListing: null,
         preOrderListingsCount: null,

package/build/validation/recommendation.js

@@ -17,10 +17,18 @@ export function buildValidationRecommendation(request, signals) {
         signals.sold.soldMedianPriceUsd ??
         signals.ebay.marketPriceUsd;
     const preorderListingsCount = signals.terapeak.preOrderListingsCount ?? signals.ebay.preOrderListingsCount;
-    const wholesale = request.item.wholesalePrice;
+    const wholesale = signals.effectiveContext.hasItem ? request.item.wholesalePrice : null;
     const marginRatio = marketPrice !== null && wholesale !== null && wholesale > 0
         ? (marketPrice - wholesale) / wholesale
         : null;
+    const subjectLabel = signals.effectiveContext.sourceType === 'event'
+        ? (signals.effectiveContext.searchEvent ??
+            signals.effectiveContext.effectiveSearchQuery ??
+            'event opportunity')
+        : (signals.effectiveContext.searchAlbum ??
+            signals.effectiveContext.searchItem ??
+            request.item.name ??
+            'release');
     const recentSoldCount = [
         signals.sold.soldVelocity.day1Sold,
         signals.sold.soldVelocity.day2Sold,
@@ -28,13 +36,12 @@ export function buildValidationRecommendation(request, signals) {
     ].reduce((sum, value) => sum + (value ?? 0), 0);
     let latestAiRecommendation = 'Continue watching until stronger market signal appears.';
     let latestAiConfidence = 'Medium';
-    let monitoringNotes = 'Baseline recommendation generated from current validation state.';
+    let monitoringNotes = `Baseline recommendation generated from current ${signals.effectiveContext.mode} validation state for ${subjectLabel}.`;
     if (!shouldAutoTrack) {
         latestAiRecommendation =
             'Automatic tracking paused because the validation is no longer in a watchable state.';
         latestAiConfidence = 'High';
-        monitoringNotes =
-            'Stop conditions were met, so automation will not schedule another validation run.';
+        monitoringNotes = `Stop conditions were met, so automation will not schedule another ${signals.effectiveContext.mode} validation run for ${subjectLabel}.`;
     }
     else if (marginRatio !== null &&
         marginRatio >= 1 &&

package/build/validation/run-validation.js

@@ -7,6 +7,7 @@ import { getChartValidationSignals } from './providers/chart.js';
 import { getPreviousComebackResearchSignals } from './providers/research.js';
 import { buildProviderQueryResolutionDebug } from './providers/query-utils.js';
 import { buildValidationRecommendation } from './recommendation.js';
+import { buildValidationEffectiveContext } from './effective-context.js';
 function addMinutes(timestamp, minutes) {
     return new Date(new Date(timestamp).getTime() + minutes * 60 * 1000).toISOString();
 }
@@ -210,12 +211,17 @@ export async function runValidation(api, input) {
         };
     }
     try {
-        const ebay = await getEbayValidationSignals(api, request);
-        const sold = await getEbaySoldValidationSignals(request);
-        const terapeak = await getTerapeakValidationSignals(api, request);
-        const social = await getSocialValidationSignals(request);
-        const chart = getChartValidationSignals(request);
-        const research = await getPreviousComebackResearchSignals(request);
+        const effectiveContext = buildValidationEffectiveContext(request);
+        const effectiveRequest = {
+            ...request,
+            effectiveContext,
+        };
+        const ebay = await getEbayValidationSignals(api, effectiveRequest);
+        const sold = await getEbaySoldValidationSignals(effectiveRequest);
+        const terapeak = await getTerapeakValidationSignals(api, effectiveRequest);
+        const social = await getSocialValidationSignals(effectiveRequest);
+        const chart = getChartValidationSignals(effectiveRequest);
+        const research = await getPreviousComebackResearchSignals(effectiveRequest);
         const mergedAvgWatchers = terapeak.avgWatchersPerListing ?? ebay.avgWatchersPerListing;
         const mergedPreorderListings = terapeak.preOrderListingsCount ?? ebay.preOrderListingsCount;
         const marketPriceUsd = terapeak.marketPriceUsd ?? sold.soldMedianPriceUsd ?? ebay.marketPriceUsd;
@@ -229,16 +235,17 @@ export async function runValidation(api, input) {
             day5Sold: sold.soldVelocity.day5Sold ?? ebay.soldVelocity.day5Sold,
             daysTracked: sold.soldVelocity.daysTracked ?? ebay.soldVelocity.daysTracked,
         };
-        const recommendation = buildValidationRecommendation(request, {
+        const recommendation = buildValidationRecommendation(effectiveRequest, {
             ebay,
             sold,
             terapeak,
             social,
             chart,
             research,
+            effectiveContext,
         });
-        const requestQueryResolution = buildProviderQueryResolutionDebug(request, Boolean(ebay.queryResolution?.queryContextUsed));
-        const mergedSignals = { ebay, sold, terapeak, social, chart, research };
+        const requestQueryResolution = buildProviderQueryResolutionDebug(effectiveRequest, Boolean(ebay.queryResolution?.queryContextUsed));
+        const mergedSignals = { effectiveContext, ebay, sold, terapeak, social, chart, research };
         const socialWrites = {
             ...(social.twitterTrending !== null ? { twitterTrending: social.twitterTrending } : {}),
             ...(social.youtubeViews24hMillions !== null
@@ -340,6 +347,13 @@ export async function runValidation(api, input) {
                 nextCheckAt: recommendation.nextCheckAt,
             },
             debug: {
+                sourceContext: effectiveRequest.sourceContext ?? null,
+                effectiveSourceType: effectiveContext.sourceType,
+                effectiveContextMode: effectiveContext.mode,
+                effectiveSearchQuery: effectiveContext.effectiveSearchQuery,
+                hasItem: effectiveContext.hasItem,
+                hasEvent: effectiveContext.hasEvent,
+                effectiveContext,
                 ebayQuery: ebay.ebayQuery,
                 soldQuery: sold.query,
                 queryCandidates: {
@@ -352,7 +366,7 @@ export async function runValidation(api, input) {
                 omittedOptionalWrites,
                 writeResolution,
                 sourceSet: ['ebay', 'sold', 'terapeak', 'social', 'chart', 'research'],
-                providers: buildProviderDebug(request, ebay, sold, terapeak, social, chart, research),
+                providers: buildProviderDebug(effectiveRequest, ebay, sold, terapeak, social, chart, research),
                 queryContextUsed: requestQueryResolution.queryContextUsed,
                 querySource: requestQueryResolution.querySource,
                 resolvedSearchQuery: requestQueryResolution.resolvedSearchQuery,

package/build/validation/schemas.js

@@ -18,29 +18,45 @@ export const validationCurrentMetricsSchema = z.object({
     daysTracked: z.number().nullable(),
 });
 export const validationQueryContextSchema = z.object({
+    directQueryActive: z.boolean().nullable().optional(),
+    directSearchQuery: z.string().nullable().optional(),
+    resolvedSearchArtist: z.string().nullable().optional(),
+    resolvedSearchItem: z.string().nullable().optional(),
+    resolvedSearchEvent: z.string().nullable().optional(),
+    resolvedSearchLocation: z.string().nullable().optional(),
     resolvedSearchQuery: z.string().nullable().optional(),
     validationScope: z.string().nullable().optional(),
     queryScope: z.string().nullable().optional(),
 });
-export const validationRunRequestSchema = z.object({
+export const validationSourceContextSchema = z.object({
+    sourceType: z.enum(['item', 'event']).optional(),
+    hasItem: z.boolean().optional(),
+    hasEvent: z.boolean().optional(),
+    itemRecordId: z.string().nullable().optional(),
+    eventRecordId: z.string().nullable().optional(),
+});
+const validationItemSchema = z.object({
+    recordId: z.string().min(1).nullable(),
+    name: z.string(),
+    variation: z.array(z.string()),
+    itemType: z.array(z.string()),
+    releaseType: z.array(z.string()),
+    releaseDate: z.string().datetime({ offset: true }).nullable(),
+    releasePeriod: z.array(z.string()),
+    availability: z.array(z.string()),
+    wholesalePrice: z.number().nullable(),
+    supplierNames: z.array(z.string()),
+    canonicalArtists: z.array(z.string()),
+    relatedAlbums: z.array(z.string()),
+});
+export const validationRunRequestSchema = z
+    .object({
     validationId: z.string().min(1),
     runType: z.enum(['scheduled', 'manual']),
     cadence: trackingCadenceSchema,
     timestamp: z.string().datetime({ offset: true }),
-    item: z.object({
-        recordId: z.string().min(1),
-        name: z.string().min(1),
-        variation: z.array(z.string()),
-        itemType: z.array(z.string()),
-        releaseType: z.array(z.string()),
-        releaseDate: z.string().datetime({ offset: true }).nullable(),
-        releasePeriod: z.array(z.string()),
-        availability: z.array(z.string()),
-        wholesalePrice: z.number().nullable(),
-        supplierNames: z.array(z.string()),
-        canonicalArtists: z.array(z.string()),
-        relatedAlbums: z.array(z.string()),
-    }),
+    sourceContext: validationSourceContextSchema.optional(),
+    item: validationItemSchema,
     validation: z.object({
         validationType: z.string(),
         buyDecision: z.string(),
@@ -53,6 +69,28 @@ export const validationRunRequestSchema = z.object({
         queryContext: validationQueryContextSchema.optional(),
         currentMetrics: validationCurrentMetricsSchema,
     }),
+})
+    .superRefine((value, ctx) => {
+    const sourceType = value.sourceContext?.sourceType ?? 'item';
+    const itemRecordId = value.item.recordId?.trim() ?? '';
+    const itemName = value.item.name.trim();
+    if (sourceType === 'event') {
+        return;
+    }
+    if (itemRecordId.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['item', 'recordId'],
+            message: 'Item-driven validations require item.recordId.',
+        });
+    }
+    if (itemName.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['item', 'name'],
+            message: 'Item-driven validations require item.name.',
+        });
+    }
 });
 export const validationWritesSchema = z.object({
     avgWatchersPerListing: z.number().nullable().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ebay-mcp-remote-edition",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Remote + Local MCP server for eBay APIs - provides access to eBay developer functionality through MCP (Model Context Protocol)",
   "type": "module",
   "main": "build/index.js",