feat: expose v2 CUDA constraints (gpu.allowedCudaVersions / gpu.minCudaVersion)

.changeset/v2-cuda-constraints.md

@@ -0,0 +1,5 @@
+---
+'@runpod/mcp-server': minor
+---
+
+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.

src/_shared/mappers.ts

@@ -33,6 +33,10 @@ interface V1PodParams {
   env?: Record<string, string>;
   dataCenterIds?: string[];
   containerRegistryAuthId?: string;
+  // v2-only: mapped into gpu.allowedCudaVersions / gpu.minCudaVersion; the v1
+  // path never sends them.
+  allowedCudaVersions?: string[];
+  minCudaVersion?: string;
 }
 
 // Drop undefined entries so we never emit explicit `undefined`/`null` the API
@@ -93,11 +97,20 @@ function containerConfigToV2(p: {
 // always emit the documented default explicitly.
 function gpuConfigToV2(
   gpuTypeIds?: string[],
-  gpuCount?: number
+  gpuCount?: number,
+  allowedCudaVersions?: string[],
+  minCudaVersion?: string
 ): Record<string, unknown> | undefined {
   const id = gpuTypeIds?.[0];
   if (id === undefined) return undefined;
-  return { id, count: gpuCount ?? 1 };
+  // CUDA host constraints are gpu-nested since 2.9.0 (never body top-level).
+  // Passed through as given: an explicit [] is a spec-legal "no constraint".
+  return compact({
+    id,
+    count: gpuCount ?? 1,
+    allowedCudaVersions,
+    minCudaVersion,
+  });
 }
 
 export function mapPodCreateToV2(params: V1PodParams): Record<string, unknown> {
@@ -124,7 +137,12 @@ export function mapPodCreateToV2(params: V1PodParams): Record<string, unknown> {
     dataCenterIds: params.dataCenterIds?.length
       ? params.dataCenterIds
       : undefined,
-    gpu: gpuConfigToV2(params.gpuTypeIds, params.gpuCount),
+    gpu: gpuConfigToV2(
+      params.gpuTypeIds,
+      params.gpuCount,
+      params.allowedCudaVersions,
+      params.minCudaVersion
+    ),
   });
 }
 
@@ -169,6 +187,8 @@ interface V2EndpointParams {
   ports?: string[];
   env?: Record<string, string>;
   containerRegistryAuthId?: string;
+  allowedCudaVersions?: string[];
+  minCudaVersion?: string;
 }
 
 type EndpointType = 'QUEUE' | 'LOAD_BALANCER';
@@ -202,14 +222,24 @@ function endpointScaling(
     : { type: 'QUEUE_DELAY', queueDelay: value };
 }
 
-// gpu requires `pools` (minItems 1) — return undefined when no pools so the
-// handler's guard, not the API, reports the omission.
+// CREATE requires `pools` (minItems 1): without them, return undefined so the
+// handler's guard, not the API, reports the omission — CUDA/count fields never
+// ride without a pool list on create. UPDATE (2.9.0) makes every gpu field
+// optional, so a pools-less gpu (CUDA-only or count-only patch) is emitted as
+// given; an empty object is still dropped. CUDA clear sentinels pass through:
+// [] clears the set, "" clears the floor.
 function endpointGpuConfig(
-  pools?: string[],
-  count?: number
+  params: V2EndpointParams,
+  mode: 'create' | 'update'
 ): Record<string, unknown> | undefined {
-  if (!pools?.length) return undefined;
-  return compact({ pools, count });
+  const gpu = compact({
+    pools: params.gpuPoolIds?.length ? params.gpuPoolIds : undefined,
+    count: params.gpuCount,
+    allowedCudaVersions: params.allowedCudaVersions,
+    minCudaVersion: params.minCudaVersion,
+  });
+  if (mode === 'create' && !('pools' in gpu)) return undefined;
+  return Object.keys(gpu).length ? gpu : undefined;
 }
 
 // `workers` absorbed `idleTimeout` from `scaling`. Returns undefined when the caller
@@ -227,7 +257,10 @@ function endpointWorkers(
 
 // The half of the body shared by create and update: container config, compute,
 // placement and workers. Only `type` and `scaling` differ between the two.
-function endpointCommonToV2(params: V2EndpointParams): Record<string, unknown> {
+function endpointCommonToV2(
+  params: V2EndpointParams,
+  mode: 'create' | 'update'
+): Record<string, unknown> {
   return compact({
     name: params.name,
     image: params.imageName,
@@ -236,7 +269,7 @@ function endpointCommonToV2(params: V2EndpointParams): Record<string, unknown> {
     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
@@ -255,7 +288,7 @@ export function mapEndpointCreateToV2(
 ): Record<string, unknown> {
   const endpointType = params.endpointType ?? DEFAULT_ENDPOINT_TYPE;
   return compact({
-    ...endpointCommonToV2(params),
+    ...endpointCommonToV2(params, 'create'),
     type: endpointType,
     scaling: endpointScaling(
       params.scalerType ?? defaultScalerType(endpointType),
@@ -273,7 +306,7 @@ export function mapEndpointUpdateToV2(
   params: V2EndpointParams
 ): Record<string, unknown> {
   return compact({
-    ...endpointCommonToV2(params),
+    ...endpointCommonToV2(params, 'update'),
     scaling: params.scalerType
       ? endpointScaling(
           params.scalerType,
@@ -283,6 +316,34 @@ export function mapEndpointUpdateToV2(
   });
 }
 
+// ---- CUDA constraint validation shared by the pod/endpoint tools ----
+// The API answers a raw 422/400; validating here names the field and the fix.
+// major.minor only — the REST body fields reject a bare major like "12" (the
+// catalog's minCudaVersion QUERY filter is the one place a bare major is legal).
+const CUDA_MAJOR_MINOR = /^\d+\.\d+$/;
+
+export function cudaConstraintError(
+  params: { allowedCudaVersions?: string[]; minCudaVersion?: string },
+  opts: { allowClear?: boolean } = {}
+): string | undefined {
+  const { allowedCudaVersions, minCudaVersion } = params;
+  if (allowedCudaVersions?.length && minCudaVersion) {
+    return 'allowedCudaVersions and minCudaVersion are mutually exclusive — pass either an exact set or an open-ended floor, not both.';
+  }
+  if (
+    minCudaVersion !== undefined &&
+    !CUDA_MAJOR_MINOR.test(minCudaVersion) &&
+    !(opts.allowClear && minCudaVersion === '')
+  ) {
+    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 !== undefined) {
+    return `allowedCudaVersions entries must be major.minor (e.g. "12.8"); got "${bad}". Discover valid values via get-capacity or list-gpu-types.`;
+  }
+  return undefined;
+}
+
 // ---- Network volume: dataCenterId → dataCenter (only field change) ----
 interface V1NetworkVolumeCreate {
   name?: string;

src/tools/catalog.ts

@@ -58,10 +58,23 @@ export function registerCatalogTools(server: McpServer, rt: ToolRuntime): void {
         .describe(
           'Product context for the availability lookup — 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: z
+        .string()
+        .optional()
+        .describe(
+          'Scope the availability lookup to hosts at or above this CUDA version (v2 only). Integer major or major.minor — "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 !== undefined && backend.version !== 'v2') {
+        return jsonReply({
+          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') {
         // v2 REST: GET /v2/catalog/gpus?include=AVAILABILITY&product=… →
         // { gpus: [...] }, each with an `availability` summary
@@ -76,9 +89,35 @@ export function registerCatalogTools(server: McpServer, rt: ToolRuntime): void {
         const product = GPU_PRODUCTS.has(String(params.product))
           ? String(params.product)
           : 'POD';
+        // The filter scopes the availability lookup, so it is meaningless (and
+        // rejected by the API) without include=AVAILABILITY. Bare major is
+        // legal here — this filter only widens a read. Re-validated like
+        // `product` because direct handler calls can bypass zod.
+        if (params.minCudaVersion !== undefined) {
+          if (!wantAvailability) {
+            return jsonReply({
+              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 jsonReply({
+              error:
+                'minCudaVersion must be an integer major ("12") or major.minor ("12.1").',
+              status: 400,
+            });
+          }
+        }
         const raw = await callRestUrl(
           `${backend.base}${backend.list}${
-            wantAvailability ? `?include=AVAILABILITY&product=${product}` : ''
+            wantAvailability
+              ? `?include=AVAILABILITY&product=${product}${
+                  params.minCudaVersion !== undefined
+                    ? `&minCudaVersion=${encodeURIComponent(params.minCudaVersion)}`
+                    : ''
+                }`
+              : ''
           }`
         );
         let gpus = backend.unwrap(raw) as Array<Record<string, unknown>>;