ai-visibility-mcp

Instructions

Implementation Reference

• mcp-server/src/index.ts:863-938 (handler)

  The 'compare_brands' tool registration and handler implementation. It takes a list of brands and an optional keyword, generates simulated data for them, and returns a comparative analysis.

  server.tool(
    "compare_brands",
    "Compare the AI visibility of multiple brands side by side. Shows per-platform scores, overall rankings, and relative strengths.",
    {
      brands: z
        .array(z.string())
        .min(2)
        .max(10)
        .describe("List of brand names to compare (2-10 brands)"),
      keyword: z
        .string()
        .optional()
        .describe(
          "Optional industry keyword for context (e.g., 'project management')"
        ),
    },
    async ({ brands, keyword }) => {
      const timeBucket = Math.floor(Date.now() / 3600000);
      const keywords = keyword ? [keyword] : [];
      const brandResults: Array<{
        brand: string;
        overallScore: number;
        platformScores: Record<string, number>;
        mentionRates: Record<string, number>;
        topSentiment: string;
      }> = [];
  
      for (const brand of brands) {
        const platformResults: PlatformResult[] = [];
  
        for (const platformId of PLATFORM_IDS) {
          const rng = seededRandom(
            `${brand}-compare-${platformId}-${timeBucket}`
          );
          const queries = generateQueries(brand, keywords, 3, rng);
          const queryResults: QueryResult[] = [];
  
          for (const query of queries) {
            const queryRng = seededRandom(
              `${brand}-compare-${query}-${platformId}-${timeBucket}`
            );
            const result = simulateCheck(
              brand,
              query,
              platformId,
              keywords,
              queryRng
            );
            queryResults.push({ query, ...result });
          }
  
          platformResults.push(
            aggregatePlatformResult(platformId, queryResults)
          );
        }
  
        const overallScore = calculateScore(platformResults);
  
        const platformScores: Record<string, number> = {};
        const mentionRates: Record<string, number> = {};
        let totalPositive = 0;
        let totalNeutral = 0;
        let totalNegative = 0;
  
        for (const pr of platformResults) {
          platformScores[pr.platformName] = calculateScore([pr]);
          mentionRates[pr.platformName] =
            Math.round(pr.mentionRate * 100);
          totalPositive += pr.sentimentBreakdown.positive;
          totalNeutral += pr.sentimentBreakdown.neutral;
          totalNegative += pr.sentimentBreakdown.negative;
        }
  
        const topSentiment =
          totalPositive >= totalNeutral && totalPositive >= totalNegative
            ? "positive"