ai_mode
Read-only
Retrieve Google AI Mode responses for local search queries. Returns AI-generated text, reference links, and shopping items to assess AI visibility in search results.
Instructions
Get Google AI Mode response for a keyword and location. Returns the AI-generated response text, reference links, and shopping items. Costs 2 credits.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Search keyword (e.g. "best plumber near me") | |
| location | Yes | City and state (e.g. "Orchard Park, NY") |
Implementation Reference
- src/tools/serp.ts:11-11 (registration)The registerSerpTools function is called from server.ts, which registers the 'ai_mode' tool via server.tool()
export function registerSerpTools(server: McpServer, getAuth: () => string) { - src/tools/serp.ts:113-125 (handler)The 'ai_mode' tool handler: calls the API endpoint /v1/serp/ai-mode with keyword/location and returns formatted results.
server.tool( "ai_mode", "Get Google AI Mode response for a keyword and location. Returns the AI-generated response text, reference links, and shopping items. Costs 2 credits.", { keyword: z.string().describe('Search keyword (e.g. "best plumber near me")'), location: z.string().describe('City and state (e.g. "Orchard Park, NY")'), }, READ_ONLY, withErrorHandling(async ({ keyword, location }) => { const result = await callApi("/v1/serp/ai-mode", { keyword, location }, getAuth()); return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] }; }) ); - src/tools/serp.ts:116-119 (schema)Zod schema for 'ai_mode' tool inputs: keyword (string) and location (string), both required.
{ keyword: z.string().describe('Search keyword (e.g. "best plumber near me")'), location: z.string().describe('City and state (e.g. "Orchard Park, NY")'), }, - src/api-client.ts:143-158 (helper)withErrorHandling wrapper that catches errors from the handler and returns 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, }; } }; } - src/api-client.ts:132-138 (helper)formatResult helper that formats API response data along with credit metadata into a display string.
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)}`; }