@runpod/mcp-server 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @runpod/mcp-server
 
+## 4.3.0
+
+### Minor Changes
+
+- 39d296f: Add `describe-tool`, which returns any tool's full definition, and list the tools with large request bodies (create/update endpoint, template and cluster, update-pod, create/update secret) with their call shape only: the top-level arguments with their types, nested objects collapsed. What each tool accepts is unchanged: the full schema still gates every call and is one `describe-tool` call away. Every client handshake carries about a quarter fewer bytes.
+- 40d9745: Resync the vendored v2 OpenAPI spec with production and update `@runpod/typescript-api-sdk` from 0.2.0 to 0.3.0 and `@runpod/plugin-knowledge` to 1.7.4. Adds the `list-global-volumes`, `get-global-volume`, `create-global-volume`, `update-global-volume`, `delete-global-volume` and `get-organization` tools, `global` mounts on `create-pod`, `mounts` on endpoints, and `pagination` on `list-clusters` and `list-network-volumes`. Those two list tools now return one page (default `limit` 1000); follow `pagination.nextCursor` until `hasNextPage` is false.
+
+  `tools/list` shrinks from 97 KB to 87 KB. `create-pod` is listed by its call shape, like `create-endpoint`; `describe-tool` serves its full schema. Tool annotations leave out `idempotentHint` when it is `false`, the MCP spec default. A description override on a composed schema is no longer repeated on each `allOf` member.
+
+- d2d12ef: The installer runs without prompts and supports opencode and Pi.
+  `npx @runpod/mcp-server@latest add --client <ids>` configures the named clients
+  with no prompts (`--hosted` by default, `--local` to read the key from
+  `RUNPOD_API_KEY`), `remove --client <ids>` undoes it, and `add --list` shows
+  which clients are detected and where each config lives. Run with no
+  `--client` and no terminal, the installer now exits 2 and says nothing was
+  configured, instead of exiting 0 having written nothing. Exit codes: 0
+  configured, 1 a client failed, 2 bad usage. `--help` and `--version` work at
+  the top level and on `add`/`remove`.
+
+  New clients: opencode (`~/.config/opencode/opencode.json`, or an existing
+  `opencode.jsonc`, under `mcp` with opencode's `remote`/`local` entry schema)
+  and Pi (`~/.pi/agent/mcp.json`, honouring `PI_CODING_AGENT_DIR`). Both config
+  formats were checked by running opencode 1.19.0 and Pi 1.2.0 against the files
+  the installer writes.
+
+### Patch Changes
+
+- 37dfc9b: Generated tool argument descriptions are compacted to what an agent needs: leading sentences up to a cap, constraints kept, REST paths replaced by tool names, response prose and status codes dropped. `tools/list` shrinks by roughly a fifth; a byte-budget test keeps it from regrowing.
+- a388ccb: Hosted usage analytics now record which guide or concept was requested: the `id`, `concept`, `query`, `kind` and `limit` arguments of `list-guides`, `read-guide`, `lookup-concept` and `search-concepts`. `read-guide` events also carry `guide_kind` (skill, reference or golden-path). Guide resource reads (`resources/read`) are recorded as a new `runpod_mcp_resource_call` event with the guide URI, or `unknown` when nothing matched. Other tools still send no arguments, stdio still sends nothing, and `X-Runpod-Analytics: off` still opts out.
+- a388ccb: The hosted server now breaks 404 loops: once a signed-in caller gets 50 404s from one tool within 10 minutes, that tool answers that caller with a retryable 429 for 1 hour. Counts live in the existing Convex sink, successful calls never touch it, and any sink failure lets calls through. Local (stdio) installs are unaffected. Each block emits one `runpod_mcp_loop_blocked` analytics event, and the 429s it serves carry `blocked_by: not_found_loop`.
+- 19cae9f: Hosted server: every request except `tools/call` now answers as `application/json` instead of an SSE stream, so the CDN compresses it (`tools/list` drops from ~65 KB to ~13 KB on the wire per handshake). `tools/call` keeps SSE because clients read it under their long stream timeout and some tools hold a response longer than the JSON request timeout.
+
+  The per-request `mcp_request` log line is sampled (`MCP_REQUEST_LOG_SAMPLE_RATE`, default `0.1`; `MCP_VERBOSE_LOGS=true` logs all) and now records the response status, duration, JSON-RPC method (with tool name), the client's `initialize` name/version, user agent, and hashed caller key and address, so traffic can be attributed by client.
+
+- c55d61a: Hosted server: the request body is validated once with the SDK's JSON-RPC schemas; `prefersJsonResponse` and `summarizeRpc` take the parsed messages, and the log line reports a client name/version only for a spec-valid `initialize`.
+- 6efc1b3: Accept the argument shapes strict-schema clients send. Clients such as Codex
+  and opencode must send every property, so an optional query filter they mean
+  to leave out arrives as `null`, `""` or `[]`. Those are now treated as omitted:
+  `cudaVersions: []` next to `minCudaVersion` on `get-gpu-type` and
+  `list-gpu-types`, `lastN: null` next to an explicit range on the billing tools,
+  and `cursor: ""` on a first page no longer fail upstream. Numbers and booleans
+  a client stringified inside a request body (`disk: "20"`, `workers.max: "1"`)
+  are converted back where the body schema asks for one; string fields stay
+  strings.
+
+  A 400 hint now names the upstream cause instead of always saying "Input shape
+  mismatch": no capacity for the requested hardware, no account balance, or two
+  conflicting arguments. Real validation failures (a 422, or field errors) keep
+  the shape hint.
+
+## 4.2.0
+
+### Minor Changes
+
+- 4865aed: Tighten what the server tells a connecting agent. The instructions now say
+  that for work done with these tools the journey playbook is the procedure,
+  whether it comes from the plugin's `runpod-mcp` skill or from
+  `read-guide`; the plugin's other skills stay the lane for the CLIs, image
+  builds and golden paths. A resource the user names by id is in scope for the
+  change they asked for and is deleted only when they ask for the delete, and
+  `create-cluster` waits for the user's go on the quoted shape and total hourly
+  price. Jobs are submitted with `run-endpoint` and waited on with
+  `get-job-status`; `runsync-endpoint` is for a warm endpoint and a fast job.
+
+  The 402 hint points at `list-billing`, and the 403 hint says a permission error
+  on a resource the agent did not create is final.
+
+  Tool descriptions: `create-cluster` prices the whole shape (pods times GPUs per
+  pod) and waits for the go; `create-endpoint` describes the CPU choice next to
+  the GPU one; `update-endpoint` puts `idleTimeout` under `workers` and states
+  that `gpu.pools` and `gpu.excludedTypes` are one selection; `delete-endpoint`,
+  `delete-pod`, `delete-cluster` and `delete-secret` allow the one resource the
+  user asked to delete by id.
+
+- 6ffb28e: The journey playbooks now come only from `@runpod/plugin-knowledge`, bumped to
+  1.7.1. The server no longer keeps its own copy under `runpod://skills/`: an
+  agent loads the plugin's `runpod-mcp` skill, or `read-guide runpod-mcp` without
+  the plugin, and that routes it to the journey guides (`discovery`,
+  `lifecycle-crud`, `serverless-deploy`, `pod-deploy`, `pod-doctor`,
+  `endpoint-ops`, `cost-audit`). `resources/list` serves the plugin guides as
+  `runpod://guides/<id>`. The instructions and the `ask_question` text point at
+  `read-guide` instead of `runpod://skills/`.
+
+  The instructions also tell an agent whose instructions look out of date to
+  reconnect the server (or ask the user to), since reconnecting re-runs
+  initialize and delivers the current instructions and tool list.
+
 ## 4.1.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # Runpod MCP server
 
-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.
+The official Runpod Model Context Protocol (MCP) server. It lets MCP clients such as Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, opencode, and Pi 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).
 
