@runpod/mcp-server 3.0.0 → 3.1.0

package/dist/http.mjs

@@ -5,7 +5,7 @@ import {
   restV2Base,
   restVersionSummary,
   serverlessBase
-} from "./chunk-GTBCNGHE.mjs";
+} from "./chunk-OM6RHPQC.mjs";
 
 // src/http.ts
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -13,7 +13,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "3.0.0" : "dev";
+var SERVER_VERSION = true ? "3.1.0" : "dev";
 function createServer(version = SERVER_VERSION) {
   return new McpServer({
     name: SERVER_NAME,

package/dist/stdio.cjs

@@ -506,15 +506,27 @@ function mapPodUpdateToV2(params) {
     ...compact({ name: params.name })
   };
 }
-function nestedOrUndefined(obj) {
-  const c = compact(obj);
-  return Object.keys(c).length ? c : void 0;
+var DEFAULT_ENDPOINT_TYPE = "QUEUE";
+var DEFAULT_SCALER_VALUE = 4;
+function defaultScalerType(endpointType) {
+  return endpointType === "LOAD_BALANCER" ? "REQUEST_COUNT" : "QUEUE_DELAY";
+}
+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 mapEndpointToV2(params) {
+function endpointWorkers(params) {
+  const workers = compact({
+    min: params.workersMin,
+    max: params.workersMax,
+    idleTimeout: params.idleTimeout
+  });
+  return Object.keys(workers).length ? workers : void 0;
+}
+function endpointCommonToV2(params) {
   return compact({
     name: params.name,
     image: params.imageName,
@@ -524,23 +536,33 @@ function mapEndpointToV2(params) {
     env: params.env,
     registry: params.containerRegistryAuthId,
     gpu: endpointGpuConfig(params.gpuPoolIds, params.gpuCount),
-    workers: nestedOrUndefined({
-      min: params.workersMin,
-      max: params.workersMax
-    }),
-    scaling: nestedOrUndefined({
-      type: params.scalerType,
-      value: params.scalerValue,
-      idleTimeout: params.idleTimeout
-    }),
+    workers: endpointWorkers(params),
     dataCenterIds: params.dataCenterIds?.length ? params.dataCenterIds : void 0,
     networkVolumes: params.networkVolumeIds?.length ? params.networkVolumeIds : void 0,
     timeout: params.executionTimeoutMs,
     flashboot: params.flashboot
   });
 }
-var mapEndpointCreateToV2 = mapEndpointToV2;
-var mapEndpointUpdateToV2 = mapEndpointToV2;
+function mapEndpointCreateToV2(params) {
+  const endpointType = params.endpointType ?? DEFAULT_ENDPOINT_TYPE;
+  return compact({
+    ...endpointCommonToV2(params),
+    type: endpointType,
+    scaling: endpointScaling(
+      params.scalerType ?? defaultScalerType(endpointType),
+      params.scalerValue ?? DEFAULT_SCALER_VALUE
+    )
+  });
+}
+function mapEndpointUpdateToV2(params) {
+  return compact({
+    ...endpointCommonToV2(params),
+    scaling: params.scalerType ? endpointScaling(
+      params.scalerType,
+      params.scalerValue ?? DEFAULT_SCALER_VALUE
+    ) : void 0
+  });
+}
 function mapNetworkVolumeCreateToV2(params) {
   return compact({
     name: params.name,
@@ -846,7 +868,7 @@ function resolveBackend(opts) {
 
 // src/server.ts
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "3.0.0" : "dev";
+var SERVER_VERSION = true ? "3.1.0" : "dev";
 function createServer(version = SERVER_VERSION) {
   return new import_mcp.McpServer({
     name: SERVER_NAME,
@@ -1023,7 +1045,7 @@ async function streamLogsReply(rt, tool, params) {
 }
 
 // src/tools/runtime.ts
-var MCP_SERVER_VERSION = true ? "3.0.0" : "dev";
+var MCP_SERVER_VERSION = true ? "3.1.0" : "dev";
 var SESSION_ID = (0, import_node_crypto.randomUUID)();
 function trackingHeaders(server, ctx) {
   const info = server.server.getClientVersion();
@@ -2409,11 +2431,22 @@ function registerPodTools(server, rt) {
 
 // src/tools/endpoints.ts
 var import_zod8 = require("zod");
+var MIN_QUEUE_DELAY = 0.5;
+var MIN_REQUEST_COUNT = 1;
+var MIN_IDLE_TIMEOUT = 1;
+var MAX_IDLE_TIMEOUT = 3600;
+function scalerValueError(scalerType, scalerValue) {
+  if (scalerType !== "REQUEST_COUNT" || scalerValue === void 0) return;
+  if (!Number.isInteger(scalerValue) || scalerValue < MIN_REQUEST_COUNT) {
+    return `REQUEST_COUNT scales on whole in-flight requests per worker, so scalerValue must be an integer >= ${MIN_REQUEST_COUNT} (got ${scalerValue}). For a fractional target use scalerType QUEUE_DELAY, which takes seconds >= ${MIN_QUEUE_DELAY}.`;
+  }
+  return;
+}
 function registerEndpointTools(server, rt) {
   const { jsonReply: jsonReply2, callRestUrl, backendFor } = rt;
   server.tool(
     "list-endpoints",
-    "List your Serverless endpoints, optionally expanding template and worker details (v1 only). Paginated via limit/cursor.",
+    "List your Serverless endpoints, optionally expanding template and worker details (v1 only). Paginated via limit/cursor. On v2 each endpoint carries its request routing in `type` and the URLs to call it in `requestUrls`.",
     {
       ...listPaginationParams,
       includeTemplate: import_zod8.z.boolean().optional().describe("Include template information (v1 only)"),
@@ -2448,7 +2481,7 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "get-endpoint",
-    "Get one Serverless endpoint by id, optionally expanding template and worker details (v1 only).",
+    "Get one Serverless endpoint by id, optionally expanding template and worker details (v1 only). On v2 the reply carries `type` (queue-based vs load-balancing routing) and `requestUrls` \u2014 the run/runsync/status/... URLs for a queue endpoint, or the base + health URLs for a load-balancing one. Read those rather than constructing endpoint URLs by hand.",
     {
       endpointId: import_zod8.z.string().describe("ID of the endpoint to retrieve"),
       includeTemplate: import_zod8.z.boolean().optional().describe("Include template information (v1 only)"),
@@ -2480,11 +2513,14 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "create-endpoint",
-    "Create a Serverless endpoint. On v2 (default), pass an inline config: imageName + gpuPoolIds (GPU pool names from list-gpu-types \u2014 the `pool` field, e.g. AMPERE_80/ADA_24) plus optional workers/scaling/disk/env. On v1, pass a templateId instead. Worker min/max set autoscaling bounds (min 0 = scale to zero).",
+    "Create a Serverless endpoint. On v2 (default), pass an inline config: imageName + gpuPoolIds (GPU pool names from list-gpu-types \u2014 the `pool` field, e.g. AMPERE_80/ADA_24) plus optional workers/scaling/disk/env. On v1, pass a templateId instead. Worker min/max set autoscaling bounds (min 0 = scale to zero). Use endpointType to pick queue-based (default) or load-balancing request routing; the response `requestUrls` carries the URLs to call the endpoint with.",
     {
       name: import_zod8.z.string().optional().describe("Name for the endpoint"),
       // --- v2 inline-config fields ---
       imageName: import_zod8.z.string().optional().describe("Docker image (v2). Required on v2 instead of a templateId."),
+      endpointType: import_zod8.z.enum(["QUEUE", "LOAD_BALANCER"]).optional().describe(
+        "How requests reach the workers (v2). QUEUE (default) = submit jobs through the managed queue (run/runsync/status/...). LOAD_BALANCER = send HTTP requests straight to worker-defined paths, and forces scalerType REQUEST_COUNT. Fixed at creation \u2014 update-endpoint cannot change it."
+      ),
       gpuPoolIds: import_zod8.z.array(import_zod8.z.string()).optional().describe(
         'GPU pool names (v2, required). The `pool` field from list-gpu-types, e.g. ["AMPERE_80"]. NOT GPU type ids.'
       ),
@@ -2504,9 +2540,15 @@ function registerEndpointTools(server, rt) {
       // --- shared autoscaling fields ---
       workersMin: import_zod8.z.number().optional().describe("Minimum number of workers"),
       workersMax: import_zod8.z.number().optional().describe("Maximum number of workers"),
-      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe("Autoscaler type"),
-      scalerValue: import_zod8.z.number().optional().describe("Autoscaler target value"),
-      idleTimeout: import_zod8.z.number().optional().describe("Idle timeout in seconds before scaling a worker down"),
+      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe(
+        "Autoscaler signal. QUEUE_DELAY scales on how long requests wait in the queue (queue endpoints only); REQUEST_COUNT scales on in-flight requests per worker. Defaults to QUEUE_DELAY for QUEUE endpoints and REQUEST_COUNT for LOAD_BALANCER ones."
+      ),
+      scalerValue: import_zod8.z.number().min(MIN_QUEUE_DELAY).optional().describe(
+        "Autoscaler target for the chosen scalerType \u2014 seconds of queue delay (min 0.5) or in-flight requests per worker (integer, min 1). Defaults to 4."
+      ),
+      idleTimeout: import_zod8.z.number().int().min(MIN_IDLE_TIMEOUT).max(MAX_IDLE_TIMEOUT).optional().describe(
+        "Idle timeout in seconds before scaling a worker down (1-3600). Does not apply to QUEUE endpoints scaling on REQUEST_COUNT."
+      ),
       dataCenterIds: import_zod8.z.array(import_zod8.z.string()).optional().describe("List of preferred data centers")
     },
     { title: "Create endpoint", ...WRITE },
@@ -2531,6 +2573,19 @@ function registerEndpointTools(server, rt) {
             status: 400
           });
         }
+        if (params.endpointType === "LOAD_BALANCER" && params.scalerType === "QUEUE_DELAY") {
+          return jsonReply2({
+            error: "LOAD_BALANCER endpoints have no request queue, so they cannot scale on QUEUE_DELAY. Use scalerType REQUEST_COUNT (the default for this endpoint type), or create a QUEUE endpoint instead.",
+            status: 400
+          });
+        }
+        const scalerError = scalerValueError(
+          params.scalerType ?? (params.endpointType === "LOAD_BALANCER" ? "REQUEST_COUNT" : void 0),
+          params.scalerValue
+        );
+        if (scalerError) {
+          return jsonReply2({ error: scalerError, status: 400 });
+        }
         const body = backend.mapCreate(params);
         const result2 = await callRestUrl(
           `${backend.base}${backend.list}`,
@@ -2568,15 +2623,21 @@ 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.",
+    "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.",
     {
       endpointId: import_zod8.z.string().describe("ID of the endpoint to update"),
       name: import_zod8.z.string().optional().describe("New name for the endpoint"),
       workersMin: import_zod8.z.number().optional().describe("New minimum number of workers"),
       workersMax: import_zod8.z.number().optional().describe("New maximum number of workers"),
-      idleTimeout: import_zod8.z.number().optional().describe("New idle timeout in seconds"),
-      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe("Scaler type"),
-      scalerValue: import_zod8.z.number().optional().describe("Scaler value"),
+      idleTimeout: import_zod8.z.number().int().min(MIN_IDLE_TIMEOUT).max(MAX_IDLE_TIMEOUT).optional().describe(
+        "New idle timeout in seconds (1-3600). Does not apply to queue endpoints scaling on REQUEST_COUNT."
+      ),
+      scalerType: import_zod8.z.enum(["QUEUE_DELAY", "REQUEST_COUNT"]).optional().describe(
+        "New autoscaler signal. Switchable on queue endpoints; load-balancing endpoints only accept REQUEST_COUNT."
+      ),
+      scalerValue: import_zod8.z.number().min(MIN_QUEUE_DELAY).optional().describe(
+        "New autoscaler target \u2014 seconds of queue delay (min 0.5) or in-flight requests per worker (integer, min 1). Applies to the endpoint's current scalerType unless you also pass a new one."
+      ),
       // --- v2-only inline-config fields ---
       imageName: import_zod8.z.string().optional().describe("New Docker image (v2)"),
       gpuPoolIds: import_zod8.z.array(import_zod8.z.string()).optional().describe('New GPU pool names (v2), e.g. ["AMPERE_80"]'),
@@ -2594,13 +2655,28 @@ function registerEndpointTools(server, rt) {
     async (params) => {
       const { endpointId, ...updateParams } = params;
       const backend = backendFor("endpoints");
-      const body = backend.mapUpdate(updateParams);
-      const result = await callRestUrl(
-        `${backend.base}${backend.get(endpointId)}`,
-        "PATCH",
-        body
+      const url = `${backend.base}${backend.get(endpointId)}`;
+      if (backend.version !== "v2") {
+        const body2 = backend.mapUpdate(updateParams);
+        return jsonReply2(await callRestUrl(url, "PATCH", body2));
+      }
+      let scalerType = updateParams.scalerType;
+      if (scalerType === void 0 && updateParams.scalerValue !== void 0) {
+        const current = await callRestUrl(url);
+        scalerType = current?.scaling?.type === "REQUEST_COUNT" ? "REQUEST_COUNT" : "QUEUE_DELAY";
+      }
+      const scalerError = scalerValueError(
+        scalerType,
+        updateParams.scalerValue
       );
-      return jsonReply2(result);
+      if (scalerError) {
+        return jsonReply2({ error: scalerError, status: 400 });
+      }
+      const body = backend.mapUpdate({
+        ...updateParams,
+        scalerType
+      });
+      return jsonReply2(await callRestUrl(url, "PATCH", body));
     }
   );
   server.tool(
@@ -2648,7 +2724,7 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "list-endpoint-workers",
-    "List the workers backing a Serverless endpoint, with their status and an aggregate summary. v2-only \u2014 returns a 501 notice on the v1 API. Paginated via limit/cursor.",
+    "List the workers backing a Serverless endpoint, with their status and an aggregate summary. v2-only \u2014 returns a 501 notice on the v1 API. An UNHEALTHY worker usually means the container is crash-looping (repeated starts that exit before the handler runs) \u2014 jobs on the endpoint will sit IN_QUEUE even though this is a worker failure, not a capacity shortage; inspect it with stream-worker-logs. Zero workers while jobs queue means the endpoint is waiting for GPU capacity. Paginated via limit/cursor.",
     {
       ...listPaginationParams,
       endpointId: import_zod8.z.string().describe("ID of the Serverless endpoint whose workers to list")
@@ -2674,7 +2750,7 @@ function registerEndpointTools(server, rt) {
   );
   server.tool(
     "stream-worker-logs",
-    "Fetch a bounded snapshot of a serverless worker's live logs (container and/or system) via Server-Sent Events. v2-only \u2014 returns a 501 notice on the v1 API. Get the workerId from list-endpoint-workers. Reads for up to maxWaitMs (default 5s) and returns the collected log lines; use `tail` to backfill recent lines first. Large output is truncated (see the `truncated` flag).",
+    "Fetch a bounded snapshot of a serverless worker's live logs (container and/or system) via Server-Sent Events. v2-only \u2014 returns a 501 notice on the v1 API. Get the workerId from list-endpoint-workers. Use this to diagnose UNHEALTHY workers: repeated `start container` system lines with no container output is the crash-loop signature (the container exits before the handler runs). Reads for up to maxWaitMs (default 5s) and returns the collected log lines; use `tail` to backfill recent lines first. Large output is truncated (see the `truncated` flag).",
     {
       endpointId: import_zod8.z.string().describe("ID of the Serverless endpoint the worker belongs to"),
       workerId: import_zod8.z.string().describe(
@@ -2697,8 +2773,67 @@ function registerEndpointTools(server, rt) {
 
 // src/tools/jobs.ts
 var import_zod9 = require("zod");
+var DIAGNOSIS_TTL_MS = 15e3;
+var MAX_DIAGNOSIS_ENTRIES = 500;
+var diagnosisCache = /* @__PURE__ */ new Map();
 function registerJobTools(server, rt) {
-  const { jsonReply: jsonReply2, serverlessRequest } = rt;
+  const { jsonReply: jsonReply2, serverlessRequest, backendFor, callRestUrl } = rt;
+  async function diagnoseQueuedJob(endpointId) {
+    const cached = diagnosisCache.get(endpointId);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.value;
+    }
+    diagnosisCache.delete(endpointId);
+    try {
+      const backend = backendFor("workers");
+      if (backend.version !== "v2") return null;
+      const raw = await callRestUrl(
+        `${backend.base}/serverless/${endpointId}/workers`
+      );
+      const summary = raw?.summary;
+      const workers = raw?.workers ?? [];
+      if (!summary) return null;
+      const remember = (value) => {
+        if (diagnosisCache.size >= MAX_DIAGNOSIS_ENTRIES) {
+          const oldest = diagnosisCache.keys().next().value;
+          if (oldest !== void 0) diagnosisCache.delete(oldest);
+        }
+        diagnosisCache.set(endpointId, {
+          value,
+          expiresAt: Date.now() + DIAGNOSIS_TTL_MS
+        });
+        return value;
+      };
+      if ((summary.unhealthy ?? 0) > 0) {
+        const badIds = workers.filter((w) => w.status === "UNHEALTHY").map((w) => w.id).join(", ");
+        return remember({
+          workerHealth: summary,
+          hint: `${summary.unhealthy} of ${summary.total} worker(s) on this endpoint are UNHEALTHY \u2014 the container is likely crash-looping (repeated starts that exit before the handler runs). The job can stay IN_QUEUE indefinitely; this is a worker failure, NOT a capacity shortage. Inspect the logs with stream-worker-logs${badIds ? ` (workerId: ${badIds})` : ""}.`
+        });
+      }
+      if ((summary.total ?? 0) === 0) {
+        return remember({
+          workerHealth: summary,
+          hint: "No workers are scheduled for this endpoint yet \u2014 it may simply be scaling up from zero (normal for the first seconds of a cold start), or it is waiting for GPU capacity / its GPU-CUDA constraints exclude the currently-available hosts. If this persists, check availability with list-gpu-types or widen the gpuIds/CUDA settings."
+        });
+      }
+      if ((summary.throttled ?? 0) > 0 && (summary.running ?? 0) === 0) {
+        return remember({
+          workerHealth: summary,
+          hint: "Workers exist but are throttled \u2014 the hosts are at capacity right now; the job should start when capacity frees up."
+        });
+      }
+      if ((summary.initializing ?? 0) > 0) {
+        return remember({
+          workerHealth: summary,
+          hint: "A worker is initializing \u2014 likely a cold start (image pull / model load); the job should start soon."
+        });
+      }
+      return remember({ workerHealth: summary, hint: "" });
+    } catch {
+      return null;
+    }
+  }
   const endpointIdSchema = import_zod9.z.string().regex(/^[a-zA-Z0-9_-]+$/, "Invalid endpoint ID format");
   const jobIdSchema = import_zod9.z.string().regex(/^[a-zA-Z0-9_-]+$/, "Invalid job ID format");
   const inputSchema = import_zod9.z.record(import_zod9.z.unknown()).describe(
@@ -2772,7 +2907,7 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "get-job-status",
-    "Check the status of an asynchronous Serverless job. Returns the current status and output when complete. Job statuses: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, TIMED_OUT.",
+    "Check the status of an asynchronous Serverless job. Returns the current status and output when complete. Job statuses: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, TIMED_OUT. IMPORTANT: a job stuck IN_QUEUE does not necessarily mean a capacity shortage \u2014 a worker may have spun up and crash-looped (the platform marks it UNHEALTHY while the job stays queued). When the job is IN_QUEUE this tool attaches a workerHealth summary and a hint; to dig deeper, call list-endpoint-workers (look for UNHEALTHY) and stream-worker-logs.",
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint the job belongs to"
@@ -2785,6 +2920,16 @@ function registerJobTools(server, rt) {
         params.endpointId,
         `/status/${params.jobId}`
       );
+      if (result && typeof result === "object" && result.status === "IN_QUEUE") {
+        const diagnosis = await diagnoseQueuedJob(params.endpointId);
+        if (diagnosis) {
+          return jsonReply2({
+            ...result,
+            workerHealth: diagnosis.workerHealth,
+            ...diagnosis.hint ? { hint: diagnosis.hint } : {}
+          });
+        }
+      }
       return jsonReply2(result);
     }
   );
@@ -2886,7 +3031,7 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "endpoint-health",
-    "Get the health and operational status of a Serverless endpoint, including worker counts and job statistics.",
+    "Get the health and operational status of a Serverless endpoint, including worker counts and job statistics. Use this when jobs are stuck IN_QUEUE: unhealthy workers mean a crash-looping container (a worker failure \u2014 inspect with stream-worker-logs), while zero workers means the endpoint is waiting for GPU capacity.",
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint to check health for"