get_multiple_series

Instructions

Implementation Reference

• src/tools/series.ts:104-120 (handler)

  Handler function for the get_multiple_series tool. Calls client.getSeriesData with series_ids, start_year, end_year, catalog, calculations, annual_average, and aspects parameters, then returns the JSON-stringified result.

    async ({ series_ids, start_year, end_year, catalog, calculations, annual_average, aspects }) => {
      try {
        const data = await client.getSeriesData({
          seriesid: series_ids,
          startyear: start_year,
          endyear: end_year,
          catalog,
          calculations,
          annualaverage: annual_average,
          aspects,
        });
        return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
      } catch (error) {
        return wrapError(error);
      }
    }
  );

• src/tools/series.ts:69-103 (schema)

  Zod schema for get_multiple_series inputs: series_ids (array of 1-50 strings matching SERIES_ID_PATTERN), optional start_year, end_year (4-digit strings), and optional booleans catalog, calculations, annual_average, aspects.

  {
    series_ids: z
      .array(
        z.string().regex(SERIES_ID_PATTERN, "Each series ID must be uppercase with no special characters except _, -, #")
      )
      .min(1)
      .max(50)
      .describe("Array of BLS series IDs"),
    start_year: z
      .string()
      .regex(/^\d{4}$/, "Must be a 4-digit year")
      .optional()
      .describe("Start year in YYYY format"),
    end_year: z
      .string()
      .regex(/^\d{4}$/, "Must be a 4-digit year")
      .optional()
      .describe("End year in YYYY format"),
    catalog: z
      .boolean()
      .optional()
      .describe("Include catalog data (requires registration key)"),
    calculations: z
      .boolean()
      .optional()
      .describe("Include calculations such as net and percent changes (requires registration key)"),
    annual_average: z
      .boolean()
      .optional()
      .describe("Include annual average data (requires registration key)"),
    aspects: z
      .boolean()
      .optional()
      .describe("Include aspect data (requires registration key)"),
  },

• src/tools/series.ts:63-120 (registration)

  Registration of the tool named 'get_multiple_series' via server.tool() within registerSeriesTools(), along with its description.

  server.tool(
    "get_multiple_series",
    "Retrieve data for one or more BLS time series. " +
      "Registered users can include up to 50 series IDs. " +
      "Optionally specify start/end years (up to 20-year range), " +
      "and enable catalog, calculations, annual averages, or aspects.",
    {
      series_ids: z
        .array(
          z.string().regex(SERIES_ID_PATTERN, "Each series ID must be uppercase with no special characters except _, -, #")
        )
        .min(1)
        .max(50)
        .describe("Array of BLS series IDs"),
      start_year: z
        .string()
        .regex(/^\d{4}$/, "Must be a 4-digit year")
        .optional()
        .describe("Start year in YYYY format"),
      end_year: z
        .string()
        .regex(/^\d{4}$/, "Must be a 4-digit year")
        .optional()
        .describe("End year in YYYY format"),
      catalog: z
        .boolean()
        .optional()
        .describe("Include catalog data (requires registration key)"),
      calculations: z
        .boolean()
        .optional()
        .describe("Include calculations such as net and percent changes (requires registration key)"),
      annual_average: z
        .boolean()
        .optional()
        .describe("Include annual average data (requires registration key)"),
      aspects: z
        .boolean()
        .optional()
        .describe("Include aspect data (requires registration key)"),
    },
    async ({ series_ids, start_year, end_year, catalog, calculations, annual_average, aspects }) => {
      try {
        const data = await client.getSeriesData({
          seriesid: series_ids,
          startyear: start_year,
          endyear: end_year,
          catalog,
          calculations,
          annualaverage: annual_average,
          aspects,
        });
        return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
      } catch (error) {
        return wrapError(error);
      }
    }
  );

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

  Top-level registration: registerSeriesTools(server, client) is called from index.ts to register all series tools including get_multiple_series.

  registerSeriesTools(server, client);
  registerSurveyTools(server, client);

• src/client.ts:17-26 (helper)

  SeriesDataParams interface used by getSeriesData, defining the shape of parameters accepted by the BLS API for fetching multiple series data.

  export interface SeriesDataParams {
    seriesid: string[];
    startyear?: string;
    endyear?: string;
    catalog?: boolean;
    calculations?: boolean;
    annualaverage?: boolean;
    aspects?: boolean;
    registrationkey?: string;
  }