get_area_schedule

Instructions

Implementation Reference

• src/index.ts:101-153 (registration)

  The tool 'get_area_schedule' is registered with the MCP server using server.tool(). The handler accepts area_id and test parameters, calls client.getAreaInfo(), and formats the response with upcoming events and schedule for the next 3 days.

  // ── Tool 3: Get area schedule ────────────────────────────────────────────────
  server.tool(
    "get_area_schedule",
    "Get the upcoming load shedding schedule and events for a specific area. Requires an area ID — use search_areas first if you don't have one.",
    {
      area_id: z
        .string()
        .describe("The area ID from search_areas (e.g. 'eskmo-7-stellenboschstellenboschwestern-cape')"),
      test: z
        .boolean()
        .optional()
        .default(false)
        .describe("Use test data (does not count against your quota)"),
    },
    async ({ area_id, test }) => {
      const data = await client.getAreaInfo(area_id, test);
  
      const events = data.events.length
        ? data.events
            .map((e) => `- 🚫 **${e.note}**\n  From: ${e.start}\n  Until: ${e.end}`)
            .join("\n")
        : "✅ No upcoming load shedding events scheduled.";
  
      const schedule = data.schedule.days
        .slice(0, 3)
        .map((day) => {
          const slots = day.stages
            .map((stage, i) => (stage.length ? `  Stage ${i + 1}: ${stage.join(", ")}` : null))
            .filter(Boolean)
            .join("\n");
          return `**${day.name} (${day.date})**\n${slots || "  No slots"}`;
        })
        .join("\n\n");
  
      return {
        content: [
          {
            type: "text",
            text: [
              `## ⚡ Load Shedding Schedule — ${data.info.name}`,
              `Region: ${data.info.region}`,
              "",
              "### Upcoming Events",
              events,
              "",
              "### Schedule (next 3 days)",
              schedule,
            ].join("\n"),
          },
        ],
      };
    }
  );

• src/index.ts:115-152 (handler)

  The async handler function for get_area_schedule. It calls client.getAreaInfo(area_id, test), maps events into a formatted list, slices schedule.days to 3 days with stage slots, and returns text content with the area name, region, upcoming events, and schedule.

  async ({ area_id, test }) => {
    const data = await client.getAreaInfo(area_id, test);
  
    const events = data.events.length
      ? data.events
          .map((e) => `- 🚫 **${e.note}**\n  From: ${e.start}\n  Until: ${e.end}`)
          .join("\n")
      : "✅ No upcoming load shedding events scheduled.";
  
    const schedule = data.schedule.days
      .slice(0, 3)
      .map((day) => {
        const slots = day.stages
          .map((stage, i) => (stage.length ? `  Stage ${i + 1}: ${stage.join(", ")}` : null))
          .filter(Boolean)
          .join("\n");
        return `**${day.name} (${day.date})**\n${slots || "  No slots"}`;
      })
      .join("\n\n");
  
    return {
      content: [
        {
          type: "text",
          text: [
            `## ⚡ Load Shedding Schedule — ${data.info.name}`,
            `Region: ${data.info.region}`,
            "",
            "### Upcoming Events",
            events,
            "",
            "### Schedule (next 3 days)",
            schedule,
          ].join("\n"),
        },
      ],
    };
  }

• src/index.ts:106-114 (schema)

  Input validation schema for get_area_schedule: area_id (string, required) and test (boolean, optional, default false).

    area_id: z
      .string()
      .describe("The area ID from search_areas (e.g. 'eskmo-7-stellenboschstellenboschwestern-cape')"),
    test: z
      .boolean()
      .optional()
      .default(false)
      .describe("Use test data (does not count against your quota)"),
  },

• src/client.ts:73-78 (helper)

  The EskomSePushClient.getAreaInfo() method that makes the actual HTTP GET request to /area endpoint with the area ID.

  async getAreaInfo(id: string, test = false): Promise<AreaInfo> {
    const params: Record<string, string> = { id };
    if (test) params.test = "current";
    const { data } = await this.http.get<AreaInfo>("/area", { params });
    return data;
  }

• src/client.ts:32-36 (schema)

  Type definitions for the AreaInfo interface (events, info.name, info.region, schedule.days) used by get_area_schedule.

  export interface AreaInfo {
    events: AreaEvent[];
    info: { name: string; region: string };
    schedule: { days: AreaDay[]; source: string };
  }