keyword_trends

Instructions

Implementation Reference

• src/tools/keywords.ts:103-111 (handler)

  The async handler function that executes the keyword_trends tool logic. It calls the API at /v1/keywords/trends with keywords, location, and an optional period parameter.

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

• src/tools/keywords.ts:96-101 (schema)

  Input schema for keyword_trends: keywords (array of 1-5 strings), location (string), and optional period (enum: '3m', '6m', '12m', '5y').

  "Get search trend data for up to 5 keywords over time. Periods: 3m, 6m, 12m (default), 5y. Costs 1 credit.",
  {
    keywords: z.array(z.string().min(1)).min(1).max(5).describe("Keywords to get trends for"),
    location: z.string().min(1).describe('Geographic location (e.g. "Orchard Park, NY")'),
    period: z.enum(["3m", "6m", "12m", "5y"]).optional().describe('Time period. Default: "12m"'),
  },

• src/tools/keywords.ts:94-111 (registration)

  Registration of the 'keyword_trends' tool via server.tool() within registerKeywordTools(), with READ_ONLY hint and description about cost and usage.

  server.tool(
    "keyword_trends",
    "Get search trend data for up to 5 keywords over time. Periods: 3m, 6m, 12m (default), 5y. Costs 1 credit.",
    {
      keywords: z.array(z.string().min(1)).min(1).max(5).describe("Keywords to get trends for"),
      location: z.string().min(1).describe('Geographic location (e.g. "Orchard Park, NY")'),
      period: z.enum(["3m", "6m", "12m", "5y"]).optional().describe('Time period. Default: "12m"'),
    },
    READ_ONLY,
    withErrorHandling(async ({ keywords, location, period }) => {
      const result = await callApi(
        "/v1/keywords/trends",
        { keywords, location, ...(period && { period }) },
        getAuth()
      );
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

• src/server.ts:42-42 (registration)

  Registration call registerKeywordTools(server, getAuth) that wires up the keyword_trends tool into the MCP server.

  registerKeywordTools(server, getAuth);

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

  withErrorHandling wrapper used by the keyword_trends handler to catch and surface errors as MCP error content.

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