Repository navigation
Update stacklok/toolhive to v0.67.0 - #1365
renovate[bot] wants to merge 3 commits into
Conversation
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Generating docs for |
Claude generation reportSession status: success · Workflow run Nine docs pages are updated for v0.67.0, and formatting and lint pass. The production build is still running, so I can't yet say whether it builds cleanly or whether any links broke. None of the changes are committed yet. I checked behavior against upstream source and architecture docs at the tag, using the GitHub API. Read and grep on the local clone were blocked in this session. Changes:
Deliberately left out: vMCP scope enforcement (only Go library users can turn it on), the delegated-access marker (nothing issues it yet), ID-JAG redemption changes (the OSS docs don't cover that side), and the Go API package moves. Two upgrade-order caveats are left for reviewers rather than the guides: install the new CRDs and operator before enabling Review requests: I'll come back with the build result when it finishes. |
Claude editorial review reportSession status: success · Workflow run I reviewed the nine docs pages written for the v0.67.0 release and fixed four small problems. Prettier and ESLint both ran cleanly, but I didn't run The Fixes:
Checked and left as is:
I couldn't search the local upstream clone because the sandbox only allows reading inside this repo, so I checked the error strings through |
|
Done · 128 turns · $4.46 · run · see PR body for details |
This PR contains the following updates:
v0.66.0→v0.67.0After this PR opens,
.github/workflows/upstream-release-docs.ymladds source-verified content edits for the new release. Forstacklok/toolhive, the same workflow also syncs reference assets (CLI help, Swagger) and regenerates the CRD MDX pages.Release Notes
stacklok/toolhive
v0.67.0Compare Source
🚀 Toolhive v0.67.0 is live!
This release expands SPIFFE workload identity with a new
client_credentialsgrant and operator support for choosing grant types per association. It tightens token-exchange and ID-JAG redemption with clearer refusal reasons, adds structured findings and link and script checks to skill validation, and sets default resource limits forMCPRemoteProxy.resources, and token exchange needs exactly oneresource. Associations withoutresourcesare rejected, and SPIFFE token-exchange requests that sendaudience=or no target now getinvalid_target. Addresourcesto everyspiffeClientAuthentry and send a single matchingresource(migration guide)thv run uvx://…now defaults to the stdio transport. Auvx://package that serves HTTP or SSE, run without--transport,--target-portor--stateless, now starts as stdio and can't be reached through the proxy. Add--transport streamable-http(or--transport sse) (migration guide)act.subof a SPIFFE token exchange is now the workload's SPIFFE ID. Cedar policies that matchclaim_act.subagainst the SPIFFE client ID no longer match. Matchclaim_client_idinstead (migration guide)MCPRemoteProxygets default CPU and memory requests and limits. Existing proxies that leave any resource field unset restart once after the operator upgrade and get a 256Mi memory limit. Set explicit limits on heavy proxies before you upgrade (migration guide)pkg/auth/tokenexchange, and replaceauthserver.SPIFFEGrantTypeTokenExchangewithoauthproto.GrantTypeTokenExchange(migration guide)Migration guide: SPIFFE associations require
resourcesWho is affected: anyone with SPIFFE associations (
spiffeClientAuth) on anMCPExternalAuthConfig(spec.embeddedAuthServer.inboundGrants), aVirtualMCPServer(spec.authServerConfig.inboundGrants), or a hand-written RunConfig. This also affects SPIFFE workloads that call token exchange. SPIFFE associations were introduced in v0.65.0.resourcesis now required and must have at least one entry. A CEL admission rule enforces this, along with RunConfig validation andValidateInboundGrants. The auth server refuses to start without it.audiencesis deprecated and ignored. A non-empty value is reported by theDeprecatedInboundGrantConfigurationcondition and by one startup WARN per association.resourcethat exactly matches an entry in the association'sresourcesand in the server's allowed audiences. The server refuses a missing, empty or repeatedresource, or anyaudienceparameter, withinvalid_target.Validcondition onMCPExternalAuthConfig, or theAuthServerConfigValidatedcondition onVirtualMCPServer, reports the missingresources, and dependent servers fail to reconcile until you add it.configured client replaced with a different policyWARN per association. Nothing is authorized differently.Before
After
Migration steps
resourceslist to everyspiffeClientAuthentry. Each entry must be one of the server's allowed audiences.audiencesfrom these entries. It is ignored now and only triggers the deprecation condition and WARN.resource=<uri>and noaudienceparameter on token-exchange requests.Valid/AuthServerConfigValidatedconditions after you upgrade.PR: #7160, part of #6204
Migration guide:
uvx://defaults to stdioWho is affected: CLI users who run
thv run uvx://<package>with no--transportand no registry metadata, for a package that serves streamable-http or SSE. For example, a package switched to HTTP through its own arguments after--. Python stdio servers, which previously restarted in a loop, now work without any flags.The transport is now chosen in this order:
--transportstdioforuvx://inputs, unless--target-portor--statelessis setstreamable-httpnpx://,go://and plain images are unchanged, and so is thethv serveAPI path.thv runlogs the implicit stdio choice at startup.Before
# ran as streamable-http implicitly thv run uvx://my-http-mcp-server -- --transport streamable-httpAfter
Migration steps
thv run uvx://…invocations for servers that speak HTTP or SSE.--transport streamable-httpor--transport sse, or set--target-port.uvx://servers need no change.PR: #7133 — Fixes #6634
Migration guide: SPIFFE
act.subnames the workloadWho is affected: deployments where SPIFFE workloads use token exchange without an
actor_token, especially Cedar policies orauthorization_detailshooks that identify the client throughact.sub.act.subis now the workload's verified SPIFFE ID instead of the client ID.client_idis unchanged./*) association can no longer exchange another workload's token. It getsinvalid_grantwith the hint "The subject token was issued to a different workload of this client."act.subis the client ID) getsinvalid_grant. These tokens are short-lived, and the workload recovers by exchanging the original token again.Before
After
Migration steps
claim_act.subcomparisons against SPIFFE client IDs.claim_client_id, or match the workload's SPIFFE ID if you want per-workload rules.authorization_detailshooks that readRequest.Actor, which now carries the SPIFFE ID.PR: #7176, part of #6204
Migration guide:
MCPRemoteProxydefault resourcesWho is affected: every
MCPRemoteProxythat leaves any resource field unset.Unset fields now default to these values:
50m64Mi200m256MiExplicit values in
spec.resourcesorpodTemplateSpecstill win, field by field. A proxy that sets only limits behaves exactly as before. Affected proxies restart once after the operator upgrade. A proxy whose working set is above 256Mi, such as a busy proxy with an embedded auth server, will be OOMKilled.Before
After
Migration steps
MCPRemoteProxypods.spec.resources.limits.memory(and CPU if needed) explicitly.PR: #7137 — Fixes #3131
Migration guide: Go API changes
Who is affected: Go programs that embed ToolHive packages. CLI flags, operator manifests, serialized runner configuration and request handling are unchanged.
Before
After
Migration steps
pkg/auth/tokenexchange. There is no compatibility wrapper.pkg/oauthproto/tokenexchangefor code that only uses the exchange client,ExchangeConfigorNormalizeTokenType.authserver.SPIFFEGrantTypeTokenExchangewithoauthproto.GrantTypeTokenExchange. The value is the same.PRs: #7197, #7173
🔄 Deprecations
spiffeClientAuth[].audiencesis deprecated in favour ofresources. It is now ignored, and a non-empty value is reported by theDeprecatedInboundGrantConfigurationcondition and a startup WARN. It stays in the schema for compatibility with v0.65.0 objects (#7160)🆕 New Features
client_credentialsgrant bound to their SPIFFE ID. The token lifetime is capped at the SVID's remaining validity. The grant and the SPIFFE auth methods are advertised in discovery, and token exchange is no longer force-enabled when no association lists it (#7173)MCPExternalAuthConfigandVirtualMCPServerSPIFFE associations gain agrantTypesfield that selectsclient_credentials, token exchange or both. It defaults to token exchange. Install the new CRDs and the new operator before you enableclient_credentials(#7175)clientNamein the DCR upstream configuration to control the name shown on the upstream IdP's authorization screen. It defaults to "ToolHive MCP Client" (#7095)thv skill validate,thv ai-plugin validateand their API endpoints now return a structuredfindingsarray with severity, rule ID, file and line, and plugin validation now reports bundled-skill warnings (#7165)ref-unresolved) or escaping (ref-escapes-root) references as warnings (#7166)script-direct-exec) when a skill tells the agent to run a bundled script directly. Installed skill files aren't executable, so the script would fail (#7167)error_descriptionwith a machine-readable reason code, such asinvalid_assertion,subject_unknown,resource_deniedorissuer_unavailable. An unreachable issuer JWKS now returns a retryable 503temporarily_unavailable(#7193)core.Config.ScopeAuthorization. This is the first of three parts, and CLI and operator deployments are unchanged (#7170)🐛 Bug Fixes
resourceclaim names a resource the server doesn't govern, or doesn't list the requested resource, as draft-06 §4.4.1 requires. A server with noallowed_audiencesnow refuses every ID-JAG that carries aresourceclaim (#7198)[::1%25lo0]) and hosts that don't parse as IP literals. Previously these could reach loopback or private addresses (#7155)User-Agentheader instead of always being reported asunknown(#7185)🧹 Misc
client_credentialssuites forMCPServerandVirtualMCPServerthat run against a real SPIRE server (#7194)actclaim survives ID-JAG redemption into the issued access token (#7156)http.DefaultTransport(#7178)actions/setup-goto v7.1.0 across CI workflows to fix the static-analysis gate (#7169)👋 Welcome to our newest contributors: @shu-chen-dot-ca and @imaxmelnyk 🎉
Full commit log
What's Changed
New Contributors
Full Changelog: stacklok/toolhive@v0.66.0...v0.67.0
🔗 Full changelog: stacklok/toolhive@v0.66.0...v0.67.0
Configuration
📅 Schedule: (in timezone America/New_York)
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Never, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR was generated by Mend Renovate. View the repository job log.
Docs update for
toolhivev0.67.0Note
Silent run — skill produced no content commits. The docs are
likely already up-to-date (e.g.
mainahead of pin, or a re-runafter a previous PR for this tag merged). Only the version bump
and refreshed reference assets are included.
At a glance
stacklok/toolhivev0.66.0→v0.67.0Who does what
@samuv cut this release and owns this PR: review your own changes, chase the remaining approvals, and merge once they're in. You don't need to wait on a review from anyone listed as having no docs impact below.
Everyone with a review request: the target is a review and approval within 2 business days.
Summary of changes
docs/toolhive/guides-vmcp/delegate-agent-identity.mdx: the newgrantTypesfield, requiredresources(audiencesis deprecated), single-resourcerequests, a new "Get a token with the client credentials grant" section, the workload's SPIFFE ID inact.sub(with aChanged in v0.67.0note for Cedar policies), workload binding, and new troubleshooting rowsdocs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx(SPIFFE acting party, new SPIFFE client credentials row) and thespiffeTrustDomainsrow indocs/toolhive/guides-k8s/embedded-auth-server-k8s.mdxdcrConfig.clientNametodocs/toolhive/guides-k8s/embedded-auth-server-k8s.mdxand the vMCPdcrConfigfield tableMCPRemoteProxydefault resources and aChanged in v0.67.0upgrade note todocs/toolhive/guides-k8s/remote-mcp-proxy.mdxdocs/toolhive/guides-cli/run-mcp-servers.mdxwith theuvx://stdio transport default and aChanged in v0.67.0note for HTTP/SSE packagesdocs/toolhive/guides-cli/skills-management.mdxandai-plugins.mdx: link, path-escape, and direct-script warnings, thefindingsJSON output, and reporting of bundled-skill warningsdocs/toolhive/guides-vmcp/accept-workload-assertions.mdxwith theinvalid_assertionreason code and the 503issuer_unavailableresponse, and updated the FAQ usage-metrics client attribution indocs/toolhive/faq.mdxDeliberately not documented:
core.Config.ScopeAuthorization(Enforce incoming scopes in the vMCP core toolhive#7170): only Go library embedders can turn it on, and CLI and operator deployments are unchanged.resourceclaim check (Add reason codes to redemption refusals toolhive#7193, Refuse ID-JAGs whose resource claim disagrees toolhive#7198): the OSS docs don't cover ToolHive as an ID-JAG redeemer. Only the plain JWT-bearer table was updated.authserver.SPIFFEGrantTypeTokenExchangeconstant (Move token-exchange middleware out of oauthproto toolhive#7197, Add client_credentials grant for SPIFFE workloads toolhive#7173): Go API only.grantTypes, so install the new CRDs and operator before you enableclient_credentials. Re-exchanging a SPIFFE token issued before the upgrade fails withinvalid_grant. Both are upgrade-sequencing notes, so they were left to the release notes rather than the guide.No docs impact identified
1 contributor(s) had no-docs-impact commits in this release. No review was requested, and the workflow did not auto-notify them.
Review routing
GitHub could not request the upstream contributor directly, so review went to the human merger of each relevant upstream PR:
Run cost
How this PR was built
Two Claude Opus sessions run per release: a generation pass
(
upstream-release-docsskill, 6 phases) followed by a fresh-context editorial pass (
docs-review). Prettier/ESLintauto-fixes are applied after.
Auto-synced paths — do not hand-edit these in review:
static/api-specs/docs/toolhive/reference/cli/(toolhive only)docs/toolhive/reference/crds/If a "Gaps needing human context" section is present above,
each entry includes a paste-ready Helper prompt for local
Claude a reviewer can use to resolve the gap.