@runpod/mcp-server 4.10.0 → 4.10.1

package/dist/stdio.mjs

@@ -12,7 +12,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/server.ts
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "4.10.0" : "dev";
+var SERVER_VERSION = true ? "4.10.1" : "dev";
 
 // src/specgen/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -219,6 +219,14 @@ function validateArguments(inputSchema, args) {
   }
   return null;
 }
+function withoutNullOptionals(inputSchema, args) {
+  const required = new Set(inputSchema.required ?? []);
+  return Object.fromEntries(
+    Object.entries(args).filter(
+      ([name, value]) => value !== null || required.has(name)
+    )
+  );
+}
 async function dispatchGeneratedTool(client, tool, args) {
   const rejected = validateArguments(tool.inputSchema, args);
   if (rejected) return rejected;
@@ -9848,23 +9856,40 @@ function createRunpodClient(options = {}) {
 // src/specgen/clients/sse.ts
 var LOG_STREAM_DEFAULT_WAIT_MS = 5e3;
 var LOG_STREAM_MAX_BYTES = 256 * 1024;
+var LOG_STREAM_CONNECT_TIMEOUT_MS = 1e4;
+var LOG_SNAPSHOT_MAX_CHARS = 32e3;
 function createSseReader(options = {}) {
   const apiKey = options.apiKey ?? process.env.RUNPOD_API_KEY;
   const fetchImpl = options.fetchImpl ?? fetch;
+  const connectTimeoutMs = options.connectTimeoutMs ?? LOG_STREAM_CONNECT_TIMEOUT_MS;
   return async (url, opts) => {
     if (!apiKey) throw missingKeyError();
     const chunks = [];
     let bytes = 0;
     let truncated = false;
     let streamEstablished = false;
+    const connect = new AbortController();
+    const connectTimer = setTimeout(
+      () => connect.abort(
+        new DOMException(
+          `Runpod log stream sent no headers within ${connectTimeoutMs}ms`,
+          "TimeoutError"
+        )
+      ),
+      connectTimeoutMs
+    );
     try {
-      const response = await createDeadlineFetch(fetchImpl, opts.maxWaitMs)(url, {
+      const response = await createDeadlineFetch(
+        fetchImpl,
+        connectTimeoutMs + opts.maxWaitMs
+      )(url, {
         method: "GET",
         headers: {
           Authorization: `Bearer ${apiKey}`,
           Accept: "text/event-stream"
-        }
-      });
+        },
+        signal: connect.signal
+      }).finally(() => clearTimeout(connectTimer));
       if (!response.ok) {
         const body = await response.text().catch(() => "");
         throw new HttpError(
@@ -9875,14 +9900,31 @@ function createSseReader(options = {}) {
       }
       streamEstablished = true;
       if (response.body) {
-        for await (const chunk of response.body) {
-          const boundedChunk = chunk.subarray(0, opts.maxBytes - bytes);
-          chunks.push(boundedChunk);
-          bytes += boundedChunk.length;
-          if (bytes >= opts.maxBytes) {
-            truncated = true;
-            break;
+        const reader = response.body.getReader();
+        let timer;
+        const windowClosed = new Promise((resolve) => {
+          timer = setTimeout(() => resolve(null), opts.maxWaitMs);
+        });
+        try {
+          for (; ; ) {
+            const read = reader.read();
+            read.catch(() => {
+            });
+            const next = await Promise.race([read, windowClosed]);
+            if (next === null || next.done) break;
+            const boundedChunk = next.value.subarray(0, opts.maxBytes - bytes);
+            chunks.push(boundedChunk);
+            bytes += boundedChunk.length;
+            if (bytes >= opts.maxBytes) {
+              truncated = true;
+              break;
+            }
           }
+        } finally {
+          clearTimeout(timer);
+          void reader.cancel().catch(() => {
+          });
+          reader.releaseLock();
         }
       }
     } catch (err) {
@@ -9908,7 +9950,80 @@ async function collectLogSnapshot(reader, logsUrl, params) {
   for await (const event of iterateLogEvents(new Response(raw).body)) {
     items.push(event.data);
   }
-  return { items, count: items.length, truncated };
+  return fitSnapshot(items, truncated);
+}
+var serializedLength = (snapshot) => JSON.stringify(snapshot, null, 2).length;
+var LOG_ENTRY_MAX_CHARS = 16e3;
+var CLIPPABLE_KEYS = ["line", "raw"];
+function clipText(text, keep) {
+  const code = text.charCodeAt(keep - 1);
+  if (keep > 0 && code >= 55296 && code <= 56319) keep--;
+  return `${text.slice(0, keep)}\u2026 [clipped ${text.length - keep} chars]`;
+}
+function clipEntry(entry) {
+  let clipped = false;
+  const out = { ...entry };
+  for (const key of CLIPPABLE_KEYS) {
+    const text = out[key];
+    if (typeof text === "string" && text.length > LOG_ENTRY_MAX_CHARS) {
+      out[key] = clipText(text, LOG_ENTRY_MAX_CHARS);
+      clipped = true;
+    }
+  }
+  return { entry: out, clipped };
+}
+function fitEntry(entry, maxChars) {
+  const size = (e) => serializedLength({ items: [e], count: 1, truncated: false });
+  const out = { ...entry };
+  const keys = Object.keys(out).filter((key) => key !== "ts" && typeof out[key] === "string").sort((a, b) => out[b].length - out[a].length);
+  for (const key of keys) {
+    if (size(out) <= maxChars) break;
+    const text = entry[key];
+    let lo = 0;
+    let hi = Math.min(text.length, LOG_ENTRY_MAX_CHARS);
+    while (lo < hi) {
+      const mid = Math.ceil((lo + hi) / 2);
+      if (size({ ...out, [key]: clipText(text, mid) }) <= maxChars)
+        lo = mid;
+      else hi = mid - 1;
+    }
+    out[key] = clipText(text, lo);
+  }
+  return out;
+}
+var entryTs = (entry) => entry?.ts;
+function fitSnapshot(items, truncated, maxChars = LOG_SNAPSHOT_MAX_CHARS) {
+  let cut = truncated;
+  const entries = items.map((item) => {
+    const { entry, clipped } = clipEntry(item);
+    if (clipped) cut = true;
+    return entry;
+  });
+  const snapshot = (n, isCut) => ({
+    items: entries.slice(0, n),
+    count: n,
+    truncated: isCut
+  });
+  const whole = snapshot(entries.length, cut);
+  if (entries.length === 0 || serializedLength(whole) <= maxChars) return whole;
+  if (serializedLength(snapshot(1, true)) > maxChars) {
+    entries[0] = fitEntry(items[0], maxChars);
+    if (entries.length === 1) return snapshot(1, true);
+  }
+  let lo = 1;
+  let hi = entries.length - 1;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (serializedLength(snapshot(mid, true)) <= maxChars) lo = mid;
+    else hi = mid - 1;
+  }
+  let keep = lo;
+  const omittedTs = entryTs(entries[keep]);
+  if (omittedTs !== void 0) {
+    while (keep > 0 && entryTs(entries[keep - 1]) === omittedTs) keep--;
+    if (keep === 0) keep = lo;
+  }
+  return snapshot(keep, true);
 }
 
 // src/specgen/tools/logs.ts
@@ -9926,13 +10041,13 @@ var logStreamProperties = {
   },
   since: {
     type: "string",
-    description: "RFC3339 timestamp to resume from; when set, `tail` is ignored."
+    description: "RFC3339 timestamp to resume after (exclusive). Replays container lines only; system lines stream live from the call. When set, `tail` is ignored."
   },
   maxWaitMs: {
     type: "integer",
     minimum: 500,
     maximum: 3e4,
-    description: "How long to read the stream, in ms (default 5000, max 30000)"
+    description: "How long to read the stream once it opens, in ms (default 5000, max 30000)"
   }
 };
 function baseUrl() {
@@ -9958,7 +10073,7 @@ var streamPodLogs = {
   title: "Stream Pod logs",
   holdsResponse: true,
   annotations: readOnly,
-  description: "Read a bounded snapshot of a Pod's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the byte cap cut the output. Use `since` to resume from a timestamp.",
+  description: "Read a bounded snapshot of a Pod's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the size cap cut the output. For later container lines, call again with `since` set to the last container line's `ts`; `since` does not replay system lines, so for those request a smaller `tail`.",
   inputSchema: {
     type: "object",
     properties: {
@@ -9980,10 +10095,10 @@ var streamPodLogs = {
 var streamWorkerLogs = {
   name: "stream-worker-logs",
   title: "Stream worker logs",
-  directoryDescription: "Read a bounded snapshot of a Serverless worker's logs (container, system, or both). Holds the live stream open for maxWaitMs and returns the parsed log lines; truncated: true means the byte cap cut the output. A worker whose container keeps failing to start can report RUNNING or THROTTLED while its logs show the failure.",
+  directoryDescription: "Read a bounded snapshot of a Serverless worker's logs (container, system, or both). Holds the live stream open for maxWaitMs and returns the parsed log lines; truncated: true means the size cap cut the output. A worker whose container keeps failing to start can report RUNNING or THROTTLED while its logs show the failure.",
   holdsResponse: true,
   annotations: readOnly,
-  description: "Read a bounded snapshot of a Serverless worker's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the byte cap cut the output. Get worker IDs from list-endpoint-workers. Use this whenever a job stays IN_QUEUE while workers exist, whatever status they report \u2014 a crash-looping container often still shows RUNNING or THROTTLED with unhealthy 0, so these logs, not the worker status, are what identify a crash loop.",
+  description: "Read a bounded snapshot of a Serverless worker's logs (container and/or system source). Holds the live stream open for maxWaitMs and returns the parsed log lines; `truncated: true` means the size cap cut the output. For later container lines, call again with `since` set to the last container line's `ts`; `since` does not replay system lines, so for those request a smaller `tail`. Get worker IDs from list-endpoint-workers. Use this whenever a job stays IN_QUEUE while workers exist, whatever status they report \u2014 a crash-looping container often still shows RUNNING or THROTTLED with unhealthy 0, so these logs, not the worker status, are what identify a crash loop.",
   inputSchema: {
     type: "object",
     properties: {
@@ -10129,6 +10244,7 @@ import {
   loadKnowledge
 } from "@runpod/plugin-knowledge";
 var knowledge = loadKnowledge();
+var resolveGuideId = (id) => knowledge.aliases?.[id] ?? id;
 var hiddenRules = new Set(
   (process.env.KNOWLEDGE_HIDDEN_RULES ?? "").split(",").map((id) => id.trim()).filter(Boolean)
 );
@@ -10305,7 +10421,9 @@ var readGuide = {
   title: "Read guide",
   annotations: bundledRead,
   recordedArguments: ["id"],
-  recordedGuideKind: (args) => knowledge.guides.find((guide) => guide.id === String(args.id).trim())?.kind,
+  recordedGuideKind: (args) => knowledge.guides.find(
+    (guide) => guide.id === resolveGuideId(String(args.id).trim())
+  )?.kind,
   description: 'Read one official Runpod guide in full, by the id list-guides returns (for example "runpod-usage/storage" or "golden-path/06-dev-pod").',
   inputSchema: {
     type: "object",
@@ -10317,7 +10435,9 @@ var readGuide = {
   },
   handler: async (_ctx, args) => {
     const id = String(args.id).trim();
-    const guide = knowledge.guides.find((candidate) => candidate.id === id);
+    const guide = knowledge.guides.find(
+      (candidate) => candidate.id === resolveGuideId(id)
+    );
     if (!guide) {
       const close = knowledge.guides.filter(
         (candidate) => candidate.id.includes(id) || id.includes(candidate.id)
@@ -10472,6 +10592,12 @@ var guideResources = knowledge.guides.map((guide) => ({
   mimeType: "text/markdown",
   text: guide.body
 }));
+var findGuideResource = (resources, uri) => {
+  const id = uri.startsWith(GUIDE_URI_PREFIX) ? resolveGuideId(uri.slice(GUIDE_URI_PREFIX.length)) : void 0;
+  return resources.find(
+    (resource) => resource.uri === uri || resource.uri === GUIDE_URI_PREFIX + id
+  );
+};
 
 // src/specgen/prose.ts
 var ABBREVIATIONS = ["e.g.", "i.e.", "etc.", "vs."];
@@ -10719,6 +10845,7 @@ function captureToolCall(apiKey, event) {
     server_version: event.serverVersion,
     ...event.clientName ? { client_name: event.clientName } : {},
     ...event.guideKind ? { guide_kind: event.guideKind } : {},
+    ...event.errorClass ? { error_class: event.errorClass } : {},
     ...event.blockedBy ? { blocked_by: event.blockedBy } : {},
     ...event.profile ? { profile: event.profile } : {},
     ...args
@@ -11496,7 +11623,7 @@ These tools manage infrastructure only. They do not do SSH sessions, file transf
 
 OFFICIAL GUIDES AND FACTS. list-guides and read-guide serve the official Runpod plugin's skills, reference docs and live-verified golden paths, so you have them even without the plugin installed. For a multi-step or billable task, look for a matching golden path first. lookup-concept and search-concepts answer exact questions about how Runpod works (what a stopped pod keeps, where a volume lives) with the public source for each fact.
 
-PLAYBOOKS \u2014 READ BEFORE ACTING. Each Runpod task has a journey playbook carrying its procedure, pitfalls and report format. Before the FIRST Runpod tool call of a session, load the plugin's runpod-mcp skill if you have it, otherwise read-guide runpod-mcp (also the runpod://guides/runpod-mcp resource): it routes the request to a journey guide \u2014 deploying an endpoint reads serverless-deploy, diagnosing a broken pod reads pod-doctor, cost questions read cost-audit, and so on \u2014 and states the answer contract. A reply produced without the routed playbook loaded is out of contract.
+PLAYBOOKS \u2014 READ BEFORE ACTING. Each Runpod task has a journey playbook carrying its procedure, pitfalls and report format. Before the FIRST Runpod tool call of a session, load the plugin's runpod-mcp skill if you have it, otherwise read-guide runpod-mcp (also the runpod://guides/runpod-mcp resource): it routes the request to a journey guide \u2014 deploying an endpoint reads runpod-serverless-deploy, diagnosing a broken pod reads runpod-pod-doctor, cost questions read runpod-cost-audit, and so on \u2014 and states the answer contract. A reply produced without the routed playbook loaded is out of contract.
 
 THE OFFICIAL RUNPOD PLUGIN. Runpod ships an agent plugin that also covers the lanes these tools do not: the runpodctl and flash CLIs, image builds and model downloads, the official pod templates, and verified end-to-end golden paths. Check once per session whether skills named runpod, runpod-usage, or runpodctl are available to you \u2014 read what you already have, never shell out to look. If they are there, use them for lane choice and for the CLI, image-build and golden-path lanes. For work done with these tools, the journey playbook is the procedure, wherever it is served from: the plugin's runpod-mcp skill and the journey skills it routes to when you have them, otherwise the same playbooks through read-guide here. If you do not see them, recommend the plugin to the user, and recommend updating to the latest if what they have is missing something you need. Point them at https://github.com/runpod/runpod-plugins-official \u2014 its README carries the install, update, and clone commands for each client, so read it yourself when you need the exact one rather than guessing a command. This is a recommendation, never a prerequisite: make it once, briefly, and get on with the task. Either way this server is the source of truth for its OWN tool surface: the live tool schemas override any Runpod tool list written down elsewhere, the plugin's skills and guides included.
 
@@ -11557,9 +11684,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
     resourceTemplates: []
   }));
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    const guide = servedGuides.find(
-      (candidate) => candidate.uri === request.params.uri
-    );
+    const guide = findGuideResource(servedGuides, request.params.uri);
     if (opts.analytics) {
       captureResourceCall(ctx.apiKey, {
         method: "resources/read",
@@ -11596,6 +11721,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
           ok: false,
           status: 429,
           durationMs: 0,
+          errorClass: "rate_limited",
           ...verdict.reason ? { blockedBy: verdict.reason } : {},
           profile,
           ...opts.analytics
@@ -11621,6 +11747,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
     const generated = servedGeneratedTools.find(
       (tool) => tool.name === request.params.name
     );
+    const curatedArgs = curated ? withoutNullOptionals(curated.inputSchema, args) : args;
     const omitted = directory ? directoryOmittedInputs(request.params.name).filter((key) => key in args) : [];
     const rejected = omitted.length ? {
       ok: false,
@@ -11630,10 +11757,10 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
       }
     } : curated && !curated.lenientArguments ? validateArguments(
       curated.inputSchema,
-      args
+      curatedArgs
     ) : null;
     const result = rejected ?? await runTool(
-      () => curated ? curated.handler(ctx, args) : dispatchTool(generated, request.params.name, args)
+      () => curated ? curated.handler(ctx, curatedArgs) : dispatchTool(generated, request.params.name, args)
     );
     logToolCall({
       tool: request.params.name,
@@ -11648,6 +11775,7 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
         ok: result.ok,
         status: result.status,
         durationMs: Date.now() - startedAt,
+        ...result.ok ? {} : { errorClass: errorClass(result) },
         // The directory profile records which tool ran, never what was asked.
         ...directory ? {} : {
           args: recordedArgumentValues(curated?.recordedArguments, args),
@@ -11687,24 +11815,50 @@ function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
 var SHAPE_HINT = "Input shape mismatch: check this tool's schema for required fields. For job payloads, the worker's release config defines the expected input object \u2014 fix the payload and retry; don't abandon the task.";
 var DETAIL_HINTS = [
   [
-    /no longer any instances available|not enough free GPUs/i,
-    "Capacity, not input: the request is valid but no machine can take it right now. Don't change the payload shape. Retry with another GPU type, data center, cloud, CUDA version or count, or try again later. For a stopped Pod, its host's GPUs are taken; that Pod can only start once they free up."
+    /no longer any instances available|no instances currently available|not enough free GPUs/i,
+    "Capacity, not input: the request is valid but no machine can take it right now. Don't change the payload shape. Retry with another GPU type, data center, cloud, CUDA version or count, or try again later. For a stopped Pod, its host's GPUs are taken; that Pod can only start once they free up.",
+    "capacity"
   ],
   [
     /at least \$\d|insufficient (?:funds|balance)|\bbalance\b/i,
-    "Account balance, not input: this operation needs funds on the account. Ask the user to add credit in the Runpod console; list-billing shows recent spend."
+    "Account balance, not input: this operation needs funds on the account. Ask the user to add credit in the Runpod console; list-billing shows recent spend.",
+    "balance"
   ],
   [
     /mutually exclusive|cannot be combined with/i,
-    "Two arguments conflict: send only one of them and leave the other out entirely. Do not change anything else."
+    "Two arguments conflict: send only one of them and leave the other out entirely. Do not change anything else.",
+    "conflicting_args"
+  ],
+  // A 400 with a bare "Unauthorized" detail from a write the same key can
+  // otherwise make is upstream's answer for an unfunded account.
+  [
+    /^\s*unauthorized\s*$/i,
+    "Upstream refused this write. With a key that can read, this usually means the account has no balance: ask the user to check their balance in the Runpod console before retrying.",
+    "balance"
   ]
 ];
+function errorClass(result) {
+  const { status } = result;
+  const payload = asRecord(result.payload) ?? { error: result.payload };
+  const detail = detailText(payload);
+  if (status === 400 && detail) {
+    for (const [pattern, , cls] of DETAIL_HINTS)
+      if (pattern.test(detail)) return cls;
+  }
+  if (status === 400 || status === 422) return "validation";
+  if (status === 401) return "auth";
+  if (status === 402) return "balance";
+  if (status === 403) return "permission";
+  if (status === 404) return "not_found";
+  if (status === 429) return "rate_limited";
+  if (status === 504) return "timeout";
+  if (status >= 500) return "server";
+  return "other";
+}
 function errorHint(status, detail) {
   if (status === 400 && detail) {
     for (const [pattern, hint] of DETAIL_HINTS)
       if (pattern.test(detail)) return hint;
-    if (/^unauthorized$/i.test(detail.trim()))
-      return "Upstream refused this write. With a key that can read, this usually means the account has no balance: ask the user to check their balance in the Runpod console before retrying.";
   }
   if (status === 400 || status === 422) return SHAPE_HINT;
   if (status === 401) return "The Runpod API key is missing or invalid.";