@@ -23,6 +23,17 @@ To undo later:
 npx @runpod/mcp-server@latest remove
 ```
 
+To skip the prompts (from a script, CI, or a coding agent's shell), name the clients. Supported ids are `claude-code`, `cursor`, `windsurf`, `claude-desktop`, `vscode`, `opencode`, and `pi`:
+
+```bash
+npx @runpod/mcp-server@latest add --client opencode,pi          # hosted, sign in with Runpod
+npx @runpod/mcp-server@latest add --client cursor --local       # local, key read from RUNPOD_API_KEY
+npx @runpod/mcp-server@latest remove --client opencode
+npx @runpod/mcp-server@latest add --list                        # what's detected, and where each config lives
+```
+
+Without `--client` and without a terminal, the installer exits with code 2 and configures nothing. With flags it exits 0 when every client was configured and 1 when one failed.
+
 ### Or install the whole Runpod plugin
 
 For the full agent setup, the [official plugin marketplace](https://github.com/runpod/runpod-plugins-official) bundles this server with a router skill plus five more — `runpod-mcp`, `runpodctl`, `flash`, `runpod-usage`, and `companion-clis`:
@@ -75,7 +86,7 @@ An OAuth-capable client starts the "Sign in with Runpod" flow automatically on f
 
 ### 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.
+The hosted server records one anonymous event per tool call (tool name, status, duration, transport) and per guide resource read (guide URI, or `unknown` on a miss), plus one event when it starts blocking a 404 loop (tool name and block length). It never records your API key or any resource data, and drops tool arguments except on the guide and concept tools (`list-guides`, `read-guide`, `lookup-concept`, `search-concepts`), where it keeps the guide id, concept name or search words, plus the kind of guide read. 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`