ci: deploy docs to py.sdk.modelcontextprotocol.io via Pages artifact (v1 at /, v2 at /v2/)

[maxisbey]

Deploys docs to py.sdk.modelcontextprotocol.io via GitHub Pages artifact deployment, building both v1.x and main into a single site (v1 at /, v2 at /v2/). This mirrors the approach used by typescript-sdk.

Closes #2614. Supersedes #2615 and #2632.

Motivation and Context

https://py.sdk.modelcontextprotocol.io/ currently returns 404. DNS is correctly configured (the CNAME and verification TXT records exist in modelcontextprotocol/dns), but this repo's Pages config has never claimed the domain (cname: null, no CNAME file on gh-pages), so GitHub serves the org-level 404.

Separately, the current mkdocs gh-deploy --force setup runs identically on both main and v1.x and force-pushes to the same gh-pages branch — whichever branch released last overwrites the other's docs entirely. The first v2 release would silently replace the stable v1 docs.

This PR fixes both: artifact-based deploy with the custom domain set in Pages settings (no CNAME file to lose), and a build script that always assembles both branches' docs into one site.

How Has This Been Tested?

Ran scripts/build-docs.sh locally; confirmed v1.x content lands at / and main content at /v2/, both mkdocs build invocations succeed under strict: true, and worktrees are cleaned up. The workflow itself can only be fully validated after merge + the Pages settings change (see below).

Breaking Changes

None for users. The modelcontextprotocol.github.io/python-sdk/ URL will auto-redirect to the custom domain once it's set.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Maintainer actions required

1. Merge this PR and the v1.x backport [v1.x] ci: deploy docs to py.sdk.modelcontextprotocol.io via Pages artifact #2635. Both Deploy Docs runs will fail at configure-pages because the Pages source is still "Deploy from a branch" — expected; the existing gh-pages content keeps serving in the meantime.
2. Settings → Pages → Build and deployment → Source: change to GitHub Actions.
3. Settings → Pages → Custom domain: py.sdk.modelcontextprotocol.io → Save. DNS check should pass immediately (records already exist). Tick "Enforce HTTPS" once the cert provisions.
4. Actions tab → Deploy Docs → Run workflow (either branch). First successful deploy publishes v1 at / and v2 at /v2/ with correct canonical URLs.
5. Once confirmed working, delete the gh-pages branch and close Fix Issue #2614 - changed the publishing url for Python docs #2615.

Merging both PRs before the settings flip means the first successful deploy reads the updated site_url from both branches; doing the flip first would work too but risks a brief 404 on the existing github.io/python-sdk/ URL.

Design notes

• /v2/ (not /dev/) so the path survives the v2.0 GA — when v2 ships, only the root redirect changes.
• cancel-in-progress: false so an in-flight Pages deploy isn't cancelled by a closely-following push.
• paths: filter on the push trigger to avoid redeploying on unrelated changes; src/mcp/** is included because mkdocstrings introspects it for the API reference.
• The workflow file must exist on both main and v1.x for the push trigger to fire on each, but build-docs.sh always builds from origin/v1.x + origin/main tips, so output is identical regardless of which branch triggered.

_{AI Disclaimer}

[claude]

Didn't spot any bugs in the workflow or build script, but this rewires the docs deployment pipeline (removing existing workflows, adding a new Pages artifact deploy, and requiring out-of-band Pages settings changes), so a maintainer should review and coordinate the manual steps.

Extended reasoning...

Overview

This PR replaces the mkdocs gh-deploy-based docs publishing (removing publish-docs-manually.yml and the docs-publish job in publish-pypi.yml) with a new deploy-docs.yml workflow that uses the GitHub Pages artifact deployment flow. It adds scripts/build-docs.sh, which uses git worktrees to build docs from both origin/v1.x (at /) and origin/main (at /v2/) into a single site directory. It also updates site_url in mkdocs.yml, adds a Documentation URL to pyproject.toml, adds a v2 admonition banner to docs/index.md, and ignores .worktrees/.

Security risks

The new workflow uses appropriately-scoped permissions (contents: read, pages: write, id-token: write) and pinned action SHAs, which is good. scripts/build-docs.sh runs uv sync and mkdocs build from a checkout of origin/v1.x inside a job triggered by a push to main (and vice versa) — this means code merged to one protected branch is executed in the workflow context of the other. Both are protected branches, so the risk is low, but it's a cross-branch trust boundary worth a maintainer being aware of. No injection or untrusted-input handling.

Level of scrutiny

This is a CI/CD pipeline change for a production-facing docs site. It removes existing publish workflows and depends on out-of-band repository settings changes (Pages source → GitHub Actions, custom domain) that must be made by a maintainer in the right order. CI/CD infrastructure changes generally warrant human sign-off, and the dependency on manual repo-settings steps means a bot approval would not be actionable on its own.

Other factors

The shell script is well-written: set -euo pipefail, a cleanup trap, defensive quoting (${OUTPUT_DIR:?}), and detached worktrees. The PR description is thorough and lists the required maintainer actions and a follow-up backport to v1.x. No automated bugs were flagged. The main design decision (always building both branches from origin tips so the output is order-independent) is sound, but it's the kind of choice a maintainer should explicitly endorse.