feat(dockhand): support transitive dependency overrides/constraints in spec.yaml

[JAORMX]

Problem

Renovate version bumps for MCP servers fail the build-containers Grype gate (--fail-on high --only-fixed) when the bumped package pins or caps a transitive dependency to a vulnerable version, and we have no way to override that pin from within dockyard. Three open PRs are blocked on exactly this:

PR	Package	Vulnerable transitive dep	Why we can't fix it	Worst
#469	@brightdata/mcp 2.9.5	@modelcontextprotocol/sdk hard-pinned 1.21.2	package pins exact version; fixes are ≥1.24	3× HIGH
#527	mcp-clickhouse 0.3.0	fastmcp capped <3.0.0	CRITICAL fix is fastmcp 3.2.0, excluded by cap	CVE-2026-32871 (Critical)
#528	mcp-neo4j-cypher 0.6.0	fastmcp capped <2.14	all fixes (2.14.x / 3.2.0) excluded by cap	Critical + 3 HIGH

(Note #527 and #528 are also regressions vs. what main currently ships — see those PRs.)

Proposal

Add an optional dependency-override mechanism to the spec.yaml schema, plumbed into the generated Dockerfile:

spec:
  package: "@brightdata/mcp"
  version: "2.9.5"
  overrides:                                  # npx → npm "overrides"
    "@modelcontextprotocol/sdk": "1.26.0"

spec:
  package: "mcp-clickhouse"
  version: "0.3.0"
  constraints:                                # uvx → uv "--override" / constraints file
    - "fastmcp>=3.2.0"

Implementation sketch

• Extend MCPServerPackageSpec (cmd/dockhand/main.go:43) with Overrides map[string]string (npx) and/or Constraints []string (uvx).
• generateDockerfile (cmd/dockhand/main.go:354) already receives the Dockerfile as a string from toolhive's BuildFromProtocolSchemeWithName(..., dryRun=true). Post-process that string to inject the override:
  • npx: emit a package.json containing an overrides block before the npm install --save <pkg> step (npm honors overrides only from package.json).
  • uvx: add --override <constraints-file> (or per-spec --override pkg>=ver) to the uv tool install step.
• Require every override entry to carry a short justification (mirroring security.allowed_issues) so the why is auditable in-repo.

Verification (already done manually)

A throwaway test of each override was run against the exact build recipe + the same Grype gate:

• chore(deps): update dependency @brightdata/mcp to v2.11.1 #469: overrides {"@modelcontextprotocol/sdk":"1.26.0"} → resolves to a single SDK 1.26.0, grype clean, gate passes, same-major so no API break.
• chore(deps): update dependency mcp-clickhouse to v0.6.0 #527: uv --override "fastmcp>=3.2.0" → fastmcp 3.4.0, import mcp_clickhouse OK, grype clean (this just restores what main's 0.2.0 already ships).
• chore(deps): update dependency mcp-neo4j-cypher to v0.6.0 #528: forcing fastmcp>=3.2.0 → grype clean + imports, but crosses upstream's deliberate <2.14 cap (major 2→3 jump) — needs functional testing of the neo4j tools before trusting.

Acceptance

• spec.overrides (npx) and spec.constraints (uvx) supported + documented
• Injected correctly into the generated Dockerfile for both protocols
• chore(deps): update dependency @brightdata/mcp to v2.11.1 #469 / chore(deps): update dependency mcp-clickhouse to v0.6.0 #527 / chore(deps): update dependency mcp-neo4j-cypher to v0.6.0 #528 pass build-containers with overrides applied
• Override entries require an inline justification

🤖 Generated with Claude Code

[danbarr]

Closing: the mechanism is delivered. Recording the disposition per acceptance criterion, since one of them is intentionally not satisfied and that reasoning is worth keeping.

• spec.overrides (npx) and spec.constraints (uvx) supported + documented — feat(dockhand): support transitive dependency overrides/constraints in spec.yaml #669. Documented in docs/adding-servers.md under "Dependency Overrides and Constraints".
• Injected correctly into the generated Dockerfile for both protocols — feat(dockhand): support transitive dependency overrides/constraints in spec.yaml #669, plus hardening in that PR: the uvx install-step anchor was matching uv tool install " and silently missed builds where toolhive emits its own flags first, the npm path rebuilt package.json from hardcoded values instead of extending what toolhive emitted, and override values were interpolated into RUN lines unquoted, which corrupted PEP 508 environment markers and allowed command injection at build time. Tests now inject against Dockerfiles generated by the pinned toolhive version so template drift fails in CI.
• chore(deps): update dependency @brightdata/mcp to v2.11.1 #469 / chore(deps): update dependency mcp-clickhouse to v0.6.0 #527 / chore(deps): update dependency mcp-neo4j-cypher to v0.6.0 #528 pass build-containers with overrides applied — not satisfied as written; see below.
• Override entries require an inline justification — reason is mandatory and validation fails without it.

Two things arrived beyond the original scope:

• The security scan reapplies overrides (feat(mcp-scan): apply npx dependency overrides during the security scan #831), so the scanned process resolves the same dependency versions the image ships. Without this the scan exercised a different tree than the one published.
• The backlog was actually cleared (fix: clear the Grype vulnerability backlog via spec overrides #833): adb-mysql-mcp-server, chroma-mcp, brightdata-mcp, mcp-jetbrains, astra-db-mcp, browserbase-mcp-server. Full picture in Grype backlog: 10 published servers fail the vulnerability gate, several fixable via spec.constraints/overrides #830.

Disposition of the three motivating cases

They have each moved on since this was filed, and they now split three ways rather than being one class of problem:

• chore(deps): update dependency @brightdata/mcp to v2.11.1 #469 (@brightdata/mcp, now v2.11.1) — unblocked. Both 2.9.0 and 2.11.1 pin @modelcontextprotocol/sdk at 1.21.2, so the SDK 1.26.0 override already on main stays correct across the bump. Safe to merge as-is.
• chore(deps): update dependency mcp-clickhouse to v0.6.0 #527 (mcp-clickhouse, now v0.4.1) — override-fixable, but not as originally analysed. 0.4.1 adds a fastmcp<3.0.0 cap that 0.2.0 does not have, so the bump is a regression rather than something waiting on this mechanism. It needs a fastmcp>=3.2.0 constraint to undo that cap. Details on the PR.
• chore(deps): update dependency mcp-neo4j-cypher to v0.6.0 #528 (mcp-neo4j-cypher v0.6.0) — not override-fixable, and should be held. The fastmcp fixes exist only at 3.2.0 with no 2.x backport, and all three neo4j servers pass stateless_http=True to the FastMCP constructor, which 3.x removed with a hard raise. Forcing it produces an image that builds and imports cleanly and then cannot start the server. Needs an upstream release. See Grype backlog: 10 published servers fail the vulnerability gate, several fixable via spec.constraints/overrides #830 and the comment on chore(deps): update dependency mcp-neo4j-cypher to v0.6.0 #528.

Two limits of the mechanism, learned while applying it

Worth carrying forward, because neither is obvious from the implementation:

1. Choosing the minimum fixed version is usually wrong. A small bump can step into an advisory the pinned version predated. Four of the six fixes in fix: clear the Grype vulnerability backlog via spec overrides #833 needed a higher target than the minimum for exactly this reason.
2. The scan cannot validate an override on an insecure_ignore server. Those need real credentials to start, so mcp-scan cannot enumerate their tools and would pass a startup-breaking override straight through. The neo4j breakage was only caught by calling the server's factory function directly.

The three renovate PRs are ordinary triage now rather than blocked work, and are tracked on their own threads. mcp-server-neon was the fourth backlog case and was removed instead in #836, since its upstream package is deprecated.