[v1.x] Move the v1.x docs to /v1/ and mark v1.x as the maintenance line

[maxisbey]

With v2 becoming the stable release, the v1.x docs move from the site root to /v1/, and this branch stops deploying the docs site itself: the combined site is built and deployed from main (companion PR #3176), which builds this branch's docs into /v1/.

Motivation and Context

After the v2 stable release, the site root serves the current major and each major keeps a permanent path (/v1/, /v2/, ...). Two things follow for this branch: its docs need to describe themselves as living under /v1/, and it must not keep deploying the old layout over the top of main's.

Changes:

• .github/workflows/deploy-docs.yml is removed; the docs build recipe moves to scripts/docs/build.sh, which is run both by main's combined deploy (for the /v1/ tree) and by a new docs job in this branch's CI. What CI checks is therefore exactly what gets published, and a change that breaks the v1 docs fails on this branch rather than at main's next deploy.
• mkdocs.yml site_url and the package Documentation URL move to /v1/, so canonical links, the sitemap, and llms.txt point at where these pages are actually served.
• The README and landing page now describe v1.x as the maintenance line and send new users to the v2 docs; every install line pins mcp<2, so a reader following these docs stays on the 1.x line now that an unpinned install selects 2.x.

Merge order for release day: after #3176 merges, then a manual Deploy Docs dispatch on main so /v1/ rebuilds with this branch's new site_url and banners.

How Has This Been Tested?

The build recipe was exercised locally through its dependency sync; the new docs CI job on this PR runs the same script, so this PR's own CI is the validation of the build.

Breaking Changes

None for SDK users. v1 doc URLs move from the root to /v1/...; existing external deep links to the old root paths will 404 (accepted as part of the layout change). Note that once merged, a docs edit on this branch is published by main's next deploy or a manual dispatch rather than by its own workflow.

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

AI disclosure

AI assistance was used to implement and validate this change; I reviewed the result and take responsibility for it.

_{AI Disclaimer}

[github-actions]

📚 Documentation preview

Preview	https://pr-3177.mcp-python-docs.pages.dev
Deployment	https://ea40ba5a.mcp-python-docs.pages.dev
Commit	d6a15f6
Triggered by	@maxisbey
Updated	2026-07-26 10:33:38 UTC

[cubic-dev-ai]

No issues found across 9 files

_{Re-trigger cubic}

[claude]

LGTM — docs-only change: URL/banner updates, install-pin edits, and a deploy-workflow → CI-build-check swap, with no SDK code touched.

What was reviewed:

• Checked for stale references to the deleted scripts/build-docs.sh and old modelcontextprotocol.github.io URLs — none remain (the one mention of the old script is a comment pointing at main's copy, which is intentional).
• Verified scripts/docs/build.sh resolves the repo root correctly and that the docs dependency group it syncs exists in pyproject.toml.
• Checked the new docs CI job: it inherits shared.yml's contents: read permission and matches the sibling jobs' action versions; removing deploy-docs.yml also removes this branch's pages: write/id-token: write grants.
• Confirmed the mcp<2 pins and /v1/ links in README/docs are consistent with the new site_url.

Extended reasoning...

Overview

This PR is part of the v2-stable docs re-layout on the v1.x branch. It (1) removes this branch's docs deploy workflow (deploy-docs.yml) so the combined site is built and deployed only from main, (2) moves the branch's build recipe into scripts/docs/build.sh (which main's combined build invokes for the /v1/ tree) and adds a docs CI job to shared.yml that runs the same script, (3) updates site_url and the package Documentation URL to /v1/, and (4) rewrites the README/landing-page banners to describe v1.x as the maintenance line, pinning every install example to mcp<2. No SDK source code, tests, or runtime behavior is touched.

Security risks

None identified. The only workflow change is additive in a low-privilege direction: the deleted deploy workflow carried pages: write and id-token: write, while the new docs job runs under shared.yml's top-level contents: read and uses the same tag-pinned actions (actions/checkout@v5, astral-sh/setup-uv@v7) as the existing jobs in that file. The build script is a straightforward uv sync --frozen + mkdocs build with no untrusted inputs.

Level of scrutiny

Low-to-moderate. This is documentation and docs-CI plumbing, not production code paths. The main things worth checking were mechanical consistency issues, which I verified directly: no dangling references to the removed scripts/build-docs.sh, no leftover modelcontextprotocol.github.io URLs, the docs dependency group referenced by the build script exists in pyproject.toml, and the script's cd correctly lands at the repo root. The bug hunting system also found no issues.

Other factors

The one non-mechanical aspect is the cross-branch deploy dependency: after this merges, v1 docs publish only via main's deploy (companion PR) or a manual dispatch. That coordination and its merge ordering are explicitly documented in the PR description, so it is a known, intentional trade-off rather than something a reviewer needs to catch. The new docs CI job on this PR itself exercises the build script, so the PR's own CI validates the recipe. Broken external deep links to old root paths are acknowledged in the description as accepted.