get_popular_series

Instructions

Implementation Reference

• src/tools/surveys.ts:21-41 (registration)

  Registers the 'get_popular_series' tool on the MCP server with its name, description, optional survey parameter schema (2-letter uppercase regex), and handler that calls client.getPopularSeries(survey).

  export function registerSurveyTools(server: McpServer, client: Client) {
    server.tool(
      "get_popular_series",
      "Retrieve the 25 most popular BLS series IDs overall or for a specific survey. " +
        "Optionally provide a survey abbreviation to filter by survey.",
      {
        survey: z
          .string()
          .regex(/^[A-Z]{2}$/, "Survey abbreviation must be exactly 2 uppercase letters")
          .optional()
          .describe("Optional 2-letter survey abbreviation, e.g. LA, CU, CE"),
      },
      async ({ survey }) => {
        try {
          const data = await client.getPopularSeries(survey);
          return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
        } catch (error) {
          return wrapError(error);
        }
      }
    );

• src/client.ts:98-107 (handler)

  The actual implementation of getPopularSeries: makes a GET request to /timeseries/popular with an optional survey query param and returns the raw API response data.

  async getPopularSeries(survey?: string): Promise<unknown> {
    try {
      const response = await this.http.get("/timeseries/popular", {
        params: survey ? { survey } : undefined,
      });
      return response.data;
    } catch (error) {
      this.handleError(error);
    }
  }

• src/tools/surveys.ts:26-32 (schema)

  Input schema for get_popular_series: an optional 'survey' parameter validated as a 2-letter uppercase string (e.g., LA, CU, CE).

  {
    survey: z
      .string()
      .regex(/^[A-Z]{2}$/, "Survey abbreviation must be exactly 2 uppercase letters")
      .optional()
      .describe("Optional 2-letter survey abbreviation, e.g. LA, CU, CE"),
  },

• src/tools/surveys.ts:5-19 (helper)

  wrapError helper used by the handler to format BlsApiError and unexpected errors into MCP content responses.

  function wrapError(error: unknown): { content: { type: "text"; text: string }[] } {
    if (error instanceof BlsApiError) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error: ${error.message}${error.isRateLimit ? "\nConsider setting BLS_API_KEY for higher rate limits." : ""}`,
          },
        ],
      };
    }
    return {
      content: [{ type: "text" as const, text: `Unexpected error: ${String(error)}` }],
    };
  }

• src/index.ts:16-16 (registration)

  Entry point calling registerSurveyTools(server, client), which registers get_popular_series among other survey tools.

  registerSurveyTools(server, client);