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): expose list_citations tool + REST endpoint (#117)
Gökhan Geyikdd4d6c1f6259
diff --git a/web/src/app/api/mcp/citations/route.ts b/web/src/app/api/mcp/citations/route.tsnew file mode 100644index 000000000..a95633959--- /dev/null+++ b/web/src/app/api/mcp/citations/route.ts@@ -0,0 +1,53 @@+import { NextResponse } from 'next/server';+import { authenticateMcpRequest } from '@/lib/mcp-auth';+import { listCitationsFor } from '@/lib/mcp/data';++/**+ * GET /api/mcp/citations+ *+ * Parallel REST surface for the `list_citations` MCP tool — same data-layer+ * function, same ownership guarantee. Query params mirror the MCP tool's args:+ * brand_id (required), date_from, date_to, model, region, topic_id, limit.+ */+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 limitParam = url.searchParams.get('limit');+ let limit: number | undefined;+ if (limitParam !== null) {+ const parsed = Number.parseInt(limitParam, 10);+ if (Number.isNaN(parsed) || parsed < 1 || parsed > 200) {+ return NextResponse.json(+ { error: 'limit must be an integer between 1 and 200' },+ { status: 400 },+ );+ }+ limit = parsed;+ }++ try {+ const result = await listCitationsFor(auth, {+ brandId,+ dateFrom: url.searchParams.get('date_from') ?? undefined,+ dateTo: url.searchParams.get('date_to') ?? undefined,+ model: url.searchParams.get('model') ?? undefined,+ region: url.searchParams.get('region') ?? undefined,+ topicId: url.searchParams.get('topic_id') ?? undefined,+ limit,+ });+ if (!result) {+ 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.tsindex aaeb01159..bd99d44c1 100644--- a/web/src/lib/mcp/data.ts+++ b/web/src/lib/mcp/data.ts@@ -1,5 +1,14 @@import { supabaseAdmin } from '@/lib/supabase/admin';import type { McpAuthContext } from '@/lib/mcp-auth';+import type { Citation } from '@/types';+import {+ classifyDomain,+ extractHostname,+ normalizeDomain,+ SOURCE_CATEGORIES,+ type SourceCategory,+} from '@/lib/citations/classify';+import { classifyArticleType } from '@/lib/citations/article-type';/*** Pure data-fetch functions shared by the MCP route and the parallel REST@@ -788,3 +797,290 @@ export async function getCompetitorComparisonFor(},};}++// ── Citations ────────────────────────────────────────────────────────────────++export interface ListCitationsParams {+ brandId: string;+ dateFrom?: string;+ dateTo?: string;+ /** Comma-separated model_used slugs (e.g. `gpt-4o,claude-sonnet-4-6`). */+ model?: string;+ region?: string;+ topicId?: string;+ /** Cap on the top_domains / top_urls arrays. Default 50, max 200. */+ limit?: number;+}++export interface CitationsOverviewOutput {+ totals: {+ domains: number;+ urls: number;+ citations: number;+ results_with_citations: number;+ avg_citations_per_result: number;+ };+ source_type_breakdown: Array<{+ category: SourceCategory;+ count: number;+ pct: number;+ }>;+ top_domains: Array<{+ domain: string;+ category: SourceCategory;+ total_citations: number;+ results_citing: number;+ usage_pct: number;+ models: string[];+ article_types: Array<{ type: string; count: number }>;+ }>;+ top_urls: Array<{+ url: string;+ domain: string;+ category: SourceCategory;+ title: string;+ total_citations: number;+ results_citing: number;+ usage_pct: number;+ article_type: string | null;+ }>;+}++const CITATIONS_DEFAULT_LIMIT = 50;+const CITATIONS_MAX_LIMIT = 200;++/**+ * Return the URLs and domains AI engines cite alongside a brand, classified by+ * source type (news / review / owned / social / forum). Ports the JS-side+ * aggregation from `getCitationsOverview` in `actions/citations.ts` — citations+ * are stored as JSONB inside `prompt_results.citations` and each URL needs the+ * `classifyDomain` / `classifyArticleType` helpers, so this can't be folded+ * into a Postgres aggregate the way the competitor / SoV surfaces were in #114.+ *+ * Ownership-check first; the prompt_results scan only runs after the brand+ * belongs to the caller's org.+ */+export async function listCitationsFor(+ auth: McpAuthContext,+ params: ListCitationsParams,+): Promise<CitationsOverviewOutput | null> {+ if (!auth.organizationId) return null;++ const { data: brand } = await supabaseAdmin+ .from('brands')+ .select('id')+ .eq('id', params.brandId)+ .eq('organization_id', auth.organizationId)+ .maybeSingle();+ if (!brand) return null;++ // Brand + competitor domains feed `classifyDomain` so a URL hosted on the+ // user's own domain comes back as `'you'`, competitor URLs as `'competitor'`.+ const [{ data: brandDomainRows }, { data: competitorRows }] = await Promise.all([+ supabaseAdmin.from('brand_domains').select('domain').eq('brand_id', params.brandId),+ supabaseAdmin.from('competitors').select('domain').eq('brand_id', params.brandId),+ ]);++ const brandDomains = (brandDomainRows ?? [])+ .map((r) => normalizeDomain((r as { domain: string }).domain))+ .filter(Boolean);+ const competitorDomains = (competitorRows ?? [])+ .map((r) => normalizeDomain((r as { domain: string }).domain))+ .filter(Boolean);+ const classifyCtx = { brandDomains, competitorDomains };++ let query = supabaseAdmin+ .from('prompt_results')+ .select('id, prompt_id, platform, model_used, region, created_at, citations, citation_count')+ .eq('brand_id', params.brandId);++ if (params.dateFrom) query = query.gte('created_at', params.dateFrom);+ if (params.dateTo) query = query.lte('created_at', params.dateTo);+ if (params.region) query = query.eq('region', params.region);+ if (params.model) {+ const list = params.model+ .split(',')+ .map((s) => s.trim())+ .filter(Boolean);+ query =+ list.length > 1+ ? query.in('model_used', list)+ : query.eq('model_used', list[0] ?? params.model);+ }+ if (params.topicId) {+ const { data: topicPrompts } = await supabaseAdmin+ .from('prompts')+ .select('id')+ .eq('topic_id', params.topicId);+ const topicPromptIds = ((topicPrompts ?? []) as { id: string }[]).map((p) => p.id);+ query = query.in(+ 'prompt_id',+ topicPromptIds.length > 0 ? topicPromptIds : ['00000000-0000-0000-0000-000000000000'],+ );+ }++ const { data: rows, error } = await query;+ if (error) throw new Error(error.message);++ const results = (rows ?? []) as Array<{+ id: string;+ platform: string | null;+ model_used: string | null;+ citations: Citation[] | null;+ }>;++ interface DomainAgg {+ domain: string;+ category: SourceCategory;+ totalCitations: number;+ resultsCiting: Set<string>;+ models: Set<string>;+ articleTypeCounts: Map<string, number>;+ }+ interface UrlAgg {+ url: string;+ domain: string;+ category: SourceCategory;+ title: string;+ totalCitations: number;+ resultsCiting: Set<string>;+ models: Set<string>;+ articleType: string | null;+ }++ const domainMap = new Map<string, DomainAgg>();+ const urlMap = new Map<string, UrlAgg>();+ let totalCitations = 0;+ let resultsWithCitations = 0;++ for (const result of results) {+ const citations = Array.isArray(result.citations) ? result.citations : [];+ if (citations.length === 0) continue;+ resultsWithCitations += 1;+ const modelKey = result.model_used || result.platform || '';++ for (const cite of citations) {+ const host = extractHostname(cite.url);+ if (!host) continue;++ const category = classifyDomain(host, classifyCtx);+ totalCitations += 1;++ const existingDomain = domainMap.get(host) ?? {+ domain: host,+ category,+ totalCitations: 0,+ resultsCiting: new Set<string>(),+ models: new Set<string>(),+ articleTypeCounts: new Map<string, number>(),+ };+ existingDomain.totalCitations += 1;+ existingDomain.resultsCiting.add(result.id);+ if (modelKey) existingDomain.models.add(modelKey);+ const articleType = classifyArticleType(cite.url, cite.title);+ if (articleType) {+ existingDomain.articleTypeCounts.set(+ articleType,+ (existingDomain.articleTypeCounts.get(articleType) ?? 0) + 1,+ );+ }+ domainMap.set(host, existingDomain);++ // De-dupe URLs by stripping query/fragment + trailing slash so the same+ // article cited with different tracking params still aggregates.+ let normalizedUrl = cite.url;+ try {+ const parsed = new URL(cite.url);+ parsed.search = '';+ parsed.hash = '';+ normalizedUrl = parsed.toString().replace(/\/$/, '');+ } catch {+ // leave as-is+ }+ const existingUrl = urlMap.get(normalizedUrl) ?? {+ url: normalizedUrl,+ domain: host,+ category,+ title: cite.title || '',+ totalCitations: 0,+ resultsCiting: new Set<string>(),+ models: new Set<string>(),+ articleType,+ };+ existingUrl.totalCitations += 1;+ existingUrl.resultsCiting.add(result.id);+ if (modelKey) existingUrl.models.add(modelKey);+ if (!existingUrl.title && cite.title) existingUrl.title = cite.title;+ urlMap.set(normalizedUrl, existingUrl);+ }+ }++ const totalResults = results.length;+ const limit = Math.min(Math.max(params.limit ?? CITATIONS_DEFAULT_LIMIT, 1), CITATIONS_MAX_LIMIT);++ const allDomains = Array.from(domainMap.values()).sort(+ (a, b) => b.totalCitations - a.totalCitations,+ );+ const topDomains = allDomains.slice(0, limit).map((agg) => {+ const resultsCiting = agg.resultsCiting.size;+ const articleTypes = Array.from(agg.articleTypeCounts.entries())+ .map(([type, count]) => ({ type, count }))+ .sort((a, b) => b.count - a.count)+ .slice(0, 3);+ return {+ domain: agg.domain,+ category: agg.category,+ total_citations: agg.totalCitations,+ results_citing: resultsCiting,+ usage_pct: totalResults > 0 ? Math.round((resultsCiting / totalResults) * 1000) / 10 : 0,+ models: Array.from(agg.models).sort(),+ article_types: articleTypes,+ };+ });++ const allUrls = Array.from(urlMap.values()).sort((a, b) => b.totalCitations - a.totalCitations);+ const topUrls = allUrls.slice(0, limit).map((agg) => {+ const resultsCiting = agg.resultsCiting.size;+ return {+ url: agg.url,+ domain: agg.domain,+ category: agg.category,+ title: agg.title,+ total_citations: agg.totalCitations,+ results_citing: resultsCiting,+ usage_pct: totalResults > 0 ? Math.round((resultsCiting / totalResults) * 1000) / 10 : 0,+ article_type: agg.articleType,+ };+ });++ // Source breakdown counts each *domain* once (matches the existing UI),+ // not each citation, so news/review/owned/social/forum percentages reflect+ // the diversity of cited sources rather than raw URL volume.+ const categoryCounts = new Map<SourceCategory, number>();+ for (const d of allDomains) {+ categoryCounts.set(d.category, (categoryCounts.get(d.category) ?? 0) + 1);+ }+ const totalDomains = allDomains.length;+ const sourceTypeBreakdown = SOURCE_CATEGORIES.map((category) => {+ const count = categoryCounts.get(category) ?? 0;+ return {+ category,+ count,+ pct: totalDomains > 0 ? Math.round((count / totalDomains) * 1000) / 10 : 0,+ };+ }).filter((b) => b.count > 0);++ return {+ totals: {+ domains: totalDomains,+ urls: allUrls.length,+ citations: totalCitations,+ results_with_citations: resultsWithCitations,+ avg_citations_per_result:+ totalResults > 0 ? Math.round((totalCitations / totalResults) * 10) / 10 : 0,+ },+ source_type_breakdown: sourceTypeBreakdown,+ top_domains: topDomains,+ top_urls: topUrls,+ };+}diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.tsindex f47f43877..50ecfa249 100644--- a/web/src/lib/mcp/server.ts+++ b/web/src/lib/mcp/server.ts@@ -9,6 +9,7 @@ import {getContentOpportunityFor,getVisibilitySummaryFor,listBrandsFor,+ listCitationsFor,listContentOpportunitiesFor,listPromptsFor,listTopicsFor,@@ -329,5 +330,60 @@ export function createMcpServer(auth: McpAuthContext): McpServer {},);+ server.registerTool(+ 'list_citations',+ {+ description:+ 'List the URLs and domains AI engines cite alongside a brand, classified by source type (news / review / owned / social / forum / competitor / you). Returns totals, a source-type breakdown, and the top cited domains + URLs (each with citation count, results citing, usage %, and article-type guess where available). Use this for "which sources cite me?", "which competitor sites get pulled?", or "what kinds of pages does AI cite?" questions. Snapshot for the given window — call again with an earlier window to compute a delta.',+ inputSchema: {+ brand_id: z.string().uuid().describe('Brand UUID, from list_brands.'),+ date_from: z+ .string()+ .optional()+ .describe('ISO timestamp (inclusive) lower bound, e.g. 2026-05-01T00:00:00Z.'),+ date_to: z.string().optional().describe('ISO timestamp (inclusive) upper bound.'),+ model: z+ .string()+ .optional()+ .describe(+ 'Optional model slug filter, or comma-separated list of slugs to filter a provider family.',+ ),+ region: z.string().optional().describe('Optional region code filter (e.g. "US", "TR").'),+ topic_id: z+ .string()+ .uuid()+ .optional()+ .describe('Optional topic UUID (from list_topics) to restrict to one topic.'),+ limit: z+ .number()+ .int()+ .min(1)+ .max(200)+ .optional()+ .describe('Row cap on top_domains / top_urls (default 50, max 200).'),+ },+ },+ async (args) => {+ const result = await listCitationsFor(auth, {+ brandId: args.brand_id,+ dateFrom: args.date_from,+ dateTo: args.date_to,+ model: args.model,+ region: args.region,+ topicId: args.topic_id,+ limit: args.limit,+ });+ if (!result) {+ return {+ content: [{ type: 'text', text: 'Brand not found' }],+ isError: true,+ };+ }+ return {+ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],+ };+ },+ );+return server;}