carlos-lopez-vecino · Oct 16, 2026 · Jun 30, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026
diff --git a/.claude/agents/mcp-protocol-expert.md b/.claude/agents/mcp-protocol-expert.md
@@ -1,7 +1,7 @@
 ---
 name: mcp-protocol-expert
-description: "PROACTIVELY use for MCP protocol questions, transport implementations, JSON-RPC debugging, and spec compliance verification. Expert in MCP 2025-11-25 specification."
-tools: [Read, Write, Edit, Glob, Grep, WebFetch]
+description: "PROACTIVELY use for MCP protocol questions, transport implementations, JSON-RPC debugging, and spec compliance verification. Expert in the current stable MCP specification."
+tools: [Read, Write, Edit, Glob, Grep, WebFetch, mcp__context7__resolve-library-id, mcp__context7__get-library-docs]
 model: inherit
 ---
 
@@ -22,35 +22,32 @@ Defer to: oauth-expert (OAuth/OIDC), kubernetes-expert (K8s operator), toolhive-
 
 ## Critical: Always Fetch Latest Spec
 
-**Before providing MCP protocol guidance, ALWAYS use WebFetch to retrieve the relevant spec page.** MCP is actively evolving — the spec is the single source of truth.
+**Before providing MCP protocol guidance, ALWAYS retrieve the relevant spec page — never answer from pre-training knowledge alone.** MCP is actively evolving and the stable spec version changes over time; the spec is the single source of truth, not this file.
 
-### Spec URLs (2025-11-25)
-- Main: https://modelcontextprotocol.io/specification/2025-11-25
-- Transports: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
-- Lifecycle: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
-- Authorization: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
-- Security: https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices
-- Tasks: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks
-- Tools: https://modelcontextprotocol.io/specification/2025-11-25/server/tools
-- Elicitation: https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
-- MCP Auth Extensions: https://modelcontextprotocol.io/extensions/auth/overview
-- Schema: https://modelcontextprotocol.io/specification/2025-11-25/schema
-
-Check for newer spec versions — the date in the URL indicates version.
+**Prefer context7. Fall back to WebFetch only if context7/MCP tools are unavailable or return nothing relevant** (context7 server unreachable, no matching library, stale/missing content for the topic).
 
 ### Workflow
-1. Use WebFetch to retrieve the relevant spec page
-2. Cross-reference fetched spec with ToolHive's implementation
-3. Provide guidance based on the latest spec
-4. Explicitly note any discrepancies between spec and implementation
+
+1. **Try context7 first**:
+   - Call `mcp__context7__resolve-library-id` fresh every time (do not hardcode or reuse a library ID across sessions) with a query like "Model Context Protocol specification". Context7 mints a new pinned library per stable release (e.g. `/websites/modelcontextprotocol_io_specification_2025-11-25`, `_2025-06-18`), so a fresh resolve naturally surfaces whichever dated snapshot is current — don't assume any specific date.
+   - Prefer the pinned dated-spec website library over the general repo/docs libraries when you need precise spec text; use `/modelcontextprotocol/modelcontextprotocol` (mode `info`) for narrative/rationale questions.
+   - Call `mcp__context7__get-library-docs` with a topic scoped to the question (e.g. "authorization discovery", "streamable http transport").
+2. **Fall back to WebFetch** if context7 didn't resolve a library, the MCP tools aren't available in this environment, or the returned snippets don't answer the question:
+   - First resolve the current version: fetch the unversioned index `https://modelcontextprotocol.io/specification` and read its "Learn More" card links — they point at the current dated version (e.g. `/specification/2025-11-25/...`). Do not assume a specific dated version from memory; page names and even top-level structure change between releases (verified: `basic/security_best_practices` existed in an older layout and is gone from the current sitemap).
+   - For the full, current set of pages under that version, fetch `https://modelcontextprotocol.io/sitemap.xml` and filter for the resolved version string — this is self-correcting as pages are added, renamed, or removed, unlike a hand-maintained list.
+   - Common pages to expect (verify against the sitemap, don't assume the exact path): architecture, basic, basic/authorization, basic/lifecycle, basic/transports, basic/utilities/{cancellation,ping,progress,tasks}, client/{elicitation,roots,sampling}, server, server/{tools,resources,prompts}, server/utilities/{completion,logging,pagination}, schema, changelog.
+   - Also check `https://modelcontextprotocol.io/extensions/auth/overview` for MCP auth extensions, which live outside the versioned spec tree.
+3. Cross-reference whichever source answered with ToolHive's implementation.
+4. Provide guidance based on the latest spec.
+5. Explicitly note any discrepancies between spec and implementation, and note which source (context7 vs. WebFetch) backed the answer if it's non-obvious.
 
 ## Your Expertise
 
 - **MCP Specification**: Authoritative protocol definition and compliance
 - **Transport protocols**: stdio (preferred), Streamable HTTP, SSE (deprecated)
 - **JSON-RPC 2.0**: Message format, request/response/notification patterns
 - **Protocol lifecycle**: Initialization, capability negotiation, operation, shutdown
-- **Tasks & Elicitation**: Long-running operations and user input collection (new in 2025-11-25)
+- **Tasks & Elicitation**: Long-running operations and user input collection
 - **Authorization**: OAuth 2.1, RFC 9728, RFC 8707, Client ID Metadata Documents
 
 ## Key ToolHive Files
@@ -71,8 +68,8 @@ Check for newer spec versions — the date in the URL indicates version.
 5. **Protocol debugging**: Analyze JSON-RPC exchanges against spec requirements
 
 <critical_behaviors>
-1. Fetch before answering — always use WebFetch for relevant spec pages
+1. Fetch before answering — try context7 first, fall back to WebFetch, never answer from memory alone
 2. Spec is authoritative — if conflict with this doc, the fetched spec wins
-3. Check for newer versions — look for dates newer than 2025-11-25
+3. Never hardcode a version — resolve the current stable version fresh each time (context7 resolve-library-id, or the unversioned spec index for WebFetch)
 4. Call out discrepancies explicitly when ToolHive differs from spec
 </critical_behaviors>
diff --git a/.claude/rules/operator.md b/.claude/rules/operator.md
@@ -318,6 +318,30 @@ write-path mechanics.)
 
 See `cmd/thv-operator/DESIGN.md` for detailed decision guidelines.
 
