@runpod/mcp-server 3.1.0 → 3.3.0

package/dist/stdio.cjs

@@ -45,32 +45,138 @@ function hostedServerConfig(strategy, serverProperty, url) {
   }
   return serverProperty === "servers" ? { type: "http", url } : { url };
 }
-function upsertJsonServer(configPath, serverProperty, value) {
+function describeDialect(dialect) {
+  return dialect === "json" ? "JSON" : "JSONC";
+}
+function parseFailure(content, dialect) {
+  if (dialect === "json") {
+    try {
+      JSON.parse(content);
+      return void 0;
+    } catch (error) {
+      return errMessage(error);
+    }
+  }
+  const errors = [];
+  jsonc.parse(content, errors, { allowTrailingComma: true });
+  return errors.length > 0 ? `JSONC parse error at offset ${errors[0].offset}` : void 0;
+}
+function parseAsClient(content, dialect) {
+  if (dialect !== "json") {
+    return jsonc.parse(content, [], { allowTrailingComma: true });
+  }
+  try {
+    return JSON.parse(content);
+  } catch {
+    return void 0;
+  }
+}
+function readBackEntry(content, serverProperty, dialect) {
+  const parsed = parseAsClient(content, dialect);
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const servers = parsed[serverProperty];
+  if (typeof servers !== "object" || servers === null) return void 0;
+  return servers[SERVER_NAME2];
+}
+function reliesOnLeniency(content) {
+  if (content.trim() === "") return false;
+  try {
+    JSON.parse(content);
+    return false;
+  } catch {
+    return parseFailure(content, "jsonc") === void 0;
+  }
+}
+function upsertJsonServer(configPath, serverProperty, value, dialect) {
+  if (!path.isAbsolute(configPath)) {
+    return {
+      success: false,
+      message: `refusing to write "${configPath}": not an absolute path, so it would resolve against the current directory. This usually means an environment variable (APPDATA, XDG_CONFIG_HOME) is set to an empty or relative value.`
+    };
+  }
   try {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     const content = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
     const edits = jsonc.modify(content, [serverProperty, SERVER_NAME2], value, {
       formattingOptions: { tabSize: 2, insertSpaces: true }
     });
-    fs.writeFileSync(configPath, jsonc.applyEdits(content, edits), "utf8");
+    const updated = jsonc.applyEdits(content, edits).replace(/^\uFEFF/, "");
+    const failure = parseFailure(updated, dialect);
+    if (failure) {
+      const wasAlreadyBroken = content.trim() !== "" && parseFailure(content, dialect) !== void 0;
+      return {
+        success: false,
+        message: wasAlreadyBroken ? `${configPath} could not be parsed as ${describeDialect(dialect)} before this change either (${failure}), so it was left untouched \u2014 this client would not load the entry. Fix the file (or move it aside) and re-run.` : `writing to ${configPath} would leave it unparseable (${failure}), so it was left untouched.`
+      };
+    }
+    const landed = readBackEntry(updated, serverProperty, dialect);
+    if (JSON.stringify(landed) !== JSON.stringify(value)) {
+      return {
+        success: false,
+        message: `${configPath} was left untouched: the entry would have been written where this client does not read it, so it would have had no effect. This usually means "${serverProperty}" appears more than once in the file \u2014 the last one wins, so merge them into a single block and re-run.`
+      };
+    }
+    fs.writeFileSync(configPath, updated, { encoding: "utf8", mode: 384 });
+    if (dialect === "unverified" && reliesOnLeniency(updated)) {
+      return {
+        success: true,
+        message: "written, but this config uses comments or trailing commas and whether this client accepts them is unverified \u2014 if the Runpod server does not appear, remove them"
+      };
+    }
     return { success: true };
   } catch (error) {
     return { success: false, message: errMessage(error) };
   }
 }
-function removeJsonServer(configPath, serverProperty) {
+function removeJsonServer(configPath, serverProperty, dialect) {
+  if (!path.isAbsolute(configPath)) {
+    return {
+      success: false,
+      message: `refusing to touch "${configPath}": not an absolute path. Check APPDATA / XDG_CONFIG_HOME.`
+    };
+  }
   try {
     if (!fs.existsSync(configPath)) {
       return { success: true, message: "nothing to remove" };
     }
     const content = fs.readFileSync(configPath, "utf8");
-    const edits = jsonc.modify(
-      content,
-      [serverProperty, SERVER_NAME2],
-      void 0,
-      { formattingOptions: { tabSize: 2, insertSpaces: true } }
-    );
-    fs.writeFileSync(configPath, jsonc.applyEdits(content, edits), "utf8");
+    if (content.trim() === "") {
+      return { success: true, message: "nothing to remove" };
+    }
+    const existingFailure = parseFailure(content, dialect);
+    if (existingFailure !== void 0) {
+      return {
+        success: false,
+        message: `could not safely remove the Runpod entry from ${configPath}: the existing config is not valid ${describeDialect(dialect)} (${existingFailure}). The original file was left unchanged; repair it or delete the entry by hand.`
+      };
+    }
+    let edits;
+    try {
+      edits = jsonc.modify(content, [serverProperty, SERVER_NAME2], void 0, {
+        formattingOptions: { tabSize: 2, insertSpaces: true }
+      });
+    } catch (error) {
+      if (/empty document/i.test(errMessage(error))) {
+        return { success: true, message: "nothing to remove" };
+      }
+      throw error;
+    }
+    if (edits.length === 0) {
+      return readBackEntry(content, serverProperty, dialect) === void 0 ? { success: true, message: "nothing to remove" } : {
+        success: false,
+        message: `the Runpod entry is still present in ${configPath} and could not be removed automatically \u2014 "${serverProperty}" appears more than once, so the edit targeted a block this client does not read. Delete the entry by hand.`
+      };
+    }
+    const updated = jsonc.applyEdits(content, edits);
+    const brokeIt = parseFailure(updated, dialect) !== void 0;
+    const stillThere = readBackEntry(updated, serverProperty, dialect) !== void 0;
+    if (brokeIt || stillThere) {
+      return {
+        success: false,
+        message: `could not remove the Runpod entry from ${configPath} without ${brokeIt ? "making the config unparseable" : "leaving the entry present"}. The original file was left unchanged so its comments and formatting are preserved; delete the Runpod entry by hand.`
+      };
+    }
+    fs.writeFileSync(configPath, updated, "utf8");
     return { success: true };
   } catch (error) {
     return { success: false, message: errMessage(error) };
@@ -98,56 +204,461 @@ function jsonClient(opts) {
     add: (mode) => {
       const value = mode.kind === "local" ? localServerConfig(mode.apiKey, serverProperty) : hostedServerConfig(hostedStrategy, serverProperty, mode.url);
       return Promise.resolve(
-        upsertJsonServer(opts.configPath(), serverProperty, value)
+        upsertJsonServer(opts.configPath(), serverProperty, value, opts.dialect)
       );
     },
-    remove: () => Promise.resolve(removeJsonServer(opts.configPath(), serverProperty)),
+    dialect: opts.dialect,
+    remove: () => Promise.resolve(
+      removeJsonServer(opts.configPath(), serverProperty, opts.dialect)
+    ),
     describeTarget: () => opts.configPath()
   };
 }
-function findClaudeBinary() {
-  const candidates = [
-    path.join(os.homedir(), ".claude", "local", "claude"),
-    "/usr/local/bin/claude",
-    "/opt/homebrew/bin/claude"
+function claudeCandidates(platform, homedir2, appdata) {
+  if (platform === "win32") {
+    const win = path.win32;
+    const defaultAppdata = win.join(homedir2, "AppData", "Roaming");
+    return [
+      {
+        path: win.join(homedir2, ".local", "bin", "claude.exe"),
+        trustedRoot: homedir2
+      },
+      // npm -g installs a .cmd shim. runClaude bypasses it and resolves the real
+      // native or JavaScript target from the installed package manifest.
+      //
+      // absoluteEnvDir, not `?? `: an empty or relative APPDATA yielded the relative
+      // `npm\claude.cmd`. Candidates are probed before any lookup, so a relative
+      // candidate would resolve against the current directory and receive the live
+      // API key.
+      {
+        path: win.join(
+          absoluteEnvDir(appdata, () => defaultAppdata),
+          "npm",
+          "claude.cmd"
+        ),
+        trustedRoot: defaultAppdata
+      }
+    ];
+  }
+  return [
+    // Where the current native installer puts it (verified on a real install:
+    // ~/.local/bin/claude -> versions/2.1.220). Same reasoning as the Windows
+    // .local\bin\claude.exe entry — it also covers an install whose PATH entry is
+    // missing, which the lookup can never find. Without it, POSIX detection depended
+    // entirely on PATH.
+    {
+      path: path.posix.join(homedir2, ".local", "bin", "claude"),
+      trustedRoot: homedir2
+    },
+    {
+      path: path.posix.join(homedir2, ".claude", "local", "claude"),
+      trustedRoot: homedir2
+    },
+    { path: "/usr/local/bin/claude", trustedRoot: "/usr/local" },
+    { path: "/opt/homebrew/bin/claude", trustedRoot: "/opt/homebrew" }
   ];
+}
+function pathIsInside(candidate, directory, pathApi) {
+  const relative = pathApi.relative(
+    pathApi.resolve(directory),
+    pathApi.resolve(candidate)
+  );
+  return relative === "" || !relative.startsWith(`..${pathApi.sep}`) && relative !== ".." && !pathApi.isAbsolute(relative);
+}
+function isNodeModulesBin(candidate) {
+  return /(^|[\\/])node_modules[\\/]\.bin([\\/]|$)/i.test(candidate);
+}
+function pickClaudeBinary(stdout, platform, cwd) {
+  if (platform === "win32") return null;
+  const hits = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  return hits.find(
+    (hit) => path.posix.isAbsolute(hit) && !isNodeModulesBin(hit) && (cwd === void 0 || !pathIsInside(hit, cwd, path.posix))
+  ) ?? null;
+}
+function projectBoundary(cwd, home2) {
+  let current = cwd;
+  let boundary = null;
+  while (true) {
+    if (current === home2) return boundary;
+    if (PROJECT_BOUNDARY_MARKERS.some(
+      (marker) => exists(path.join(current, marker))
+    )) {
+      boundary = current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return boundary;
+    current = parent;
+  }
+}
+function trustedClaudeBinary(binary, cwd, home2, requiredRoot) {
+  try {
+    const canonicalBinary = fs.realpathSync.native(binary);
+    const canonicalCwd = fs.realpathSync.native(cwd);
+    let canonicalHome;
+    if (home2 !== void 0) {
+      try {
+        canonicalHome = fs.realpathSync.native(home2);
+      } catch {
+        canonicalHome = void 0;
+      }
+    }
+    const projectRoot = projectBoundary(canonicalCwd, canonicalHome);
+    const canonicalRequiredRoot = requiredRoot === void 0 ? void 0 : fs.realpathSync.native(requiredRoot);
+    if (isNodeModulesBin(canonicalBinary) || canonicalRequiredRoot !== void 0 && !pathIsInside(canonicalBinary, canonicalRequiredRoot, path) || projectRoot !== null && pathIsInside(canonicalBinary, projectRoot, path)) {
+      return null;
+    }
+    return canonicalBinary;
+  } catch {
+    return null;
+  }
+}
+function findClaudeBinary(options = {}) {
+  const platform = options.platform ?? process.platform;
+  let homedir2 = options.homedir;
+  if (homedir2 === void 0) {
+    try {
+      homedir2 = os.userInfo().homedir;
+    } catch {
+      homedir2 = null;
+    }
+  }
+  const appdata = options.appdata ?? process.env.APPDATA;
+  const cwd = options.cwd ?? process.cwd();
+  const candidates = homedir2 == null ? [] : claudeCandidates(platform, homedir2, appdata);
   for (const candidate of candidates) {
-    if (exists(candidate)) return candidate;
+    if (!path.isAbsolute(candidate.path) && !path.win32.isAbsolute(candidate.path))
+      continue;
+    if (exists(candidate.path)) {
+      const trusted = trustedClaudeBinary(
+        candidate.path,
+        cwd,
+        homedir2 ?? void 0,
+        candidate.trustedRoot
+      );
+      if (trusted !== null) return trusted;
+    }
   }
   try {
-    (0, import_child_process.execSync)("command -v claude", { stdio: "pipe" });
-    return "claude";
+    if (platform === "win32") return null;
+    const out = (0, import_child_process.execSync)("command -v claude", {
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8"
+    });
+    const binary = pickClaudeBinary(out, platform);
+    return binary === null ? null : trustedClaudeBinary(binary, cwd, homedir2 ?? void 0);
   } catch {
     return null;
   }
 }
-function runClaude(binary, args) {
+function describeCommand(binary, args) {
+  const quote = (s) => /\s/.test(s) || CMD_META.test(s) ? `"${s}"` : s;
+  return [binary, ...args].map(quote).join(" ");
+}
+function describeCommandRedacted(binary, args) {
+  return describeCommand(
+    binary,
+    args.map(
+      (arg) => arg.startsWith("RUNPOD_API_KEY=") ? `RUNPOD_API_KEY=${KEY_PLACEHOLDER}` : arg
+    )
+  );
+}
+function redactSecret(text, secret) {
+  if (!secret) return text;
+  return text.split(secret).join(KEY_PLACEHOLDER);
+}
+function sanitizedClaudeEnv() {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (["path", "comspec", "pathext", "node_options", "node_path"].includes(
+      key.toLowerCase()
+    )) {
+      delete env[key];
+    }
+  }
+  if (process.platform === "win32") {
+    env.Path = path.dirname(process.execPath);
+  } else {
+    env.PATH = [
+      path.dirname(process.execPath),
+      "/usr/local/bin",
+      "/opt/homebrew/bin",
+      "/usr/bin",
+      "/bin"
+    ].join(path.delimiter);
+  }
+  return env;
+}
+function windowsNpmClaudeTarget(binary) {
+  if (process.platform !== "win32" || !binary.toLowerCase().endsWith(".cmd")) {
+    return null;
+  }
   try {
-    (0, import_child_process.execFileSync)(binary, args, { stdio: "pipe" });
-    return { success: true };
-  } catch (error) {
-    const message = errMessage(error);
-    if (message.includes("already exists")) {
-      return { success: true, message: "already configured" };
+    const npmRoot = fs.realpathSync.native(path.dirname(binary));
+    const packageRoot = fs.realpathSync.native(
+      path.join(npmRoot, "node_modules", "@anthropic-ai", "claude-code")
+    );
+    if (!pathIsInside(packageRoot, npmRoot, path)) return null;
+    const manifestPath = fs.realpathSync.native(
+      path.join(packageRoot, "package.json")
+    );
+    if (!pathIsInside(manifestPath, packageRoot, path)) return null;
+    const manifest = JSON.parse(
+      fs.readFileSync(manifestPath, "utf8")
+    );
+    if (manifest === null || typeof manifest !== "object") return null;
+    const bin = manifest.bin;
+    const target = typeof bin === "string" ? bin : bin !== null && typeof bin === "object" ? bin.claude : void 0;
+    if (typeof target !== "string" || target.trim() === "") return null;
+    const entrypoint = fs.realpathSync.native(
+      path.resolve(packageRoot, target)
+    );
+    if (!pathIsInside(entrypoint, packageRoot, path)) return null;
+    if (/\.(?:exe|com)$/i.test(entrypoint)) {
+      return { command: entrypoint, argsPrefix: [] };
+    }
+    if (/\.(?:c?js|mjs)$/i.test(entrypoint)) {
+      return { command: process.execPath, argsPrefix: [entrypoint] };
     }
-    return { success: false, message };
+    return null;
+  } catch {
+    return null;
   }
 }
+function runClaude(binary, args, secret) {
+  const isWindowsCmd = process.platform === "win32" && binary.toLowerCase().endsWith(".cmd");
+  const npmTarget = windowsNpmClaudeTarget(binary);
+  if (isWindowsCmd && npmTarget === null) {
+    return {
+      success: false,
+      refused: true,
+      message: `could not locate a trusted Claude Code npm entrypoint beside ${binary}. Run the shim yourself, substituting your key:
+    ${describeCommandRedacted(binary, args)}`
+    };
+  }
+  const command = npmTarget?.command ?? binary;
+  const commandArgs = [...npmTarget?.argsPrefix ?? [], ...args];
+  const result = (0, import_child_process.spawnSync)(command, commandArgs, {
+    stdio: "pipe",
+    encoding: "utf8",
+    env: sanitizedClaudeEnv()
+  });
+  if (result.error)
+    return {
+      success: false,
+      message: redactSecret(errMessage(result.error), secret)
+    };
+  const stdio = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  if (result.status === 0) return { success: true, output: stdio };
+  if (result.status === null) {
+    return { success: false, message: `killed by ${result.signal}` };
+  }
+  if (stdio.includes("already exists")) {
+    return {
+      success: true,
+      // Deliberately not "to replace the API key": this branch is also reached in
+      // hosted mode, where there is no key — and the pre-existing entry may be of the
+      // other kind entirely, which is exactly what the user needs to know.
+      message: `already configured, existing entry left unchanged \u2014 it was NOT updated to what you just chose (to replace it, run \`${describeCommand(binary, ["mcp", "remove", SERVER_NAME2, "--scope", "user"])}\` first, then re-run this wizard)`
+    };
+  }
+  return {
+    success: false,
+    message: redactSecret(
+      stdio.trim() || `${path.basename(binary)} exited with code ${result.status}`,
+      secret
+    )
+  };
+}
+function absoluteEnvDir(value, fallback) {
+  if (!value || !value.trim()) return fallback();
+  if (!path.isAbsolute(value) && !path.win32.isAbsolute(value))
+    return fallback();
+  return value;
+}
+function claudeUserConfigPath() {
+  const configured = process.env.CLAUDE_CONFIG_DIR;
+  return path.join(
+    configured ? path.resolve(configured) : os.homedir(),
+    ".claude.json"
+  );
+}
+function readClaudeConfigState(configPath) {
+  const unknown = {
+    configPath,
+    userScope: void 0,
+    localScopeDirs: []
+  };
+  if (!path.isAbsolute(configPath)) return unknown;
+  let raw;
+  try {
+    if (!fs.existsSync(configPath)) {
+      return { configPath, userScope: false, localScopeDirs: [] };
+    }
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch {
+    return unknown;
+  }
+  const errors = [];
+  const parsed = jsonc.parse(raw.replace(/^\uFEFF/, ""), errors, {
+    allowTrailingComma: true
+  });
+  if (errors.length > 0 || typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return unknown;
+  }
+  const has = (servers) => typeof servers === "object" && servers !== null && Object.prototype.hasOwnProperty.call(servers, SERVER_NAME2);
+  const own = (key) => Object.prototype.hasOwnProperty.call(parsed, key) ? parsed[key] : void 0;
+  const projects = own("projects");
+  const localScopeDirs = typeof projects === "object" && projects !== null && !Array.isArray(projects) ? Object.entries(projects).filter(([, project]) => has(project?.mcpServers)).map(([dir]) => dir) : [];
+  return { configPath, userScope: has(own("mcpServers")), localScopeDirs };
+}
+function describeDirs(dirs) {
+  if (dirs.length === 1) return dirs[0];
+  return `${dirs.length} project directories (${dirs.slice(0, 3).join(", ")}${dirs.length > 3 ? ", \u2026" : ""})`;
+}
+function interpretRemoveResult(result, state, binary = "claude") {
+  if (result.refused) return result;
+  const alsoElsewhere = state.localScopeDirs.length > 0 ? ` A separate local-scope ${SERVER_NAME2} entry (which may carry its own API key) also exists in ${describeDirs(state.localScopeDirs)} \u2014 this wizard does not touch those. Remove with \`${describeCommand(binary, ["mcp", "remove", SERVER_NAME2, "--scope", "local"])}\` from each.` : "";
+  if (state.userScope === true) {
+    return {
+      success: false,
+      message: `the ${SERVER_NAME2} entry is STILL in Claude Code's user config (${state.configPath}), so your API key is still on disk. ${result.success ? "Most likely that file is not writable \u2014 the CLI reports success anyway." : `The removal command itself failed: ${result.message ?? "no output"}`}${alsoElsewhere}`
+    };
+  }
+  if (state.userScope === false) {
+    return {
+      success: true,
+      message: (result.success ? "removed from your user config" : "nothing to remove in your user config") + alsoElsewhere
+    };
+  }
+  if (result.success) {
+    return {
+      success: true,
+      message: `removal reported success, but ${state.configPath} could not be read to confirm it`
+    };
+  }
+  return { success: false, message: result.message };
+}
+function interpretAddResult(result, state, binary) {
+  if (result.refused || !result.success) return result;
+  if (state.userScope === false) {
+    return {
+      success: false,
+      message: `Claude Code reported success but no ${SERVER_NAME2} entry is in its user config afterwards (${state.configPath}) \u2014 that file is most likely not writable. Nothing was configured.`
+    };
+  }
+  if (state.userScope === true && state.localScopeDirs.length > 0) {
+    return {
+      success: true,
+      message: `${result.message ? `${result.message}; ` : ""}note a local-scope ${SERVER_NAME2} entry also exists in ${describeDirs(state.localScopeDirs)} and takes precedence over the user config there, so Claude Code will keep using it in those projects \u2014 remove it with \`${describeCommand(binary, ["mcp", "remove", SERVER_NAME2, "--scope", "local"])}\` run from each`
+    };
+  }
+  if (state.userScope === void 0) {
+    return {
+      success: true,
+      message: `${result.message ? `${result.message}; ` : ""}could not read ${state.configPath} to confirm the entry landed`
+    };
+  }
+  return { success: true, message: result.message };
+}
+function createClaudeCodeClient(resolveBinary, readState = () => readClaudeConfigState(claudeUserConfigPath())) {
+  return {
+    id: "claude-code",
+    name: "Claude Code",
+    detect: () => Promise.resolve(resolveBinary() !== null),
+    add: (mode) => {
+      const args = mode.kind === "local" ? [
+        "mcp",
+        "add",
+        SERVER_NAME2,
+        "--scope",
+        "user",
+        "-e",
+        `RUNPOD_API_KEY=${mode.apiKey}`,
+        "--",
+        "npx",
+        "-y",
+        NPM_PACKAGE
+      ] : [
+        "mcp",
+        "add",
+        "--transport",
+        "http",
+        "--scope",
+        "user",
+        SERVER_NAME2,
+        mode.url
+      ];
+      const binary = resolveBinary();
+      if (!binary) {
+        return Promise.resolve({
+          success: false,
+          message: `claude CLI not found in the standard install locations. If Claude Code is installed somewhere custom, register it yourself${mode.kind === "local" ? ", substituting your key" : ""}:
+    ${describeCommandRedacted("claude", args)}`
+        });
+      }
+      const result = runClaude(
+        binary,
+        args,
+        mode.kind === "local" ? mode.apiKey : void 0
+      );
+      if (!result.success) return Promise.resolve(result);
+      return Promise.resolve(interpretAddResult(result, readState(), binary));
+    },
+    remove: () => {
+      const binary = resolveBinary();
+      if (!binary) {
+        return Promise.resolve({
+          success: false,
+          message: `claude CLI not found in the standard install locations. If Claude Code is installed somewhere custom, remove the entry yourself:
+    ${describeCommand("claude", ["mcp", "remove", SERVER_NAME2, "--scope", "user"])}`
+        });
+      }
+      const result = runClaude(binary, [
+        "mcp",
+        "remove",
+        "--scope",
+        "user",
+        SERVER_NAME2
+      ]);
+      if (result.refused) return Promise.resolve(result);
+      return Promise.resolve(
+        interpretRemoveResult(result, readState(), binary)
+      );
+    },
+    describeTarget: () => "Claude Code user config (via `claude mcp` CLI)"
+  };
+}
+function appDataDir() {
+  return absoluteEnvDir(
+    process.env.APPDATA,
+    () => path.join(home, "AppData", "Roaming")
+  );
+}
 function claudeDesktopConfigPath() {
   if (process.platform === "win32") {
-    return path.join(appData, "Claude", "claude_desktop_config.json");
+    return path.join(appDataDir(), "Claude", "claude_desktop_config.json");
+  }
+  if (process.platform === "darwin") {
+    return path.join(
+      home,
+      "Library",
+      "Application Support",
+      "Claude",
+      "claude_desktop_config.json"
+    );
   }
   return path.join(
-    home,
-    "Library",
-    "Application Support",
+    absoluteEnvDir(
+      process.env.XDG_CONFIG_HOME,
+      () => path.join(home, ".config")
+    ),
     "Claude",
     "claude_desktop_config.json"
   );
 }
 function vsCodeConfigPath() {
   if (process.platform === "win32") {
-    return path.join(appData, "Code", "User", "mcp.json");
+    return path.join(appDataDir(), "Code", "User", "mcp.json");
   }
   if (process.platform === "darwin") {
     return path.join(
@@ -159,9 +670,17 @@ function vsCodeConfigPath() {
       "mcp.json"
     );
   }
-  return path.join(home, ".config", "Code", "User", "mcp.json");
+  return path.join(
+    absoluteEnvDir(
+      process.env.XDG_CONFIG_HOME,
+      () => path.join(home, ".config")
+    ),
+    "Code",
+    "User",
+    "mcp.json"
+  );
 }
-var fs, os, path, import_child_process, jsonc, SERVER_NAME2, NPM_PACKAGE, HOSTED_URL, claudeCodeClient, home, appData, CLIENTS;
+var fs, os, path, import_child_process, jsonc, SERVER_NAME2, NPM_PACKAGE, HOSTED_URL, PROJECT_BOUNDARY_MARKERS, CMD_META, KEY_PLACEHOLDER, claudeCodeClient, home, CLIENTS;
 var init_clients = __esm({
   "src/install/clients.ts"() {
     "use strict";
@@ -173,73 +692,37 @@ var init_clients = __esm({
     SERVER_NAME2 = "runpod";
     NPM_PACKAGE = "@runpod/mcp-server@latest";
     HOSTED_URL = process.env.RUNPOD_MCP_URL ?? "https://mcp.getrunpod.io/";
-    claudeCodeClient = {
-      id: "claude-code",
-      name: "Claude Code",
-      detect: () => Promise.resolve(findClaudeBinary() !== null),
-      add: (mode) => {
-        const binary = findClaudeBinary();
-        if (!binary) {
-          return Promise.resolve({
-            success: false,
-            message: "claude CLI not found"
-          });
-        }
-        const args = mode.kind === "local" ? [
-          "mcp",
-          "add",
-          SERVER_NAME2,
-          "--scope",
-          "user",
-          "-e",
-          `RUNPOD_API_KEY=${mode.apiKey}`,
-          "--",
-          "npx",
-          "-y",
-          NPM_PACKAGE
-        ] : [
-          "mcp",
-          "add",
-          "--transport",
-          "http",
-          "--scope",
-          "user",
-          SERVER_NAME2,
-          mode.url
-        ];
-        return Promise.resolve(runClaude(binary, args));
-      },
-      remove: () => {
-        const binary = findClaudeBinary();
-        if (!binary) {
-          return Promise.resolve({
-            success: false,
-            message: "claude CLI not found"
-          });
-        }
-        try {
-          (0, import_child_process.execFileSync)(binary, ["mcp", "remove", "--scope", "user", SERVER_NAME2], {
-            stdio: "pipe"
-          });
-          return Promise.resolve({ success: true });
-        } catch (error) {
-          return Promise.resolve({ success: true, message: errMessage(error) });
-        }
-      },
-      describeTarget: () => "Claude Code user config (via `claude mcp` CLI)"
-    };
+    PROJECT_BOUNDARY_MARKERS = [
+      ".git",
+      "package.json",
+      "pnpm-workspace.yaml",
+      "pnpm-lock.yaml",
+      "package-lock.json",
+      "yarn.lock",
+      "bun.lock",
+      "bun.lockb"
+    ];
+    CMD_META = /[()\][%!^"`<>&|;, *?\t\n\v\r]/;
+    KEY_PLACEHOLDER = "YOUR_RUNPOD_API_KEY";
+    claudeCodeClient = createClaudeCodeClient(findClaudeBinary);
     home = os.homedir();
-    appData = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
     CLIENTS = [
       claudeCodeClient,
       jsonClient({
         id: "cursor",
         name: "Cursor",
+        // A VS Code fork, and its MCP reader keeps VS Code's tolerance — comments and
+        // trailing commas both parse. Read out of the shipped bundle, not assumed from
+        // "Electron app"; see ConfigDialect.
+        dialect: "jsonc",
         configPath: () => path.join(home, ".cursor", "mcp.json")
       }),
       jsonClient({
         id: "windsurf",
         name: "Windsurf",
+        // Not installed on any machine this was checked on, so its parser was never read.
+        // Lenient-and-disclosed rather than a guess in either direction.
+        dialect: "unverified",
         // Windsurf is stdio-only, so it reaches the hosted server via mcp-remote.
         hostedStrategy: "mcp-remote",
         configPath: () => path.join(home, ".codeium", "windsurf", "mcp_config.json")
@@ -247,6 +730,9 @@ var init_clients = __esm({
       jsonClient({
         id: "claude-desktop",
         name: "Claude Desktop",
+        // Genuinely strict: its reader is a bare `JSON.parse(readFileSync(...))` with no
+        // preprocessing and no retry, so a comment or trailing comma is fatal.
+        dialect: "json",
         // Claude Desktop config files are stdio-only; use the mcp-remote bridge.
         hostedStrategy: "mcp-remote",
         configPath: claudeDesktopConfigPath,
@@ -257,6 +743,9 @@ var init_clients = __esm({
         id: "vscode",
         name: "Visual Studio Code",
         serverProperty: "servers",
+        // The one client that genuinely reads JSONC — comments and trailing commas in
+        // mcp.json are supported and common.
+        dialect: "jsonc",
         configPath: vsCodeConfigPath,
         detectPaths: () => [path.dirname(vsCodeConfigPath())]
       })
@@ -264,6 +753,33 @@ var init_clients = __esm({
   }
 });
 
+// src/install/verify-key.ts
+async function verifyApiKey(apiKey, timeoutMs = VERIFY_API_KEY_TIMEOUT_MS) {
+  try {
+    const base = process.env.RUNPOD_REST_API_URL ?? "https://rest.runpod.io/v1";
+    const response = await fetch(`${base}/pods`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      // Without this the wizard sits at "Verifying…" forever against a host
+      // that accepts the connection and goes quiet, with no way out but ^C.
+      // An abort lands in the catch below and is reported as "check failed",
+      // which is exactly what it is.
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (response.ok) return true;
+    if (response.status === 401 || response.status === 403) return false;
+    return null;
+  } catch {
+    return null;
+  }
+}
+var VERIFY_API_KEY_TIMEOUT_MS;
+var init_verify_key = __esm({
+  "src/install/verify-key.ts"() {
+    "use strict";
+    VERIFY_API_KEY_TIMEOUT_MS = 1e4;
+  }
+});
+
 // src/install/wizard.ts
 var wizard_exports = {};
 __export(wizard_exports, {
@@ -281,25 +797,12 @@ function openBrowser(url) {
   } catch {
   }
 }
-async function verifyApiKey(apiKey) {
-  try {
-    const base = process.env.RUNPOD_REST_API_URL ?? "https://rest.runpod.io/v1";
-    const response = await fetch(`${base}/pods`, {
-      headers: { Authorization: `Bearer ${apiKey}` }
-    });
-    if (response.ok) return true;
-    if (response.status === 401 || response.status === 403) return false;
-    return null;
-  } catch {
-    return null;
-  }
-}
 function bail(message = "Cancelled.") {
   p.cancel(message);
   process.exit(0);
 }
 async function promptForApiKey() {
-  const fromEnv = process.env.RUNPOD_API_KEY;
+  const fromEnv = process.env.RUNPOD_API_KEY?.trim();
   if (fromEnv) {
     const useEnv = await p.confirm({
       message: "Use the RUNPOD_API_KEY from your environment?"
@@ -394,7 +897,9 @@ async function runAdd() {
     const result = await client.add(mode);
     if (result.success) {
       spinner2.stop(`${client.name} configured.`);
-      results.push(`\u2713 ${client.name} \u2014 ${client.describeTarget()}`);
+      results.push(
+        `\u2713 ${client.name} \u2014 ${result.message ? `${result.message}; ` : ""}${client.describeTarget()}`
+      );
     } else {
       spinner2.stop(`${client.name} failed.`);
       results.push(`\u2717 ${client.name} \u2014 ${result.message ?? "unknown error"}`);
@@ -438,6 +943,7 @@ var init_wizard = __esm({
     import_child_process2 = require("child_process");
     p = __toESM(require("@clack/prompts"), 1);
     init_clients();
+    init_verify_key();
     API_KEYS_URL = "https://www.runpod.io/console/user/settings";
   }
 });
@@ -476,7 +982,7 @@ function containerConfigToV2(p2) {
 function gpuConfigToV2(gpuTypeIds, gpuCount) {
   const id = gpuTypeIds?.[0];
   if (id === void 0) return void 0;
-  return compact({ id, count: gpuCount });
+  return { id, count: gpuCount ?? 1 };
 }
 function mapPodCreateToV2(params) {
   return compact({
@@ -603,6 +1109,42 @@ function podBodyFromTemplate(template) {
   }
   return out;
 }
+var SSH_PUBLIC_KEY_LINE = /^(ssh-[a-z0-9-]+|ecdsa-[a-z0-9-]+|sk-[a-z0-9@.-]+)\s+\S+/i;
+var PRIVATE_KEY_MARKER = /private[-\s]?key|PuTTY-User-Key-File/i;
+function normalizeSshPublicKey(input) {
+  if (PRIVATE_KEY_MARKER.test(input))
+    return {
+      ok: false,
+      error: 'sshPublicKey looks like a PRIVATE key. Pass the PUBLIC key instead \u2014 the contents of your ~/.ssh/<key>.pub file (e.g. "ssh-ed25519 AAAA\u2026").'
+    };
+  const lines = input.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length === 0)
+    return {
+      ok: false,
+      error: "sshPublicKey is empty. Pass the contents of your ~/.ssh/<key>.pub file, or omit the parameter entirely to create the pod without SSH."
+    };
+  if (lines.some((line) => !SSH_PUBLIC_KEY_LINE.test(line)))
+    return {
+      ok: false,
+      error: 'sshPublicKey is not an SSH public key. Expected the CONTENTS of your ~/.ssh/<key>.pub file \u2014 a line like "ssh-ed25519 AAAAC3Nza\u2026 you@host" (ssh-*, ecdsa-*, or sk-* followed by the base64 key) \u2014 not a file path, a SHA256 fingerprint, or a bare base64 blob. Newline-separate multiple keys.'
+    };
+  return { ok: true, key: lines.join("\n") };
+}
+function applySshPublicKey(body, sshPublicKey) {
+  const ports = Array.isArray(body.ports) ? body.ports : [];
+  const hasSshPort = ports.some((p2) => /^\s*22\/tcp\s*$/i.test(String(p2)));
+  const env = { ...body.env ?? {} };
+  const key = sshPublicKey.trim();
+  if (!env.PUBLIC_KEY) env.PUBLIC_KEY = key;
+  else if (!env.PUBLIC_KEY.includes(key))
+    env.PUBLIC_KEY = `${env.PUBLIC_KEY}
+${key}`;
+  return {
+    ...body,
+    ports: hasSshPort ? ports : [...ports, "22/tcp"],
+    env
+  };
+}
 function mapTemplateUpdateToV2(params) {
   return {
     ...containerConfigToV2(params),
@@ -646,7 +1188,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,32 +1410,203 @@ 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.3.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;
   }
 };
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var MIN_REQUEST_TIMEOUT_MS = 1e3;
+var RequestTimeoutError = class extends Error {
+  constructor(prefix, timeoutMs, method) {
+    const write = method !== "GET" && method !== "HEAD";
+    super(
+      `${prefix}: no response after ${timeoutMs}ms for ${method} (the API may be overloaded, or still be working on it). ${write ? "This request may have SUCCEEDED upstream \u2014 do not retry blindly. Check with the matching list-/get- tool first and retry only if it did not take effect." : "This was a read and changed nothing, so retrying is safe."}`
+    );
+    this.name = "RequestTimeoutError";
+    this.timeoutMs = timeoutMs;
+    this.method = method;
+  }
+};
+async function withRequestTimeout(errorPrefix, timeoutMs, method, run) {
+  const signal = AbortSignal.timeout(timeoutMs);
+  try {
+    return await run(signal);
+  } catch (error) {
+    if (error instanceof HttpError || !signal.aborted) throw error;
+    throw new RequestTimeoutError(errorPrefix, timeoutMs, method);
+  }
+}
 function isJsonContentType(contentType) {
   if (!contentType) return false;
   const ct = contentType.toLowerCase();
@@ -909,24 +1622,49 @@ function buildRequestHeaders(apiKey, tracking) {
     ...tracking()
   };
 }
+function resolveCeiling(ceiling) {
+  if (ceiling === void 0) return Infinity;
+  if (typeof ceiling !== "function") return ceiling;
+  return Math.max(ceiling(), MIN_REQUEST_TIMEOUT_MS);
+}
+function clampTimeout(requestedMs, ceiling, defaultMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  return Math.min(requestedMs ?? defaultMs, resolveCeiling(ceiling));
+}
 function createHttpClient(deps) {
-  return async function request(url, method = "GET", body) {
-    const init = {
+  const defaultTimeoutMs = deps.defaultTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  return async function request(url, method = "GET", body, options) {
+    const timeoutMs = clampTimeout(
+      options?.timeoutMs,
+      deps.maxTimeoutMs,
+      defaultTimeoutMs
+    );
+    return withRequestTimeout(
+      deps.errorPrefix,
+      timeoutMs,
       method,
-      headers: buildRequestHeaders(deps.apiKey, deps.tracking)
-    };
-    if (body && methodSendsBody(method)) {
-      init.body = JSON.stringify(body);
-    }
-    const response = await deps.fetch(url, init);
-    if (!response.ok) {
-      throw new HttpError(
-        deps.errorPrefix,
-        response.status,
-        await response.text()
-      );
-    }
-    return isJsonContentType(response.headers.get("content-type")) ? response.json() : { success: true, status: response.status };
+      async (signal) => {
+        const init = {
+          method,
+          headers: buildRequestHeaders(deps.apiKey, deps.tracking),
+          signal
+        };
+        if (body && methodSendsBody(method)) {
+          init.body = JSON.stringify(body);
+        }
+        const response = await deps.fetch(url, init);
+        if (!response.ok) {
+          const hint = response.status === 429 ? rateLimitHint(
+            response.headers.get("ratelimit"),
+            response.headers.get("retry-after")
+          ) : response.status === 401 ? EXPIRED_CREDENTIAL_HINT : void 0;
+          const text = await response.text().catch(
+            () => "<body unavailable: the connection closed while reading it>"
+          );
+          throw new HttpError(deps.errorPrefix, response.status, text, hint);
+        }
+        return isJsonContentType(response.headers.get("content-type")) ? response.json() : { success: true, status: response.status };
+      }
+    );
   };
 }
 
@@ -982,7 +1720,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 +1791,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.3.0" : "dev";
 var SESSION_ID = (0, import_node_crypto.randomUUID)();
 function trackingHeaders(server, ctx) {
   const info = server.server.getClientVersion();
@@ -1060,6 +1806,11 @@ function trackingHeaders(server, ctx) {
     sessionId: SESSION_ID
   });
 }
+var HTTP_TRANSPORT_BUDGET_MS = 5e4;
+function invocationBudget(totalMs) {
+  const startedAt = Date.now();
+  return () => totalMs - (Date.now() - startedAt);
+}
 var defaultFetch = import_node_fetch.default;
 async function withApiErrorLog(label, call) {
   try {
@@ -1083,6 +1834,23 @@ var DESTRUCTIVE = {
   openWorldHint: true
 };
 async function graphqlRequest(query, tracking, fetchImpl, url, options) {
+  return withRequestTimeout(
+    "Runpod GraphQL Error",
+    clampTimeout(options?.timeoutMs, options?.maxTimeoutMs),
+    // GraphQL is POST on the wire whatever it carries, but the retry advice keys
+    // off the method, and telling a caller its list-gpu-types "may have
+    // SUCCEEDED upstream — check with the matching list-/get- tool first" points
+    // it back at the tool that just failed. The operation keyword is what
+    // actually says whether anything could have been written.
+    isGraphqlMutation(query) ? "POST" : "GET",
+    (signal) => runGraphql(query, tracking, fetchImpl, url, signal, options)
+  );
+}
+function isGraphqlMutation(query) {
+  const firstMeaningful = query.split("\n").map((line) => line.trim()).find((line) => line.length > 0 && !line.startsWith("#"));
+  return /^mutation\b/.test(firstMeaningful ?? "");
+}
+async function runGraphql(query, tracking, fetchImpl, url, signal, options) {
   const response = await fetchImpl(url, {
     method: "POST",
     headers: {
@@ -1093,8 +1861,39 @@ async function graphqlRequest(query, tracking, fetchImpl, url, options) {
     body: JSON.stringify({
       query,
       ...options?.variables ? { variables: options.variables } : {}
-    })
+    }),
+    signal
   });
+  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(
@@ -1119,39 +1918,53 @@ function createToolRuntime(server, ctx, deps = {}) {
   }
   const rawFetch = deps.fetch ?? defaultFetch;
   const httpFetch = observeUnauthorized(rawFetch);
+  const remainingHttpBudgetMs = invocationBudget(HTTP_TRANSPORT_BUDGET_MS);
+  const timeouts = {
+    defaultTimeoutMs: deps.defaultTimeoutMs,
+    maxTimeoutMs: deps.maxTimeoutMs ?? (ctx.transport === "http" ? remainingHttpBudgetMs : void 0)
+  };
   const v1Client = createHttpClient({
     apiKey: ctx.apiKey,
     fetch: httpFetch,
     tracking,
-    errorPrefix: "Runpod API Error"
+    errorPrefix: "Runpod API Error",
+    ...timeouts
   });
-  const runpodRequest = (endpoint, method = "GET", body) => withApiErrorLog(
+  const runpodRequest = (endpoint, method = "GET", body, options) => withApiErrorLog(
     "Error calling Runpod API:",
-    () => v1Client(`${restV1Base(process.env)}${endpoint}`, method, body)
+    () => v1Client(
+      `${restV1Base(process.env)}${endpoint}`,
+      method,
+      body,
+      options
+    )
   );
   const serverlessClient = createHttpClient({
     apiKey: ctx.apiKey,
     fetch: httpFetch,
     tracking,
-    errorPrefix: "Runpod Serverless API Error"
+    errorPrefix: "Runpod Serverless API Error",
+    ...timeouts
   });
-  const serverlessRequest = (endpointId, path2, method = "GET", body) => withApiErrorLog(
+  const serverlessRequest = (endpointId, path2, method = "GET", body, options) => withApiErrorLog(
     "Error calling Runpod Serverless API:",
     () => serverlessClient(
       `${serverlessBase(process.env)}/${endpointId}${path2}`,
       method,
-      body
+      body,
+      options
     )
   );
   const restClient = createHttpClient({
     apiKey: ctx.apiKey,
     fetch: httpFetch,
     tracking,
-    errorPrefix: "Runpod API Error"
+    errorPrefix: "Runpod API Error",
+    ...timeouts
   });
-  const callRestUrl = (url, method = "GET", body) => withApiErrorLog(
+  const callRestUrl = (url, method = "GET", body, options) => withApiErrorLog(
     "Error calling Runpod API:",
-    () => restClient(url, method, body)
+    () => restClient(url, method, body, options)
   );
   const sseFetch = observeUnauthorized(
     deps.sseFetch ?? import_node_fetch.default
@@ -1184,12 +1997,18 @@ function createToolRuntime(server, ctx, deps = {}) {
   };
   return {
     jsonReply,
+    // No GraphQL caller overrides a deadline, but both are still capped by the
+    // shared budget: deploy-hub-repo spends one of each back to back.
     graphql: (query) => graphqlRequest(
       query,
       tracking,
       // rawFetch, not httpFetch: this call carries no credential (see above).
       rawFetch,
-      publicGraphqlBase(process.env)
+      publicGraphqlBase(process.env),
+      {
+        timeoutMs: deps.defaultTimeoutMs,
+        maxTimeoutMs: timeouts.maxTimeoutMs
+      }
     ),
     graphqlAuthed: (query, variables) => graphqlRequest(
       query,
@@ -1197,7 +2016,12 @@ function createToolRuntime(server, ctx, deps = {}) {
       httpFetch,
       // NOT publicGraphqlBase: this call carries the caller's API key.
       authedGraphqlBase(process.env),
-      { variables, apiKey: ctx.apiKey }
+      {
+        variables,
+        apiKey: ctx.apiKey,
+        timeoutMs: deps.defaultTimeoutMs,
+        maxTimeoutMs: timeouts.maxTimeoutMs
+      }
     ),
     runpodRequest,
     serverlessRequest,
@@ -1205,7 +2029,8 @@ function createToolRuntime(server, ctx, deps = {}) {
     backendFor,
     streamSse,
     podAction,
-    env: process.env
+    env: process.env,
+    transport: ctx.transport
   };
 }
 
@@ -1274,6 +2099,7 @@ function capListResult(result, options, extra) {
 }
 
 // src/tools/catalog.ts
+var GPU_PRODUCTS = /* @__PURE__ */ new Set(["POD", "CLUSTER", "SERVERLESS"]);
 function registerCatalogTools(server, rt) {
   const { jsonReply: jsonReply2, graphql, callRestUrl, backendFor } = rt;
   server.tool(
@@ -1292,6 +2118,9 @@ function registerCatalogTools(server, rt) {
       ),
       includeAvailability: import_zod3.z.boolean().optional().describe(
         "Request realtime stock and annotate each GPU with an availability summary (HIGH/MEDIUM/LOW/NONE). Default true. Set false to skip the availability lookup \u2014 then out-of-stock GPUs cannot be filtered."
+      ),
+      product: import_zod3.z.enum(["POD", "CLUSTER", "SERVERLESS"]).optional().describe(
+        "Product context for the availability lookup \u2014 the same GPU can be scarce for Pods and plentiful for Serverless. Default POD. Use SERVERLESS when picking a GPU for an endpoint, CLUSTER for Instant Clusters. Ignored when includeAvailability is false."
       )
     },
     { title: "List GPU types", ...READ_ONLY },
@@ -1299,8 +2128,9 @@ function registerCatalogTools(server, rt) {
       const backend = backendFor("gpus");
       if (backend.version === "v2") {
         const wantAvailability = params.includeAvailability !== false;
+        const product = GPU_PRODUCTS.has(String(params.product)) ? String(params.product) : "POD";
         const raw = await callRestUrl(
-          `${backend.base}${backend.list}${wantAvailability ? "?include=AVAILABILITY" : ""}`
+          `${backend.base}${backend.list}${wantAvailability ? `?include=AVAILABILITY&product=${product}` : ""}`
         );
         let gpus = backend.unwrap(raw);
         gpus = gpus.filter((g) => g.id !== "unknown");
@@ -1473,6 +2303,9 @@ function registerCatalogTools(server, rt) {
       gpuTypeId: import_zod3.z.string().describe("ID of the GPU type to retrieve"),
       includeAvailability: import_zod3.z.boolean().optional().describe(
         "Include realtime per-datacenter availability (HIGH/MEDIUM/LOW/NONE). Default true."
+      ),
+      product: import_zod3.z.enum(["POD", "CLUSTER", "SERVERLESS"]).optional().describe(
+        "Product context for the availability lookup \u2014 stock differs by product. Default POD. Use SERVERLESS when picking a GPU for an endpoint, CLUSTER for Instant Clusters. Ignored when includeAvailability is false."
       )
     },
     { title: "Get GPU type", ...READ_ONLY },
@@ -1485,7 +2318,8 @@ function registerCatalogTools(server, rt) {
         });
       }
       const path2 = backend.get(encodeURIComponent(params.gpuTypeId));
-      const query = params.includeAvailability === false ? "" : "?include=AVAILABILITY";
+      const product = GPU_PRODUCTS.has(String(params.product)) ? String(params.product) : "POD";
+      const query = params.includeAvailability === false ? "" : `?include=AVAILABILITY&product=${product}`;
       const result = await callRestUrl(`${backend.base}${path2}${query}`);
       return jsonReply2(result);
     }
@@ -1511,6 +2345,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).",
@@ -2193,9 +3199,11 @@ function registerPodTools(server, rt) {
   );
   server.tool(
     "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.',
+    '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). For full SSH access (including SCP/SFTP/rsync), pass sshPublicKey \u2014 it sets the PUBLIC_KEY env var and exposes 22/tcp, which official Runpod images turn into a running sshd with the key authorized. 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."
@@ -2205,12 +3213,18 @@ function registerPodTools(server, rt) {
       ),
       cloudType: import_zod7.z.enum(["SECURE", "COMMUNITY"]).optional().describe("SECURE or COMMUNITY cloud"),
       gpuTypeIds: import_zod7.z.array(import_zod7.z.string()).optional().describe("List of acceptable GPU types"),
-      gpuCount: import_zod7.z.number().optional().describe("Number of GPUs"),
+      // v2 GpuConfig.count is `integer, minimum: 1`. Without these bounds a 0,
+      // a negative, or a fractional count reached the wire as-is and came back
+      // as a raw 422; reject it here with a message that names the field.
+      gpuCount: import_zod7.z.number().int().min(1).optional().describe("Number of GPUs (minimum 1)"),
       containerDiskInGb: import_zod7.z.number().optional().describe("Container disk size in GB"),
       volumeInGb: import_zod7.z.number().optional().describe("Volume size in GB"),
       volumeMountPath: import_zod7.z.string().optional().describe("Path to mount the volume"),
       ports: import_zod7.z.array(import_zod7.z.string()).optional().describe("Ports to expose (e.g., '8888/http', '22/tcp')"),
       env: import_zod7.z.record(import_zod7.z.string()).optional().describe("Environment variables"),
+      sshPublicKey: import_zod7.z.string().optional().describe(
+        'SSH PUBLIC key(s) to authorize on the pod \u2014 the CONTENTS of your ~/.ssh/<key>.pub file, i.e. a literal "ssh-ed25519 AAAAC3Nza\u2026 you@host" line, NOT a path to the file, a fingerprint, or the private key; newline-separate multiple keys. Merges the key into the PUBLIC_KEY env var and ensures 22/tcp is exposed, enabling full SSH (SCP/SFTP/rsync) on any image that honors the PUBLIC_KEY convention \u2014 all runpod/* official images do. Extends template ports/env rather than replacing them.'
+      ),
       containerRegistryAuthId: import_zod7.z.string().optional().describe(
         "Container registry credential ID for pulling a private image (see list-container-registry-auths). When deploying from a templateId, this overrides the credential the template carries; pass an empty string to deploy with NO credential (clears a template\u2019s inherited registry)."
       ),
@@ -2219,6 +3233,15 @@ function registerPodTools(server, rt) {
     { title: "Create pod", ...WRITE },
     async (params) => {
       const backend = backendFor("pods");
+      const { sshPublicKey, ...podParams } = params;
+      let sshKey;
+      if (sshPublicKey !== void 0) {
+        const validated = normalizeSshPublicKey(sshPublicKey);
+        if (!validated.ok)
+          return jsonReply2({ error: validated.error, status: 400 });
+        sshKey = validated.key;
+      }
+      const sshNote = "sshPublicKey applied: PUBLIC_KEY env set and 22/tcp exposed. Full SSH (incl. SCP/SFTP/rsync) also requires an image that installs PUBLIC_KEY into authorized_keys and starts sshd (all runpod/* official images do) and a machine with a public IP \u2014 read the pod\u2019s portMappings for port 22 once it is running.";
       if (params.templateId && backend.version !== "v2") {
         return jsonReply2({
           error: "Deploying a pod from a templateId is only supported on the v2 REST API. Set RUNPOD_REST_VERSION=v2, or pass imageName instead.",
@@ -2254,6 +3277,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({
@@ -2262,13 +3291,15 @@ function registerPodTools(server, rt) {
             });
           }
           try {
+            const cpuBody = sshKey ? applySshPublicKey(podParams, sshKey) : podParams;
             const result = await callRestUrl(
               `${restV1Base(env)}/pods`,
               "POST",
-              params
+              cpuBody
             );
             return jsonReply2({
               ...result,
+              ...sshKey ? { _ssh: sshNote } : {},
               _servedBy: "v1",
               _note: "CPU pod: created on the v1 API, because the v2 REST API does not support CPU pods yet."
             });
@@ -2285,7 +3316,7 @@ function registerPodTools(server, rt) {
           }
         }
       }
-      let body = backend.mapCreate(params);
+      let body = backend.mapCreate(podParams);
       if (params.templateId) {
         let template;
         try {
@@ -2303,19 +3334,21 @@ function registerPodTools(server, rt) {
         }
         body = { ...podBodyFromTemplate(template), ...body };
       }
+      if (sshKey) body = applySshPublicKey(body, sshKey);
       try {
         const result = await callRestUrl(
           `${backend.base}${backend.list}`,
           "POST",
           body
         );
+        const extras = {};
+        if (sshKey) extras._ssh = sshNote;
         if (backend.version === "v2" && (params.gpuTypeIds?.length ?? 0) > 1) {
-          return jsonReply2({
-            ...result,
-            _warning: `v2 accepts one GPU type per pod; used "${params.gpuTypeIds[0]}" and ignored ${params.gpuTypeIds.length - 1} other(s): ${params.gpuTypeIds.slice(1).join(", ")}.`
-          });
+          extras._warning = `v2 accepts one GPU type per pod; used "${params.gpuTypeIds[0]}" and ignored ${params.gpuTypeIds.length - 1} other(s): ${params.gpuTypeIds.slice(1).join(", ")}.`;
         }
-        return jsonReply2(result);
+        return jsonReply2(
+          Object.keys(extras).length ? { ...result, ...extras } : result
+        );
       } catch (error) {
         if (error instanceof HttpError) {
           return jsonReply2({ error: error.message, status: error.status });
@@ -2776,8 +3809,108 @@ var import_zod9 = require("zod");
 var DIAGNOSIS_TTL_MS = 15e3;
 var MAX_DIAGNOSIS_ENTRIES = 500;
 var diagnosisCache = /* @__PURE__ */ new Map();
+var HTTP_LONG_POLL_BUDGET_MS = 45e3;
+var STDIO_STREAM_BUDGET_MS = 5 * 60 * 1e3;
+var RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS = 9e4;
+var STREAM_UPSTREAM_DEFAULT_WAIT_MS = 1e4;
+var HTTP_STREAM_POLL_WAIT_MS = 1e3;
+var STREAM_JOB_POLL_INTERVAL_MS = 1e3;
+var MAX_CONSECUTIVE_STREAM_ERRORS = 5;
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "COMPLETED",
+  "FAILED",
+  "CANCELLED",
+  "TIMED_OUT"
+]);
+function isUnfinishedJobReply(result) {
+  return result !== null && typeof result === "object" && !Array.isArray(result) && !("waitClamped" in result) && !TERMINAL_STATUSES.has(result.status ?? "");
+}
+function formatBudget(ms) {
+  return ms >= 12e4 ? `${Math.round(ms / 6e4)} minutes` : `${Math.round(ms / 1e3)} seconds`;
+}
+var UPSTREAM_HOLD_SLACK_MS = 5e3;
+var MIN_STREAM_POLL_TIMEOUT_MS = 2e3;
+var QUEUED_DIAGNOSIS_TIMEOUT_MS = 5e3;
+function streamPollTimeoutMs(remainingMs, holdMs) {
+  return Math.max(
+    Math.min(remainingMs, holdMs + UPSTREAM_HOLD_SLACK_MS),
+    MIN_STREAM_POLL_TIMEOUT_MS
+  );
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function streamPollPlan(hosted) {
+  return hosted ? {
+    budgetMs: HTTP_LONG_POLL_BUDGET_MS,
+    holdMs: HTTP_STREAM_POLL_WAIT_MS,
+    query: `?wait=${HTTP_STREAM_POLL_WAIT_MS}`
+  } : {
+    budgetMs: STDIO_STREAM_BUDGET_MS,
+    holdMs: STREAM_UPSTREAM_DEFAULT_WAIT_MS,
+    query: ""
+  };
+}
+var RESUME_ADVICE = "Call stream-job again to continue collecting output, get-job-status to check the job without streaming, or stream without a budget by calling the runtime API directly (GET https://api.runpod.ai/v2/{endpointId}/stream/{jobId} with a Bearer API key).";
+function budgetExhaustedNote(budgetMs, lastError) {
+  return {
+    pollingTimedOut: true,
+    note: `Polling stopped after ${formatBudget(
+      budgetMs
+    )} with the job possibly still running. ${RESUME_ADVICE}`,
+    // Surface the trailing error (if any) instead of discarding it — the last
+    // polls may have been failing (e.g. job expired) even though earlier ones
+    // succeeded. Cleared on success, so this is never a stale error from
+    // minutes of healthy streaming ago.
+    ...lastError ? { lastError } : {}
+  };
+}
+function errorCapNote(lastError) {
+  return {
+    error: `Polling aborted after ${MAX_CONSECUTIVE_STREAM_ERRORS} consecutive errors: ${lastError}`,
+    note: `Polling stopped after ${MAX_CONSECUTIVE_STREAM_ERRORS} consecutive errors with the job possibly still running. ${RESUME_ADVICE}`
+  };
+}
+async function collectJobStream(deps) {
+  const { poll, budgetMs, holdMs } = deps;
+  const startedAt = Date.now();
+  const elapsed = () => Date.now() - startedAt;
+  const chunks = [];
+  let result = {};
+  let consecutiveErrors = 0;
+  let lastError;
+  while (true) {
+    try {
+      const reply = await poll(
+        streamPollTimeoutMs(budgetMs - elapsed(), holdMs)
+      );
+      consecutiveErrors = 0;
+      lastError = void 0;
+      if (Array.isArray(reply.stream)) chunks.push(...reply.stream);
+      result = reply;
+      if (TERMINAL_STATUSES.has(reply.status)) break;
+    } catch (error) {
+      consecutiveErrors++;
+      lastError = error instanceof Error ? error.message : String(error);
+      if (consecutiveErrors >= MAX_CONSECUTIVE_STREAM_ERRORS) {
+        result = { ...result, ...errorCapNote(lastError) };
+        break;
+      }
+    }
+    if (elapsed() > budgetMs) {
+      result = { ...result, ...budgetExhaustedNote(budgetMs, lastError) };
+      break;
+    }
+    await sleep(STREAM_JOB_POLL_INTERVAL_MS);
+  }
+  return { result, chunks };
+}
 function registerJobTools(server, rt) {
   const { jsonReply: jsonReply2, serverlessRequest, backendFor, callRestUrl } = rt;
+  const hosted = rt.transport === "http";
+  const streamBudget = formatBudget(
+    hosted ? HTTP_LONG_POLL_BUDGET_MS : STDIO_STREAM_BUDGET_MS
+  );
   async function diagnoseQueuedJob(endpointId) {
     const cached = diagnosisCache.get(endpointId);
     if (cached && cached.expiresAt > Date.now()) {
@@ -2788,7 +3921,10 @@ function registerJobTools(server, rt) {
       const backend = backendFor("workers");
       if (backend.version !== "v2") return null;
       const raw = await callRestUrl(
-        `${backend.base}/serverless/${endpointId}/workers`
+        `${backend.base}/serverless/${endpointId}/workers`,
+        "GET",
+        void 0,
+        { timeoutMs: QUEUED_DIAGNOSIS_TIMEOUT_MS }
       );
       const summary = raw?.summary;
       const workers = raw?.workers ?? [];
@@ -2879,14 +4015,14 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "runsync-endpoint",
-    "Submit a synchronous job to a Serverless endpoint and wait for the result. Best for tasks completing within 90 seconds. If processing exceeds 90 seconds, the response returns a job ID to poll with get-job-status. Max payload: 20 MB. Results expire after 1 minute. Use the wait parameter to extend the server-side wait up to 5 minutes (300000 ms).",
+    `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. ${hosted ? `This server waits up to ${HTTP_LONG_POLL_BUDGET_MS} ms \u2014 it runs behind a 60-second gateway deadline, so that is both the default and the ceiling for the wait parameter. For longer jobs use run-endpoint + get-job-status, or POST https://api.runpod.ai/v2/{endpointId}/runsync?wait=300000 directly with a Bearer API key.` : "The wait parameter extends the server-side wait to up to 5 minutes (300000 ms); it defaults to 90000 (90 seconds)."}`,
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint to run synchronously"
       ),
       input: inputSchema,
       wait: import_zod9.z.number().min(1e3).max(3e5).optional().describe(
-        "How long in milliseconds the server should wait for a result before returning a job ID to poll (1000\u2013300000). Defaults to 90000 (90 seconds)."
+        hosted ? `How long in milliseconds the server should wait for a result before returning a job ID to poll. Accepted range 1000\u2013300000, but this server clamps anything above ${HTTP_LONG_POLL_BUDGET_MS} down to ${HTTP_LONG_POLL_BUDGET_MS}, which is also the effective default.` : "How long in milliseconds the server should wait for a result before returning a job ID to poll (1000\u2013300000). Defaults to 90000 (90 seconds)."
       ),
       webhook: webhookSchema,
       policy: policySchema,
@@ -2895,13 +4031,36 @@ function registerJobTools(server, rt) {
     { title: "Run endpoint (sync)", ...WRITE },
     async (params) => {
       const { endpointId, wait, ...body } = params;
-      const path2 = wait ? `/runsync?wait=${wait}` : "/runsync";
+      const effectiveWait = hosted ? Math.min(
+        wait ?? RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS,
+        HTTP_LONG_POLL_BUDGET_MS
+      ) : wait;
+      const waitQuery = effectiveWait === void 0 ? "" : `?wait=${effectiveWait}`;
+      const path2 = `/runsync${waitQuery}`;
       const result = await serverlessRequest(
         endpointId,
         path2,
         "POST",
-        body
+        body,
+        {
+          // From the wait actually sent — on http the clamped 45s, not the
+          // 300s the caller may have asked for.
+          timeoutMs: (effectiveWait ?? RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS) + UPSTREAM_HOLD_SLACK_MS
+        }
       );
+      const requestedWait = wait ?? RUNSYNC_UPSTREAM_DEFAULT_WAIT_MS;
+      if (hosted && requestedWait > HTTP_LONG_POLL_BUDGET_MS && isUnfinishedJobReply(result)) {
+        return jsonReply2({
+          ...result,
+          waitClamped: {
+            requestedMs: requestedWait,
+            effectiveMs: effectiveWait,
+            reason: `This server runs behind a 60-second gateway deadline, so a non-terminal status here means the job outlived ${formatBudget(
+              HTTP_LONG_POLL_BUDGET_MS
+            )}, not the requested wait \u2014 poll get-job-status rather than treating it as stuck.`
+          }
+        });
+      }
       return jsonReply2(result);
     }
   );
@@ -2935,7 +4094,7 @@ function registerJobTools(server, rt) {
   );
   server.tool(
     "stream-job",
-    "Retrieve all streaming output from a Serverless job by polling until the job reaches a terminal state. The worker must support streaming output. Polls /stream/{jobId} repeatedly and collects every chunk until status is COMPLETED, FAILED, CANCELLED, or TIMED_OUT.",
+    `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 ${streamBudget}${hosted ? " (this server runs behind a 60-second gateway deadline)" : ""}. 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.${hosted ? " To collect with no budget, poll GET https://api.runpod.ai/v2/{endpointId}/stream/{jobId} yourself with a Bearer API key until the status is terminal \u2014 each request drains only the chunks buffered so far, so a single request is not the whole output." : ""}`,
     {
       endpointId: endpointIdSchema.describe(
         "ID of the Serverless endpoint the job belongs to"
@@ -2944,51 +4103,16 @@ function registerJobTools(server, rt) {
     },
     { title: "Stream job", ...READ_ONLY },
     async (params) => {
-      const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
-        "COMPLETED",
-        "FAILED",
-        "CANCELLED",
-        "TIMED_OUT"
-      ]);
-      const MAX_POLL_TIME_MS = 5 * 60 * 1e3;
-      const POLL_INTERVAL_MS = 1e3;
-      const MAX_CONSECUTIVE_ERRORS = 5;
-      const allChunks = [];
-      let finalResult = {};
-      let consecutiveErrors = 0;
-      let lastError;
-      const startTime = Date.now();
-      while (true) {
-        try {
-          const result = await serverlessRequest(
-            params.endpointId,
-            `/stream/${params.jobId}`
-          );
-          consecutiveErrors = 0;
-          if (Array.isArray(result.stream)) {
-            allChunks.push(...result.stream);
-          }
-          finalResult = result;
-          if (TERMINAL_STATUSES.has(result.status)) {
-            break;
-          }
-        } catch (error) {
-          consecutiveErrors++;
-          lastError = error instanceof Error ? error.message : String(error);
-          if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
-            finalResult.error = `Polling aborted after ${MAX_CONSECUTIVE_ERRORS} consecutive errors: ${lastError}`;
-            break;
-          }
-        }
-        if (Date.now() - startTime > MAX_POLL_TIME_MS) {
-          finalResult.pollingTimedOut = true;
-          finalResult.note = "Polling timed out after 5 minutes. Use get-job-status to check the job later.";
-          if (lastError) finalResult.lastError = lastError;
-          break;
-        }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-      }
-      return jsonReply2({ ...finalResult, stream: allChunks });
+      const plan = streamPollPlan(hosted);
+      const streamPath = `/stream/${params.jobId}${plan.query}`;
+      const { result, chunks } = await collectJobStream({
+        budgetMs: plan.budgetMs,
+        holdMs: plan.holdMs,
+        poll: (timeoutMs) => serverlessRequest(params.endpointId, streamPath, "GET", void 0, {
+          timeoutMs
+        })
+      });
+      return jsonReply2({ ...result, stream: chunks });
     }
   );
   server.tool(