opa_get_rig_counts

Instructions

Implementation Reference

• src/index.ts:1070-1099 (registration)

  Registration of the 'opa_get_rig_counts' tool using server.tool(), with description, empty schema, and async handler callback.

  server.tool(
    "opa_get_rig_counts",
    "Get the latest US oil and gas rig count data (Baker Hughes). Use when the user asks about drilling activity, rig counts, or oil field operations. Returns oil rigs, gas rigs, total count, and week-over-week change. No parameters needed.",
    {},
    async () => {
      const response = await makeApiRequest<ApiResponse<RigCountData>>(
        "/v1/rig-counts/latest",
      );
  
      if (!response || response.status !== "success") {
        return errorResult(
          "Rig count data not available. This may require a paid plan with energy intelligence access.",
        );
      }
  
      const data = response.data;
      let text = `# US Rig Count (Baker Hughes)\n\n`;
      text += `- **Oil Rigs**: ${data.oil}\n`;
      text += `- **Gas Rigs**: ${data.gas}\n`;
      text += `- **Total**: ${data.total}\n`;
      if (data.change_from_prior_week !== undefined) {
        const sign = data.change_from_prior_week >= 0 ? "+" : "";
        text += `- **Change from Prior Week**: ${sign}${data.change_from_prior_week}\n`;
      }
      text += `- **Date**: ${data.date}\n`;
      text += `\n_Data from [OilPriceAPI](https://oilpriceapi.com)_`;
  
      return textResult(text);
    },
  );

• src/index.ts:1074-1098 (handler)

  Handler function that calls makeApiRequest to /v1/rig-counts/latest, checks for success, and formats rig count data (oil, gas, total, change_from_prior_week, date) into a text result.

  async () => {
    const response = await makeApiRequest<ApiResponse<RigCountData>>(
      "/v1/rig-counts/latest",
    );
  
    if (!response || response.status !== "success") {
      return errorResult(
        "Rig count data not available. This may require a paid plan with energy intelligence access.",
      );
    }
  
    const data = response.data;
    let text = `# US Rig Count (Baker Hughes)\n\n`;
    text += `- **Oil Rigs**: ${data.oil}\n`;
    text += `- **Gas Rigs**: ${data.gas}\n`;
    text += `- **Total**: ${data.total}\n`;
    if (data.change_from_prior_week !== undefined) {
      const sign = data.change_from_prior_week >= 0 ? "+" : "";
      text += `- **Change from Prior Week**: ${sign}${data.change_from_prior_week}\n`;
    }
    text += `- **Date**: ${data.date}\n`;
    text += `\n_Data from [OilPriceAPI](https://oilpriceapi.com)_`;
  
    return textResult(text);
  },

• src/index.ts:284-292 (schema)

  RigCountData interface defining the shape of the API response: oil, gas, total, misc (optional), change_from_prior_week (optional), date, and source (optional).

  interface RigCountData {
    oil: number;
    gas: number;
    total: number;
    misc?: number;
    change_from_prior_week?: number;
    date: string;
    source?: string;
  }

• src/index.ts:457-518 (helper)

  makeApiRequest helper function that performs HTTP requests with retry and exponential backoff, used by the rig count handler to fetch data.

  export async function makeApiRequest<T>(
    endpoint: string,
    fetchFn: typeof fetch = fetch,
  ): Promise<T | null> {
    const headers: Record<string, string> = {
      "User-Agent": USER_AGENT,
      Accept: "application/json",
    };
  
    if (API_KEY) {
      headers["Authorization"] = `Bearer ${API_KEY}`;
    }
  
    const maxRetries = 3;
  
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        const response = await fetchFn(`${API_BASE}${endpoint}`, { headers });
  
        if (response.ok) {
          return (await response.json()) as T;
        }
  
        if (response.status === 401) {
          console.error(
            "Authentication failed. Set OILPRICEAPI_KEY environment variable. Get a free key at https://oilpriceapi.com/signup",
          );
          return null;
        }
  
        // Retry on 429 and 5xx
        if (
          (response.status === 429 || response.status >= 500) &&
          attempt < maxRetries
        ) {
          const retryAfter = response.headers.get("Retry-After");
          const delay = retryAfter
            ? Math.min(parseInt(retryAfter, 10), 60) * 1000
            : Math.pow(2, attempt) * 1000;
          await new Promise((resolve) => setTimeout(resolve, delay));
          continue;
        }
  
        console.error(
          `HTTP ${response.status}: ${response.statusText} for ${endpoint}`,
        );
        return null;
      } catch (error) {
        if (attempt === maxRetries) {
          console.error(
            `API request failed after ${maxRetries + 1} attempts: ${endpoint}`,
            error,
          );
          return null;
        }
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
      }
    }
  
    return null;
  }

• src/index.ts:396-400 (helper)

  textResult helper function that builds a successful TextContent result.

  function textResult(text: string) {
    return {
      content: [{ type: "text" as const, text }],
    };
  }