+## Phase and Conditions
+
+**Conditions** are the primary status mechanism. Each condition represents one
+aspect of readiness, validity, or external dependency state, and controllers
+should set conditions with specific reason constants and actionable messages.
+Use specific condition types such as `ConfigurationValid` or `RemoteAvailable`
+when the condition is scoped to one CRD; reserve truly shared types for
+cross-CRD conventions.
+
+**Phase** is a human-readable lifecycle summary for `kubectl get` output. It
+must be derived from the current conditions and observed state, never set as an
+independent source of truth.
+
+Rules:
+
+- Never set `Phase` directly from a separate code path; derive it from the
+  current condition states.
+- `Ready` means all readiness conditions are `True`.
+- `Failed` means at least one condition is `False` with a terminal reason.
+- `Pending` means required conditions are not all satisfied yet, and no terminal
+  failure has been observed.
+- Condition `Type` names should be specific and have meaningful `Reason`
+  constants.
+
 ## CRD Type Conventions
 
 - Use `metav1.Duration` for duration fields in CRD types, not `string` or

diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml
@@ -59,7 +59,7 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@a92e7c70a4da9793dc164451d829089dc057a464 # v1
+        uses: anthropics/claude-code-action@f1bd27ca5b54584506e40e17884d90bdaaa1a9b3 # v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           # Security: Restrict tools to prevent arbitrary code execution.

diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
@@ -123,7 +123,7 @@ jobs:
         run: |
           # Pre-pull images used by E2E tests so that workload creation
           # does not pay the image-pull cost inside the 60s API timeout.
-          docker pull ghcr.io/stackloklabs/osv-mcp/server:0.1.0 &
+          docker pull ghcr.io/stackloklabs/osv-mcp/server:0.1.3 &
           docker pull ghcr.io/stackloklabs/gofetch/server:1.0.2 &
           docker pull ghcr.io/stacklok/toolhive/egress-proxy:latest &
           # yardstick is only needed for the vmcp test suite
@@ -154,3 +154,43 @@ jobs:
           path: |
             test/e2e/junit-report.xml
           retention-days: 7
