@runpod/mcp-server 3.1.0 → 3.2.0

package/dist/stdio.cjs

@@ -646,7 +646,7 @@ function restV1Base(env) {
   return env.RUNPOD_REST_API_URL ?? "https://rest.runpod.io/v1";
 }
 function restV2Base(env) {
-  return env.RUNPOD_REST_V2_API_URL ?? "https://v2-rest.runpod.io/v2";
+  return env.RUNPOD_REST_V2_API_URL ?? "https://api.runpod.io/v2";
 }
 function serverlessBase(env) {
   return env.RUNPOD_SERVERLESS_API_URL ?? "https://api.runpod.ai/v2";
@@ -868,27 +868,176 @@ function resolveBackend(opts) {
 
 // src/server.ts
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "3.1.0" : "dev";
+var SERVER_VERSION = true ? "3.2.0" : "dev";
+var SERVER_INSTRUCTIONS = `These tools cover common Runpod operations, but they are curated projections: the underlying APIs expose more fields and parameters than the tools surface.
+
+When you need data or capability beyond these tools, consult the full API contracts directly. The REST v2 API lives at https://api.runpod.io/v2 \u2014 the same host these tools call \u2014 and is machine-readable at https://api.runpod.io/v2/openapi.json (fetch and search it to enumerate every path, parameter, and response schema). REST v1 at https://rest.runpod.io/v1 is deprecated; prefer v2. The REST version these tools are actually configured for is reported in the serverInfo.version string of the initialize response, e.g. "[RUNPOD_REST_VERSION=v2]". The GraphQL API at https://api.runpod.io/graphql may expose data the REST API does not yet cover; its schema is documented at https://graphql-spec.runpod.io/, and introspection is disabled in production, so use that reference rather than __schema queries. Both APIs take Bearer auth with a Runpod API key: use the key this client is already configured with \u2014 do not search the environment or filesystem for a credential.`;
 function createServer(version = SERVER_VERSION) {
-  return new import_mcp.McpServer({
-    name: SERVER_NAME,
-    version: `${version} [${restVersionSummary(process.env)}]`,
-    capabilities: {
-      resources: {},
-      tools: {}
+  return new import_mcp.McpServer(
+    {
+      name: SERVER_NAME,
+      version: `${version} [${restVersionSummary(process.env)}]`
+    },
+    {
+      // Only advertise capabilities the server implements. It registers
+      // tools and no resources — advertising `resources` would invite
+      // `resources/list` calls that answer -32601.
+      capabilities: {
+        tools: {}
+      },
+      instructions: SERVER_INSTRUCTIONS
     }
-  });
+  );
 }
 
 // src/tools/runtime.ts
 var import_node_fetch = __toESM(require("node-fetch"), 1);
 var import_node_crypto = require("crypto");
 
+// src/_shared/rate-limit.ts
+var GENERIC_RATE_LIMIT_HINT = "rate limited \u2014 back off before retrying, and pace bulk operations";
+var MAX_PLAUSIBLE_WAIT_S = 7 * 86400;
+function remainingRequests(raw) {
+  const value = raw?.trim();
+  return value && /^\d+$/.test(value) ? Number(value) : null;
+}
+function waitSeconds(raw) {
+  const value = raw?.trim();
+  if (!value || !/^\d+$/.test(value)) return null;
+  const seconds = Number(value);
+  return seconds <= MAX_PLAUSIBLE_WAIT_S ? seconds : null;
+}
+var WINDOW_NAME_RE = /^(?:"([\x20-\x21\x23-\x5b\x5d-\x7e]{1,32})"|([A-Za-z*][A-Za-z0-9!#$%&'*+.^_`|~:/-]{0,31}))$/;
+function windowName(raw) {
+  const match = WINDOW_NAME_RE.exec(raw.trim());
+  return match ? match[1] ?? match[2] : null;
+}
+var QUOTED_VALUE_RE = /^"(?:[\x20-\x21\x23-\x5b\x5d-\x7e]|\\["\\])*"$/;
+var DISPLAY_VALUE_RE = /^%"(?:[\x20-\x21\x23-\x24\x26-\x5b\x5d-\x7e]|\\|%[0-9a-f]{2})*"$/;
+function isWellFormedParam(param) {
+  const eq = param.indexOf("=");
+  const key = (eq === -1 ? param : param.slice(0, eq)).trim();
+  if (key.includes('"')) return false;
+  if (eq === -1) return true;
+  const value = param.slice(eq + 1).trim();
+  if (value.startsWith('"')) return QUOTED_VALUE_RE.test(value);
+  if (value.startsWith('%"')) return DISPLAY_VALUE_RE.test(value);
+  return !/[\s"]/.test(value);
+}
+function splitOutsideStrings(input, sep) {
+  const parts = [];
+  let current = "";
+  let inString = false;
+  let inDisplay = false;
+  let escaped = false;
+  let prev = "";
+  for (const ch of input) {
+    if (escaped) escaped = false;
+    else if (inString && !inDisplay && ch === "\\") escaped = true;
+    else if (ch === '"') {
+      if (!inString) inDisplay = prev === "%";
+      inString = !inString;
+    } else if (ch === sep && !inString) {
+      parts.push(current);
+      current = "";
+      prev = ch;
+      continue;
+    }
+    current += ch;
+    prev = ch;
+  }
+  parts.push(current);
+  return parts;
+}
+function readParams(params) {
+  const values = /* @__PURE__ */ new Map();
+  let unreadable = false;
+  let valuelessAt = -1;
+  for (const [index, param] of params.entries()) {
+    const eq = param.indexOf("=");
+    const key = (eq === -1 ? param : param.slice(0, eq)).trim().toLowerCase();
+    if (!key) continue;
+    if (eq === -1) {
+      if (key === "r") unreadable = true;
+      if (key === "t") values.delete("t");
+      valuelessAt = index;
+      continue;
+    }
+    if ((key === "r" || key === "t") && (values.has(key) || valuelessAt !== -1 && index > valuelessAt)) {
+      unreadable = true;
+    }
+    values.set(key, param.slice(eq + 1));
+  }
+  return { values, unreadable };
+}
+function parseExhaustedWindows(header) {
+  if (!header) return { windows: [], dropped: false };
+  const windows = [];
+  let dropped = false;
+  for (const item of splitOutsideStrings(header, ",")) {
+    if (item.trim() === "") continue;
+    const [rawName, ...params] = splitOutsideStrings(item, ";");
+    if (!params.every(isWellFormedParam)) {
+      dropped = true;
+      continue;
+    }
+    const { values, unreadable } = readParams(params);
+    if (unreadable) {
+      dropped = true;
+      continue;
+    }
+    const remaining = remainingRequests(values.get("r"));
+    if (remaining === null) {
+      dropped = true;
+      continue;
+    }
+    if (remaining !== 0) continue;
+    windows.push({
+      window: windowName(rawName),
+      resetS: waitSeconds(values.get("t"))
+    });
+  }
+  return { windows, dropped };
+}
+function humanWait(seconds) {
+  if (seconds < 120) return `~${seconds}s`;
+  if (seconds < 3600)
+    return `~${Math.ceil(seconds / 60)} minutes (${seconds}s)`;
+  if (seconds < 2 * 86400) {
+    const hours = Math.ceil(seconds / 3600);
+    return `~${hours} hour${hours === 1 ? "" : "s"} (${seconds}s)`;
+  }
+  return `~${Math.ceil(seconds / 86400)} days (${seconds}s)`;
+}
+function rateLimitHint(rateLimitHeader, retryAfterHeader) {
+  const { windows, dropped } = parseExhaustedWindows(rateLimitHeader);
+  windows.sort((a, b) => (b.resetS ?? -1) - (a.resetS ?? -1));
+  const longestWindow = windows[0];
+  const waitCandidates = [
+    waitSeconds(retryAfterHeader),
+    longestWindow?.resetS
+  ].filter((n) => typeof n === "number" && n > 0);
+  const waitS = waitCandidates.length ? Math.max(...waitCandidates) : null;
+  const retryAfterUnreadable = typeof retryAfterHeader === "string" && retryAfterHeader.trim() !== "" && waitSeconds(retryAfterHeader) === null;
+  if (!longestWindow && waitS === null) {
+    if (!retryAfterUnreadable) return GENERIC_RATE_LIMIT_HINT;
+  }
+  const namedClause = longestWindow?.window ? `the ${longestWindow.window} quota is exhausted` : "";
+  if (waitS === null) {
+    const cause = namedClause ? `${namedClause}, but the response gave no usable reset time` : "the response gave no usable reset time";
+    return `rate limited \u2014 ${cause}; back off substantially before retrying, and pace bulk operations`;
+  }
+  const hedge = dropped || retryAfterUnreadable || windows.some((w) => w.resetS === null) ? "at least " : "";
+  const wait = `wait ${hedge}${humanWait(waitS)} before retrying, and pace bulk operations`;
+  return `rate limited \u2014 ${namedClause ? `${namedClause}; ` : ""}${wait}`;
+}
+
 // src/_shared/http.ts
+var EXPIRED_CREDENTIAL_HINT = "the Runpod API rejected the credential \u2014 the API key may be expired or revoked; re-authenticate or update RUNPOD_API_KEY";
 var HttpError = class extends Error {
-  constructor(prefix, status, body) {
-    const hint = status === 401 ? " (the Runpod API rejected the credential \u2014 the API key may be expired or revoked; re-authenticate or update RUNPOD_API_KEY)" : "";
-    super(`${prefix}: ${status} - ${body}${hint}`);
+  constructor(prefix, status, body, hint) {
+    const shownBody = body.length > 2048 ? `${body.slice(0, 2048)}\u2026 [truncated ${body.length - 2048} chars]` : body;
+    super(`${prefix}: ${status} - ${shownBody}${hint ? ` (${hint})` : ""}`);
     this.name = "HttpError";
     this.status = status;
     this.body = body;
@@ -923,7 +1072,11 @@ function createHttpClient(deps) {
       throw new HttpError(
         deps.errorPrefix,
         response.status,
-        await response.text()
+        await response.text(),
+        response.status === 429 ? rateLimitHint(
+          response.headers.get("ratelimit"),
+          response.headers.get("retry-after")
+        ) : response.status === 401 ? EXPIRED_CREDENTIAL_HINT : void 0
       );
     }
     return isJsonContentType(response.headers.get("content-type")) ? response.json() : { success: true, status: response.status };
@@ -982,7 +1135,15 @@ async function readSseSnapshot(fetchImpl, url, headers, opts) {
       throw new HttpError(
         "Runpod API Error",
         res.status,
-        await res.text().catch(() => "")
+        await res.text().catch(() => ""),
+        // This throw bypasses createHttpClient, so the status hints are built
+        // here too or these two tools alone return a bare 429/401. The 401
+        // hint applies: this request always carries Authorization (see the
+        // headers bound in runtime.ts streamSse).
+        res.status === 429 ? rateLimitHint(
+          res.headers.get("ratelimit"),
+          res.headers.get("retry-after")
+        ) : res.status === 401 ? EXPIRED_CREDENTIAL_HINT : void 0
       );
     }
     for await (const chunk of res.body ?? []) {
@@ -1045,7 +1206,7 @@ async function streamLogsReply(rt, tool, params) {
 }
 
 // src/tools/runtime.ts
-var MCP_SERVER_VERSION = true ? "3.1.0" : "dev";
+var MCP_SERVER_VERSION = true ? "3.2.0" : "dev";
 var SESSION_ID = (0, import_node_crypto.randomUUID)();
 function trackingHeaders(server, ctx) {
   const info = server.server.getClientVersion();
@@ -1095,6 +1256,36 @@ async function graphqlRequest(query, tracking, fetchImpl, url, options) {
       ...options?.variables ? { variables: options.variables } : {}
     })
   });
+  if (!response.ok) {
+    const bodyText = await response.text();
+    let gqlErrors;
+    try {
+      gqlErrors = JSON.parse(bodyText).errors;
+    } catch {
+    }
+    if (Array.isArray(gqlErrors) && gqlErrors.length > 0 && response.status !== 401 && response.status !== 429) {
+      throw new HttpError(
+        "Runpod GraphQL Error",
+        response.status,
+        gqlErrors.map((e) => String(e?.message ?? JSON.stringify(e))).join(", ")
+      );
+    }
+    throw new HttpError(
+      "Runpod GraphQL Error",
+      response.status,
+      bodyText,
+      response.status === 429 ? rateLimitHint(
+        response.headers.get("ratelimit"),
+        response.headers.get("retry-after")
+      ) : (
+        // Only when this request actually carried the caller's API key: the
+        // public path sends no Authorization header, so a 401 from that
+        // host (WAF, misconfigured RUNPOD_PUBLIC_GRAPHQL_URL) says nothing
+        // about the credential — same rationale as observeUnauthorized.
+        response.status === 401 && options?.apiKey ? EXPIRED_CREDENTIAL_HINT : void 0
+      )
+    );
+  }
   const result = await response.json();
   if (result.errors && result.errors.length > 0) {
     throw new Error(
@@ -1511,6 +1702,178 @@ function registerCatalogTools(server, rt) {
       return jsonReply2(result);
     }
   );
+  server.tool(
+    "get-capacity",
+    "GPU capacity across host CUDA versions, as a matrix. Use this to choose an endpoint's allowedCudaVersions/minCudaVersion (or diagnose/widen a capacity-starved one) and to distinguish capacity problems from compatibility problems. Default mode is one call returning, per GPU type, overall stock plus AVAILABLE/UNAVAILABLE per host-reported CUDA version. Pass cudaVersions to deep-probe instead: one stock lookup per listed version, returning graded stock (High/Medium/Low/Out) and the lowest on-demand price per version; a probe that fails transiently reports a per-version error instead of failing the call. Nothing is hidden by default \u2014 set includeUnavailable:false to drop GPUs with no stock on any listed version. Credential-free public catalog data; works on both v1 and v2 APIs. Stock is live, so page cursors can shift between calls. Note: the matrix reflects host-reported versions, but endpoint allowedCudaVersions only accepts values from the platform enum \u2014 check create-endpoint/update-endpoint for the accepted list.",
+    {
+      ...listPaginationParams,
+      cudaVersions: import_zod3.z.array(import_zod3.z.string().regex(/^\d{1,2}\.\d{1,2}$/)).min(1).max(12).optional().describe(
+        'Deep-probe these host CUDA versions (e.g. ["12.8", "13.0"], max 12): one stock lookup per version returns graded stock and price. Omit for the single-call AVAILABLE/UNAVAILABLE matrix across all versions the fleet currently reports.'
+      ),
+      includeUnavailable: import_zod3.z.boolean().optional().describe(
+        'Out-of-stock GPUs are included by default (explicit "Out" cells / all-UNAVAILABLE rows, sorted last). Set false to hide GPUs with no stock on any listed version.'
+      ),
+      gpuTypeIds: import_zod3.z.array(import_zod3.z.string()).optional().describe(
+        "Filter to GPU types matching any of these ids or display names (case-insensitive substring, e.g. ['NVIDIA GeForce RTX 4090'] or ['4090', 'H200'])."
+      ),
+      gpuCount: import_zod3.z.number().int().min(1).max(8).optional().describe("GPUs per worker/pod to check stock for (default 1)."),
+      secureCloudOnly: import_zod3.z.boolean().optional().describe("Restrict the stock lookup to Secure Cloud hosts.")
+    },
+    { title: "Get GPU capacity by CUDA version", ...READ_ONLY },
+    async (params) => {
+      const gpuCount = Math.min(
+        8,
+        Math.max(1, Math.floor(Number(params.gpuCount)) || 1)
+      );
+      const secureArg = params.secureCloudOnly ? ", secureCloud: true" : "";
+      const filterTerms = (params.gpuTypeIds ?? []).filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => t.toLowerCase());
+      const matchesFilter = (gpu) => {
+        if (filterTerms.length === 0) return true;
+        const id = gpu.id.toLowerCase();
+        const name = gpu.displayName.toLowerCase();
+        return filterTerms.some(
+          (term) => id.includes(term) || name.includes(term)
+        );
+      };
+      const stockPriority = {
+        High: 3,
+        Medium: 2,
+        Low: 1
+      };
+      if (!params.cudaVersions?.length) {
+        const data = await graphql(`
+          query {
+            gpuTypes {
+              id
+              displayName
+              memoryInGb
+              secureCloud
+              communityCloud
+              lowestPrice(input: { gpuCount: ${gpuCount}${secureArg} }) {
+                stockStatus
+                uninterruptablePrice
+                gpuTypeCudaVersions {
+                  cudaVersion
+                  availability
+                }
+              }
+            }
+          }
+        `);
+        let rows2 = data.gpuTypes.filter((gpu) => gpu.id !== "unknown" && matchesFilter(gpu)).map((gpu) => {
+          const cuda = {};
+          for (const c of gpu.lowestPrice?.gpuTypeCudaVersions ?? []) {
+            cuda[c.cudaVersion] = c.availability;
+          }
+          return {
+            id: gpu.id,
+            displayName: gpu.displayName,
+            memoryGb: gpu.memoryInGb,
+            secureCloud: gpu.secureCloud,
+            communityCloud: gpu.communityCloud,
+            stockStatus: gpu.lowestPrice?.stockStatus || "unavailable",
+            pricePerHr: gpu.lowestPrice?.uninterruptablePrice ?? null,
+            cudaVersions: cuda
+          };
+        });
+        const availableCount = (r) => Object.values(r.cudaVersions).filter((a) => a === "AVAILABLE").length;
+        if (params.includeUnavailable === false)
+          rows2 = rows2.filter((r) => availableCount(r) > 0);
+        rows2.sort((a, b) => {
+          const diff = availableCount(b) - availableCount(a);
+          if (diff !== 0) return diff;
+          const stockDiff = (stockPriority[b.stockStatus] || 0) - (stockPriority[a.stockStatus] || 0);
+          if (stockDiff !== 0) return stockDiff;
+          return b.memoryGb - a.memoryGb;
+        });
+        return capListResult(rows2, {
+          limit: params.limit,
+          cursor: params.cursor
+        });
+      }
+      const versions = [...new Set(params.cudaVersions)].slice(0, 12);
+      const invalid = versions.filter((v) => !/^\d{1,2}\.\d{1,2}$/.test(v));
+      if (invalid.length > 0) {
+        return jsonReply2({
+          error: `Invalid CUDA version format: ${invalid.join(", ")}. Use "major.minor" strings like "12.8".`,
+          status: 400
+        });
+      }
+      const perVersion = await Promise.allSettled(
+        versions.map(
+          (v) => graphql(`
+            query {
+              gpuTypes {
+                id
+                displayName
+                memoryInGb
+                secureCloud
+                communityCloud
+                lowestPrice(input: { gpuCount: ${gpuCount}, allowedCudaVersions: ["${v}"]${secureArg} }) {
+                  stockStatus
+                  uninterruptablePrice
+                }
+              }
+            }
+          `)
+        )
+      );
+      const probeErrors = {};
+      const byId = /* @__PURE__ */ new Map();
+      versions.forEach((v, i) => {
+        const settled = perVersion[i];
+        if (settled.status === "rejected") {
+          probeErrors[v] = settled.reason instanceof Error ? settled.reason.message : String(settled.reason);
+          return;
+        }
+        for (const gpu of settled.value.gpuTypes) {
+          if (gpu.id === "unknown" || !matchesFilter(gpu)) continue;
+          let row = byId.get(gpu.id);
+          if (!row) {
+            row = {
+              id: gpu.id,
+              displayName: gpu.displayName,
+              memoryGb: gpu.memoryInGb,
+              secureCloud: gpu.secureCloud,
+              communityCloud: gpu.communityCloud,
+              cudaVersions: {}
+            };
+            byId.set(gpu.id, row);
+          }
+          const stock = gpu.lowestPrice?.stockStatus;
+          row.cudaVersions[v] = !stock || stock === "Out" ? { stock: "Out", pricePerHr: null } : {
+            stock,
+            pricePerHr: gpu.lowestPrice?.uninterruptablePrice ?? null
+          };
+        }
+      });
+      let rows = [...byId.values()];
+      const inStockCount = (r) => Object.values(r.cudaVersions).filter((c) => c.stock !== "Out").length;
+      if (params.includeUnavailable === false)
+        rows = rows.filter((r) => inStockCount(r) > 0);
+      rows.sort((a, b) => {
+        const diff = inStockCount(b) - inStockCount(a);
+        if (diff !== 0) return diff;
+        const best = (r) => Math.max(
+          0,
+          ...Object.values(r.cudaVersions).map(
+            (c) => stockPriority[c.stock] || 0
+          )
+        );
+        const bestDiff = best(b) - best(a);
+        if (bestDiff !== 0) return bestDiff;
+        return b.memoryGb - a.memoryGb;
+      });
+      return capListResult(
+        rows,
+        { limit: params.limit, cursor: params.cursor },
+        {
+          probedCudaVersions: versions,
+          ...Object.keys(probeErrors).length > 0 ? { probeErrors } : {}
+        }
+      );
+    }
+  );
   server.tool(
     "get-data-center",
     "Get details for a single data center by id. v2-only \u2014 returns a 501 notice on the v1 API (use list-data-centers there).",
@@ -2195,7 +2558,9 @@ function registerPodTools(server, rt) {
     "create-pod",
     'Create a new GPU/CPU pod on Runpod. Pass gpuTypeIds for a GPU pod, or computeType:"CPU" for a CPU pod (CPU pods are served by the v1 API for now). Pass either imageName or templateId (templateId deploys from an existing template \u2014 its name, image, start command, ports, env, disk, volume, and registry credential are used as defaults, and any field you also pass explicitly replaces the template value for that field, e.g. passing env replaces the whole env set rather than merging; pass containerRegistryAuthId to override or supply a private-image credential, or an empty string to deploy with none). If the user specifies neither an image nor a template, recommend the "Runpod Pytorch 2.8.0" image (runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404) as the default \u2014 it has the most up-to-date CUDA and PyTorch versions.',
     {
-      name: import_zod7.z.string().optional().describe("Name for the pod"),
+      name: import_zod7.z.string().optional().describe(
+        "Name for the pod. Required on v2 unless deploying from a templateId (the template supplies its name as the default)."
+      ),
       imageName: import_zod7.z.string().optional().describe("Docker image to use. Optional when templateId is provided."),
       templateId: import_zod7.z.string().optional().describe(
         "Deploy from an existing template (see list-templates / get-template). The template supplies name, image, start command, ports, env, disk, volume, and registry credential as defaults; any field you also pass replaces the template value for that field (whole-field, not a merge). Override the registry credential with containerRegistryAuthId. Requires the v2 REST API. Still pass gpuTypeIds or computeType to choose the compute \u2014 a template does not pin the pod compute."
@@ -2254,6 +2619,12 @@ function registerPodTools(server, rt) {
             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).",
+            status: 400
+          });
+        }
         if (wantsCpu) {
           if (params.templateId) {
             return jsonReply2({