Expand site-absolute spec links in generated docstrings to full URLs - #2885
Merged
maxisbey merged 1 commit intoJun 16, 2026
Merged
Expand site-absolute spec links in generated docstrings to full URLs#2885maxisbey merged 1 commit into
maxisbey merged 1 commit into
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
The vendored schema descriptions link to spec pages with site-absolute paths like (/specification/2025-11-25/basic/index#meta). Copied verbatim into the generated per-version docstrings, those links don't resolve from the rendered API reference, and mkdocs' link validation flags each one as a warning, so the strict docs build on main aborts (54 warnings, all from api/mcp/types/v2025_11_25/). Rewrite site-absolute markdown link targets to full https://modelcontextprotocol.io/... URLs in the generator's post-processing and regenerate the 2025-11-25 package. The 2026-07-28 package has no such links and is unchanged.
maxisbey
marked this pull request as ready for review
June 16, 2026 19:39
maxisbey
enabled auto-merge (squash)
June 16, 2026 20:39
localden
approved these changes
Jun 16, 2026
Copy link
Copy Markdown
Contributor
|
This pull request is included in pre-release v2.0.0a2 |
Sorry, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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?
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
Checklist
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