@runpod/mcp-server 4.3.0 → 4.4.0

package/dist/http.d.cts

@@ -26,6 +26,11 @@ interface RpcSummary {
     client?: string;
 }
 
+/**
+ * Extract the bearer token from an HTTP request's Authorization header.
+ * Returns null if the header is missing or malformed.
+ */
+declare function extractBearerToken(req: IncomingMessage): string | null;
 declare function getBaseUrl(req: {
     headers: {
         host?: string;
@@ -59,4 +64,4 @@ declare function summarizeRpc(messages: JSONRPCMessage[]): RpcSummary;
  */
 declare function handleMcpRequest(req: IncomingMessage, res: ServerResponse, opts?: HandleMcpRequestOptions): Promise<void>;
 
-export { bodyIsCheckable, defaultCredentialChecker, getBaseUrl, handleMcpRequest, parseMcpMessages, prefersJsonResponse, requestLogSampleRate, summarizeRpc };
+export { bodyIsCheckable, defaultCredentialChecker, extractBearerToken, getBaseUrl, handleMcpRequest, parseMcpMessages, prefersJsonResponse, requestLogSampleRate, summarizeRpc };

package/dist/http.d.ts

@@ -26,6 +26,11 @@ interface RpcSummary {
     client?: string;
 }
 
+/**
+ * Extract the bearer token from an HTTP request's Authorization header.
+ * Returns null if the header is missing or malformed.
+ */
+declare function extractBearerToken(req: IncomingMessage): string | null;
 declare function getBaseUrl(req: {
     headers: {
         host?: string;
@@ -59,4 +64,4 @@ declare function summarizeRpc(messages: JSONRPCMessage[]): RpcSummary;
  */
 declare function handleMcpRequest(req: IncomingMessage, res: ServerResponse, opts?: HandleMcpRequestOptions): Promise<void>;
 
-export { bodyIsCheckable, defaultCredentialChecker, getBaseUrl, handleMcpRequest, parseMcpMessages, prefersJsonResponse, requestLogSampleRate, summarizeRpc };
+export { bodyIsCheckable, defaultCredentialChecker, extractBearerToken, getBaseUrl, handleMcpRequest, parseMcpMessages, prefersJsonResponse, requestLogSampleRate, summarizeRpc };

package/dist/http.mjs

@@ -5695,6 +5695,8 @@ var listHubRepos = {
 };
 var deployHubRepo = {
   name: "deploy-hub-repo",
+  // Two sequential upstream calls: together they can outlast a client's request timeout.
+  holdsResponse: true,
   annotations: write,
   description: "Deploy a Runpod Hub repo's listed release as a new Serverless endpoint (the same as clicking Deploy on the Hub). Identify the repo by `repo` (\"owner/name\" from list-hub-repos) or by `hubReleaseId`. The release supplies the prebuilt image, container disk, CUDA constraints, and env-var defaults; pass `env` to override or fill in values (required keys without a default must be provided \u2014 check list-hub-repos with includeConfig:true for the schema). GPU selection comes from the release config when it specifies one; otherwise pass gpuIds (GPU pool names, e.g. 'ADA_24' or 'ADA_80_PRO,AMPERE_80'). Uses the authenticated GraphQL API (no REST home for Hub deploys yet).",
   inputSchema: {
@@ -6183,6 +6185,7 @@ var runEndpoint = {
 };
 var runsyncEndpoint = {
   name: "runsync-endpoint",
+  holdsResponse: true,
   annotations: write,
   description: "Submit a synchronous job to a Serverless endpoint and wait for the result. Best for fast tasks: if the job outlives the wait, the response returns a job ID and a non-terminal status (IN_QUEUE or IN_PROGRESS) to poll with get-job-status. Max payload 20 MB; results expire after 1 minute. The wait parameter extends the server-side wait" + (HOSTED ? ` \u2014 this server runs behind a 60-second gateway deadline, so waits clamp to ${HTTP_LONG_POLL_BUDGET_MS} ms, which is also the effective default. For longer jobs use run-endpoint + get-job-status.` : " to up to 5 minutes (300000 ms); it defaults to 90000 (90 seconds)."),
   inputSchema: {
@@ -6227,6 +6230,7 @@ var runsyncEndpoint = {
 };
 var getJobStatus = {
   name: "get-job-status",
+  holdsResponse: true,
   annotations: readOnly,
   description: "Check the status of a Serverless job. Returns the current status and output when complete. Job statuses: IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, TIMED_OUT. Pass `wait` (milliseconds, up to " + STATUS_WAIT_MAX_MS + ") to BLOCK server-side, polling until the job reaches a terminal status or the budget expires \u2014 use it to ride out a cold start (a first job on a fresh worker pulls the image and loads the model, commonly 1\u20135+ minutes) in a single call instead of returning on the first IN_QUEUE and tight-looping the tool. Without `wait` it returns the current status immediately (a single check). If the budget expires before a terminal status, it returns the latest non-terminal status with pollingTimedOut:true \u2014 call again (with `wait`) to keep blocking. IMPORTANT: a job stuck IN_QUEUE does not necessarily mean a capacity shortage \u2014 a worker may have spun up and crash-looped. When the job is IN_QUEUE this tool attaches a workerHealth summary and a hint. To dig deeper call list-endpoint-workers, then read stream-worker-logs regardless of the status a worker reports: a container failing to start loops while its worker still shows RUNNING or THROTTLED and unhealthy stays 0, so UNHEALTHY is one symptom of a crash loop and not a test for it. The logs are the authority.",
   inputSchema: {
@@ -6275,6 +6279,7 @@ var getJobStatus = {
 };
 var streamJob = {
   name: "stream-job",
+  holdsResponse: true,
   annotations: readOnly,
   description: `Retrieve streaming output from a Serverless job. The worker must support streaming output. Polls /stream/{jobId} and collects chunks until the status is COMPLETED, FAILED, CANCELLED, or TIMED_OUT, for up to ${formatBudget(STREAM_BUDGET_MS)}. If the budget expires first, returns the chunks collected so far with pollingTimedOut: true \u2014 call stream-job again to resume where it left off, or get-job-status to check without streaming.`,
   inputSchema: {
@@ -6507,6 +6512,9 @@ function publicGraphqlBase(env) {
 function authedGraphqlBase(env) {
   return pick(env.RUNPOD_AUTHED_GRAPHQL_URL, "https://api.runpod.io/graphql");
 }
+function knowledgeSearchBase(env) {
+  return pick(env.KNOWLEDGE_SEARCH_URL, "") || void 0;
+}
 
 // node_modules/.pnpm/@runpod+typescript-api-sdk@0.3.0/node_modules/@runpod/typescript-api-sdk/dist/index.js
 var PATH_PARAM_RE = /\{[^{}]+\}/g;
@@ -7912,6 +7920,7 @@ function logParams(args) {
 }
 var streamPodLogs = {
   name: "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.",
   inputSchema: {
@@ -7934,6 +7943,7 @@ var streamPodLogs = {
 };
 var streamWorkerLogs = {
   name: "stream-worker-logs",
+  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.",
   inputSchema: {
@@ -8527,7 +8537,7 @@ function words2(name) {
 
 // src/server.ts
 var SERVER_NAME = "Runpod API Server";
-var SERVER_VERSION = true ? "4.3.0" : "dev";
+var SERVER_VERSION = true ? "4.4.0" : "dev";
 
 // src/specgen/analytics.ts
 import { createHmac } from "crypto";
@@ -8857,6 +8867,177 @@ function createAlpTools(opts) {
   return [reportFeedback, saveToJournal, askQuestion, readJournalTool];
 }
 
+// src/search/knowledge.ts
+var SEARCH_NAMESPACES = ["docs", "knowledge", "blog", "site"];
+var MAX_QUERY_CHARS = 2e3;
+var MAX_SEARCH_LIMIT = 20;
+var ATTEMPTS = 7;
+var BASE_DELAY_MS = 250;
+var ATTEMPT_TIMEOUT_MS = 1e4;
+var RETRY_DEADLINE_MS = 3e4;
+var PLATFORM_LIMIT = /TooManyConcurrentRequests|Too many concurrent requests/;
+var AT_CAPACITY = {
+  status: 503,
+  body: {
+    error: "Runpod knowledge search is at capacity.",
+    hint: "Retry the same call in a few seconds."
+  }
+};
+var UNREACHABLE = {
+  status: 504,
+  body: {
+    error: "Runpod knowledge search did not respond.",
+    hint: "Retry the same call once."
+  }
+};
+function searchConfigured(env = process.env) {
+  return Boolean(knowledgeSearchBase(env) && env.RUNPOD_ASSISTANT_API_KEY);
+}
+function parseSearchRequest(raw) {
+  if (typeof raw.query !== "string" || !raw.query.trim()) {
+    return { error: "query must be a non-empty string." };
+  }
+  if (raw.query.length > MAX_QUERY_CHARS) {
+    return { error: `query exceeds ${MAX_QUERY_CHARS} characters.` };
+  }
+  const request = { query: raw.query };
+  if (raw.namespaces !== void 0) {
+    if (!Array.isArray(raw.namespaces) || raw.namespaces.length === 0 || !raw.namespaces.every(
+      (ns) => SEARCH_NAMESPACES.includes(ns)
+    )) {
+      return {
+        error: `namespaces must be a non-empty list of: ${SEARCH_NAMESPACES.join(", ")}.`
+      };
+    }
+    request.namespaces = raw.namespaces;
+  }
+  if (raw.limit !== void 0) {
+    if (typeof raw.limit !== "number" || !Number.isInteger(raw.limit) || raw.limit < 1 || raw.limit > MAX_SEARCH_LIMIT) {
+      return {
+        error: `limit must be an integer from 1 to ${MAX_SEARCH_LIMIT}.`
+      };
+    }
+    request.limit = raw.limit;
+  }
+  return { request };
+}
+async function searchKnowledge(request, opts = {}) {
+  const env = opts.env ?? process.env;
+  const doFetch = opts.fetch ?? fetch;
+  const sleep2 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = opts.now ?? Date.now;
+  if (!searchConfigured(env)) {
+    return {
+      status: 503,
+      body: { error: "Knowledge search is not configured on this server." }
+    };
+  }
+  const url = `${knowledgeSearchBase(env)}/v1/search`;
+  const init = {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${env.RUNPOD_ASSISTANT_API_KEY}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ ...request, source: "runpod-mcp" })
+  };
+  const startedAt = now();
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const res = await doFetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(ATTEMPT_TIMEOUT_MS)
+      });
+      if (res.ok) {
+        const data = await res.json().catch(() => null);
+        if (!data) {
+          console.warn("knowledge_search_failed status=200 invalid_json");
+          return {
+            status: 502,
+            body: { error: "Runpod knowledge search failed." }
+          };
+        }
+        return {
+          status: 200,
+          body: {
+            text: String(data.text ?? ""),
+            totalResults: Number(data.totalResults ?? 0),
+            failedNamespaces: Array.isArray(data.failedNamespaces) ? data.failedNamespaces : []
+          }
+        };
+      }
+      const text = await res.text();
+      const retryable = res.status === 503 || res.status === 429 || PLATFORM_LIMIT.test(text);
+      if (!retryable) {
+        console.warn(`knowledge_search_failed status=${res.status}`);
+        return res.status === 400 ? { status: 400, body: { error: errorField(text) } } : { status: 502, body: { error: "Runpod knowledge search failed." } };
+      }
+    } catch (error) {
+      console.warn(
+        `knowledge_search_unreachable ${error instanceof Error ? error.name : "error"}`
+      );
+      return UNREACHABLE;
+    }
+    const delay = Math.random() * BASE_DELAY_MS * 2 ** (attempt - 1);
+    if (attempt >= ATTEMPTS || now() - startedAt + delay > RETRY_DEADLINE_MS) {
+      return AT_CAPACITY;
+    }
+    await sleep2(delay);
+  }
+}
+function errorField(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.error === "string") return parsed.error;
+  } catch {
+  }
+  return "Invalid search request.";
+}
+
+// src/specgen/tools/search.ts
+function createSearchDocsTool(search) {
+  return {
+    name: "search-docs",
+    annotations: readOnly,
+    recordedArguments: ["limit"],
+    description: 'Search Runpod documentation, curated support knowledge, the Runpod blog and runpod.io for passages that answer a question, for example "how do I attach a network volume to a Serverless endpoint". Returns ranked passages with their source URLs. Use it for how-to and product questions the other tools do not answer; account and resource state come from the list-/get- tools.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          maxLength: MAX_QUERY_CHARS,
+          description: "The question, in natural language."
+        },
+        namespaces: {
+          type: "array",
+          items: { type: "string", enum: [...SEARCH_NAMESPACES] },
+          minItems: 1,
+          description: "Sources to search: docs (docs.runpod.io), knowledge (curated support answers), blog, site (runpod.io pages). Default: docs, knowledge, blog."
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: MAX_SEARCH_LIMIT,
+          description: "Most passages to return. Default 8."
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    handler: async (ctx, args) => {
+      const parsed = parseSearchRequest(args);
+      if ("error" in parsed) return badRequest(parsed.error);
+      const outcome = await search(parsed.request, ctx.apiKey);
+      return {
+        ok: outcome.status === 200,
+        status: outcome.status,
+        payload: outcome.body
+      };
+    }
+  };
+}
+
 // src/specgen/ops.ts
 import { createHash, randomBytes } from "crypto";
 var SALT = randomBytes(16).toString("hex");
@@ -8881,6 +9062,9 @@ var curatedTools = [
   listPublicEndpoints,
   ...knowledgeTools
 ];
+var responseHoldingTools = new Set(
+  curatedTools.filter((tool) => tool.holdsResponse).map((tool) => tool.name)
+);
 var SERVER_INSTRUCTIONS = `These tools cover the Runpod v2 REST surface: compute catalog (GPUs, CPUs, data centers, capacity), pods, serverless endpoints and jobs, templates, network volumes, container registries, billing, public endpoints, and the Hub.
 
 Answer from live reads, as facts. Account and availability questions can only be answered from tool data: call the relevant list-/get- tool and quote the figures, names, and ids it returns verbatim. State stock and status definitively from the read you just made \u2014 never "probably" or "check later". When the user names a resource loosely ("my comfyui pod"), resolve it with a list- tool; ask only on genuine ambiguity. If nothing exists (no pods, zero spend), say exactly that \u2014 an honest empty answer is complete.
@@ -8904,9 +9088,10 @@ CONTRIBUTING BACK IS OPTIONAL. Four tools feed Runpod's agent-learning pipeline,
 function createSpecgenServer(ctx, version = "0.1.0", opts = {}) {
   const rateLimiter = opts.rateLimiter ?? noopRateLimiter;
   const caller = callerId(ctx.apiKey);
-  const configuredCuratedTools = opts.alp ? [...curatedTools, ...createAlpTools(opts.alp)] : curatedTools;
   const servedCuratedTools = [
-    ...configuredCuratedTools,
+    ...curatedTools,
+    ...opts.search ? [createSearchDocsTool(opts.search)] : [],
+    ...opts.alp ? createAlpTools(opts.alp) : [],
     createDescribeTool(() => [...servedCuratedTools, ...generatedTools])
   ];
   const callShapeOnlyTools = new Set(
@@ -9531,9 +9716,12 @@ function earlyCredentialCheckSkip(req) {
   if (credentialCheckMayBeWrongEnvironment()) return "skip_env_mismatch";
   return null;
 }
-var isToolCall = (message) => CallToolRequestSchema2.safeParse(message).success;
+var callsResponseHoldingTool = (message) => {
+  const call = CallToolRequestSchema2.safeParse(message);
+  return call.success && responseHoldingTools.has(call.data.params.name);
+};
 function prefersJsonResponse(messages) {
-  return messages.length > 0 && !messages.some(isToolCall);
+  return messages.length > 0 && !messages.some(callsResponseHoldingTool);
 }
 var DEFAULT_REQUEST_LOG_SAMPLE_RATE = 0.1;
 function requestLogSampleRate(env = process.env) {
@@ -9718,6 +9906,9 @@ async function handleMcpRequest(req, res, opts = {}) {
           harnessSource: "user_agent"
         }
       } : {},
+      // search-docs: listed only where the deployment holds the assistant's
+      // service key; the search runs in-process with it.
+      ...searchConfigured() ? { search: (request) => searchKnowledge(request) } : {},
       ...notFoundLimiter ? {
         rateLimiter: notFoundLimiter.rateLimiter,
         onToolResult: notFoundLimiter.onToolResult
@@ -9746,6 +9937,7 @@ async function handleMcpRequest(req, res, opts = {}) {
 export {
   bodyIsCheckable,
   defaultCredentialChecker,
+  extractBearerToken,
   getBaseUrl,
   handleMcpRequest,
   parseMcpMessages,