reputation_audit

Instructions

Implementation Reference

• src/tools/audit.ts:77-86 (handler)

  The reputation_audit tool handler: calls API endpoint /v1/audit/reputation with business_name and location, returns formatted results. Uses a 120-second timeout.

    withErrorHandling(async ({ business_name, location }) => {
      const result = await callApi(
        "/v1/audit/reputation",
        { business_name, location },
        getAuth(),
        120_000
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

• src/tools/audit.ts:72-75 (schema)

  Input schema for reputation_audit: requires business_name (string) and location (string).

  {
    business_name: z.string().describe("Business name"),
    location: z.string().describe("City and state"),
  },

• src/tools/audit.ts:69-86 (registration)

  Tool registration via server.tool('reputation_audit', ...) inside registerAuditTools function. Description notes 30 credit cost and 10-30 second response time.

  server.tool(
    "reputation_audit",
    "Audit online reputation across review platforms. Returns a reputation score, sentiment analysis (positive/negative themes), response rate, and recommendations. Costs 30 credits. Note: this tool queries multiple review sources and may take 10-30 seconds to return — this is normal, not an error.",
    {
      business_name: z.string().describe("Business name"),
      location: z.string().describe("City and state"),
    },
    READ_ONLY,
    withErrorHandling(async ({ business_name, location }) => {
      const result = await callApi(
        "/v1/audit/reputation",
        { business_name, location },
        getAuth(),
        120_000
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

• src/tools/audit.ts:12-36 (helper)

  pollAsyncJob helper: polls an async job URL until 'complete' or 'failed' status, with exponential backoff up to 3 minutes. Not used by reputation_audit (which is synchronous), but a shared helper in the same module.

  async function pollAsyncJob(
    pollUrl: string,
    auth: string,
    maxWaitMs: number = 180_000
  ): Promise<{ data: unknown; credits_used: number; credits_remaining: number; cached: boolean }> {
    const start = Date.now();
    let delay = 2000;
  
    while (Date.now() - start < maxWaitMs) {
      await new Promise((r) => setTimeout(r, delay));
      const result = await callApiGet(pollUrl, auth);
      const data = result.data as Record<string, unknown>;
  
      if (data.status === "complete") {
        return result;
      }
      if (data.status === "failed") {
        throw new Error((data.error as string) || "Audit job failed");
      }
      // Still pending/running — increase delay up to 4s
      delay = Math.min(delay * 1.3, 4000);
    }
  
    throw new Error("Audit timed out after 3 minutes. The job may still be processing — try polling the status URL.");
  }

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

  withErrorHandling wrapper and formatResult helper used by the reputation_audit handler to catch errors and format API responses.

  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,
        };
      }
    };
  }