Serve v2 docs at the site root, with permanent per-major paths (#3176)

Author: maxisbey

.github/workflows/deploy-docs.yml

@@ -3,8 +3,10 @@ name: Deploy Docs
 on:
   push:
     branches:
+      # main is the sole deployer of the combined site (v2 at / and /v2/, v1.x
+      # at /v1/); the v1.x branch has no deploy workflow. A v1.x docs change is
+      # published by the next main deploy or a manual workflow_dispatch here.
       - main
-      - v1.x
     paths:
       - docs/**
       # docs pages include their code blocks from these files via `--8<--`, so a
@@ -48,7 +50,7 @@ jobs:
           enable-cache: true
           version: 0.9.5
 
-      - name: Build combined docs (v1.x at /, main at /v2/)
+      - name: Build combined docs (main at / and /v2/, v1.x at /v1/)
         run: bash scripts/build-docs.sh site
 
       - name: Configure Pages

docs/index.md

@@ -1,7 +1,7 @@
 # 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/).
+!!! info "You are viewing the v2 documentation"
+    The v1.x documentation is at [/v1/](https://py.sdk.modelcontextprotocol.io/v1/).
     New to v2, or coming from v1? **[What's new in v2](whats-new.md)** is the five-minute tour of what changed.
     Trying v2? [Tell us what you find](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml) — it is the most useful thing you can do for the SDK right now.
 

mkdocs.yml

@@ -4,7 +4,7 @@ site_description: The official Python SDK for the Model Context Protocol
 repo_name: modelcontextprotocol/python-sdk
 repo_url: https://github.com/modelcontextprotocol/python-sdk
 edit_uri: edit/main/docs/
-site_url: https://py.sdk.modelcontextprotocol.io/v2/
+site_url: https://py.sdk.modelcontextprotocol.io/
 
 # TODO(Marcelo): Add Anthropic copyright?
 # copyright: © Model Context Protocol 2025 to present

pyproject.toml

@@ -142,7 +142,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://modelcontextprotocol.io"
-Documentation = "https://py.sdk.modelcontextprotocol.io/v2/"
+Documentation = "https://py.sdk.modelcontextprotocol.io/"
 Repository = "https://github.com/modelcontextprotocol/python-sdk"
 Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"
 

scripts/build-docs.sh

@@ -2,16 +2,20 @@
 #
 # Build combined v1 + v2 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/.
+# The current major (v2, from main) is placed at the site root and mirrored
+# under /v2/; the v1 maintenance line (from the v1.x branch) is placed under
+# /v1/. Per-major paths are permanent: /v2/ is a byte-identical copy of the
+# root so that /v2/... links keep resolving after a future major takes the
+# root, the way /v1/... does for v1 today.
 #
 # The two lines use different toolchains: v1.x still builds with MkDocs, while
 # main builds with Zensical (which needs a pre-build step to materialise the API
 # reference and a post-build step for llms.txt — see scripts/docs/). Each branch
-# is fetched fresh from origin and built with its own synced `docs` group, so
-# the output is identical regardless of which branch triggered the workflow.
-# This script is intended to run in CI; for a local v2 preview use
-# `scripts/serve-docs.sh`.
+# is fetched fresh from origin and built with its own synced `docs` group. Only
+# main deploys the combined site (the v1.x branch carries no deploy workflow), so
+# a v1.x docs change goes live on the next main deploy or a manual
+# `workflow_dispatch` of deploy-docs.yml. This script is intended to run in CI;
+# for a local v2 preview use `scripts/serve-docs.sh`.
 #
 # Usage:
 #   scripts/build-docs.sh [output-dir]
@@ -50,6 +54,9 @@ build_site() {
     fi
 }
 
+# Fetch a branch fresh from origin, build its docs, and copy the result to
+# `dest`. The built tree stays in `worktree/site` afterwards so a caller can
+# mirror it to a second destination.
 build_branch() {
     local branch="$1" worktree="$2" dest="$3"
 
@@ -70,7 +77,12 @@ build_branch() {
 
 rm -rf "${OUTPUT_DIR:?}"/*
 
-build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR"
-build_branch main "$V2_WORKTREE" "$OUTPUT_DIR/v2"
+# v2 (main) at the root, then mirrored to /v2/ from the same build, then v1
+# under /v1/. The mirror is copied from the worktree's build directory rather
+# than from the root so it never picks up the /v1/ tree.
+build_branch main "$V2_WORKTREE" "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR/v2"
+cp -a "$V2_WORKTREE/site/." "$OUTPUT_DIR/v2/"
+build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR/v1"
 
 echo "=== Combined docs built at $OUTPUT_DIR ==="

src/mcp-types/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://modelcontextprotocol.io"
-Documentation = "https://py.sdk.modelcontextprotocol.io/v2/"
+Documentation = "https://py.sdk.modelcontextprotocol.io/"
 Repository = "https://github.com/modelcontextprotocol/python-sdk"
 Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"