ai_mentions

Instructions

Implementation Reference

• src/tools/ai-visibility.ts:22-29 (handler)

  The handler function for the 'ai_mentions' tool. Calls the API endpoint '/v1/ai/mentions' with keyword, location, platforms, and limit parameters, then formats and returns the result.

  withErrorHandling(async ({ keyword, location, platforms, limit }) => {
    const result = await callApi(
      "/v1/ai/mentions",
      { keyword, ...(location && { location }), ...(platforms && { platforms }), ...(limit && { limit }) },
      getAuth()
    );
    return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
  })

• src/tools/ai-visibility.ts:15-20 (schema)

  Zod schema definitions for the 'ai_mentions' tool inputs: keyword (required string), location (optional string), platforms (optional array of 'chat_gpt' or 'google'), and limit (optional int 1-100).

  {
    keyword: z.string().min(1).describe('Keyword to search for (e.g. "best plumber in Buffalo")'),
    location: z.string().optional().describe('Location for results (e.g. "Portland, OR"). Default: US'),
    platforms: z.array(z.enum(["chat_gpt", "google"])).optional().describe("Platforms to query. Default: all"),
    limit: z.number().int().min(1).max(100).optional().describe("Max mentions. Default: 10, max: 100"),
  },

• src/tools/ai-visibility.ts:12-30 (registration)

  Registration of the 'ai_mentions' tool via server.tool() with its name, description, schema, read-only flags, and handler.

  server.tool(
    "ai_mentions",
    "Find where a keyword appears in AI model outputs (ChatGPT, Google AI). Returns mention context and sources. Costs 5 credits.",
    {
      keyword: z.string().min(1).describe('Keyword to search for (e.g. "best plumber in Buffalo")'),
      location: z.string().optional().describe('Location for results (e.g. "Portland, OR"). Default: US'),
      platforms: z.array(z.enum(["chat_gpt", "google"])).optional().describe("Platforms to query. Default: all"),
      limit: z.number().int().min(1).max(100).optional().describe("Max mentions. Default: 10, max: 100"),
    },
    READ_ONLY,
    withErrorHandling(async ({ keyword, location, platforms, limit }) => {
      const result = await callApi(
        "/v1/ai/mentions",
        { keyword, ...(location && { location }), ...(platforms && { platforms }), ...(limit && { limit }) },
        getAuth()
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

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

  Registration of the registerAIVisibilityTools function in the MCP server setup, which is how the 'ai_mentions' tool gets included in the server.

  registerAIVisibilityTools(server, getAuth);

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

  The 'withErrorHandling' wrapper that catches errors thrown by the ai_mentions handler and formats 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,
        };
      }
    };
  }