ai-visibility-mcp

Instructions

Implementation Reference

• mcp-server/src/index.ts:984-1085 (handler)

  The implementation of the get_recommendations tool, which calculates (or accepts) a visibility score and returns prioritized recommendations.

  server.tool(
    "get_recommendations",
    "Get actionable recommendations to improve a brand's AI visibility. Prioritized suggestions based on current score and industry best practices.",
    {
      brand: z.string().describe("The brand name to get recommendations for"),
      current_score: z
        .number()
        .min(0)
        .max(100)
        .optional()
        .describe(
          "Current visibility score (0-100) if known. If not provided, a quick check will be performed."
        ),
    },
    async ({ brand, current_score }) => {
      let score = current_score;
  
      // If no score provided, do a quick check
      if (score === undefined) {
        const timeBucket = Math.floor(Date.now() / 3600000);
        const results: PlatformResult[] = [];
  
        for (const platformId of PLATFORM_IDS) {
          const rng = seededRandom(
            `${brand}-recscore-${platformId}-${timeBucket}`
          );
          const queries = generateQueries(brand, [], 2, rng);
          const queryResults: QueryResult[] = [];
  
          for (const query of queries) {
            const queryRng = seededRandom(
              `${brand}-recscore-${query}-${platformId}-${timeBucket}`
            );
            const result = simulateCheck(
              brand,
              query,
              platformId,
              [],
              queryRng
            );
            queryResults.push({ query, ...result });
          }
  
          results.push(aggregatePlatformResult(platformId, queryResults));
        }
  
        score = calculateScore(results);
      }
  
      // Select and prioritize recommendations
      const allRecs = RECOMMENDATIONS.map((r) => ({
        ...r,
        recommendation: r.recommendation.replace(/{brand}/g, brand),
        details: r.details.replace(/{brand}/g, brand),
      }));
  
      // More recommendations for lower scores
      let selectedRecs;
      if (score >= 70) {
        selectedRecs = allRecs.filter(
          (r) => r.priority === "low" || r.priority === "medium"
        );
      } else if (score >= 40) {
        selectedRecs = allRecs;
      } else {
        // Low score: prioritize high-priority items first
        selectedRecs = [
          ...allRecs.filter((r) => r.priority === "high"),
          ...allRecs.filter((r) => r.priority === "medium"),
          ...allRecs.filter((r) => r.priority === "low"),
        ];
      }
  
      const output = {
        brand,
        currentScore: score,
        totalRecommendations: selectedRecs.length,
        recommendations: selectedRecs.map((r, i) => ({
          number: i + 1,
          priority: r.priority,
          category: r.category,
          recommendation: r.recommendation,
          details: r.details,
        })),
        summary:
          score >= 70
            ? `${brand} has good AI visibility. Focus on advanced strategies to maintain and extend your lead.`
            : score >= 40
            ? `${brand} has moderate AI visibility. Implementing these recommendations can significantly improve your presence across AI platforms.`
            : `${brand} has low AI visibility. Start with the high-priority recommendations to establish a strong foundation.`,
      };
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(output, null, 2),
          },
        ],
      };
    }
  );