BLS MCP

Instructions

Implementation Reference

• src/tools/surveys.ts:33-40 (handler)

  The handler function for 'get_popular_series' which calls the underlying client method and formats the response.

  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/tools/surveys.ts:22-41 (registration)

  Registration of the 'get_popular_series' tool with its schema definition and handler.

  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 API implementation of getPopularSeries in the Client class.

  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);
    }
  }