ai-visibility-mcp

Instructions

Implementation Reference

• mcp-server/src/index.ts:762-835 (handler)

  The handler for get_visibility_score tool, which calculates an AI visibility score for a brand across multiple platforms.

  server.tool(
    "get_visibility_score",
    "Calculate an overall AI visibility score (0-100) for a brand across all four AI platforms. Includes per-platform breakdowns and improvement recommendations.",
    {
      brand: z.string().describe("The brand name to score"),
    },
    async ({ brand }) => {
      const timeBucket = Math.floor(Date.now() / 3600000);
      const results: PlatformResult[] = [];
  
      for (const platformId of PLATFORM_IDS) {
        const rng = seededRandom(`${brand}-score-${platformId}-${timeBucket}`);
        const queries = generateQueries(brand, [], 3, rng);
        const queryResults: QueryResult[] = [];
  
        for (const query of queries) {
          const queryRng = seededRandom(
            `${brand}-score-${query}-${platformId}-${timeBucket}`
          );
          const result = simulateCheck(brand, query, platformId, [], queryRng);
          queryResults.push({ query, ...result });
        }
  
        results.push(aggregatePlatformResult(platformId, queryResults));
      }
  
      const overallScore = calculateScore(results);
  
      // Generate tier
      let tier: string;
      let tierDescription: string;
      if (overallScore >= 80) {
        tier = "Excellent";
        tierDescription =
          "Your brand has strong visibility across AI platforms. Focus on maintaining and expanding your presence.";
      } else if (overallScore >= 60) {
        tier = "Good";
        tierDescription =
          "Your brand is visible on most platforms but has room for improvement. Targeted optimization can boost your score.";
      } else if (overallScore >= 40) {
        tier = "Moderate";
        tierDescription =
          "Your brand appears in some AI responses but is missing from many. Significant optimization opportunities exist.";
      } else if (overallScore >= 20) {
        tier = "Low";
        tierDescription =
          "Your brand has limited AI visibility. A comprehensive strategy is needed to improve presence across platforms.";
      } else {
        tier = "Very Low";
        tierDescription =
          "Your brand is rarely mentioned by AI platforms. Immediate action is recommended to establish AI visibility.";
      }
  
      const platformScores = results.map((r) => ({
        platform: r.platformName,
        score: calculateScore([r]),
        mentionRate: `${Math.round(r.mentionRate * 100)}%`,
        averagePosition: r.averagePosition,
        topSentiment:
          r.sentimentBreakdown.positive >= r.sentimentBreakdown.neutral &&
          r.sentimentBreakdown.positive >= r.sentimentBreakdown.negative
            ? "positive"
            : r.sentimentBreakdown.neutral >= r.sentimentBreakdown.negative
            ? "neutral"
            : "negative",
      }));
  
      // Select relevant recommendations based on score
      const numRecs = overallScore >= 60 ? 4 : overallScore >= 30 ? 6 : 8;
      const rng = seededRandom(`${brand}-recs-${timeBucket}`);
      const selectedRecs = pickMultiple(RECOMMENDATIONS, numRecs, rng).map(
        (r) => ({
          ...r,
          recommendation: r.recommendation.replace(/{brand}/g, brand),