local_authority

Instructions

Implementation Reference

• src/tools/intelligence.ts:11-28 (handler)

  The registerIntelligenceTools function registers the 'local_authority' tool on the MCP server. Lines 13-29 define the tool: name 'local_authority', description about calculating a Local Authority Score (0-100), schema with business_name (required string), location (required string), and keyword (optional string). The handler calls the API endpoint '/v1/score/local-authority' with the input parameters and returns the result.

  export function registerIntelligenceTools(server: McpServer, getAuth: () => string) {
    server.tool(
      "local_authority",
      "Calculate a Local Authority Score (0-100) based on rankings, reviews, profile completeness, and citations. Includes a breakdown of each component and a percentile ranking. Costs 10 credits.",
      {
        business_name: z.string().describe("Business name"),
        location: z.string().describe("City and state"),
        keyword: z.string().optional().describe("Keyword to evaluate authority for (defaults to business name)"),
      },
      READ_ONLY,
      withErrorHandling(async ({ business_name, location, keyword }) => {
        const result = await callApi(
          "/v1/score/local-authority",
          { business_name, location, ...(keyword && { keyword }) },
          getAuth()
        );
        return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
      })

• src/tools/intelligence.ts:15-19 (schema)

  Zod schema for the 'local_authority' tool inputs: business_name (required string), location (required string), keyword (optional string, defaults to business name).

  {
    business_name: z.string().describe("Business name"),
    location: z.string().describe("City and state"),
    keyword: z.string().optional().describe("Keyword to evaluate authority for (defaults to business name)"),
  },

• src/server.ts:41-51 (registration)

  Registration of the intelligence tools (including 'local_authority') via registerIntelligenceTools(server, getAuth) in the MCP server setup.

    registerIntelligenceTools(server, getAuth);
    registerKeywordTools(server, getAuth);
    registerBacklinkTools(server, getAuth);
    registerSiteTools(server, getAuth);
    registerAIVisibilityTools(server, getAuth);
    registerCompetitiveTools(server, getAuth);
    registerLocationTools(server, getAuth);
    registerDiagnosticTools(server, getAuth);
  
    return server;
  }

• src/api-client.ts:25-38 (helper)

  The callApi helper function that sends a POST request to API_BASE_URL + path (here '/v1/score/local-authority') with JSON body and Authorization header, returning the response data and metadata.

  export async function callApi(
    path: string,
    body: Record<string, unknown>,
    authHeader: string,
    timeoutMs = 60_000
  ): Promise<{ data: unknown; credits_used: number; credits_remaining: number; cached: boolean }> {
    const url = `${env.API_BASE_URL}${path}`;
  
    console.log(`[api] POST ${url} (timeout: ${timeoutMs / 1000}s, auth: ${authHeader ? `${authHeader.slice(0, 15)}...` : "MISSING"})`);
  
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",

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

  The withErrorHandling wrapper that catches errors thrown by the tool 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,
        };
      }
    };
  }