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.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(mcp): read the product catalog: its sources and its products (#1729)
Cihan5e2078a4c43a
diff --git a/docs/guides/mcp-server.mdx b/docs/guides/mcp-server.mdxindex ae18085c2..1ff845e25 100644--- a/docs/guides/mcp-server.mdx+++ b/docs/guides/mcp-server.mdx@@ -336,13 +336,13 @@ The MCP never sends a page to a CMS: Ansvisor's own **Send to CMS** stays in the### Shopping-Shopping analytics comes with the Growth plan and above. On Starter, `list_shopping_cards`, `get_product_visibility`, `get_shopping_shelf`, `get_shopping_readiness` and `get_product_ai_says` answer `plan_limit`; the catalog tools read on.+Shopping analytics comes with the Growth plan and above. On Starter, `list_shopping_cards`, `get_product_visibility`, `get_shopping_shelf`, `get_shopping_readiness` and `get_product_ai_says` answer `plan_limit`. The catalog tools read on: on Starter, `list_catalog_products` lists the products with their `readiness`, Merchant Center issues and AI visits, orders and revenue as `null`.| Tool | What it does | Writes || --- | --- | --- || `list_shopping_cards` | Shopping cards surfaced in AI commercial contexts; filter by role, platform, and region. | || `get_product_visibility` | Aggregate visibility for one product title across platforms, regions, and dates. | |-| `get_catalog_sources` | Where the product catalog is read from (feed URLs, uploads, connected stores such as Shopify or Google Merchant Center) and how each last sync went: status, error, what it read and its products in the catalog now. | |+| `get_catalog_sources` | Where the product catalog is read from (feed URLs, uploads, or a Google Merchant Center account where the server offers it) and how each last sync went: status, error, what it read and its products in the catalog now. | || `list_catalog_products` | The live catalog products, by title, as Product Visibility reads them: price, stock, GTIN, `readiness` for AI shopping (`score` 0–100, the checks `missing`, and the `unknown` ones that can't be made), Merchant Center issues by severity (each issue once per product), and the AI visits, orders and revenue (`revenue_30d`) their pages brought over 30 days. Optional `search`; paged with `limit` (max 200) and `offset`. | || `get_shopping_shelf` | Product Visibility's Shelf: for each shopping question and AI channel, the first 10 products the latest answer showed, in order (`products_total` counts them all), the brand's best place on it (`own_rank`) and its last 7 days there; on a shelf the brand isn't on, `why_not_you` names its catalog product the question asks for most, with its readiness. Optional `period` (7d, 30d, 90d, all), `platform`, `market` (us, europe), `absent_only`; paged with `limit` (default 10, max 50) and `offset`. | || `get_shopping_readiness` | Product Visibility's Readiness: the checklist scored 0–100, each check's state (pass, warn, fail, unknown), its text as the page writes it and where its fix starts, and each AI channel's state (showing, notShowing, notTracked). Optional `period` and `market`. | |diff --git a/web/src/lib/mcp/catalog.test.ts b/web/src/lib/mcp/catalog.test.tsindex 9fcdfcef4..02ef8abd4 100644--- a/web/src/lib/mcp/catalog.test.ts+++ b/web/src/lib/mcp/catalog.test.ts@@ -8,7 +8,19 @@ import type { McpAuthContext } from '@/lib/mcp-auth';*/const brandInOrg = vi.hoisted(() => vi.fn());-vi.mock('@/lib/mcp/data', () => ({ brandInOrg }));+// The shopping reads' plan check: whether the plan has shopping analytics.+const planIncludes = vi.hoisted(() => vi.fn());+vi.mock('@/lib/mcp/data', () => ({ brandInOrg, planIncludes }));+// The REST mirror's key: the organization's.+vi.mock('@/lib/mcp-auth', () => ({+ authenticateMcpRequest: vi.fn(async () => ({+ userId: 'user-1',+ email: null,+ organizationId: 'org-1',+ apiKeyId: 'key-1',+ role: 'admin',+ })),+}));// The paged reads and the Merchant Center check run as they are; the// Product Visibility reads answer what each test says.@@ -100,6 +112,7 @@ vi.mock('@/lib/supabase/admin', () => ({}));const { getCatalogSourcesFor, listCatalogProductsFor } = await import('./catalog');+const { GET: productsRoute } = await import('@/app/api/mcp/catalog/products/route');const auth: McpAuthContext = {userId: 'user-1',@@ -147,6 +160,7 @@ function expectBrandScoped(brandId: string) {beforeEach(() => {brandInOrg.mockReset().mockResolvedValue(true);+ planIncludes.mockReset().mockResolvedValue(true);read.readCatalogSources.mockReset();read.readCatalogProducts.mockReset();tables = {};@@ -250,9 +264,84 @@ describe('listCatalogProductsFor', () => {orders_30d: 0,revenue_30d: null,});+ expect(planIncludes).toHaveBeenCalledWith('org-1', 'shopping_analytics');expectBrandScoped('brand-1');});+ describe('by plan: readiness, issues and AI visits are shopping analytics', () => {+ /** One product with a Merchant Center issue and AI visits. */+ const withAnalytics = () => {+ tables.catalog_products = [{ id: 'p1' }];+ tables.catalog_sources = merchantCenter();+ tables.catalog_variants = [{ product_id: 'p1', external_id: 'offer-1' }];+ tables.catalog_item_issues = [+ { external_id: 'offer-1', severity: 'demoted', code: 'image_too_small', attribute: null },+ ];+ stats = [{ product_id: 'p1', ai_visits: 12, orders: 2, revenue: 240, currency: 'USD' }];+ read.readCatalogProducts.mockResolvedValue([product('p1', { hasGtin: false })]);+ };+ const listed = {+ id: 'p1',+ title: 'Boots p1',+ price: 120,+ currency: 'USD',+ in_stock: true,+ has_gtin: false,+ };+ const rest = async () => {+ const res = await productsRoute(+ new Request('http://localhost/api/mcp/catalog/products?brand_id=brand-1'),+ );+ expect(res.status).toBe(200);+ return res.json();+ };++ it('gives them on a plan with it (Growth), over MCP and REST', async () => {+ withAnalytics();+ const growth = {+ ...listed,+ readiness: { score: expect.any(Number), missing: ['gtin'], unknown: [] },+ merchant_center_issues: { disapproved: 0, demoted: 1, not_impacted: 0 },+ ai_visits_30d: 12,+ orders_30d: 2,+ revenue_30d: 240,+ revenue_currency: 'USD',+ };+ const page = (await listCatalogProductsFor(auth, { brandId: 'brand-1' }))!;+ expect(page.products).toEqual([expect.objectContaining(growth)]);+ expect((await rest()).products).toEqual([expect.objectContaining(growth)]);+ });++ it('gives them as null without it (Starter), the products still listed, and reads neither', async () => {+ withAnalytics();+ planIncludes.mockResolvedValue(false);+ const starter = {+ ...listed,+ readiness: null,+ merchant_center_issues: null,+ ai_visits_30d: null,+ orders_30d: null,+ revenue_30d: null,+ revenue_currency: null,+ };+ const page = (await listCatalogProductsFor(auth, { brandId: 'brand-1' }))!;+ expect(page).toMatchObject({ total: 1, next_offset: null });+ expect(page.products).toEqual([expect.objectContaining(starter)]);+ const body = await rest();+ expect(body).toMatchObject({ total: 1, next_offset: null });+ expect(body.products).toEqual([expect.objectContaining(starter)]);+ expect(planIncludes).toHaveBeenCalledWith('org-1', 'shopping_analytics');+ expect(filters.some(([table]) => table === 'catalog_item_issues')).toBe(false);+ expect(rpcArgs).toEqual([]);+ });++ it("checks the plan only for the key's own brand", async () => {+ brandInOrg.mockResolvedValue(false);+ expect(await listCatalogProductsFor(auth, { brandId: 'brand-2' })).toBeNull();+ expect(planIncludes).not.toHaveBeenCalled();+ });+ });+it('finds a search as written: its regex characters, % and _ stay themselves', async () => {tables.catalog_products = [{ id: 'p1' }];read.readCatalogProducts.mockResolvedValue([product('p1')]);diff --git a/web/src/lib/mcp/catalog.ts b/web/src/lib/mcp/catalog.tsindex 5a3351174..ae756c345 100644--- a/web/src/lib/mcp/catalog.ts+++ b/web/src/lib/mcp/catalog.ts@@ -10,7 +10,7 @@ import {readForIds,} from '@/lib/shopping/catalog-read';import { readiness, type ReadinessCheck } from '@/lib/shopping/products';-import { brandInOrg } from './data';+import { brandInOrg, planIncludes } from './data';/*** A brand's product catalog (#1263) for the MCP tools get_catalog_sources and@@ -19,7 +19,10 @@ import { brandInOrg } from './data';* Visibility reads them (readCatalogProducts), each with its readiness for* AI shopping, its Google Merchant Center issues (00296) and the AI visits* and orders its page brought (00361). Read through the service role once- * the brand is the key's.+ * the brand is the key's. The readiness, the issues and the AI visits are+ * Product Visibility's Products tab, so like that tab (and the other shopping+ * reads) they need a plan with shopping analytics: on another plan they are+ * null and only the products themselves are read.*//** A catalog source and its last sync, as Settings › Integrations › Catalog shows it. */@@ -79,9 +82,10 @@ export interface McpCatalogProduct {has_gtin: boolean;/*** How ready it is for AI shopping, 0–100, the checks it misses, and those- * that can't be made (left out of the score).+ * that can't be made (left out of the score). Null on a plan without+ * shopping analytics, as are the issues and the AI visits below.*/- readiness: { score: number; missing: ReadinessCheck[]; unknown: ReadinessCheck[] };+ readiness: { score: number; missing: ReadinessCheck[]; unknown: ReadinessCheck[] } | null;/*** Google Merchant Center's issues on its offers by severity, each issue* (its code and attribute) once however many of its variants and@@ -90,8 +94,8 @@ export interface McpCatalogProduct {*/merchant_center_issues: McpIssueCounts | null;/** AI-referred visits to its page and the orders they led to, over the last 30 days. */- ai_visits_30d: number;- orders_30d: number;+ ai_visits_30d: number | null;+ orders_30d: number | null;/** Those orders' revenue, in their main currency; null without orders. */revenue_30d: number | null;revenue_currency: string | null;@@ -134,13 +138,16 @@ const literal = (text: string) => text.replace(/[\\^$.*+?()[\]{}|]/g, (c) => `\\/*** A page of the brand's live catalog products, by title, each read as* Product Visibility reads it; `search` narrows to titles containing it.- * Null for a brand outside the key's organization.+ * Null for a brand outside the key's organization. Without shopping+ * analytics in the plan, each product's readiness, issues and AI visits are+ * null, and neither the issues nor the visits are read.*/export async function listCatalogProductsFor(auth: McpAuthContext,params: { brandId: string; search?: string; limit?: number; offset?: number },): Promise<McpCatalogPage | null> {if (!(await brandInOrg(auth, params.brandId))) return null;+ const analytics = await planIncludes(auth.organizationId!, 'shopping_analytics');const limit = Math.min(Math.max(params.limit ?? PRODUCTS_DEFAULT, 1), PRODUCTS_MAX);const offset = Math.max(params.offset ?? 0, 0);const search = params.search?.trim();@@ -172,17 +179,19 @@ export async function listCatalogProductsFor(const since = new Date(Date.now() - STATS_DAYS * 86_400_000).toISOString();const [catalog, issues, stats] = await Promise.all([readCatalogProducts(supabaseAdmin, params.brandId, ids),- issuesOf(params.brandId, ids),- readAllRpcRows<ProductAiStatsRow>(- (start, end) =>- supabaseAdmin- .rpc('catalog_product_ai_stats', { p_brand_id: params.brandId, p_from: since })- .order('product_id')- .range(start, end) as unknown as PromiseLike<{- data: ProductAiStatsRow[] | null;- error: { message: string } | null;- }>,- ),+ analytics ? issuesOf(params.brandId, ids) : null,+ analytics+ ? readAllRpcRows<ProductAiStatsRow>(+ (start, end) =>+ supabaseAdmin+ .rpc('catalog_product_ai_stats', { p_brand_id: params.brandId, p_from: since })+ .order('product_id')+ .range(start, end) as unknown as PromiseLike<{+ data: ProductAiStatsRow[] | null;+ error: { message: string } | null;+ }>,+ )+ : [],]);const statsOf = new Map(stats.map((row) => [row.product_id, row]));const byId = new Map(catalog.map((product) => [product.id, product]));@@ -204,10 +213,10 @@ export async function listCatalogProductsFor(currency: product.currency,in_stock: product.inStock,has_gtin: product.hasGtin,- readiness: readiness(product),+ readiness: analytics ? readiness(product) : null,merchant_center_issues: issues && (issues.get(id) ?? noIssues()),- ai_visits_30d: Number(stat?.ai_visits ?? 0),- orders_30d: Number(stat?.orders ?? 0),+ ai_visits_30d: analytics ? Number(stat?.ai_visits ?? 0) : null,+ orders_30d: analytics ? Number(stat?.orders ?? 0) : null,revenue_30d: stat?.revenue == null ? null : Number(stat.revenue),revenue_currency: stat?.currency ?? null,},diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.tsindex d47b81018..512dcfb7d 100644--- a/web/src/lib/mcp/server.ts+++ b/web/src/lib/mcp/server.ts@@ -1915,7 +1915,7 @@ export function createMcpServer(auth: McpAuthContext): McpServer {{title: 'Catalog sources',description:- "Where the brand's product catalog is read from, as Settings › Integrations › Catalog shows it: each source's kind (a feed URL, an upload, or a connected store such as Shopify or Google Merchant Center), its address or account, and its last sync — when, its status (ok, failed, format_error, or auth_failed when the store refused the saved sign-in), the error, and what it read (items, skipped and why, products added/changed/removed, Merchant Center issues, products past the plan's cap) — and how many of its products are in the catalog now. Empty for a brand with no catalog.",+ "Where the brand's product catalog is read from, as Settings › Integrations › Catalog shows it: each source's kind (a feed URL, an upload, or a Google Merchant Center account where the server offers it), its address or account, and its last sync — when, its status (ok, failed, format_error, or auth_failed when the store refused the saved sign-in), the error, and what it read (items, skipped and why, products added/changed/removed, Merchant Center issues, products past the plan's cap) — and how many of its products are in the catalog now. Empty for a brand with no catalog.",inputSchema: {brand_id: relaxedUuid.describe('Brand UUID, from list_brands.'),},@@ -1932,7 +1932,7 @@ export function createMcpServer(auth: McpAuthContext): McpServer {{title: 'Catalog products',description:- "The brand's live catalog products, by title, as Product Visibility reads them: title, page, brand, product type, category, photo, lowest price in stock, in stock, GTIN; `readiness` for AI shopping (`score` 0–100; `missing`, the checks it fails: gtin, image, inStock, price, description, typeFirst — what the product is in its description's first 40 words — category, brand; `unknown`, those that can't be made, such as typeFirst without a product type, left out of the score); its Google Merchant Center issues by severity (disapproved, demoted, not_impacted), each issue once however many of its variants and destinations it is on (null without a Merchant Center account whose last sync went through); and over the last 30 days the AI visits its page got, the orders they led to and their revenue (`revenue_30d` in `revenue_currency`, null without orders). `search` narrows to titles containing it, as written. Paged: `limit` (default 50, max 200) and `offset`; `next_offset` is null on the last page, `total` counts the matches.",+ "The brand's live catalog products, by title, as Product Visibility reads them: title, page, brand, product type, category, photo, lowest price in stock, in stock, GTIN; `readiness` for AI shopping (`score` 0–100; `missing`, the checks it fails: gtin, image, inStock, price, description, typeFirst — what the product is in its description's first 40 words — category, brand; `unknown`, those that can't be made, such as typeFirst without a product type, left out of the score); its Google Merchant Center issues by severity (disapproved, demoted, not_impacted), each issue once however many of its variants and destinations it is on (null without a Merchant Center account whose last sync went through); and over the last 30 days the AI visits its page got, the orders they led to and their revenue (`revenue_30d` in `revenue_currency`, null without orders). `search` narrows to titles containing it, as written. Paged: `limit` (default 50, max 200) and `offset`; `next_offset` is null on the last page, `total` counts the matches. The readiness, the Merchant Center issues and the AI visits, orders and revenue need a plan with shopping analytics (Growth and above): on Starter they are null and the products are listed without them.",inputSchema: {brand_id: relaxedUuid.describe('Brand UUID, from list_brands.'),search: z.string().max(200).optional().describe('Only products whose title contains it.'),