ai_visibility

Instructions

Implementation Reference

• src/tools/ai-visibility.ts:72-90 (handler)

  The 'ai_visibility' tool handler: calls /v1/ai/visibility API with domain, keywords, location, and platforms parameters. Returns formatted result with credit usage.

  server.tool(
    "ai_visibility",
    "Measure a domain's visibility across AI platforms for up to 10 keywords. Shows how often and where AI models cite your site. Costs 10 credits.",
    {
      domain: z.string().min(1).describe('Domain to analyze (e.g. "example.com")'),
      keywords: z.array(z.string().min(1)).min(1).max(10).describe("Keywords to check visibility for"),
      location: z.string().optional().describe('Location for results (e.g. "Austin, TX"). Default: US'),
      platforms: z.array(z.enum(["chat_gpt", "google"])).optional().describe("Platforms to query. Default: all"),
    },
    READ_ONLY,
    withErrorHandling(async ({ domain, keywords, location, platforms }) => {
      const result = await callApi(
        "/v1/ai/visibility",
        { domain, keywords, ...(location && { location }), ...(platforms && { platforms }) },
        getAuth()
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

• src/tools/ai-visibility.ts:72-80 (schema)

  Input schema for 'ai_visibility': requires domain (string), keywords (array of strings, 1-10), optional location (string), optional platforms (enum chat_gpt|google).

  server.tool(
    "ai_visibility",
    "Measure a domain's visibility across AI platforms for up to 10 keywords. Shows how often and where AI models cite your site. Costs 10 credits.",
    {
      domain: z.string().min(1).describe('Domain to analyze (e.g. "example.com")'),
      keywords: z.array(z.string().min(1)).min(1).max(10).describe("Keywords to check visibility for"),
      location: z.string().optional().describe('Location for results (e.g. "Austin, TX"). Default: US'),
      platforms: z.array(z.enum(["chat_gpt", "google"])).optional().describe("Platforms to query. Default: all"),
    },

• src/server.ts:13-13 (registration)

  Import of registerAIVisibilityTools from the ai-visibility.ts module.

  import { registerAIVisibilityTools } from "./tools/ai-visibility.js";

• src/server.ts:45-45 (registration)

  Registration call: registerAIVisibilityTools(server, getAuth) which registers the 'ai_visibility' tool on the MCP server.

  registerAIVisibilityTools(server, getAuth);

• src/api-client.ts:143-158 (helper)

  withErrorHandling helper wraps the handler to catch errors and return them as MCP error content.

  export function withErrorHandling<T>(
    fn: (args: T) => Promise<ToolResult>
  ): (args: T) => Promise<ToolResult> {
    return async (args) => {
      try {
        return await fn(args);
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        console.error(`[mcp] Tool error: ${message}`);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    };
  }