competitor_ads

Instructions

Implementation Reference

• src/tools/competitive.ts:11-54 (registration)

  The function registerCompetitiveTools registers multiple competitive tools on the McpServer, including 'competitor_ads' (line 13).

  export function registerCompetitiveTools(server: McpServer, getAuth: () => string) {
    server.tool(
      "competitor_ads",
      "Find Google Ads campaigns from a competitor domain. Returns ad copy, keywords, and landing pages. Costs 2 credits.",
      {
        domain: z.string().min(1).describe('Competitor domain (e.g. "competitor.com")'),
        location: z.string().optional().describe("Geographic location filter"),
        format: z.enum(["text", "image", "video"]).optional().describe("Ad format filter"),
        limit: z.number().int().min(1).max(100).optional().describe("Max ads. Default: 20, max: 100"),
      },
      READ_ONLY,
      withErrorHandling(async ({ domain, location, format, limit }) => {
        const result = await callApi(
          "/v1/ads/competitor",
          {
            domain,
            ...(location && { location }),
            ...(format && { format }),
            ...(limit && { limit }),
          },
          getAuth()
        );
        return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
      })
    );
  
    server.tool(
      "brand_mentions",
      "Find online mentions of a brand across the web. Returns mention sources, sentiment, and context. Costs 3 credits.",
      {
        business_name: z.string().min(1).describe("Business or brand name to search for"),
        limit: z.number().int().min(1).max(100).optional().describe("Max mentions. Default: 20, max: 100"),
      },
      READ_ONLY,
      withErrorHandling(async ({ business_name, limit }) => {
        const result = await callApi(
          "/v1/brand/mentions",
          { business_name, ...(limit && { limit }) },
          getAuth()
        );
        return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
      })
    );
  }

• src/tools/competitive.ts:12-35 (handler)

  The 'competitor_ads' tool handler: accepts domain (required), location, format, limit params; calls POST /v1/ads/competitor with those params via callApi helper; returns text content with formatted API result.

  server.tool(
    "competitor_ads",
    "Find Google Ads campaigns from a competitor domain. Returns ad copy, keywords, and landing pages. Costs 2 credits.",
    {
      domain: z.string().min(1).describe('Competitor domain (e.g. "competitor.com")'),
      location: z.string().optional().describe("Geographic location filter"),
      format: z.enum(["text", "image", "video"]).optional().describe("Ad format filter"),
      limit: z.number().int().min(1).max(100).optional().describe("Max ads. Default: 20, max: 100"),
    },
    READ_ONLY,
    withErrorHandling(async ({ domain, location, format, limit }) => {
      const result = await callApi(
        "/v1/ads/competitor",
        {
          domain,
          ...(location && { location }),
          ...(format && { format }),
          ...(limit && { limit }),
        },
        getAuth()
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

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

  The input schema for 'competitor_ads' defines domain (string), location (optional string), format (optional enum: text/image/video), and limit (optional int 1-100).

  {
    domain: z.string().min(1).describe('Competitor domain (e.g. "competitor.com")'),
    location: z.string().optional().describe("Geographic location filter"),
    format: z.enum(["text", "image", "video"]).optional().describe("Ad format filter"),
    limit: z.number().int().min(1).max(100).optional().describe("Max ads. Default: 20, max: 100"),
  },

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

  The 'registerCompetitiveTools' function is imported from ./tools/competitive.js.

  import { registerCompetitiveTools } from "./tools/competitive.js";

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

  registerCompetitiveTools is called in createMcpServer with the server instance and auth getter.

  registerCompetitiveTools(server, getAuth);