Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(mcp): expose list_shopping_cards / get_product_visibility tools + REST endpoints (#177)

Pallavi Kumari969f719a6a1e
diff --git a/web/src/app/api/mcp/product-visibility/route.ts b/web/src/app/api/mcp/product-visibility/route.ts
new file mode 100644
index 000000000..3d8776b61
--- /dev/null
+++ b/web/src/app/api/mcp/product-visibility/route.ts
@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server';
+import { authenticateMcpRequest } from '@/lib/mcp-auth';
+import { getProductVisibility } from '@/lib/mcp/data';
+
+export async function GET(req: Request) {
+ const auth = await authenticateMcpRequest(req);
+ if (auth instanceof NextResponse) return auth;
+
+ const url = new URL(req.url);
+ const brandId = url.searchParams.get('brand_id');
+ if (!brandId) {
+ return NextResponse.json({ error: 'brand_id is required' }, { status: 400 });
+ }
+
+ const productTitle = url.searchParams.get('product_title');
+ if (!productTitle) {
+ return NextResponse.json({ error: 'product_title is required' }, { status: 400 });
+ }
+
+ try {
+ const result = await getProductVisibility(auth, {
+ brandId,
+ productTitle,
+ });
+ if (result === null) {
+ return NextResponse.json({ error: 'Product or Brand not found' }, { status: 404 });
+ }
+ return NextResponse.json({ visibility: result });
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Failed';
+ return NextResponse.json({ error: message }, { status: 500 });
+ }
+}
diff --git a/web/src/app/api/mcp/shopping-cards/route.ts b/web/src/app/api/mcp/shopping-cards/route.ts
new file mode 100644
index 000000000..588d2c045
--- /dev/null
+++ b/web/src/app/api/mcp/shopping-cards/route.ts
@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+import { authenticateMcpRequest } from '@/lib/mcp-auth';
+import { listShoppingCards } from '@/lib/mcp/data';
+
+export async function GET(req: Request) {
+ const auth = await authenticateMcpRequest(req);
+ if (auth instanceof NextResponse) return auth;
+
+ const url = new URL(req.url);
+ const brandId = url.searchParams.get('brand_id');
+ if (!brandId) {
+ return NextResponse.json({ error: 'brand_id is required' }, { status: 400 });
+ }
+
+ const role = url.searchParams.get('role') || undefined;
+ const platform = url.searchParams.get('platform') || undefined;
+ const region = url.searchParams.get('region') || undefined;
+
+ const limitRaw = url.searchParams.get('limit');
+ const limit = limitRaw ? Number.parseInt(limitRaw, 10) : undefined;
+ const cursor = url.searchParams.get('cursor') || undefined;
+
+ if (role && !['own', 'competitor', 'other'].includes(role)) {
+ return NextResponse.json({ error: 'Invalid role' }, { status: 400 });
+ }
+
+ try {
+ const result = await listShoppingCards(auth, {
+ brandId,
+ role: role as 'own' | 'competitor' | 'other' | undefined,
+ platform,
+ region,
+ limit: Number.isFinite(limit) ? limit : undefined,
+ cursor,
+ });
+ if (result === null) {
+ return NextResponse.json({ error: 'Brand not found' }, { status: 404 });
+ }
+ return NextResponse.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Failed';
+ return NextResponse.json({ error: message }, { status: 500 });
+ }
+}
diff --git a/web/src/lib/mcp/data.ts b/web/src/lib/mcp/data.ts
index a6d9ee033..81b4ee364 100644
--- a/web/src/lib/mcp/data.ts
+++ b/web/src/lib/mcp/data.ts
@@ -1406,3 +1406,219 @@ export async function getPromptVolumesFor(
};
});
}
+
+// ── Shopping Cards ────────────────────────────────────────────────────────────
+
+export interface ListShoppingCardsParams {
+ brandId: string;
+ role?: 'own' | 'competitor' | 'other';
+ platform?: string;
+ region?: string;
+ limit?: number;
+ cursor?: string;
+}
+
+export interface ShoppingCardRow {
+ id: string;
+ prompt_result_id: string;
+ brand_id: string;
+ position: number;
+ product_title: string | null;
+ product_brand: string | null;
+ price_amount: number | null;
+ price_currency: string | null;
+ image_url: string | null;
+ merchant_url: string | null;
+ merchant_domain: string | null;
+ rating: number | null;
+ review_count: number | null;
+ raw: Record<string, unknown>;
+ matched_brand_id: string | null;
+ matched_brand_role: string;
+ platform: string;
+ region: string | null;
+ created_at: string;
+}
+
+export interface ListShoppingCardsOutput {
+ cards: ShoppingCardRow[];
+ next_cursor: string | null;
+}
+
+export async function listShoppingCards(
+ auth: McpAuthContext,
+ params: ListShoppingCardsParams,
+): Promise<ListShoppingCardsOutput | null> {
+ if (!auth.organizationId) return null;
+
+ // Brand ownership check
+ const { data: brand } = await supabaseAdmin
+ .from('brands')
+ .select('id')
+ .eq('id', params.brandId)
+ .eq('organization_id', auth.organizationId)
+ .maybeSingle();
+ if (!brand) return null;
+
+ const finalLimit = Math.min(Math.max(params.limit ?? 50, 1), 200);
+
+ let cursorData: { created_at: string; id: string } | null = null;
+ if (params.cursor) {
+ try {
+ cursorData = JSON.parse(Buffer.from(params.cursor, 'base64').toString('utf8'));
+ } catch {
+ // Ignore invalid cursor
+ }
+ }
+
+ let query = supabaseAdmin
+ .from('prompt_result_shopping_cards')
+ .select('*')
+ .eq('brand_id', params.brandId)
+ .order('created_at', { ascending: false })
+ .order('id', { ascending: false })
+ .limit(finalLimit + 1);
+
+ if (params.role) {
+ query = query.eq('matched_brand_role', params.role);
+ }
+ if (params.platform) {
+ query = query.eq('platform', params.platform);
+ }
+ if (params.region) {
+ query = query.eq('region', params.region);
+ }
+
+ if (cursorData) {
+ query = query.or(
+ `created_at.lt.${cursorData.created_at},and(created_at.eq.${cursorData.created_at},id.lt.${cursorData.id})`,
+ );
+ }
+
+ const { data: rows, error } = await query;
+ if (error) throw new Error(error.message);
+
+ const cards = (rows ?? []) as ShoppingCardRow[];
+ const hasNextPage = cards.length > finalLimit;
+ const slicedCards = hasNextPage ? cards.slice(0, finalLimit) : cards;
+
+ let nextCursor: string | null = null;
+ if (hasNextPage && slicedCards.length > 0) {
+ const lastItem = slicedCards[slicedCards.length - 1];
+ nextCursor = Buffer.from(
+ JSON.stringify({ created_at: lastItem.created_at, id: lastItem.id }),
+ ).toString('base64');
+ }
+
+ return {
+ cards: slicedCards,
+ next_cursor: nextCursor,
+ };
+}
+
+export interface ProductVisibilityOutput {
+ product_title: string;
+ total_appearances: number;
+ by_platform: Array<{ platform: string; count: number }>;
+ by_region: Array<{ region: string; count: number }>;
+ by_date: Array<{ date: string; count: number }>;
+ latest_appearance: string | null;
+ average_rating: number | null;
+ total_reviews: number | null;
+ merchant_domains: Array<{ domain: string; count: number }>;
+}
+
+export async function getProductVisibility(
+ auth: McpAuthContext,
+ params: { brandId: string; productTitle: string },
+): Promise<ProductVisibilityOutput | null> {
+ if (!auth.organizationId) return null;
+
+ // Brand ownership check
+ const { data: brand } = await supabaseAdmin
+ .from('brands')
+ .select('id')
+ .eq('id', params.brandId)
+ .eq('organization_id', auth.organizationId)
+ .maybeSingle();
+ if (!brand) return null;
+
+ const { data: cards, error } = await supabaseAdmin
+ .from('prompt_result_shopping_cards')
+ .select(
+ 'platform, region, created_at, price_amount, price_currency, rating, review_count, merchant_domain',
+ )
+ .eq('brand_id', params.brandId)
+ .eq('product_title', params.productTitle)
+ .order('created_at', { ascending: false });
+
+ if (error) throw new Error(error.message);
+ if (!cards || cards.length === 0) return null;
+
+ const total_appearances = cards.length;
+
+ const platformMap = new Map<string, number>();
+ const regionMap = new Map<string, number>();
+ const dateMap = new Map<string, number>();
+ const domainMap = new Map<string, number>();
+
+ let ratingSum = 0;
+ let ratingCount = 0;
+ let totalReviews: number | null = null;
+
+ for (const card of cards) {
+ const platform = card.platform || 'unknown';
+ platformMap.set(platform, (platformMap.get(platform) ?? 0) + 1);
+
+ const region = card.region || 'unknown';
+ regionMap.set(region, (regionMap.get(region) ?? 0) + 1);
+
+ const date = card.created_at ? card.created_at.slice(0, 10) : 'unknown';
+ dateMap.set(date, (dateMap.get(date) ?? 0) + 1);
+
+ if (card.merchant_domain) {
+ domainMap.set(card.merchant_domain, (domainMap.get(card.merchant_domain) ?? 0) + 1);
+ }
+
+ if (card.rating !== null && card.rating !== undefined) {
+ ratingSum += Number(card.rating);
+ ratingCount += 1;
+ }
+
+ if (card.review_count !== null && card.review_count !== undefined) {
+ if (totalReviews === null) totalReviews = 0;
+ totalReviews += card.review_count;
+ }
+ }
+
+ const by_platform = Array.from(platformMap.entries())
+ .map(([platform, count]) => ({ platform, count }))
+ .sort((a, b) => b.count - a.count);
+
+ const by_region = Array.from(regionMap.entries())
+ .map(([region, count]) => ({ region, count }))
+ .sort((a, b) => b.count - a.count);
+
+ const by_date = Array.from(dateMap.entries())
+ .map(([date, count]) => ({ date, count }))
+ .sort((a, b) => b.date.localeCompare(a.date)); // Sort chronologically descending
+
+ const merchant_domains = Array.from(domainMap.entries())
+ .map(([domain, count]) => ({ domain, count }))
+ .sort((a, b) => b.count - a.count);
+
+ const average_rating = ratingCount > 0 ? Math.round((ratingSum / ratingCount) * 10) / 10 : null;
+ const latest_appearance = cards[0]?.created_at || null;
+
+ return {
+ product_title: params.productTitle,
+ total_appearances,
+ by_platform,
+ by_region,
+ by_date,
+ latest_appearance,
+ average_rating,
+ total_reviews: totalReviews,
+ merchant_domains,
+ };
+}
diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.ts
index ee87eead2..1122980c3 100644
--- a/web/src/lib/mcp/server.ts
+++ b/web/src/lib/mcp/server.ts
@@ -17,6 +17,8 @@ import {
updateOpportunityStatusFor,
getAiTrafficFor,
getPromptVolumesFor,
+ listShoppingCards,
+ getProductVisibility,
} from './data';
/**
@@ -501,5 +503,86 @@ export function createMcpServer(auth: McpAuthContext): McpServer {
},
);
+ server.registerTool(
+ 'list_shopping_cards',
+ {
+ description:
+ 'List normalized shopping cards for a brand, showing which products are surfaced by AI engines in commercial-intent contexts. Supports filtering by matched brand role ("own" | "competitor" | "other"), platform, and region. Pagination is cursor-based (default limit 50, max 200). Use this to see which product brands, URLs, and prices are visible in search results.',
+ inputSchema: {
+ brand_id: relaxedUuid.describe('Brand UUID, from list_brands.'),
+ role: z
+ .enum(['own', 'competitor', 'other'])
+ .optional()
+ .describe(
+ 'Filter by role relationship of the matched brand: "own" (this brand), "competitor" (tracked competitors), or "other" (untracked brands).',
+ ),
+ platform: z
+ .string()
+ .optional()
+ .describe(
+ 'Optional scraper/platform filter (e.g. "chatgpt-shopping", "perplexity-web").',
+ ),
+ region: z.string().optional().describe('Optional region code filter (e.g. "US", "TR").'),
+ limit: z
+ .number()
+ .int()
+ .min(1)
+ .max(200)
+ .optional()
+ .describe('Optional limit (default 50, max 200).'),
+ cursor: z
+ .string()
+ .optional()
+ .describe('Base64 encoded pagination cursor from next_cursor.'),
+ },
+ },
+ async (args) => {
+ const result = await listShoppingCards(auth, {
+ brandId: args.brand_id,
+ role: args.role,
+ platform: args.platform,
+ region: args.region,
+ limit: args.limit,
+ cursor: args.cursor,
+ });
+ if (result === null) {
+ return {
+ content: [{ type: 'text', text: 'Brand not found' }],
+ isError: true,
+ };
+ }
+ return {
+ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+ };
+ },
+ );
+
+ server.registerTool(
+ 'get_product_visibility',
+ {
+ description:
+ "Get aggregate visibility metrics for a specific product title across platforms, regions, and dates. Returns total appearances, platform breakdown, region breakdown, chronological trend of dates, average rating, total reviews, and associated merchant domains. Use this to audit a single product's performance and organic footprint in AI-driven shopping results.",
+ inputSchema: {
+ brand_id: relaxedUuid.describe('Brand UUID, from list_brands.'),
+ product_title: z.string().describe('The product title/name to query.'),
+ },
+ },
+ async (args) => {
+ const result = await getProductVisibility(auth, {
+ brandId: args.brand_id,
+ productTitle: args.product_title,
+ });
+ if (result === null) {
+ return {
+ content: [{ type: 'text', text: 'Product or Brand not found' }],
+ isError: true,
+ };
+ }
+ return {
+ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+ };
+ },
+ );
+
return server;
}