@runpod/mcp-server 3.4.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @runpod/mcp-server
 
+## 4.1.0
+
+### Minor Changes
+
+- 1d049b6: Serve the official Runpod plugin's guides and concept graph: `list-guides`, `read-guide`, `lookup-concept` and `search-concepts`, plus each guide as a `runpod://guides/` resource, from the `@runpod/plugin-knowledge` package.
+- 09a565a: `list-templates` now returns 20 templates per page by default instead of the
+  full list. Follow `nextCursor` to see the rest.
+
+  Resync the vendored v2 OpenAPI spec with production. Adds five account-secret
+  tools (`list-secrets`, `get-secret`, `create-secret`, `update-secret`,
+  `delete-secret`) and refreshes the schemas for pods, endpoints, templates,
+  registries, and clusters — most visibly the `cursor`/`limit` query parameters
+  and `pagination` response block the API now serves on its list endpoints.
+
+  `list-endpoints` and `list-templates` now page on the server: `limit` and
+  `cursor` go to the API, and `pagination` returns its `nextCursor` and
+  `hasNextPage` plus `returned`. `list-endpoints` drops the old client-side
+  `total`, `offset`, and `truncated` fields, which only counted one server page.
+  Requires `@runpod/typescript-api-sdk` 0.2.0.
+
+### Patch Changes
+
+- 531ecb0: Serve MCP tool annotations. Every tool now advertises `readOnlyHint`,
+  `destructiveHint`, `idempotentHint`, and `openWorldHint` in `tools/list`:
+  generated tools derive them from the HTTP method they wrap, so they cannot
+  drift from the spec, with generator-config overrides for operations that delete
+  through a POST or PUT (`pod-action`, `update-ssh-keys`), and the curated
+  overlay declares them per tool. Hosts can
+  auto-approve reads and gate deletions, cancels, and queue purges on a human.
+
+## 4.0.0
+
+### Major Changes
+
+- 57b3973: Require Node.js 20 or newer and add the published Runpod TypeScript API SDK as the REST client foundation. Share deadline enforcement across REST, runtime, GraphQL, and log readers; preserve per-caller credentials and bounded polling. Update GPU selection with a sparse REST PATCH and isolate queued-job diagnostics by caller.
+
+  Pin the bundled TypeScript API SDK to 0.1.1. Reject null required arguments and invalid endpoint IDs before issuing requests.
+
+- 57b3973: Serve the same REST v2 generated tools and skill resources over HTTP and stdio. Remove the legacy v1 fallback, hand-written tool surface, and package tools export. See specgen/old-mcp-tools.yaml for renamed tools and pod-action replacements. Include argument checks, compact lists, bounded log snapshots, upstream retry guidance, caller tracking, and opt-in hosted analytics. The REST SDK is bundled into both entrypoints.
+
+  Remove the repository Dockerfile, Smithery manifest/install instructions, and bundled Cursor configuration. Use the hosted MCP URL or the published npm CLI, configured in your MCP client, instead. The install wizard verifies keys against REST v2 and honors RUNPOD_API_BASE_URL; retired REST host variables no longer disable credential preflight.
+
+### Minor Changes
+
+- 57b3973: Add hosted-only feedback, question, and private journal tools when a storage sink is configured. Contributions are optional and scrubbed for secrets. Scope journal reads to the authenticated account, bound reads, verify storage confirmation, and reject malformed storage requests. Local stdio does not advertise these tools.
+
+  Redact nested YAML/Compose secrets, Hugging Face tokens, and URL query credentials. Clarify that journals are not published to other accounts and Runpod stores submissions for review.
+
+### Patch Changes
+
+- 57b3973: Fix two secret-redaction leaks in ALP submission scrubbing, and replace the config-assignment regex with an explicit scan.
+
+  `password: p&ss#word123` and `password=abc&def` were truncated at the `&` and everything after it was stored in plaintext. A sensitive assignment nested inside a non-sensitive value was skipped entirely, so `https://host/?password=secret` passed through untouched. Values now keep `&` and `#` unless the key sits in a URL query string, where those characters really do bound the value, and the scan resumes inside a non-sensitive value instead of past it. Unbalanced and unterminated quotes no longer disable redaction. Scrub version is now 5.
+
 ## 3.4.0
 
 ### Minor Changes
