@runpod/mcp-server 4.3.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @runpod/mcp-server
 
+## 4.5.0
+
+### Minor Changes
+
+- 83bffb7: Hosted server: a new optional ALP tool, `report_how_user_found_runpod`, asks
+  the agent once per account how its user ended up on Runpod: the kind of
+  work (`useCase`) and why Runpod came up (`source`: `searched`,
+  `user_named`, `recommended`, `other`), or that it has no such context
+  (`noContext`). It collects categories and at most a short generic note,
+  never the user's own words. The ask rides in the `initialize` instructions; on each
+  `initialize` with a resolved account the server checks the storage sink and
+  omits the ask once the account has answered (a failed lookup keeps the ask),
+  and the sink keeps the first answer per account, with the server answering
+  `already_submitted` to any later one. Answers are stored with the
+  other ALP submissions under their own `referral` route, with the note capped at 200
+  characters, and scrubbed like every other submission. Absent on local stdio
+  and whenever the sink is not configured, like the other ALP tools.
+- ff02fdb: Every tool now carries a human-readable `title` in tools/list (for example `List GPU types` for `list-gpu-types`), so hosts can show readable names and the server meets directory review requirements. Generated tools derive the title from their name, with overrides in `specgen/generator-config.yaml`; curated tools declare their own.
+
+### Patch Changes
+
+- da524df: GraphQL errors that Runpod returns on an HTTP 200 now fail the tool call with a status taken from the error code (401, 403, 400 including Runpod's own `RUNPOD` input errors, otherwise 502) instead of 200, so agents get the matching recovery hint. A non-array `errors` field no longer crashes the call.
+- d075b00: Network failures reaching the Runpod API (DNS, connection refused, unreachable host, TLS errors, or a connection dropped mid-request) now come back as tool errors with the underlying `cause` code and a recovery hint, instead of escaping as an opaque JSON-RPC `-32603 fetch failed`. Failures where the request never reached Runpod say a retry is safe; a dropped connection says a write may have been applied and to check with a get- or list- tool before calling again.
+- 6a577ea: Update `@runpod/plugin-knowledge` from 1.7.4 to 1.8.0, so `list-guides` and `read-guide` serve the plugin's 1.8.0 skills and guides, including the new `runpod-build-template` skill.
+
+## 4.4.0
+
+### Minor Changes
+
+- a58f9f1: New `search-docs` tool: searches Runpod documentation, curated support knowledge, the Runpod blog and runpod.io through the runpod-assistant knowledge index, and returns ranked passages with source URLs. The hosted server searches with its own service key and retries the index's capacity rejections with jittered backoff. Local installs call the hosted `POST /api/search` with the user's API key.
+
+### Patch Changes
+
+- 4b53720: Hosted server: `tools/call` now answers as `application/json` too, so the CDN compresses tool results; only tools that hold their response open (`runsync-endpoint`, `get-job-status`, `stream-job`, `stream-pod-logs`, `stream-worker-logs`, `deploy-hub-repo`) keep SSE, declared with `CuratedTool.holdsResponse`.
+
 ## 4.3.0
 
 ### Minor Changes

package/README.md

@@ -84,6 +84,22 @@ An OAuth-capable client starts the "Sign in with Runpod" flow automatically on f
 
 > 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.
 
+### If sign-in fails with HTTP 403
+
+A `403 Forbidden` response with the header `X-Vercel-Mitigated: deny` means the hosted server's firewall has temporarily blocked your IP address, usually after a burst of unauthenticated requests from an MCP client. This happens most often with Codex, which sends many unauthenticated requests while it signs in. The block covers every path, including `/register` and requests that carry an API key, and lifts on its own within an hour. Wait for it to expire, then use one of these options so the next connection doesn't trip it again.
+
+You can send your API key as a header instead of signing in with OAuth, as described above. Authenticated requests don't count toward the limit. In Codex, add the key to the server entry in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.runpod]
+url = "https://mcp.getrunpod.io/"
+bearer_token_env_var = "RUNPOD_API_KEY"
+```
+
+Then export `RUNPOD_API_KEY` in the shell that launches Codex.
+
+You can also [run the server locally](#run-locally-with-npx). The local server calls the Runpod API directly, so the hosted firewall only affects its `search-docs` tool, which still searches through the hosted server.
+
 ### Usage analytics
 
 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.

package/dist/{chunk-DDX42UTT.mjs → chunk-4GF3CMSH.mjs}

@@ -16,11 +16,15 @@ function publicGraphqlBase(env) {
 function authedGraphqlBase(env) {
   return pick(env.RUNPOD_AUTHED_GRAPHQL_URL, "https://api.runpod.io/graphql");
 }
+function hostedMcpBase(env) {
+  return pick(env.RUNPOD_MCP_URL, "https://mcp.getrunpod.io");
+}
 
 export {
   sdkBase,
   serverlessBase,
   publicGraphqlBase,
-  authedGraphqlBase
+  authedGraphqlBase,
+  hostedMcpBase
 };
-//# sourceMappingURL=chunk-DDX42UTT.mjs.map
+//# sourceMappingURL=chunk-4GF3CMSH.mjs.map

package/dist/{chunk-DDX42UTT.mjs.map → chunk-4GF3CMSH.mjs.map}

@@ -1 +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":[]}
+{"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/** The hosted MCP server: install target, and stdio's search-docs backend. */\nexport function hostedMcpBase(env: Env): string {\n  return pick(env.RUNPOD_MCP_URL, 'https://mcp.getrunpod.io');\n}\n/** The runpod-assistant Convex site serving /v1/search. No default: unset\n *  means search is not configured. */\nexport function knowledgeSearchBase(env: Env): string | undefined {\n  return pick(env.KNOWLEDGE_SEARCH_URL, '') || undefined;\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;AAEO,SAAS,cAAc,KAAkB;AAC9C,SAAO,KAAK,IAAI,gBAAgB,0BAA0B;AAC5D;","names":[]}