wordstat_get_top

Instructions

Implementation Reference

• src/register-tools.ts:201-257 (registration)

  Registration of the 'wordstat_get_top' tool with input schema and handler on the MCP server.

  server.registerTool(
    "wordstat_get_top",
    {
      description:
        "Get popular and related search queries for a keyword using Yandex Wordstat.",
      inputSchema: {
        phrase: z
          .string()
          .min(1)
          .max(400)
          .describe("Keyword/phrase to analyze in Wordstat."),
        numPhrases: z
          .number()
          .int()
          .min(1)
          .max(2000)
          .optional()
          .describe("How many top phrases to return. Default is 20."),
        regions: z
          .array(z.string().min(1))
          .max(100)
          .optional()
          .describe("Optional list of region IDs to filter statistics."),
        devices: z
          .array(WordstatDeviceSchema)
          .max(3)
          .optional()
          .describe("Optional device filter: all/desktop/phone/tablet."),
      },
    },
    async ({ phrase, numPhrases, regions, devices }) => {
      return withToolErrorHandling(async () => {
        const response = await client.post<Record<string, unknown>>("/v2/wordstat/topRequests", {
          phrase,
          numPhrases: numPhrases ?? 20,
          ...(regions !== undefined ? { regions } : {}),
          ...(devices !== undefined ? { devices } : {}),
        });
  
        const structuredContent = {
          totalCount: response.totalCount,
          results: response.results,
          associations: response.associations,
        };
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(structuredContent, null, 2),
            },
          ],
          structuredContent,
        };
      });
    },
  );

• src/register-tools.ts:231-256 (handler)

  Handler function for wordstat_get_top that calls the Yandex API endpoint /v2/wordstat/topRequests and returns structured content with totalCount, results, and associations.

  async ({ phrase, numPhrases, regions, devices }) => {
    return withToolErrorHandling(async () => {
      const response = await client.post<Record<string, unknown>>("/v2/wordstat/topRequests", {
        phrase,
        numPhrases: numPhrases ?? 20,
        ...(regions !== undefined ? { regions } : {}),
        ...(devices !== undefined ? { devices } : {}),
      });
  
      const structuredContent = {
        totalCount: response.totalCount,
        results: response.results,
        associations: response.associations,
      };
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(structuredContent, null, 2),
          },
        ],
        structuredContent,
      };
    });
  },

• src/register-tools.ts:207-230 (schema)

  Input schema for wordstat_get_top: phrase (required), numPhrases (optional, default 20), regions (optional array of region IDs), devices (optional array of device filters).

      phrase: z
        .string()
        .min(1)
        .max(400)
        .describe("Keyword/phrase to analyze in Wordstat."),
      numPhrases: z
        .number()
        .int()
        .min(1)
        .max(2000)
        .optional()
        .describe("How many top phrases to return. Default is 20."),
      regions: z
        .array(z.string().min(1))
        .max(100)
        .optional()
        .describe("Optional list of region IDs to filter statistics."),
      devices: z
        .array(WordstatDeviceSchema)
        .max(3)
        .optional()
        .describe("Optional device filter: all/desktop/phone/tablet."),
    },
  },

• src/register-tools.ts:58-69 (helper)

  withToolErrorHandling helper function that wraps handler logic and converts YandexApiError to user-friendly error messages.

  async function withToolErrorHandling<T>(action: () => Promise<T>): Promise<T> {
    try {
      return await action();
    } catch (error) {
      if (error instanceof YandexApiError) {
        const detailsText =
          error.details == null ? "" : ` Details: ${JSON.stringify(error.details, null, 2)}`;
        throw new Error(`Yandex Search API error (${error.status}).${detailsText}`);
      }
      throw new Error(`Unhandled error: ${toErrorMessage(error)}`);
    }
  }