René's URL Explorer Experiment

Title: Expand site-absolute spec links in generated docstrings to full URLs by maxisbey · Pull Request #2885 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Expand site-absolute spec links in generated docstrings to full URLs by maxisbey · Pull Request #2885 · modelcontextprotocol/python-sdk

X Title: Expand site-absolute spec links in generated docstrings to full URLs by maxisbey · Pull Request #2885 · modelcontextprotocol/python-sdk

Description: The Deploy Docs workflow on main is failing since #2849: the strict mkdocs build aborts with 54 warnings, all of them mkdocs flagging the site-absolute link (/specification/2025-11-25/basic/index#meta) in the generated api/mcp/types/v2025_11_25 API reference page (failing run). Motivation and Context The vendored schema descriptions link to spec pages with site-absolute paths (they're written for modelcontextprotocol.io). gen_surface_types.py copies them verbatim into the per-version package docstrings, so the rendered API reference ends up with links that don't resolve from the SDK docs site, and validation.absolute_links: warn + strict: true in mkdocs.yml turns each occurrence into a build failure. The docs site can't deploy until this is fixed. This PR adds one post-processing step to the generator that expands site-absolute markdown link targets to full https://modelcontextprotocol.io/... URLs, and regenerates the 2025-11-25 package (54 docstring lines change, nothing else). The 2026-07-28 package has no such links and is byte-identical after regeneration. The rewrite matches any site-absolute link target rather than just /specification/, so a future schema vendoring that links to other spec-site pages won't reintroduce the failure. How Has This Been Tested? uv run --frozen --group codegen python scripts/gen_surface_types.py --check passes (no drift between the generator and the committed packages). uv run --frozen --group docs mkdocs build (strict mode) now exits 0 with zero absolute-link warnings; before the change it aborted with 54. The built api/mcp/types/v2025_11_25/index.html contains 54 href="https://modelcontextprotocol.io/specification/2025-11-25/basic/index#meta" links and no site-absolute ones. The "MkDocs 2.0 is incompatible with Material for MkDocs" notice in the build log is unrelated: it's informational output from mkdocs-material 9.7.x (mkdocs is locked at 1.6.1) and doesn't trip strict mode. Breaking Changes None — only docstrings in a generated internal module and the generator script change. 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 A separate question this PR doesn't take a position on: whether the internal, versioned wire-shape packages (mcp.types.v2025_11_25, mcp.types.v2026_07_28) should appear in the rendered API reference at all — docs/hooks/gen_ref_pages.py currently publishes every package under src/. Even if they're later excluded, the full URLs are still the right thing for IDE tooltips and help() output. AI Disclaimer

Open Graph Description: The Deploy Docs workflow on main is failing since #2849: the strict mkdocs build aborts with 54 warnings, all of them mkdocs flagging the site-absolute link (/specification/2025-11-25/basic/index#m...

X Description: The Deploy Docs workflow on main is failing since #2849: the strict mkdocs build aborts with 54 warnings, all of them mkdocs flagging the site-absolute link (/specification/2025-11-25/basic/index#m...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/2885

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width