+
+  conformance:
+    name: MCP Conformance
+    runs-on: ubuntu-8cores-32gb
+    needs: build-binary
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: '22'
+
+      - name: Download ToolHive binary
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: toolhive-binary
+          path: ./bin/
+
+      - name: Set binary permissions
+        run: chmod +x ./bin/thv
+
+      - name: Set up container runtime (Docker)
+        run: |
+          docker --version
+          sudo systemctl start docker
+
+      - name: Run MCP conformance suite
+        env:
+          THV_BINARY: ${{ github.workspace }}/bin/thv
+        run: ./test/conformance/run-conformance.sh
+
+      - name: Upload conformance results
+        if: always()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: conformance-results
+          path: test/conformance/results
+          retention-days: 7
diff --git a/.github/workflows/issue-triage.yml b/.github/workflows/issue-triage.yml
@@ -19,7 +19,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run Claude Code for Issue Triage
-        uses: anthropics/claude-code-action@a92e7c70a4da9793dc164451d829089dc057a464 # v1.0.159
+        uses: anthropics/claude-code-action@558b1d6cab4085c7753fe402c10bef0fbb92ac7a # v1.0.165
         with:
           prompt: |
             You are an issue triage assistant. Analyze issue #${{ github.event.issue.number }} in ${{ github.repository }} and apply appropriate labels.

diff --git a/.github/workflows/release-notes.yml b/.github/workflows/release-notes.yml
@@ -98,7 +98,7 @@ jobs:
 
       - name: Generate release notes with Claude
         id: claude
-        uses: anthropics/claude-code-action@a92e7c70a4da9793dc164451d829089dc057a464 # v1
+        uses: anthropics/claude-code-action@f1bd27ca5b54584506e40e17884d90bdaaa1a9b3 # v1
         env:
           # gh CLI used by the skill (read-only PR/issue lookups) authenticates
           # via GH_TOKEN. Read access is sufficient — publishing happens in a

diff --git a/.github/workflows/releaser.yml b/.github/workflows/releaser.yml
@@ -195,7 +195,7 @@ jobs:
 
       - name: Run GoReleaser
         id: run-goreleaser
-        uses: goreleaser/goreleaser-action@5daf1e915a5f0af01ddbcd89a43b8061ff4f1a89 # v7
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
         with:
           distribution: goreleaser
           version: "~> v2"

diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml
@@ -32,7 +32,7 @@ jobs:
           fail-build: false
 
       - name: Upload Grype scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
+        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4
         if: always()
         with:
           sarif_file: ${{ steps.grype-scan.outputs.sarif }}
@@ -80,6 +80,13 @@ jobs:
           # CI's `setup-go: stable` still resolves to go1.26.3 because the
           # actions/go-versions manifest lags the Go release. Temporary
           # exclusion; remove once CI builds on go1.26.4 or later.
