list-gpu-instances
List and filter GPU instances on the Novita AI platform to manage resources by name, product, or status.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageSize | No | Number of instances to return, | |
| pageNumber | No | Page number to return, start from | |
| name | No | Filter by the instance name | |
| productName | No | Filter by the product name | |
| status | No | Filter by the instance status |
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 })); } }