@@ -92,7 +146,7 @@
 
 - 259241d: Enforce PKCE (S256) in every hosted OAuth flow. `/authorize` rejects missing, malformed, or non-S256 challenges before issuing a code and forwards a valid challenge to the flash backend. `/token` requires a valid, matching `code_verifier` before returning the minted key; missing PKCE state, `plain`, and non-matching verifiers are rejected.
 
-  Requires the backend `codeChallenge` / `codeChallengeMethod` fields on `createFlashAuthRequest` / `flashAuthRequestStatus` (runpod/RunPod, DR-1398) to be deployed.
+  Requires the backend `codeChallenge` / `codeChallengeMethod` fields on `createFlashAuthRequest` / `flashAuthRequestStatus` to be deployed.
 
 - f6208cd: Diagnose stuck queued jobs instead of leaving them ambiguous. A job that stays IN_QUEUE has two very different causes that its status alone cannot distinguish: no host has the endpoint's GPU available (capacity), or a worker spun up and is crash-looping — the platform marks it UNHEALTHY while the job stays queued indefinitely, and agents reliably misread that as a capacity shortage. `get-job-status` now best-effort attaches the endpoint's worker summary (`workerHealth`) and a plain-language `hint` whenever the job is IN_QUEUE (v2 only; the extra lookup never fails the status call, and the diagnosis is cached ~15s per endpoint so polling loops do not amplify into repeated worker-list fetches): UNHEALTHY workers → crash-loop guidance naming the worker ids to inspect with `stream-worker-logs`; zero workers → capacity guidance; throttled/initializing → wait guidance. The `get-job-status`, `endpoint-health`, `list-endpoint-workers`, and `stream-worker-logs` descriptions now cross-reference each other so agents are routed from a stuck job to the worker logs without prior knowledge of the platform's queueing behavior.
 - f36f191: Send the reshaped v2 Serverless write schema, and support load-balancing endpoints.

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2025 RunPod, Inc.
+Copyright 2025 Runpod, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/README.md

@@ -1,7 +1,5 @@
 # Runpod MCP server
 
