docs: replace MkDocs with Zensical

Migrate the v2 docs build from MkDocs Material to Zensical, the Material
team's successor (as Starlette and uvicorn have done). Zensical natively
re-implements search, glightbox and mkdocstrings, but — unlike MkDocs — runs
no arbitrary plugins or hooks. This SDK's docs relied on three of those, so
they are reimplemented as standalone build steps around `zensical build`:

- API reference: `mkdocs-gen-files` + `mkdocs-literate-nav` become
  `scripts/docs/gen_ref_pages.py` (writes the `docs/api/` mkdocstrings stubs)
  and `scripts/docs/build_config.py` (splices the nested API nav into a
  generated `mkdocs.gen.yml`, since Zensical has no literate-nav).
- llms.txt: the former MkDocs hook becomes `scripts/docs/llms_txt.py`, a
  post-build step over the source tree, with no dependency on build internals.

`mkdocs.yml` stays the source config, with the MkDocs-only YAML tags
(`!relative`, `!ENV`, `!!python/name:`) translated to the string forms
Zensical understands and the emoji functions pointed at
`zensical.extensions.emoji`. The generators moved out of `docs/` (Zensical
publishes everything under docs_dir) into `scripts/docs/`, and
`scripts/build-docs.sh` now picks the toolchain per worktree so the combined
v1 (MkDocs) + v2 (Zensical) build stays correct. Adds `scripts/serve-docs.sh`
for local preview.

The docs dependency group drops mkdocs, mkdocs-material[imaging] and the
gen-files/glightbox/literate-nav plugins for `zensical`. mkdocstrings is
floored at 1.0.4 / mkdocstrings-python 2.0.5: Zensical's compatibility layer
targets that API, and the older line renders API pages with an
unregistered-autorefs error.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CTkPwxyKkLTnqZdeiCMCzK

Author: claude

.github/workflows/deploy-docs.yml