+          #
+          # GO-2026-5932: golang.org/x/crypto/openpgp is deprecated-by-design
+          # ("unsafe, not maintained, should not be used"). No fixed version
+          # exists and none is planned. ToolHive does not import openpgp
+          # directly; it is pulled transitively via sigstore (rekor/sigstore-go)
+          # for backward-compatible OpenPGP verification. Remove when sigstore
+          # drops the openpgp dependency.
           IGNORED_VULNS="GO-2026-4514 GO-2026-4883 GO-2026-4887 GO-2026-5617 GO-2026-5668 GO-2026-5746 GO-2026-5932 GO-2026-5037 GO-2026-5038 GO-2026-5039"
 
           # Show the raw output for debugging

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,6 +6,8 @@ This file provides guidance to Claude Code when working with this repository.
 
 ToolHive is a lightweight, secure manager for MCP (Model Context Protocol: https://modelcontextprotocol.io) servers written in Go. It provides a CLI (`thv`), a Kubernetes operator (`thv-operator`), and a proxy runner (`thv-proxyrunner`) for container-based MCP server isolation.
 
+**To understand the system, start with the [Architecture Documentation](docs/arch/README.md).** Begin at the [Architecture Overview](docs/arch/00-overview.md) and [Core Concepts](docs/arch/02-core-concepts.md), then read the component deep-dives relevant to your task — [Deployment Modes](docs/arch/01-deployment-modes.md), [Transport Architecture](docs/arch/03-transport-architecture.md), [Kubernetes Operator](docs/arch/09-operator-architecture.md), [Virtual MCP](docs/arch/10-virtual-mcp-architecture.md), and more. The [architecture index](docs/arch/README.md) has a full map and by-topic navigation.
+
 ## Build and Development Commands
 
 ```bash
@@ -84,7 +86,7 @@ Detailed rules are in `.claude/rules/` (loaded automatically when matching files
 
 ## Architecture Documentation
 
-When making changes that affect architecture, update relevant docs in `docs/arch/`. See `docs/arch/README.md` for structure.
+When making changes that affect architecture, update relevant docs in `docs/arch/`. See the [architecture documentation index](docs/arch/README.md) for structure and the per-component documents.
 
 ## Things That Will Bite You
 

diff --git a/FORK.md b/FORK.md
@@ -4,7 +4,7 @@
 fork patches we carry. Upstream releases are brought in with a merge commit
 (`Merge upstream vX.Y.Z into dp-stable`), never a rebase.
 
-Merge base: upstream **v0.32.0** (`ecb9a8d84`), merged in `38edac4e3` (PAIINFRA-228).
+Merge base: upstream **v0.39.0** (`4ebb610f2`), merged in `75ba8d1d5` (PAIINFRA-233).
 
 ## Changes that live only in a merge commit
 
@@ -56,6 +56,17 @@ merge, see below):
 `VMCP_SESSION_HMAC_SECRET` is no longer used (upstream logs and ignores it). Sessions stored with the
 old token-hash key are invalidated on read, so clients re-initialize once after the upgrade.
 
+### `75ba8d1d5` — Merge upstream v0.39.0
+
+Fork behaviour kept while resolving:
+
+| Behaviour | Where it lives now | Original commit |
+|---|---|---|
+| The MCPServer Service is updated before the Deployment, so Deployment drift cannot starve a port fix; labels and annotations are now merged, as upstream #5731 does | `cmd/thv-operator/controllers/mcpserver_controller.go` (`Reconcile`) | `5df636980`, `e88959899` |
+| Explicit `spec.config.backends` (hub remote backends) are merged with the discovered backends, an explicit backend winning on the same name; upstream's `excludedBackends` filters only the discovered ones | `cmd/thv-operator/controllers/virtualmcpserver_vmcpconfig.go` (`mergeStaticBackends`) | `8e474c8b2` |
+
+`PodTemplateSpecBuilder.SchedulingSpec()` stays: MCPServer and the vMCP drift check still use it.
+
 ## Fork behaviour re-ported after the v0.32.0 merge
 
 In v0.32.0 every vMCP caller goes through `server.Serve`: tool, resource and prompt calls go
@@ -132,3 +143,5 @@ They stay in history; don't re-apply them on a replay.
 | `7a6c9a2f3` | Restore with the owner's live identity (`ownsStoredSession`) | Upstream #5650 restores with the request identity; `enforceSessionBinding` rejects other callers. Dropped in the v0.32.0 merge. |
 | `c2cb472a2` (status map) | Upstream-token status map (`UpstreamCredentialStatus`, `UpstreamTokenStatuses`) | Upstream #5651 returns 401 when a refresh fails; the missing-token case is `44b70f6a5`. No Cedar policy read the status. Dropped in the v0.32.0 merge. |
 | `8d09330f5` (alias) | Redis `address` alias of `addr` on `MCPExternalAuthConfig` (CRD, `EffectiveAddr`) and `LegacyAddress` in the auth-server RunConfig | All values and live objects use `addr` (PAIINFRA-219). Dropped in the v0.32.0 merge. |
+| `5b6448a0d` (remote proxy part) | `MCPRemoteProxy.spec.podTemplateSpec`, applying only nodeSelector, tolerations and affinity | Upstream #5531 (v0.37.0) adds the same field with a full strategic-merge patch, a `PodTemplateValid` condition and drift detection by hash. No live MCPRemoteProxy exists. Dropped in the v0.39.0 merge. |
+| `8e474c8b2` (env sort) | `sortEnvVarsByName` on the vMCP env, plus sorted workload and backend loops | Upstream already sorts each discovered and inline secret env group; the rest of the list has a fixed order. Dropping it changes the env order once, inside the rollout the new image causes anyway. Dropped in the v0.39.0 merge. |
diff --git a/Taskfile.yml b/Taskfile.yml
@@ -215,6 +215,14 @@ tasks:
       - task: test-integration-windows
         platforms: [windows]
 
+  conformance:
+    desc: Run the MCP conformance suite against a `thv run` deployment (requires Docker + Node)
+    deps: [build]
+    env:
+      THV_BINARY: "{{.PWD}}/bin/thv"
+    cmds:
+      - ./test/conformance/run-conformance.sh
+
   test-all:
     desc: Run all tests (unit, integration, and e2e)
     deps: [test, test-integration, test-e2e]

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.32.0
+0.39.0
diff --git a/cmd/thv-operator/README.md b/cmd/thv-operator/README.md
@@ -129,6 +129,10 @@ helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-
 helm upgrade -i <release_name> oci://ghcr.io/stacklok/toolhive/toolhive-operator --version=<version> -n toolhive-system --create-namespace
 ```
 
+For the full list of configurable values, see the
+[operator chart](../../deploy/charts/operator/README.md) and
+[operator CRDs chart](../../deploy/charts/operator-crds/README.md) documentation.
+
 ## Usage
 
 ### Creating an MCP Server