-[![smithery badge](https://smithery.ai/badge/@runpod/runpod-mcp-ts)](https://smithery.ai/server/@runpod/runpod-mcp-ts)
-
 The official Runpod Model Context Protocol (MCP) server. It lets MCP clients such as Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code manage your Runpod Pods, Serverless endpoints, templates, network volumes, and more.
 
 **We host it for you at [`https://mcp.getrunpod.io/`](https://mcp.getrunpod.io/)** — point your client at that URL and sign in with Runpod. Nothing to install, no API key on disk. Or run it locally from npm as [`@runpod/mcp-server`](https://www.npmjs.com/package/@runpod/mcp-server).
@@ -44,7 +42,7 @@ In **Claude Code**, the native plugin route also wires up the hosted MCP server
 
 ### Requirements
 
-- Node.js 18 or higher.
+- Node.js 20 or higher.
 - A Runpod account and [API key](https://www.runpod.io/console/user/settings).
 
 ## Connect to the hosted server
@@ -71,8 +69,14 @@ claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/
 
 An OAuth-capable client starts the "Sign in with Runpod" flow automatically on first connect: it opens a browser, you log in to the Runpod console and approve, and the server obtains a Runpod API key scoped to your session. Nothing is stored on disk.
 
+> **Which account does OAuth pick?** The key is minted for whichever account or team profile your browser's console session has selected when you approve. If you belong to multiple teams, switch to the right profile in the [console](https://console.runpod.io) first (or check afterwards — the resources the tools return are that profile's). To change it later, switch profiles in the console and re-authenticate from your MCP client.
+
 > Prefer your own API key over OAuth? Append `--header "Authorization: Bearer YOUR_API_KEY"` to the `claude mcp add` command (or add a `headers` block in the JSON). The server forwards that key to the Runpod API directly.
 
+### Usage analytics
+
+The hosted server records one anonymous event per tool call (tool name, status, duration, transport — never your API key, arguments, or any resource data; your identity is an irreversible salted hash). To opt out, send the header `X-Runpod-Analytics: off` — e.g. append `--header "X-Runpod-Analytics: off"` to the `claude mcp add` command. Running locally, nothing is ever sent.
+
 ## Run locally with `npx`
 
 Run the server as a local `stdio` process with your own API key:
@@ -81,12 +85,6 @@ Run the server as a local `stdio` process with your own API key:
 RUNPOD_API_KEY=YOUR_API_KEY npx -y @runpod/mcp-server@latest
 ```
 
-Or install via [Smithery](https://smithery.ai/server/@runpod/runpod-mcp-ts):
-
-```bash
-npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude
-```
-
 ### Local client setup
 
 Local clients launch the `stdio` server and set `RUNPOD_API_KEY` in the environment.
@@ -138,16 +136,25 @@ Create a Serverless endpoint named my-endpoint with image
 runpod/test-output:0.0.1, GPU pool AMPERE_80, 0 min workers, 3 max workers.
 ```
 
-On the v2 API (the default), endpoints are image-based — pass an image and a GPU pool (a `pool` value from `list-gpu-types`), not a template.
+Endpoints are image-based — pass an image and a GPU pool (a `pool` value from `list-gpu-types`), not a template.
+
+See [`docs/configuration.md`](docs/configuration.md) for host overrides, private image pull (registry credentials vs ECR delegation), and large-output handling.
+
+## Upgrading from 3.x
 
-See [`docs/configuration.md`](docs/configuration.md) for REST v1/v2 selection and the `templateId` migration note, private image pull (registry credentials vs ECR delegation), and large-output handling.
+Eight tools follow their spec operationIds (e.g.
+`create-container-registry-auth` → `create-registry`, `get-billing` →
+`list-billing`) and `start-pod`/`stop-pod`/`restart-pod` fold into
+`pod-action` with an `action` argument. The full old→new map is
+[`specgen/old-mcp-tools.yaml`](specgen/old-mcp-tools.yaml). The server is
+v2-only; `RUNPOD_REST_VERSION` and the v1 fallback are retired.
 
 ## Security
 
 This server acts with the full permissions of the supplied API key.
 
 - Never share your API key.
-- Be deliberate with destructive tools.
+- Be deliberate with destructive tools. Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) derived from the operation it wraps, so a host can auto-approve reads and gate `delete-pod` or `purge-endpoint-queue` on a human.
 - Each request authenticates with its own caller-supplied token, which is forwarded to the Runpod API and **never persisted server-side**. The server never holds a credential of its own and never shares one across users.
 
 ## Local development
@@ -174,8 +181,19 @@ pnpm test    # offline unit suite — no network or API key required
 pnpm build
 ```
 
+Tools are generated from the vendored v2 OpenAPI spec rather than hand-written: see [specgen/DESIGN.md](specgen/DESIGN.md) for the walkthrough and [specgen/README.md](specgen/README.md) for the regeneration workflow and drift gates.
+
 This project uses [changesets](https://github.com/changesets/changesets) for versioning and npm publishing; every PR with user-facing changes needs a changeset. See `CLAUDE.md` and `docs/context.md` for full contributor guidance, architecture, and the test suite.
 
 ## License
 
 Apache-2.0
+
+### JavaScript API migration
+
+This major release removes the `@runpod/mcp-server/tools` package export and
+its `registerTools` API. The legacy registration API is not compatible with
+the new generated surface. Applications should connect to the server through
+MCP using the `runpod-mcp` CLI, or use `handleMcpRequest` from
+`@runpod/mcp-server/http` when embedding the HTTP handler. The HTTP entry point
+also no longer re-exports the legacy `registerTools` or `ToolContext`.

package/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,73 @@
+Bundled Runpod REST API v2 TypeScript SDK
+=======================================
+
+MIT License
+
+Copyright (c) 2026 RunPod, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+This package bundles openapi-fetch (https://github.com/openapi-ts/openapi-typescript).
+
+MIT License
+
+Copyright (c) 2023 Drew Powers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This package also bundles structured-headers (https://github.com/evert/structured-headers).
+
+MIT License
+
+Copyright (c) 2018-2026 Evert Pot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/chunk-DDX42UTT.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+// src/_shared/hosts.ts
+function pick(value, fallback) {
+  return value?.trim().replace(/\/+$/, "") || fallback;
+}
+function sdkBase(env) {
+  return pick(env.RUNPOD_API_BASE_URL, "https://api.runpod.io");
+}
+function serverlessBase(env) {
+  return pick(env.RUNPOD_SERVERLESS_API_URL, "https://api.runpod.ai/v2");
+}
+function publicGraphqlBase(env) {
+  return pick(env.RUNPOD_PUBLIC_GRAPHQL_URL, "https://api.runpod.io/graphql");
+}
+function authedGraphqlBase(env) {
+  return pick(env.RUNPOD_AUTHED_GRAPHQL_URL, "https://api.runpod.io/graphql");
+}
+
+export {
+  sdkBase,
+  serverlessBase,
+  publicGraphqlBase,
+  authedGraphqlBase
+};
+//# sourceMappingURL=chunk-DDX42UTT.mjs.map

package/dist/chunk-DDX42UTT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/_shared/hosts.ts"],"sourcesContent":["// Env-resolved API base URLs, extracted from the retired dual-version backend\n// resolver (backend.ts) when the spec-generated surface became the only one.\n// The credential preflight compares only active SDK and runtime destinations.\n\nexport type Env = Record<string, string | undefined>;\n\n// '' reads as unset everywhere: the wrong-environment guard already strips\n// empty vars before comparing, and every consumer (the credential checker's\n// probe URL, the GraphQL/log clients) must resolve identically or the\n// guard's \"checker and guard cannot disagree\" invariant breaks.\nfunction pick(value: string | undefined, fallback: string): string {\n  return value?.trim().replace(/\\/+$/, '') || fallback;\n}\n\n// Generated paths include /v2, so the SDK base is the API origin.\nexport function sdkBase(env: Env): string {\n  return pick(env.RUNPOD_API_BASE_URL, 'https://api.runpod.io');\n}\nexport function serverlessBase(env: Env): string {\n  return pick(env.RUNPOD_SERVERLESS_API_URL, 'https://api.runpod.ai/v2');\n}\nexport function publicGraphqlBase(env: Env): string {\n  return pick(env.RUNPOD_PUBLIC_GRAPHQL_URL, 'https://api.runpod.io/graphql');\n}\n// A separate var from publicGraphqlBase despite the identical default:\n// RUNPOD_PUBLIC_GRAPHQL_URL is the documented credential-free discovery\n// override and gets pointed at stubs freely, so routing authed calls through it\n// would turn \"point this anywhere\" into \"send the caller's API key there\".\nexport function authedGraphqlBase(env: Env): string {\n  return pick(env.RUNPOD_AUTHED_GRAPHQL_URL, 'https://api.runpod.io/graphql');\n}\n"],"mappings":";;;AAUA,SAAS,KAAK,OAA2B,UAA0B;AACjE,SAAO,OAAO,KAAK,EAAE,QAAQ,QAAQ,EAAE,KAAK;AAC9C;AAGO,SAAS,QAAQ,KAAkB;AACxC,SAAO,KAAK,IAAI,qBAAqB,uBAAuB;AAC9D;AACO,SAAS,eAAe,KAAkB;AAC/C,SAAO,KAAK,IAAI,2BAA2B,0BAA0B;AACvE;AACO,SAAS,kBAAkB,KAAkB;AAClD,SAAO,KAAK,IAAI,2BAA2B,+BAA+B;AAC5E;AAKO,SAAS,kBAAkB,KAAkB;AAClD,SAAO,KAAK,IAAI,2BAA2B,+BAA+B;AAC5E;","names":[]}