Repository navigation
List indexed versions from REPOS instead of hardcoding them - #16
Open
thefactremains wants to merge 2 commits into
Open
thefactremains wants to merge 2 commits into
thefactremains wants to merge 2 commits into
Conversation
The search_percona_docs and get_percona_doc descriptions and the MCP server instructions said PS, PXC, PXB and PDMySQL were indexed on 8.0 and 8.4 only, and listed PXB 9.x as not indexed. The live index also holds 9.7 for all four, so agents skipped DK for 9.7 questions. - shared.py: configured_versions() reads the versions per repo from REPOS (owner/repo:branch entries); parse_repos moves here from ingest. - mcp_server.py: the instructions and both tool descriptions are built from that list at startup. - server.py: GET /versions returns the same list. - mcp_remote_shim.py: at startup the shim loads the list from GET /versions and re-registers its tools; if the backend is unreachable the descriptions say the versions are unknown. - get_percona_doc: the Repos list was an indented block that FastMCP parsed as a docstring section and dropped from the tool description. It is now a flat list, so agents see it. - tests: fail if any configured repo and version is missing from the server's instructions or either tool description, or from the shim's. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
"Percona Server for MySQL 9.7 release notes" ranked 5.7 forum
announcements above the 9.7 release notes, because the version was only
in the query text and forum chunks carry no version tag.
When `version` isn't passed and the query names exactly one indexed
version (9.7, 8.0.35 -> 8.0, ...), search_chunks() also queries chunks
tagged with that version and ranks them up by 0.03 relevance. Queries
naming two versions ("8.0 to 8.4") aren't boosted, and an explicit
`version` still scopes strictly. Displayed scores stay unboosted. Used by
the MCP tool, POST /search and GET /search.
0.03 was tuned on the live index: 0.05 pushed loosely related 8.0 pages
above strong forum hits for "innodb_redo_log_capacity 8.0".
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
Why
The
search_percona_docsandget_percona_docdescriptions and the MCP server instructions said PS, PXC, PXB and PDMySQL were indexed on 8.0 and 8.4 only, and listed "PXB 9.x" as not indexed. Sherpa'sREPOSand its Chroma collection both also hold 9.7 for psmysql-docs, pxc-docs, pxb-docs and pdmysql-docs. Agents read the description and skipped DK for 9.7 questions.Live index on Sherpa (distinct
source_repo,version):Every other repo, the blog and the forums are unversioned. This matches
REPOSexactly.What changed
shared.py:configured_versions()reads the versions for each repo fromREPOS(owner/repo:branchentries).describe_versions()formats them.parse_reposmoves here fromingest.py.mcp_server.py: the VERSIONS paragraph in the instructions and the version lists in both tool descriptions are built fromREPOSat startup. The "NOT indexed" list is replaced by "Versions not listed above are not indexed."server.py: newGET /versionsreturns the same list.mcp_remote_shim.py: the shim has no ingest config, so at startup it callsGET /versionsand re-registers its two tools with the list. FastMCP copies theArgstext into the parameter schema, so editing only the description would miss that copy. If the backend is unreachable, the descriptions say the versions are unknown.get_percona_docfix: theRepos:list was an indented block, which FastMCP parsed as a docstring section and dropped from the served description. Agents never saw it. It is now a flat list and shows up.REPOS, andGET /versions.With Sherpa's
REPOS, the server now serves:Version boost for queries that name a version
"Percona Server for MySQL 9.7 release notes" ranked 5.7 forum announcements above the 9.7 release notes. The version was only in the query text, and forum chunks have no version tag. Now, when
versionisn't passed and the query names exactly one indexed version (9.7, or8.0.35read as8.0),search_chunks()also queries chunks tagged with that version and ranks them up by 0.03 relevance. Queries that name two versions ("upgrade 8.0 to 8.4") get no boost. An explicitversionstill scopes strictly. Displayed scores are the real, unboosted ones, so a boosted result can show a slightly lower score than one below it. The boost applies to the MCP tool,POST /searchandGET /search.Top 5 on Sherpa's live index:
clone-sst.mdinnodb-show-statusThe last row is the cost: the redo-log blog drops out for tangential 8.0 pages. At 0.05 the same query also put an 8.0 page above the strong forum hits, so I chose 0.03. "PSMDB 7.0 release notes" is unchanged because no 7.0 chunk scores close enough. Bare major versions such as "PostgreSQL 17" aren't detected, only
major.minor.Tests
tests/test_indexed_versions.pyfails if any configured repo and version is missing from:REPOSthat includes an unknown repo, and again with this checkout's own config/versionsThe shim parity test now loads versions first, as
main()does. Boost tests:query_versiondetection, merge order, a much better match still wins, and no extra query whenversionis passed or two versions are named.pytest: 96 passed.Deploy notes
.envREPOS, which already lists 9.7. The boost lives server-side, so shim users get it as soon as the backend is redeployed.uvxrun orpip install, then restart their client. The backend needs this PR deployed first. Until then the shim's descriptions say the versions are unknown, which is still better than the old wrong list.GET /versionsis a new public path. It should go on the proxy allowlist in Container image, compose file and deploy runbook for the IT-hosted instance #14'sDEPLOY.md. Container image, compose file and deploy runbook for the IT-hosted instance #14 and Rebuild the index without a daily outage #15 also touchmcp_server.py,server.pyand README, so expect small conflicts whichever merges second.🤖 Generated with Claude Code