brand_mentions

Instructions

Implementation Reference

• src/tools/competitive.ts:45-53 (handler)

  The handler function for the brand_mentions tool. Calls POST /v1/brand/mentions with business_name and optional limit, then formats the result.

    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:40-43 (schema)

  Input schema for brand_mentions: business_name (string, required) and limit (number, optional, max 100).

  {
    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"),
  },

• src/tools/competitive.ts:37-53 (registration)

  Registration of the 'brand_mentions' tool on the MCP server via server.tool() inside registerCompetitiveTools.

  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/server.ts:14-46 (registration)

  Import and registration call of registerCompetitiveTools which registers brand_mentions on the MCP server.

  import { registerCompetitiveTools } from "./tools/competitive.js";
  import { registerLocationTools } from "./tools/locations.js";
  import { registerAccountTools } from "./tools/account.js";
  
  export function createMcpServer(getAuth: () => string): McpServer {
    const server = new McpServer({
      name: "localseodata",
      version: "1.0.0",
      description: `LocalSEOData — Local SEO intelligence API.
  
  IMPORTANT — Credit budget awareness:
  1. ALWAYS call get_balance FIRST before starting any analysis. This is free (0 credits).
  2. Plan your tool usage based on the available balance. Each tool description includes its credit cost.
  3. Prefer cheaper tools when possible: local_pack (1 cr) over local_audit (50 cr) when a full audit isn't needed.
  4. For multi-step analyses, estimate total cost upfront and warn the user if it will exceed 50% of their balance.
  5. Composite tools (local_audit, citation_audit, geogrid_scan) are premium — confirm with the user before using them.
  6. Every successful tool call response includes credits_used and credits_remaining — monitor these as you work.
  7. If a tool returns an insufficient credits error, inform the user of their balance and the cost required.`,
    });
  
    registerAccountTools(server, getAuth);
    registerSerpTools(server, getAuth);
    registerBusinessTools(server, getAuth);
    registerReviewTools(server, getAuth);
    registerAuditTools(server, getAuth);
    registerGeogridTools(server, getAuth);
    registerReportTools(server, getAuth);
    registerIntelligenceTools(server, getAuth);
    registerKeywordTools(server, getAuth);
    registerBacklinkTools(server, getAuth);
    registerSiteTools(server, getAuth);
    registerAIVisibilityTools(server, getAuth);
    registerCompetitiveTools(server, getAuth);

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

  The withErrorHandling helper wraps the tool handler to catch errors and return MCP-friendly error content.

  type ToolResult = { content: { type: "text"; text: string }[]; isError?: boolean };
  
  /** Wrap an MCP tool handler so thrown errors always surface 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,
        };
      }
    };
  }