ai_keyword_data

Instructions

Implementation Reference

• src/tools/ai-visibility.ts:111-127 (handler)

  The handler for the ai_keyword_data tool. It calls the /v1/ai/keyword-data API endpoint with keywords and optional location, then formats the result.

  server.tool(
    "ai_keyword_data",
    "Get AI search volume and trends for keywords — how often they're searched in ChatGPT and other LLMs. Costs 1 credit per 50 keywords.",
    {
      keywords: z.array(z.string().min(1)).min(1).max(100).describe('Keywords to get AI volume for (e.g. ["plumber near me", "emergency plumber"])'),
      location: z.string().optional().describe('Location for results (e.g. "Miami, FL"). Default: US'),
    },
    READ_ONLY,
    withErrorHandling(async ({ keywords, location }) => {
      const result = await callApi(
        "/v1/ai/keyword-data",
        { keywords, ...(location && { location }) },
        getAuth()
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

• src/tools/ai-visibility.ts:114-117 (schema)

  Zod schema for ai_keyword_data: keywords (array of strings, 1-100) and optional location string.

  {
    keywords: z.array(z.string().min(1)).min(1).max(100).describe('Keywords to get AI volume for (e.g. ["plumber near me", "emergency plumber"])'),
    location: z.string().optional().describe('Location for results (e.g. "Miami, FL"). Default: US'),
  },

• src/tools/ai-visibility.ts:111-127 (registration)

  Registration of ai_keyword_data tool via server.tool() in registerAIVisibilityTools function.

  server.tool(
    "ai_keyword_data",
    "Get AI search volume and trends for keywords — how often they're searched in ChatGPT and other LLMs. Costs 1 credit per 50 keywords.",
    {
      keywords: z.array(z.string().min(1)).min(1).max(100).describe('Keywords to get AI volume for (e.g. ["plumber near me", "emergency plumber"])'),
      location: z.string().optional().describe('Location for results (e.g. "Miami, FL"). Default: US'),
    },
    READ_ONLY,
    withErrorHandling(async ({ keywords, location }) => {
      const result = await callApi(
        "/v1/ai/keyword-data",
        { keywords, ...(location && { location }) },
        getAuth()
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

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

  registerAIVisibilityTools is called here in createMcpServer to register all AI visibility tools including ai_keyword_data.

  registerAIVisibilityTools(server, getAuth);

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

  withErrorHandling wrapper used by the ai_keyword_data handler to catch and surface errors as MCP 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,
        };
      }
    };
  }