@@ -14,6 +14,7 @@ on:
       - src/mcp/**
       - src/mcp-types/**
       - scripts/build-docs.sh
+      - scripts/docs/**
       - pyproject.toml
       - uv.lock
       - .github/workflows/deploy-docs.yml

.github/workflows/shared.yml

@@ -139,11 +139,13 @@ jobs:
       - name: Check README snippets are up to date
         run: uv run --frozen scripts/update_readme_snippets.py --check
 
-  # `mkdocs.yml` sets `strict: true` and `pymdownx.snippets: check_paths: true`,
-  # but until this job existed the docs were only ever built post-merge by
-  # `deploy-docs.yml`, so a broken link, a missing nav target, or a deleted
-  # `docs_src/` include went green on the PR and broke the next deploy of main.
-  # This is the check path; `deploy-docs.yml` stays the deploy path.
+  # `zensical build --strict` fails on broken links / missing nav targets and
+  # `pymdownx.snippets: check_paths: true` fails on a deleted `docs_src/`
+  # include; the llms_txt step additionally re-resolves every snippet and link.
+  # Until this job existed the docs were only ever built post-merge by
+  # `deploy-docs.yml`, so those failures went green on the PR and broke the next
+  # deploy of main. This is the check path; `deploy-docs.yml` stays the deploy
+  # path.
   docs:
     runs-on: ubuntu-latest
     steps:
@@ -171,8 +173,7 @@ jobs:
       - name: Install dependencies
         run: uv sync --frozen --all-extras --python 3.10
 
+      # Zensical runs no MkDocs plugins/hooks: generate the API reference and
+      # the concrete config, build strictly, then generate llms.txt.
       - name: Build the docs in strict mode
-        run: uv run --frozen --no-sync mkdocs build --strict
-        env:
-          # Silence mkdocs-material's MkDocs 2.0 warning banner in CI logs.
-          NO_MKDOCS_2_WARNING: "1"
+        run: bash scripts/docs/build.sh

.gitignore

@@ -141,9 +141,13 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# documentation
 /site
 /.worktrees/
+# Generated at build time by docs/hooks/ (the API reference tree and the
+# concrete Zensical config spliced from mkdocs.yml).
+/docs/api/
+/mkdocs.gen.yml
 
 # mypy
 .mypy_cache/

docs/hooks/gen_ref_pages.py

@@ -1,6 +1,5 @@
 site_name: MCP Python SDK
 site_description: The official Python SDK for the Model Context Protocol
-strict: true
 
 repo_name: modelcontextprotocol/python-sdk
 repo_url: https://github.com/modelcontextprotocol/python-sdk
@@ -10,6 +9,9 @@ site_url: https://py.sdk.modelcontextprotocol.io/v2/
 # TODO(Marcelo): Add Anthropic copyright?
 # copyright: © Model Context Protocol 2025 to present
 
+# The "API Reference" entry is a placeholder: `scripts/docs/gen_ref_pages.py`
+# generates the `docs/api/` tree and `scripts/docs/build_config.py` splices the
+# real nested nav in before the build. See `scripts/build-docs.sh`.
 nav:
   - MCP Python SDK: index.md
   - "What's new in v2": whats-new.md
@@ -122,13 +124,6 @@ theme:
 extra_css:
   - extra.css
 
-# https://www.mkdocs.org/user-guide/configuration/#validation
-validation:
-  omitted_files: warn
-  absolute_links: warn
-  unrecognized_links: warn
-  anchors: warn
-
 markdown_extensions:
   - tables
   - admonition
@@ -138,29 +133,28 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.critic
   - pymdownx.mark
-  - pymdownx.superfences
   # Code examples live as complete, importable, tested files under `docs_src/`
   # and are included into pages with `--8<-- "docs_src/<chapter>/tutorialNNN.py"`
-  # (resolved against the repo root regardless of the build's working
-  # directory; the extension's default base_path is the CWD).
-  # `check_paths: true` + `strict: true` turn a renamed/deleted example into a
-  # build failure instead of a silently empty code block.
+  # (resolved against the repo root, which is the build's working directory).
+  # `check_paths: true` turns a renamed/deleted example into a build failure
+  # instead of a silently empty code block.
   - pymdownx.snippets:
-      base_path: !relative $config_dir
+      base_path: [.]
       check_paths: true
   - pymdownx.tilde
   - pymdownx.inlinehilite
   - pymdownx.highlight:
       pygments_lang_class: true
-  - pymdownx.extra:
-      pymdownx.superfences:
-        custom_fences:
-          - name: mermaid
-            class: mermaid
-            format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: pymdownx.superfences.fence_code_format
+  # Zensical re-implements the emoji extension; the generator/index functions
+  # live under `zensical.extensions.emoji`, not `material.extensions.emoji`.
   - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: zensical.extensions.emoji.twemoji
+      emoji_generator: zensical.extensions.emoji.to_svg
       options:
         custom_icons:
           - docs/.overrides/.icons
@@ -170,23 +164,13 @@ markdown_extensions:
       custom_checkbox: true
   - sane_lists # this means you can start a list from any number
 
-watch:
-  - src
-  - docs_src
-
-hooks:
-  - docs/hooks/llms_txt.py
-
+# Zensical natively re-implements `search`, `glightbox` and `mkdocstrings`; it
+# does not run arbitrary MkDocs plugins or hooks, so the former `gen-files`,
+# `literate-nav`, `social` and `llms_txt` hook are handled by the standalone
+# scripts under `scripts/docs/` invoked around the build (see build-docs.sh).
 plugins:
   - search
-  - social:
-      enabled: !ENV [ENABLE_SOCIAL_CARDS, false]
   - glightbox
-  - gen-files:
-      scripts:
-        - docs/hooks/gen_ref_pages.py
-  - literate-nav:
-      nav_file: SUMMARY.md
   - mkdocstrings:
       handlers:
         python: