ai-visibility-mcp

Instructions

Implementation Reference

• src/lib/checker.ts:153-272 (handler)

  The core logic (handler) for `check_brand_visibility` which simulates brand presence, sentiment, and context based on input parameters.

  export async function checkBrandVisibility(
    brand: string,
    query: string,
    platform: string,
    keywords: string[] = []
  ): Promise<CheckResult> {
    // Simulate network delay (50-200ms)
    await new Promise((resolve) =>
      setTimeout(resolve, 50 + Math.random() * 150)
    );
  
    // Create a deterministic-ish seed from inputs, but add time-based variance
    const timeBucket = Math.floor(Date.now() / 3600000); // changes every hour
    const seed = `${brand}-${query}-${platform}-${timeBucket}`;
    const rng = seededRandom(seed);
  
    // Platform-specific mention probability
    const platformBias: Record<string, number> = {
      chatgpt: 0.55,
      perplexity: 0.65, // Perplexity tends to cite more sources
      claude: 0.5,
      gemini: 0.6,
    };
  
    // Query type affects mention probability
    let mentionBoost = 0;
    const queryLower = query.toLowerCase();
    const brandLower = brand.toLowerCase();
  
    if (queryLower.includes(brandLower)) {
      mentionBoost = 0.3; // Direct brand queries almost always mention it
    }
    if (
      queryLower.includes("what is") ||
      queryLower.includes("review") ||
      queryLower.includes("pros and cons")
    ) {
      mentionBoost += 0.15;
    }
    if (queryLower.includes("alternative") || queryLower.includes("compare")) {
      mentionBoost += 0.1;
    }
  
    const baseProbability = platformBias[platform] || 0.5;
    const mentioned = rng() < Math.min(baseProbability + mentionBoost, 0.95);
  
    const competitorPool = getCompetitorPool(keywords).filter(
      (c) => c.toLowerCase() !== brandLower
    );
    const numCompetitors = Math.floor(rng() * 4) + 2;
    const competitors = pickMultiple(competitorPool, numCompetitors, rng);
  
    const keyword = keywords.length > 0 ? pickRandom(keywords, rng) : "software";
  
    if (mentioned) {
      // Determine sentiment
      const sentimentRoll = rng();
      let sentiment: "positive" | "neutral" | "negative";
      if (sentimentRoll < 0.5) sentiment = "positive";
      else if (sentimentRoll < 0.82) sentiment = "neutral";
      else sentiment = "negative";
  
      const templates = SENTIMENT_TEMPLATES[sentiment];
      const template = pickRandom(templates, rng);
  
      // Build the response
      const mainText = template
        .replace(/{brand}/g, brand)
        .replace(/{keyword}/g, keyword);
      const competitorMention =
        competitors.length > 0
          ? `\n\nOther notable tools in this space include ${competitors.join(", ")}.`
          : "";
      const fullResponse = mainText + competitorMention;
  
      // Find the position of the brand mention
      const position =
        rng() < 0.4 ? 1 : rng() < 0.7 ? 2 : Math.floor(rng() * 3) + 3;
  
      // Extract context around brand mention
      const contextStart = Math.max(
        0,
        mainText.indexOf(brand) - 50
      );
      const contextEnd = Math.min(
        mainText.length,
        mainText.indexOf(brand) + brand.length + 50
      );
      const context =
        (contextStart > 0 ? "..." : "") +
        mainText.slice(contextStart, contextEnd) +
        (contextEnd < mainText.length ? "..." : "");
  
      return {
        mentioned: true,
        position,
        context,
        fullResponse,
        sentiment,
        competitors,
      };
    } else {
      // Brand not mentioned
      const template = pickRandom(NOT_MENTIONED_TEMPLATES, rng);
      const competitorList = competitors.slice(0, 4).join(", ");
      const fullResponse = template
        .replace(/{keyword}/g, keyword)
        .replace(/{competitors}/g, competitorList)
        .replace(/{brand}/g, brand);
  
      return {
        mentioned: false,
        position: null,
        context: "",
        fullResponse,
        sentiment: "neutral",
        competitors,
      };
    }
  }

• src/lib/checker.ts:1-8 (schema)

  The TypeScript interface defining the output structure for the `check_brand_visibility` tool.

  export interface CheckResult {
    mentioned: boolean;
    position: number | null;
    context: string;
    fullResponse: string;
    sentiment: "positive" | "neutral" | "negative";
    competitors: string[];
  }

• mcp-server/src/index.ts:637-641 (registration)

  Registration of the `check_brand_visibility` tool within the MCP server implementation.

  // Tool: check_brand_visibility
  server.tool(
    "check_brand_visibility",
    "Check a brand's visibility across AI platforms (ChatGPT, Perplexity, Claude, Gemini). Simulates realistic queries and analyzes mention rates, positions, sentiment, and competitor landscape.",
    {