docs(mcp[tools]): Search tool owns its xref anchor#90
Draft
tony wants to merge 1 commit into
Draft
Conversation
tony
force-pushed
the
fix/mcp-search-tool-xref
branch
from
b964e28 to
1745cce
Compare
tony
force-pushed
the
fix/mcp-search-tool-xref
branch
from
1745cce to
93c45df
Compare
tony
force-pushed
the
fix/mcp-search-tool-xref
branch
from
83bc0ed to
93c45df
Compare
tony
force-pushed
the
fix/mcp-search-tool-xref
branch
from
93c45df to
6e5a11c
Compare
tony
force-pushed
the
fix/mcp-search-tool-xref
branch
from
6e5a11c to
0b55537
Compare
tony
force-pushed
the
fix/mcp-search-tool-xref
branch
from
0b55537 to
2c3f0f1
Compare
why: The search tool card was the only one of twelve marked
:no-index:, yet it is the tool's single canonical invocation.
:no-index: suppressed registration of the fastmcp-tool-search
cross-reference label, so {tooliconl}`search` (and the other tool
roles) silently linked to Sphinx's reserved `search` "Search Page"
instead of the MCP search tool reference — with no build error.
what:
- Drop :no-index: from the search {fastmcp-tool} card so it
registers its canonical fastmcp-tool-search anchor.
Full resolution also needs the canonical-first tool-role fix in
sphinx-autodoc-fastmcp (gp-sphinx#60); until that ships in a32 and
the pin is bumped, the bare slug still resolves to the built-in.
tony
force-pushed
the
fix/mcp-search-tool-xref
branch
from
2c3f0f1 to
dd1f18b
Compare
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
1 participant
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.
Summary
On the changelog page (
/history/), the{tooliconl}search`` badge in the 0.1.0a22 entry linked to the documentation's own site-search page (/search/) instead of the MCP `search` tool reference — while the sibling `find` and `inspect_result` badges linked correctly to `/mcp/tools/#fastmcp-tool-*`. The build reported no error.Two causes compounded:
search{fastmcp-tool}card indocs/mcp/tools.mdwas the only one of twelve marked:no-index:, even though it is the tool's single canonical invocation.:no-index:skips registering thefastmcp-tool-searchcross-reference label, so the tool had no reference home.searchis a Sphinx-reserved standard label (the JS "Search Page"), seeded intoStandardDomainbefore any document is read. The tool's bare-slug alias can never claim it, so{tool}-family roles resolving by bare slug fell through to the built-in.This PR fixes cause 1: dropping
:no-index:registers the canonicalfastmcp-tool-searchanchor.Dependency (why this is a draft)
Cause 2 is fixed upstream in
sphinx-autodoc-fastmcpby resolving the canonicalfastmcp-tool-<slug>id first: git-pull/gp-sphinx#60. Until that ships in0.0.1a32and this repo bumps its pin (sphinx-autodoc-fastmcp>=0.0.1a32,gp-sphinx>=0.0.1a32), the bare slug still resolves to the built-in. The pin bump +uv.lock+ full completion gate will be added to this PR once a32 is released, at which point it leaves draft.Verification
Built locally against the patched extension (gp-sphinx#60 editable): every
{tooliconl}search`` on/history/then resolves to `../mcp/tools/#fastmcp-tool-search`, matching `find` and `inspect_result`; the old `href="../search/"` tool badge is gone.Test plan
git diff --checkclean;just build-docssucceeds;fastmcp-tool-searchis now a registeredstd:label(/mcp/tools/#fastmcp-tool-search).