Adding MCP endpoint for finding ref guide URLs

[jzonthemtn]

Creating a PR because it's easier to understand to see the code.

Closes #85

[jzonthemtn]

Converting back to draft for a bit.

[adityamparikh]

Hi! A new PR-validation CI workflow recently landed on main (#117). To get this PR's tests evaluated against the new pipeline, could you rebase your branch onto current main and push? That will trigger the new ci.yml (build / unit / integration). Thanks!

[adityamparikh]

Heads-up: this branch currently shows as conflicting against main, but the conflict surface is much smaller than the 53-commit gap suggests. I rebased it locally onto main (a57f4d9) to check, and it comes out clean — sharing what I found in case it saves you time.

The two conflicts, and how they resolve:

1. config/SolrConfig.java — import-block collision only. main added org.springframework.util.StringUtils; this branch added org.springframework.web.client.RestClient. Keep both.
2. McpToolRegistrationTest.java — SchemaService moved from org.apache.solr.mcp.server.metadata to org.apache.solr.mcp.server.schema on main. Switch the import to the new package and keep the refguide.RefGuideService one.

That's the whole manual resolution — two import lines.

The metadata → schema package split doesn't bite. It was a pure rename in git history and this branch never touched those files, so git replays it automatically. No duplicate SchemaService, no stale metadata/ package left behind.

Result after rebase: +293 / -0 across the 4 files, and ./gradlew build is green — 359 tests, 0 failures, 0 errors (RefGuideServiceTest 6/6). RefGuideService is self-contained enough (Spring + MCP annotations + RestClient) that none of the upstream churn reached it.

One thing that will block the native path: RefGuideServiceTest is Mockito-based (@ExtendWith(MockitoExtension.class)), but doesn't carry @DisabledInNativeImage. Every other Mockito test in the repo does, because ByteBuddy proxies don't survive GraalVM's closed-world assumption — so ./gradlew nativeTest -Pnative will fail on it. One-line fix:

import org.junit.jupiter.api.condition.DisabledInNativeImage;

@DisabledInNativeImage
@ExtendWith(MockitoExtension.class)
class RefGuideServiceTest {

Two smaller review notes, take or leave:

• The RestClient @Bean is added to SolrConfig, which is otherwise scoped to SolrJ client wiring. It works, but it might sit more naturally in the refguide package's own config.
• getRefGuideUrl fetches https://solr.apache.org/guide/sitemap.xml on every invocation, with no caching and no explicit timeout. Might be worth a cache and a connect/read timeout given it's a remote call on a hot path.

Happy to send the rebased commits as a patch if that's useful — they preserve your authorship and sign-off.

[adityamparikh]

Updating my earlier comment — it's gone stale, and I'd rather not have you work from it.

Back then I said this branch rebased onto main cleanly with only an import-block collision in SolrConfig.java. That is no longer true as of a84033b. Re-running the rebase now gives two conflicts, one of which is structural:

1. McpToolRegistrationTest.java — this branch imports org.apache.solr.mcp.server.metadata.SchemaService. That package no longer exists; it was split into collection/ and schema/, so the import is now org.apache.solr.mcp.server.schema.SchemaService. RefGuideService slots in alongside it fine.

2. SolrConfig.java — no longer just imports. buildSolrClient was rewritten in fix: correct indexing, collection-name and service defects #176 to normalise the Solr path via URI (parsing the URL's path rather than searching the whole string, so a host literally named solr stops matching the /solr/ in its own authority). Your RestClient @Bean and that rewrite land in the same region, so it needs a real resolution rather than taking one side — keep the new URI-based buildSolrClient and add the RestClient bean next to it.

No rush given this is a draft — flagging it mainly so the "it's just imports" read doesn't cost you time when you pick it back up. Happy to push a rebased branch to your fork if that's easier; just say so.

[adityamparikh]

Hi @jzonthemtn — this branch has drifted a fair way from main (68 commits since the
merge base, 6009213) and now conflicts, so GitHub won't let it merge. Would you mind
rebasing onto current main?

There are two conflicting files, and both are semantic rather than just textual — worth
flagging so the rebase isn't surprising:

1. src/test/java/org/apache/solr/mcp/server/McpToolRegistrationTest.java — package
rename. SchemaService moved on main:

// this branch
import org.apache.solr.mcp.server.metadata.SchemaService;
// main
import org.apache.solr.mcp.server.schema.SchemaService;

CollectionService moved metadata/ -> collection/ in the same reorganisation, so
it's worth grepping the branch for any other .metadata. imports while you're in there.

2. src/main/java/org/apache/solr/mcp/server/config/SolrConfig.java — this one needs
a real decision. main has since refactored the solrClient bean into a static
buildSolrClient(...) helper that normalises the Solr URL against its path (so a
/solr/ inside an authority like http://solr/ isn't mistaken for the path already
being present). This PR adds a RestClient bean and its own solrClient bean over the
older shape. The two want the same region of the file, so the RestClient addition needs
re-applying on top of main's normalising version rather than replacing it.

Happy to help if it turns out more tangled than that. For what it's worth, I couldn't
check whether the branch builds green because the conflicts block the merge entirely —
once it's rebased that'll be answerable.

[adityamparikh]

Design review of the current head, since the branch has drifted (81 commits behind, two conflicts: the SolrConfig import block and McpToolRegistrationTest's metadata.SchemaService import, which moved to schema).

Blocking:

• RefGuideService.java:66 fetches https://solr.apache.org/guide/sitemap.xml on every tool call and regex-scans it. That sitemap covers every version, so each query is a multi-megabyte download with no cache and no timeouts on the RestClient. Cache the parsed <loc> list with a TTL and set connect/read timeouts.
• RefGuideService.java:74 calls query.toLowerCase(); the MCP SDK on main does not validate required inputs, so an omitted query is an NPE. Blank-guard it the way AliasService does.
• RefGuideServiceTest uses MockitoExtension with deep stubs and no @DisabledInNativeImage, so ./gradlew nativeTest -Pnative will fail on it.

Non-blocking: the tool name searchRefGuide is camelCase where every other tool is kebab-case; it has no readOnlyHint and no @Observed; the pre-9 branch returns a hard-coded archive PDF URL without checking it exists (5.0 yields a 404); and the bare RestClient bean sits in SolrConfig rather than its own configuration with timeouts.

@jzonthemtn, do you still plan to finish this? If not, I would close the draft and keep #85 open for a cached-sitemap version.