@runpod/mcp-server 4.3.0 → 4.4.0

package/dist/stdio.cjs

@@ -46,6 +46,9 @@ function publicGraphqlBase(env) {
 function authedGraphqlBase(env) {
   return pick(env.RUNPOD_AUTHED_GRAPHQL_URL, "https://api.runpod.io/graphql");
 }
+function hostedMcpBase(env) {
+  return pick(env.RUNPOD_MCP_URL, "https://mcp.getrunpod.io");
+}
 var init_hosts = __esm({
   "src/_shared/hosts.ts"() {
     "use strict";
@@ -736,9 +739,10 @@ var init_clients = __esm({
     path = __toESM(require("path"), 1);
     import_child_process = require("child_process");
     jsonc = __toESM(require("jsonc-parser"), 1);
+    init_hosts();
     SERVER_NAME2 = "runpod";
     NPM_PACKAGE = "@runpod/mcp-server@latest";
-    HOSTED_URL = process.env.RUNPOD_MCP_URL ?? "https://mcp.getrunpod.io/";
+    HOSTED_URL = `${hostedMcpBase(process.env)}/`;
     PROJECT_BOUNDARY_MARKERS = [
       ".git",
       "package.json",
@@ -1179,7 +1183,7 @@ var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // 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/server.ts
 var import_server3 = require("@modelcontextprotocol/sdk/server/index.js");
@@ -6864,6 +6868,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: {
@@ -7352,6 +7358,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: {
@@ -7396,6 +7403,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: {
@@ -7444,6 +7452,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: {
@@ -9067,6 +9076,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: {
@@ -9089,6 +9099,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: {
@@ -9943,6 +9954,70 @@ function logToolCall(entry) {
   console.error("tool_call", JSON.stringify(entry));
 }
 
+// src/search/knowledge.ts
+init_hosts();
+var SEARCH_NAMESPACES = ["docs", "knowledge", "blog", "site"];
+var MAX_QUERY_CHARS = 2e3;
+var MAX_SEARCH_LIMIT = 20;
+var UNREACHABLE = {
+  status: 504,
+  body: {
+    error: "Runpod knowledge search did not respond.",
+    hint: "Retry the same call once."
+  }
+};
+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 };
+}
+var HOSTED_CLIENT_TIMEOUT_MS = 55e3;
+function hostedSearch(searchUrl, doFetch = fetch) {
+  return async (request, apiKey) => {
+    try {
+      const res = await doFetch(searchUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+        },
+        body: JSON.stringify(request),
+        signal: AbortSignal.timeout(HOSTED_CLIENT_TIMEOUT_MS)
+      });
+      const body = await res.json().catch(() => null);
+      return body ? { status: res.status, body } : {
+        status: 502,
+        body: { error: `Runpod knowledge search returned ${res.status}.` }
+      };
+    } catch {
+      return UNREACHABLE;
+    }
+  };
+}
+
 // src/_shared/credential-check.ts
 var import_node_crypto4 = require("crypto");
 var VALID_TTL_MS = 6e4;
@@ -10274,6 +10349,50 @@ function createAlpTools(opts) {
   return [reportFeedback, saveToJournal, askQuestion, readJournalTool];
 }
 
+// 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/server.ts
 var curatedTools = [
   listEndpoints,
@@ -10286,6 +10405,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.
@@ -10309,9 +10431,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(
@@ -10507,6 +10630,8 @@ function asRecord(value) {
 }
 
 // src/stdio.ts
+init_hosts();
+var SEARCH_URL = `${hostedMcpBase(process.env)}/api/search`;
 var WIZARD_SUBCOMMANDS = ["add", "remove"];
 var subcommand = process.argv[2];
 var isWizardMode = WIZARD_SUBCOMMANDS.includes(subcommand);
@@ -10516,7 +10641,8 @@ async function main(apiKey) {
       apiKey,
       tracking: { transport: "stdio", serverVersion: SERVER_VERSION }
     }),
-    SERVER_VERSION
+    SERVER_VERSION,
+    { search: hostedSearch(SEARCH_URL) }
   );
   await server.connect(new import_stdio.StdioServerTransport());
 }