keyword_suggestions

Instructions

Implementation Reference

• src/tools/keywords.ts:41-53 (handler)

  The handler function for the 'keyword_suggestions' tool. It calls the API endpoint /v1/keywords/suggestions with the keyword, location, optional limit, and optional include_seed_keyword parameters, then formats the result.

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

• src/tools/keywords.ts:34-39 (schema)

  Zod schema for input validation: keyword (required string), location (required string), limit (optional number 1-1000), include_seed_keyword (optional boolean).

  {
    keyword: z.string().min(1).describe('Seed keyword (e.g. "plumber")'),
    location: z.string().min(1).describe('Geographic location (e.g. "Orchard Park, NY")'),
    limit: z.number().int().min(1).max(1000).optional().describe("Max suggestions. Default: 50, max: 1000"),
    include_seed_keyword: z.boolean().optional().describe("Include seed keyword in results. Default: true"),
  },

• src/tools/keywords.ts:31-54 (registration)

  Registration of 'keyword_suggestions' tool via server.tool() inside registerKeywordTools(), with description 'Get keyword suggestions for a seed keyword...' and READ_ONLY hint.

  server.tool(
    "keyword_suggestions",
    "Get keyword suggestions for a seed keyword. Returns related keywords with search volume and metrics. Costs 2 credits.",
    {
      keyword: z.string().min(1).describe('Seed keyword (e.g. "plumber")'),
      location: z.string().min(1).describe('Geographic location (e.g. "Orchard Park, NY")'),
      limit: z.number().int().min(1).max(1000).optional().describe("Max suggestions. Default: 50, max: 1000"),
      include_seed_keyword: z.boolean().optional().describe("Include seed keyword in results. Default: true"),
    },
    READ_ONLY,
    withErrorHandling(async ({ keyword, location, limit, include_seed_keyword }) => {
      const result = await callApi(
        "/v1/keywords/suggestions",
        {
          keyword,
          location,
          ...(limit && { limit }),
          ...(include_seed_keyword !== undefined && { include_seed_keyword }),
        },
        getAuth()
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

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

  The callApi helper invoked by the handler to make the POST request to the API. It sends the request with auth headers and returns data with credit 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",
        Authorization: authHeader,
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
    });
  
    if (!response.ok) {
      const text = await response.text();
      console.error(`[api] ${response.status} ${response.statusText} from ${path}: ${text.slice(0, 200)}`);
      // Try to parse as structured error
      try {
        const result = JSON.parse(text) as ApiErrorResponse;
        if (result.status === "error") {
          const err = result.error;
          const reqId = result.request_id ? ` [request_id: ${result.request_id}]` : "";
          throw new Error(
            err.required_credits
              ? `${err.message} (requires ${err.required_credits} credits, balance: ${err.current_balance})${reqId}`
              : `${err.message}${reqId}`
          );
        }
      } catch (parseErr) {
        if (parseErr instanceof Error && parseErr.message !== "error") {
          // Re-throw if it's our structured error from above
          if (!text.includes('"status":"error"')) {
            throw new Error(`API returned ${response.status}: ${text.slice(0, 200)}`);
          }
          throw parseErr;
        }
      }
      throw new Error(`API returned ${response.status}: ${text.slice(0, 200)}`);
    }
  
    const result = (await response.json()) as ApiResponse;
  
    if (result.status === "error") {
      const err = (result as ApiErrorResponse).error;
      const reqId = (result as ApiErrorResponse).request_id ? ` [request_id: ${(result as ApiErrorResponse).request_id}]` : "";
      throw new Error(
        err.required_credits
          ? `${err.message} (requires ${err.required_credits} credits, balance: ${err.current_balance})${reqId}`
          : `${err.message}${reqId}`
      );
    }
  
    console.log(`[api] ${path} OK (${result.credits_used} credits used, ${result.credits_remaining} remaining)`);
  
    return {
      data: result.data,
      credits_used: result.credits_used,
      credits_remaining: result.credits_remaining,
      cached: result.cached,
    };
  }

• src/api-client.ts:132-138 (helper)

  The formatResult helper used by the handler to format the response data into a text string with credit usage metadata.

  export function formatResult(
    data: unknown,
    meta: { credits_used: number; credits_remaining: number; cached: boolean }
  ): string {
    const metaLine = `[${meta.credits_used} credit${meta.credits_used !== 1 ? "s" : ""} used | ${meta.credits_remaining} remaining${meta.cached ? " | cached" : ""}]`;
    return `${metaLine}\n\n${JSON.stringify(data, null, 2)}`;
  }