cos_list_buckets

Instructions

Implementation Reference

• src/tools/cos/index.ts:13-17 (handler)

  The 'cos_list_buckets' tool handler: uses IBMCloudAPIClient.request() to GET https://config.cloud-object-storage.cloud.ibm.com/v1/b with the instance CRN as the ibm-service-instance-id header. The handler is an inline async function passed to server.tool().

  server.tool("cos_list_buckets", "List all Cloud Object Storage buckets", {
    instance_crn: z.string().describe("COS instance CRN"),
  }, async (p) => safeTool(() =>
    client.request(`${cfgBase}/b`, {headers:{"ibm-service-instance-id":p.instance_crn}})
  ));

• src/tools/cos/index.ts:13-14 (schema)

  The input schema for 'cos_list_buckets': requires a single parameter 'instance_crn' of type string (Zod schema), described as 'COS instance CRN'.

  server.tool("cos_list_buckets", "List all Cloud Object Storage buckets", {
    instance_crn: z.string().describe("COS instance CRN"),

• src/tools/cos/index.ts:13-17 (registration)

  The tool is registered via server.tool('cos_list_buckets', ...) inside the registerCOSTools() function in src/tools/cos/index.ts.

  server.tool("cos_list_buckets", "List all Cloud Object Storage buckets", {
    instance_crn: z.string().describe("COS instance CRN"),
  }, async (p) => safeTool(() =>
    client.request(`${cfgBase}/b`, {headers:{"ibm-service-instance-id":p.instance_crn}})
  ));

• src/server.ts:59-60 (registration)

  The registerCOSTools function is called from src/server.ts to register all COS tools, including cos_list_buckets.

  registerCOSTools(server, client, config);
  console.error(`  ✓ Cloud Object Storage (12 tools)`);

• src/lib/api-client.ts:30-123 (helper)

  The IBMCloudAPIClient.request() method is the underlying helper that executes the HTTP request for the tool handler. It handles authentication, retries, and error parsing.

  async request<T = unknown>(
    url: string,
    options: RequestOptions = {}
  ): Promise<T> {
    const {
      method = "GET",
      headers = {},
      body,
      queryParams,
      skipAuth = false,
      retries = 3,
    } = options;
  
    // Build URL with query params
    const fullUrl = this.buildUrl(url, queryParams);
  
    // Build headers
    const requestHeaders: Record<string, string> = {
      "Accept": "application/json",
      ...headers,
    };
  
    if (!skipAuth) {
      const token = await this.auth.getToken();
      requestHeaders["Authorization"] = `Bearer ${token}`;
    }
  
    if (body && !requestHeaders["Content-Type"]) {
      requestHeaders["Content-Type"] = "application/json";
    }
  
    const requestBody =
      body && typeof body === "object" ? JSON.stringify(body) : (body as string | undefined);
  
    // Execute with retry logic
    let lastError: Error | null = null;
  
    for (let attempt = 0; attempt < retries; attempt++) {
      try {
        const response = await fetch(fullUrl, {
          method,
          headers: requestHeaders,
          body: requestBody,
        });
  
        if (!response.ok) {
          const error = await parseAPIError(response);
  
          // Retry on rate limit with exponential backoff
          if (error instanceof RateLimitError && attempt < retries - 1) {
            const retryAfter = response.headers.get("Retry-After");
            const waitMs = retryAfter
              ? parseInt(retryAfter, 10) * 1000
              : Math.pow(2, attempt + 1) * 1000;
            await this.sleep(waitMs);
            lastError = error;
            continue;
          }
  
          // Retry on 5xx errors
          if (response.status >= 500 && attempt < retries - 1) {
            await this.sleep(Math.pow(2, attempt + 1) * 1000);
            lastError = error;
            continue;
          }
  
          throw error;
        }
  
        // Handle 204 No Content
        if (response.status === 204) {
          return undefined as T;
        }
  
        // Check if response has body
        const contentType = response.headers.get("content-type") || "";
        if (contentType.includes("application/json")) {
          return (await response.json()) as T;
        }
  
        return (await response.text()) as T;
      } catch (error) {
        if (error instanceof TypeError && attempt < retries - 1) {
          // Network error — retry
          await this.sleep(Math.pow(2, attempt + 1) * 1000);
          lastError = error;
          continue;
        }
        throw error;
      }
    }
  
    throw lastError || new Error("Request failed after retries");
  }