list-gpu-instances

Implementation Reference

• src/tools.ts:91-115 (handler)

  Handler function that constructs URL query parameters from input params, makes API request to /gpu/instances endpoint using novitaRequest helper, clears sensitive information, and returns the result as JSON-formatted text content.

      if (params.pageSize)
          queryParams.append("pageSize", params.pageSize.toString());
      if (params.pageNumber)
          queryParams.append("pageNumber", params.pageNumber.toString());
      if (params.name)
          queryParams.append("name", params.name);
      if (params.productName)
          queryParams.append("productName", params.productName);
      if (params.status)
          queryParams.append("status", params.status);
      const queryString = queryParams.toString()
          ? `?${queryParams.toString()}`
          : "";
      const result = await novitaRequest(`/gpu/instances${queryString}`);
      clearSensitiveInfo(result);
  
      return {
          content: [
              {
                  type: "text",
                  text: JSON.stringify(result, null, 2),
              },
          ],
      };
  });

• src/tools.ts:63-90 (schema)

  Zod-based input schema defining optional parameters for pagination (pageSize, pageNumber), filtering by name, productName, and status.

      pageSize: z
          .number()
          .min(0)
          .default(10)
          .optional()
          .describe("Number of instances to return, "),
      pageNumber: z
          .number()
          .min(0)
          .default(1)
          .optional()
          .describe("Page number to return, start from "),
      name: z
          .string()
          .max(1024)
          .optional()
          .describe("Filter by the instance name"),
      productName: z
          .string()
          .optional()
          .describe("Filter by the product name"),
      status: z
          .enum(["running", "pulling", "exited", "resetting", "removed", "migrating", "freezing"])
          .optional()
          .describe("Filter by the instance status"),
  }, async (params) => {
      // Construct query parameters
      const queryParams = new URLSearchParams();

• src/tools.ts:62-115 (registration)

  Direct registration of the 'list-gpu-instances' tool on the MCP server within registerGPUInstanceTools function.

  server.tool("list-gpu-instances", {
      pageSize: z
          .number()
          .min(0)
          .default(10)
          .optional()
          .describe("Number of instances to return, "),
      pageNumber: z
          .number()
          .min(0)
          .default(1)
          .optional()
          .describe("Page number to return, start from "),
      name: z
          .string()
          .max(1024)
          .optional()
          .describe("Filter by the instance name"),
      productName: z
          .string()
          .optional()
          .describe("Filter by the product name"),
      status: z
          .enum(["running", "pulling", "exited", "resetting", "removed", "migrating", "freezing"])
          .optional()
          .describe("Filter by the instance status"),
  }, async (params) => {
      // Construct query parameters
      const queryParams = new URLSearchParams();
      if (params.pageSize)
          queryParams.append("pageSize", params.pageSize.toString());
      if (params.pageNumber)
          queryParams.append("pageNumber", params.pageNumber.toString());
      if (params.name)
          queryParams.append("name", params.name);
      if (params.productName)
          queryParams.append("productName", params.productName);
      if (params.status)
          queryParams.append("status", params.status);
      const queryString = queryParams.toString()
          ? `?${queryParams.toString()}`
          : "";
      const result = await novitaRequest(`/gpu/instances${queryString}`);
      clearSensitiveInfo(result);
  
      return {
          content: [
              {
                  type: "text",
                  text: JSON.stringify(result, null, 2),
              },
          ],
      };
  });

• src/utils.ts:15-55 (helper)

  novitaRequest helper: Performs authenticated HTTP requests to the Novita AI GPU instance API, used by the tool handler to fetch the list of GPU instances.

  export async function novitaRequest(
      endpoint: string,
      method: string = "GET",
      body: any = null
  ) {
      // Base URL for Novita AI API
      const API_BASE_URL = "https://api.novita.ai/gpu-instance/openapi/v1";
      // Get API key from environment variable
      const API_KEY = process.env.NOVITA_API_KEY;
  
      const url = `${API_BASE_URL}${endpoint}`;
      const headers = {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
      };
      const options: any = {
          method,
          headers,
      };
  
      if (body && (method === "POST" || method === "PATCH")) {
          options.body = JSON.stringify(body);
      }
      try {
          const response = await fetch(url, options);
          if (!response.ok) {
              const errorText = await response.text();
              throw new Error(`Novita AI API Error: ${response.status} - ${errorText}`);
          }
          // Some endpoints might not return JSON
          const contentType = response.headers.get("content-type");
          if (contentType && contentType.includes("application/json")) {
              return await response.json();
          }
          return { success: true, status: response.status };
      }
      catch (error) {
          console.error("Error calling Novita AI API:", error);
          throw error;
      }
  }

• src/utils.ts:5-12 (helper)

  clearSensitiveInfo helper: Removes sensitive fields like sshPassword from the API response data before returning it.

  export function clearSensitiveInfo(data: any) {
      if (data && data.instances) {
          data.instances = data.instances.map((instance: any) => ({
              ...instance,
              sshPassword: undefined
          }));
      }
  }