From 357a7ce7aa4e68c679a583fbf27974f1cfa36910 Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Mon, 18 May 2026 13:11:15 +0000
Subject: [PATCH] ci: deploy docs to py.sdk.modelcontextprotocol.io via GitHub
 Pages artifact

Build both v1.x and main into a single Pages artifact (v1 at /, v2 at
/v2/), deployed via actions/deploy-pages on push to either branch. This
fixes the 404 at the custom domain (which DNS already points at GitHub
Pages but the repo never claimed) and stops the two branches from
overwriting each other's docs on release.

The legacy mkdocs gh-deploy path (docs-publish job in publish-pypi.yml
and the manual workflow) is removed; the gh-pages branch can be deleted
once the new deploy is confirmed working.

Closes #2614. Supersedes #2615.
---
 .github/workflows/deploy-docs.yml           | 57 +++++++++++++++++++++
 .github/workflows/publish-docs-manually.yml | 35 -------------
 .github/workflows/publish-pypi.yml          | 29 -----------
 .gitignore                                  |  1 +
 docs/index.md                               |  3 ++
 mkdocs.yml                                  |  2 +-
 pyproject.toml                              |  1 +
 scripts/build-docs.sh                       | 54 +++++++++++++++++++
 8 files changed, 117 insertions(+), 65 deletions(-)
 create mode 100644 .github/workflows/deploy-docs.yml
 delete mode 100644 .github/workflows/publish-docs-manually.yml
 create mode 100755 scripts/build-docs.sh

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 0000000000..d9362afd57
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,57 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+      - v1.x
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - src/mcp/**
+      - scripts/build-docs.sh
+      - pyproject.toml
+      - uv.lock
+      - .github/workflows/deploy-docs.yml
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: false
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          version: 0.9.5
+
+      - name: Build combined docs (v1.x at /, main at /v2/)
+        run: bash scripts/build-docs.sh site
+
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
diff --git a/.github/workflows/publish-docs-manually.yml b/.github/workflows/publish-docs-manually.yml
deleted file mode 100644
index ee45ab5c8a..0000000000
--- a/.github/workflows/publish-docs-manually.yml
+++ /dev/null
@@ -1,35 +0,0 @@
-name: Publish Docs manually
-
-on:
-  workflow_dispatch:
-
-jobs:
-  docs-publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
-        with:
-          enable-cache: true
-          version: 0.9.5
-
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-
-      - run: uv sync --frozen --group docs
-      - run: uv run --frozen --no-sync mkdocs gh-deploy --force
-        env:
-          ENABLE_SOCIAL_CARDS: "true"
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
index bfc3cc64e1..7ba11e86fa 100644
--- a/.github/workflows/publish-pypi.yml
+++ b/.github/workflows/publish-pypi.yml
@@ -51,32 +51,3 @@ jobs:
 
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
-
-  docs-publish:
-    runs-on: ubuntu-latest
-    needs: ["pypi-publish"]
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
-        with:
-          enable-cache: true
-          version: 0.9.5
-
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-
-      - run: uv sync --frozen --group docs
-      - run: uv run --frozen --no-sync mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
index 5ff4ce9771..3443adf7c8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -143,6 +143,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/.worktrees/
 
 # mypy
 .mypy_cache/
diff --git a/docs/index.md b/docs/index.md
index 436d1c8fcd..6a937da67f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,5 +1,8 @@
 # MCP Python SDK
 
+!!! info "You are viewing the in-development v2 documentation"
+    For the current stable release, see the [v1.x documentation](https://py.sdk.modelcontextprotocol.io/).
+
 The **Model Context Protocol (MCP)** allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.
 
 This Python SDK implements the full MCP specification, making it easy to:
diff --git a/mkdocs.yml b/mkdocs.yml
index 3a555785a7..e48c64242d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,7 +5,7 @@ strict: true
 repo_name: modelcontextprotocol/python-sdk
 repo_url: https://github.com/modelcontextprotocol/python-sdk
 edit_uri: edit/main/docs/
-site_url: https://modelcontextprotocol.github.io/python-sdk
+site_url: https://py.sdk.modelcontextprotocol.io/v2/
 
 # TODO(Marcelo): Add Anthropic copyright?
 # copyright: © Model Context Protocol 2025 to present
diff --git a/pyproject.toml b/pyproject.toml
index 364b9add0b..d88869da1c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -115,6 +115,7 @@ bump = true
 
 [project.urls]
 Homepage = "https://modelcontextprotocol.io"
+Documentation = "https://py.sdk.modelcontextprotocol.io/v2/"
 Repository = "https://github.com/modelcontextprotocol/python-sdk"
 Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"
 
diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh
new file mode 100755
index 0000000000..5a61309acf
--- /dev/null
+++ b/scripts/build-docs.sh
@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+#
+# Build combined v1 + v2 MkDocs documentation for GitHub Pages.
+#
+# v1 docs (from the v1.x branch) are placed at the site root.
+# v2 docs (from main) are placed under /v2/.
+#
+# Both branches are fetched fresh from origin, so the output is identical
+# regardless of which branch triggered the workflow. This script is intended
+# to run in CI; for local single-branch preview use `uv run mkdocs serve`.
+#
+# Usage:
+#   scripts/build-docs.sh [output-dir]
+#
+# Default output directory: site
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+OUTPUT_DIR="$(cd "$REPO_ROOT" && mkdir -p "${1:-site}" && cd "${1:-site}" && pwd)"
+V1_WORKTREE="$REPO_ROOT/.worktrees/v1-docs"
+V2_WORKTREE="$REPO_ROOT/.worktrees/v2-docs"
+
+cleanup() {
+    cd "$REPO_ROOT"
+    git worktree remove --force "$V1_WORKTREE" 2>/dev/null || true
+    git worktree remove --force "$V2_WORKTREE" 2>/dev/null || true
+    rmdir "$REPO_ROOT/.worktrees" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+rm -rf "${OUTPUT_DIR:?}"/*
+
+build_branch() {
+    local branch="$1" worktree="$2" dest="$3"
+
+    echo "=== Building docs for ${branch} ==="
+    git fetch origin "$branch"
+    git worktree remove --force "$worktree" 2>/dev/null || true
+    rm -rf "$worktree"
+    git worktree add --detach "$worktree" "origin/${branch}"
+
+    (
+        cd "$worktree"
+        uv sync --frozen --group docs
+        uv run --frozen --no-sync mkdocs build --site-dir "$dest"
+    )
+}
+
+build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR"
+build_branch main "$V2_WORKTREE" "$OUTPUT_DIR/v2"
+
+echo "=== Combined docs built at $OUTPUT_DIR ==="