@runpod/mcp-server 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @runpod/mcp-server
 
+## 3.4.0
+
+### Minor Changes
+
+- bae0e5d: Expose the REST v2 CUDA host constraints on create-pod, create-endpoint, and update-endpoint (`allowedCudaVersions`, `minCudaVersion`, nested under `gpu.*` on the wire per rphttp2 2.9.0), support CUDA-only endpoint patches without resending `gpuPoolIds`, warn when a `gpuPoolIds` update clears GPU-type exclusions set elsewhere, and add the `minCudaVersion` availability filter to list-gpu-types. Requires a server running rphttp2 2.9.0 or later for the new fields.
+
 ## 3.3.0
 
 ### Minor Changes

package/dist/{chunk-ICUS4KGX.mjs → chunk-G4URDODF.mjs}

@@ -380,10 +380,15 @@ function containerConfigToV2(p) {
     mounts: persistentMount(p.volumeInGb, p.volumeMountPath)
   });
 }
-function gpuConfigToV2(gpuTypeIds, gpuCount) {
+function gpuConfigToV2(gpuTypeIds, gpuCount, allowedCudaVersions, minCudaVersion2) {
   const id = gpuTypeIds?.[0];
   if (id === void 0) return void 0;
-  return { id, count: gpuCount ?? 1 };
+  return compact({
+    id,
+    count: gpuCount ?? 1,
+    allowedCudaVersions,
+    minCudaVersion: minCudaVersion2
+  });
 }
 function mapPodCreateToV2(params) {
   return compact({
@@ -404,7 +409,12 @@ function mapPodCreateToV2(params) {
     // singular on v2 (`gpu.id`): gpuConfigToV2 takes the first id; the
     // create-pod handler warns when more than one gpuTypeId was supplied.
     dataCenterIds: params.dataCenterIds?.length ? params.dataCenterIds : void 0,
-    gpu: gpuConfigToV2(params.gpuTypeIds, params.gpuCount)
+    gpu: gpuConfigToV2(
+      params.gpuTypeIds,
+      params.gpuCount,
+      params.allowedCudaVersions,
+      params.minCudaVersion
+    )
   });
 }
 function mapPodUpdateToV2(params) {
@@ -421,9 +431,15 @@ function defaultScalerType(endpointType) {
 function endpointScaling(scalerType, value) {
   return scalerType === "REQUEST_COUNT" ? { type: "REQUEST_COUNT", requestCount: value } : { type: "QUEUE_DELAY", queueDelay: value };
 }
-function endpointGpuConfig(pools, count) {
-  if (!pools?.length) return void 0;
-  return compact({ pools, count });
+function endpointGpuConfig(params, mode) {
+  const gpu = compact({
+    pools: params.gpuPoolIds?.length ? params.gpuPoolIds : void 0,
+    count: params.gpuCount,
+    allowedCudaVersions: params.allowedCudaVersions,
+    minCudaVersion: params.minCudaVersion
+  });
+  if (mode === "create" && !("pools" in gpu)) return void 0;
+  return Object.keys(gpu).length ? gpu : void 0;
 }
 function endpointWorkers(params) {
   const workers = compact({
@@ -433,7 +449,7 @@ function endpointWorkers(params) {
   });
   return Object.keys(workers).length ? workers : void 0;
 }
-function endpointCommonToV2(params) {
+function endpointCommonToV2(params, mode) {
   return compact({
     name: params.name,
     image: params.imageName,
@@ -442,7 +458,7 @@ function endpointCommonToV2(params) {
     ports: params.ports,
     env: params.env,
     registry: params.containerRegistryAuthId,
-    gpu: endpointGpuConfig(params.gpuPoolIds, params.gpuCount),
+    gpu: endpointGpuConfig(params, mode),
     workers: endpointWorkers(params),
     dataCenterIds: params.dataCenterIds?.length ? params.dataCenterIds : void 0,
     networkVolumes: params.networkVolumeIds?.length ? params.networkVolumeIds : void 0,
@@ -453,7 +469,7 @@ function endpointCommonToV2(params) {
 function mapEndpointCreateToV2(params) {
   const endpointType = params.endpointType ?? DEFAULT_ENDPOINT_TYPE;
   return compact({
-    ...endpointCommonToV2(params),
+    ...endpointCommonToV2(params, "create"),
     type: endpointType,
     scaling: endpointScaling(
       params.scalerType ?? defaultScalerType(endpointType),
@@ -463,13 +479,28 @@ function mapEndpointCreateToV2(params) {
 }
 function mapEndpointUpdateToV2(params) {
   return compact({
-    ...endpointCommonToV2(params),
+    ...endpointCommonToV2(params, "update"),
     scaling: params.scalerType ? endpointScaling(
       params.scalerType,
       params.scalerValue ?? DEFAULT_SCALER_VALUE
     ) : void 0
   });
 }
+var CUDA_MAJOR_MINOR = /^\d+\.\d+$/;
+function cudaConstraintError(params, opts = {}) {
+  const { allowedCudaVersions, minCudaVersion: minCudaVersion2 } = params;
+  if (allowedCudaVersions?.length && minCudaVersion2) {
+    return "allowedCudaVersions and minCudaVersion are mutually exclusive \u2014 pass either an exact set or an open-ended floor, not both.";
+  }
+  if (minCudaVersion2 !== void 0 && !CUDA_MAJOR_MINOR.test(minCudaVersion2) && !(opts.allowClear && minCudaVersion2 === "")) {
+    return `minCudaVersion must be major.minor (e.g. "12.0", not "12")${opts.allowClear ? "; an empty string clears the floor" : ""}.`;
+  }
+  const bad = allowedCudaVersions?.find((v) => !CUDA_MAJOR_MINOR.test(v));
+  if (bad !== void 0) {
+    return `allowedCudaVersions entries must be major.minor (e.g. "12.8"); got "${bad}". Discover valid values via get-capacity or list-gpu-types.`;
+  }
+  return void 0;
+}
 function mapNetworkVolumeCreateToV2(params) {
   return compact({
     name: params.name,
@@ -760,7 +791,7 @@ function resolveBackend(opts) {
 }
 
 // src/tools/runtime.ts
-var MCP_SERVER_VERSION = true ? "3.3.0" : "dev";
+var MCP_SERVER_VERSION = true ? "3.4.0" : "dev";
 var SESSION_ID = randomUUID();
 function trackingHeaders(server, ctx) {
   const info = server.server.getClientVersion();
@@ -1090,16 +1121,47 @@ function registerCatalogTools(server, rt) {
       ),
       product: z3.enum(["POD", "CLUSTER", "SERVERLESS"]).optional().describe(
         "Product context for the availability lookup \u2014 the same GPU can be scarce for Pods and plentiful for Serverless. Default POD. Use SERVERLESS when picking a GPU for an endpoint, CLUSTER for Instant Clusters. Ignored when includeAvailability is false."
+      ),
+      minCudaVersion: z3.string().optional().describe(
+        'Scope the availability lookup to hosts at or above this CUDA version (v2 only). Integer major or major.minor \u2014 "12" means any 12.x release; unlike the create-pod/create-endpoint body fields, a bare major is accepted here because the filter only widens a read. Requires includeAvailability (the default).'
       )
     },
     { title: "List GPU types", ...READ_ONLY },
     async (params) => {
       const backend = backendFor("gpus");
+      if (params.minCudaVersion !== void 0 && backend.version !== "v2") {
+        return jsonReply2({
+          error: "The minCudaVersion filter is only supported on the v2 REST API. Set RUNPOD_REST_VERSION=v2, or use get-capacity for per-CUDA-version availability.",
+          status: 501
+        });
+      }
       if (backend.version === "v2") {
         const wantAvailability = params.includeAvailability !== false;
         const product = GPU_PRODUCTS.has(String(params.product)) ? String(params.product) : "POD";
+        if (params.minCudaVersion !== void 0) {
+          if (!wantAvailability) {
+            return jsonReply2({
+              error: "minCudaVersion filters the availability lookup, so it requires includeAvailability (the default). Drop includeAvailability:false or the filter.",
+              status: 400
+            });
+          }
+          if (!/^\d+(\.\d+)?$/.test(params.minCudaVersion)) {
+            return jsonReply2({
+              error: 'minCudaVersion must be an integer major ("12") or major.minor ("12.1").',
+              status: 400
+            });
+          }
+        }
+        const query = new URLSearchParams();
+        if (wantAvailability) {
+          query.set("include", "AVAILABILITY");
+          query.set("product", product);
+          if (params.minCudaVersion !== void 0) {
+            query.set("minCudaVersion", params.minCudaVersion);
+          }
+        }
         const raw = await callRestUrl(
-          `${backend.base}${backend.list}${wantAvailability ? `?include=AVAILABILITY&product=${product}` : ""}`
+          `${backend.base}${backend.list}${query.size ? `?${query}` : ""}`
         );
         let gpus = backend.unwrap(raw);
         gpus = gpus.filter((g) => g.id !== "unknown");
@@ -2197,7 +2259,13 @@ function registerPodTools(server, rt) {
       containerRegistryAuthId: z7.string().optional().describe(
         "Container registry credential ID for pulling a private image (see list-container-registry-auths). When deploying from a templateId, this overrides the credential the template carries; pass an empty string to deploy with NO credential (clears a template\u2019s inherited registry)."
       ),
-      dataCenterIds: z7.array(z7.string()).optional().describe("List of data centers")
+      dataCenterIds: z7.array(z7.string()).optional().describe("List of data centers"),
+      allowedCudaVersions: z7.array(z7.string()).optional().describe(
+        'Acceptable host CUDA versions as major.minor, e.g. ["12.8","12.6"] (v2, GPU pods only). Exact match \u2014 discover valid values per GPU type with get-capacity. Mutually exclusive with minCudaVersion.'
+      ),
+      minCudaVersion: z7.string().optional().describe(
+        'Lowest acceptable host CUDA version as major.minor, e.g. "12.4" (v2, GPU pods only). A bare major like "12" is rejected. Open-ended floor; mutually exclusive with a non-empty allowedCudaVersions.'
+      )
     },
     { title: "Create pod", ...WRITE },
     async (params) => {
@@ -2211,6 +2279,13 @@ function registerPodTools(server, rt) {
         sshKey = validated.key;
       }
       const sshNote = "sshPublicKey applied: PUBLIC_KEY env set and 22/tcp exposed. Full SSH (incl. SCP/SFTP/rsync) also requires an image that installs PUBLIC_KEY into authorized_keys and starts sshd (all runpod/* official images do) and a machine with a public IP \u2014 read the pod\u2019s portMappings for port 22 once it is running.";
+      const hasCudaParams = params.allowedCudaVersions !== void 0 || params.minCudaVersion !== void 0;
+      if (hasCudaParams && backend.version !== "v2") {
+        return jsonReply2({
+          error: "allowedCudaVersions/minCudaVersion are only supported on the v2 REST API. Set RUNPOD_REST_VERSION=v2.",
+          status: 501
+        });
+      }
       if (params.templateId && backend.version !== "v2") {
         return jsonReply2({
           error: "Deploying a pod from a templateId is only supported on the v2 REST API. Set RUNPOD_REST_VERSION=v2, or pass imageName instead.",
@@ -2246,6 +2321,16 @@ function registerPodTools(server, rt) {
             status: 400
           });
         }
+        if (hasCudaParams && !wantsGpu) {
+          return jsonReply2({
+            error: "allowedCudaVersions/minCudaVersion apply to GPU pods only \u2014 pass gpuTypeIds (see list-gpu-types).",
+            status: 400
+          });
+        }
+        if (hasCudaParams) {
+          const cudaError = cudaConstraintError(params);
+          if (cudaError) return jsonReply2({ error: cudaError, status: 400 });
+        }
         if (!wantsCpu && !params.name && !params.templateId) {
           return jsonReply2({
             error: "Provide a name for the pod (deploying from a templateId inherits the template name).",
@@ -2435,6 +2520,9 @@ function registerPodTools(server, rt) {
 import { z as z8 } from "zod";
 var MIN_QUEUE_DELAY = 0.5;
 var MIN_REQUEST_COUNT = 1;
+function isRequestCountScaler(type) {
+  return type === "REQUEST_COUNT";
+}
 var MIN_IDLE_TIMEOUT = 1;
 var MAX_IDLE_TIMEOUT = 3600;
 function scalerValueError(scalerType, scalerValue) {
@@ -2527,6 +2615,12 @@ function registerEndpointTools(server, rt) {
         'GPU pool names (v2, required). The `pool` field from list-gpu-types, e.g. ["AMPERE_80"]. NOT GPU type ids.'
       ),
       gpuCount: z8.number().optional().describe("GPUs per worker (v2)"),
+      allowedCudaVersions: z8.array(z8.string()).optional().describe(
+        'Acceptable host CUDA versions for worker placement as major.minor, e.g. ["12.8"] (v2). Exact match \u2014 see get-capacity for which versions have stock. Mutually exclusive with minCudaVersion.'
+      ),
+      minCudaVersion: z8.string().optional().describe(
+        'Lowest acceptable host CUDA version as major.minor, e.g. "12.4" (v2). A bare major like "12" is rejected. Mutually exclusive with a non-empty allowedCudaVersions.'
+      ),
       args: z8.string().optional().describe("Container start command/args (v2)"),
       containerDiskInGb: z8.number().optional().describe("Container disk size in GB (v2)"),
       ports: z8.array(z8.string()).optional().describe("Ports to expose (v2), e.g. ['8000/http']"),
@@ -2556,6 +2650,13 @@ function registerEndpointTools(server, rt) {
     { title: "Create endpoint", ...WRITE },
     async (params) => {
       const backend = backendFor("endpoints");
+      const hasCudaParams = params.allowedCudaVersions !== void 0 || params.minCudaVersion !== void 0;
+      if (hasCudaParams && backend.version !== "v2") {
+        return jsonReply2({
+          error: "allowedCudaVersions/minCudaVersion are only supported on the v2 REST API. Set RUNPOD_REST_VERSION=v2.",
+          status: 501
+        });
+      }
       if (backend.version === "v2") {
         if (!params.name) {
           return jsonReply2({
@@ -2588,6 +2689,10 @@ function registerEndpointTools(server, rt) {
         if (scalerError) {
           return jsonReply2({ error: scalerError, status: 400 });
         }
+        if (hasCudaParams) {
+          const cudaError = cudaConstraintError(params);
+          if (cudaError) return jsonReply2({ error: cudaError, status: 400 });
+        }
         const body = backend.mapCreate(params);
         const result2 = await callRestUrl(
           `${backend.base}${backend.list}`,
@@ -2625,7 +2730,7 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "update-endpoint",
-    "Update a Serverless endpoint's config. On v2 you can change image/disk/env/ports/registry/workers/scaling/networkVolumes/timeout/flashboot; on v1, scaling fields (worker min/max, idle timeout, scaler type/value, name). Only provided fields change. An endpoint's request routing (queue vs load balancer) is fixed at creation and cannot be changed here \u2014 recreate the endpoint instead.",
+    "Update a Serverless endpoint's config. On v2 you can change image/disk/env/ports/registry/workers/scaling/networkVolumes/timeout/flashboot, plus the GPU selection (gpuPoolIds/gpuCount) and its CUDA constraints (allowedCudaVersions/minCudaVersion) \u2014 CUDA-only or count-only changes do not require resending gpuPoolIds; on v1, scaling fields (worker min/max, idle timeout, scaler type/value, name). Only provided fields change. An endpoint's request routing (queue vs load balancer) is fixed at creation and cannot be changed here \u2014 recreate the endpoint instead. Note: passing gpuPoolIds replaces the GPU selection wholesale, which clears any GPU-type exclusions set elsewhere (console or set-endpoint-gpus) \u2014 the reply carries a _warning when that happens.",
     {
       endpointId: z8.string().describe("ID of the endpoint to update"),
       name: z8.string().optional().describe("New name for the endpoint"),
@@ -2644,6 +2749,12 @@ function registerEndpointTools(server, rt) {
       imageName: z8.string().optional().describe("New Docker image (v2)"),
       gpuPoolIds: z8.array(z8.string()).optional().describe('New GPU pool names (v2), e.g. ["AMPERE_80"]'),
       gpuCount: z8.number().optional().describe("New GPUs per worker (v2)"),
+      allowedCudaVersions: z8.array(z8.string()).optional().describe(
+        "New acceptable host CUDA versions as major.minor (v2). Changing only this does not require resending gpuPoolIds. An explicit [] clears the constraint. Mutually exclusive with minCudaVersion."
+      ),
+      minCudaVersion: z8.string().optional().describe(
+        'New lowest acceptable host CUDA version as major.minor (v2). An empty string clears the floor; a bare major like "12" is rejected. Mutually exclusive with a non-empty allowedCudaVersions.'
+      ),
       args: z8.string().optional().describe("New container args (v2)"),
       containerDiskInGb: z8.number().optional().describe("New container disk size in GB (v2)"),
       ports: z8.array(z8.string()).optional().describe("New ports (v2)"),
@@ -2658,14 +2769,41 @@ function registerEndpointTools(server, rt) {
       const { endpointId, ...updateParams } = params;
       const backend = backendFor("endpoints");
       const url = `${backend.base}${backend.get(endpointId)}`;
+      const hasCudaParams = updateParams.allowedCudaVersions !== void 0 || updateParams.minCudaVersion !== void 0;
       if (backend.version !== "v2") {
+        if (hasCudaParams) {
+          return jsonReply2({
+            error: "allowedCudaVersions/minCudaVersion are only supported on the v2 REST API. Set RUNPOD_REST_VERSION=v2.",
+            status: 501
+          });
+        }
         const body2 = backend.mapUpdate(updateParams);
         return jsonReply2(await callRestUrl(url, "PATCH", body2));
       }
+      if (hasCudaParams) {
+        const cudaError = cudaConstraintError(updateParams, {
+          allowClear: true
+        });
+        if (cudaError) return jsonReply2({ error: cudaError, status: 400 });
+      }
+      if (updateParams.gpuPoolIds !== void 0 && !updateParams.gpuPoolIds.length) {
+        return jsonReply2({
+          error: "gpuPoolIds cannot be empty \u2014 omit it to keep the current GPU selection.",
+          status: 400
+        });
+      }
       let scalerType = updateParams.scalerType;
-      if (scalerType === void 0 && updateParams.scalerValue !== void 0) {
+      const needScalerRead = scalerType === void 0 && updateParams.scalerValue !== void 0;
+      const needExclusionRead = (updateParams.gpuPoolIds?.length ?? 0) > 0;
+      let clearedExclusions = [];
+      if (needScalerRead || needExclusionRead) {
         const current = await callRestUrl(url);
-        scalerType = current?.scaling?.type === "REQUEST_COUNT" ? "REQUEST_COUNT" : "QUEUE_DELAY";
+        if (needScalerRead) {
+          scalerType = isRequestCountScaler(current?.scaling?.type) ? "REQUEST_COUNT" : "QUEUE_DELAY";
+        }
+        if (needExclusionRead && current?.gpu?.excludedTypes?.length) {
+          clearedExclusions = current.gpu.excludedTypes;
+        }
       }
       const scalerError = scalerValueError(
         scalerType,
@@ -2678,7 +2816,14 @@ function registerEndpointTools(server, rt) {
         ...updateParams,
         scalerType
       });
-      return jsonReply2(await callRestUrl(url, "PATCH", body));
+      const result = await callRestUrl(url, "PATCH", body);
+      if (clearedExclusions.length) {
+        return jsonReply2({
+          ...result,
+          _warning: `Supplying gpuPoolIds replaced the GPU selection wholesale, clearing ${clearedExclusions.length} GPU-type exclusion(s) previously set on this endpoint: ${clearedExclusions.join(", ")}. Re-apply them with set-endpoint-gpus if still wanted.`
+        });
+      }
+      return jsonReply2(result);
     }
   );
   server.tool(
@@ -3628,4 +3773,4 @@ export {
   restVersionSummary,
   registerTools
 };
-//# sourceMappingURL=chunk-ICUS4KGX.mjs.map
+//# sourceMappingURL=chunk-G4URDODF.mjs.map