search_areas

Instructions

Implementation Reference

• src/index.ts:59-98 (registration)

  The search_areas tool is registered with the MCP server. It accepts a 'text' (area name to search) and optional 'test' boolean. Calls client.searchAreas() and formats the results.

  // ── Tool 2: Search for areas ─────────────────────────────────────────────────
  server.tool(
    "search_areas",
    "Search for load shedding areas by name or suburb. Returns area IDs you can use with get_area_schedule. Always search first if you don't have an area ID.",
    {
      text: z.string().describe("Suburb, city, or area name to search for (e.g. 'Stellenbosch', 'Sandton', 'Ballito')"),
      test: z
        .boolean()
        .optional()
        .default(false)
        .describe("Use test data (does not count against your quota)"),
    },
    async ({ text, test }) => {
      const data = await client.searchAreas(text, test);
  
      if (!data.areas.length) {
        return {
          content: [{ type: "text", text: `No areas found for "${text}". Try a broader search term.` }],
        };
      }
  
      const list = data.areas
        .map((a) => `- **${a.name}** (${a.region})\n  ID: \`${a.id}\``)
        .join("\n");
  
      return {
        content: [
          {
            type: "text",
            text: [
              `## 🔍 Areas matching "${text}"`,
              "",
              list,
              "",
              "Use the area ID with `get_area_schedule` to see upcoming load shedding events.",
            ].join("\n"),
          },
        ],
      };
    }

• src/index.ts:71-98 (handler)

  The handler function for search_areas tool. Calls the client, handles empty results, formats a markdown list of areas with name, region, and ID, and returns a text content block.

  async ({ text, test }) => {
    const data = await client.searchAreas(text, test);
  
    if (!data.areas.length) {
      return {
        content: [{ type: "text", text: `No areas found for "${text}". Try a broader search term.` }],
      };
    }
  
    const list = data.areas
      .map((a) => `- **${a.name}** (${a.region})\n  ID: \`${a.id}\``)
      .join("\n");
  
    return {
      content: [
        {
          type: "text",
          text: [
            `## 🔍 Areas matching "${text}"`,
            "",
            list,
            "",
            "Use the area ID with `get_area_schedule` to see upcoming load shedding events.",
          ].join("\n"),
        },
      ],
    };
  }

• src/client.ts:66-71 (helper)

  The EskomSePushClient.searchAreas method. Sends a GET request to /areas_search with the text query and optional test parameter, returning AreasSearchResult which contains an array of Area objects (id, name, region).

  async searchAreas(text: string, test = false): Promise<AreasSearchResult> {
    const params: Record<string, string> = { text };
    if (test) params.test = "true";
    const { data } = await this.http.get<AreasSearchResult>("/areas_search", { params });
    return data;
  }

• src/client.ts:10-18 (schema)

  Type definitions for search_areas responses: Area (id, name, region) and AreasSearchResult wrapping an array of Areas.

  export interface Area {
    id: string;
    name: string;
    region: string;
  }
  
  export interface AreasSearchResult {
    areas: Area[];
  }