[BLOCKED on #160 + apache/solr-mcp#143] Restructure MCP site with full documentation content by adityamparikh · Pull Request #175 · apache/solr-site

adityamparikh · 2026-04-24T18:40:19Z

Depends on apache/solr-mcp#143 — per @janhoy's review, the MCP doc content (Markdown + DOAP) now lives in apache/solr-mcp under docs/site/content/. This PR keeps the Pelican theme/templates here and fetches that content at build time (build.sh + the Pelican CI workflows), removing the now-sourced content. Merge #143 first; until then the PR-build will not find the MCP content on apache/solr-mcp main.

Summary

Rewrites the MCP subproject website from a thin link-hub into a full documentation site with actual usage content, following the SonarQube MCP Server docs pattern.

New pages

Quick Start — step-by-step from zero to working AI + Solr integration in 2 minutes
Per-client setup pages (one page each, SonarQube pattern):
- Claude Desktop, Claude Code, VS Code / GitHub Copilot, Cursor, JetBrains IDEs, MCP Inspector
- Each with STDIO and HTTP mode configs, secured HTTP (OAuth2) notes
Security — OAuth2 setup with Auth0 and Keycloak (full walkthroughs)
Observability — LGTM stack setup, Grafana exploration (Tempo, Loki, Prometheus), actuator endpoints
Resources — organized documentation links and references

Updated pages

Features — replaced generic card layout with tool reference tables, MCP resources table, env vars reference, and platform cards
Index — added Quick Start and AI Clients to the Next Steps section (4-column grid)
Header — added Quick Start, Clients, Resources nav items
Footer — reorganized into Features, Get Started, Resources, Community columns

Fixes

DOAP: programming-language Go → Java, category go → java
pelicanconf.py: version v0.0.0 → v1.0.0

Depends on #160 (should be merged after that PR). Supersedes #174.

Companion to apache/solr-mcp#95 (README/CONTRIBUTING restructure).

Test plan

./bin/solr-site build passes without errors (after merging SOLR-17992 First version of MCP web site #160)
All new pages render correctly
Navigation links work across all pages
Client sub-navigation bar links all 6 client pages
Code blocks in client/security/observability pages render correctly
Footer links resolve to correct pages

🤖 Generated with Claude Code

janhoy · 2026-06-09T21:07:52Z

Ideally I'd like the mcp docs to live in the same repo as code, but be deployed to solr site. Benefit is that each PR will also carry documentation updates for the feature.

How we do that for solr ref guide is that the ready built static site is copied to a location which is mounted into the web server for solr using .htaccess. Not sure how to achieve that here.

The MCP documentation content now lives in apache/solr-mcp (docs/site/content) so that docs travel with the code. This repo keeps the presentation layer (Pelican templates, theme, CSS, pelicanconf) and assembles the content at build time, so the MCP pages keep the shared Solr site theme and their published URLs are unchanged. - build.sh: add fetch_mcp_docs (uses a sibling ../solr-mcp checkout when present for live preview, otherwise clones the pinned MCP_DOCS_REF) before Pelican runs. - build-pelican.yml / pr-build-pelican.yml: add a "Fetch MCP docs" step after checkout. MCP_DOCS_REF is a fixed branch (never untrusted event input). - build-pelican.yml: add a daily schedule + repository_dispatch(mcp-docs-updated) so asf-staging refreshes when solr-mcp docs change (push here won't fire). - Remove the now-sourced content/pages/mcp/** and content/doap/solr-mcp.rdf and gitignore them so there is a single source of truth. Restructures apache#175 per review: keep theme here, content in solr-mcp. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Rewrite the MCP subproject website to contain actual usage content instead of just linking to GitHub, following the SonarQube MCP Server docs pattern. New pages: - Quick Start: step-by-step from zero to working integration - Per-client setup pages (one page each): Claude Desktop, Claude Code, VS Code/Copilot, Cursor, JetBrains, MCP Inspector Each with STDIO and HTTP mode configs. - Security: OAuth2 setup with Auth0 and Keycloak - Observability: LGTM stack traces, metrics, and logs - Resources: documentation links and references Updated pages: - Features: replaced generic cards with tool reference tables, MCP resources table, environment variables reference - Index: added Quick Start and Clients to Next Steps section - Header: added Quick Start, Clients, Resources nav items - Footer: reorganized into Features, Get Started, Resources, Community columns with links to all new pages Fixes: - DOAP: programming-language Go -> Java, category go -> java - pelicanconf: version v0.0.0 -> v1.0.0 Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Reorder all client configs to show JAR setup first (ATR release path) and local Docker images second. Remove all ghcr.io references — use solr-mcp:latest built locally via ./gradlew jibDockerBuild. Applies to: quick-start, all 6 client pages, security page. Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

- quick-start: #start-solr -> #start-solr-with-sample-data, etc. - security: #how-oauth2-works -> #how-oauth2-works-with-mcp-clients - observability: #actuator -> #actuator-endpoints, #production -> #production-configuration - community: remove #powered-by (no matching heading) Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Update GitHub links from dev-docs/ and security-docs/ to the new docs/development/ paths in resources and security pages. Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

- _head.html: fix stray space in license URL (LICENSE- 2.0 -> LICENSE-2.0) - downloads.html: remove incorrect "incubating" language, link to README - mcp-inspector.md: reorder STDIO before HTTP for consistency Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Document the GraalVM native image build path on the MCP quick-start page. Spring Boot's bootBuildImage produces an opt-in native image for the STDIO profile that starts in milliseconds and uses substantially less memory than the JVM Jib image. Note that the native image is AOT-locked to the STDIO profile (Spring Boot bakes a profile-specific bean graph at build time, so a single native image cannot serve both transports). HTTP deployments use the JVM Jib image; native HTTP support is a future enhancement. Signed-off-by: Aditya Parikh <aditya.m.parikh@gmail.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

apache/solr-mcp now ships two native image variants instead of just one: solr-mcp:<v>-native-stdio (built via `bootBuildImage -Pnative`) and solr-mcp:<v>-native-http (`bootBuildImage -Pnative -Pprofile=http`). Each is AOT-pinned to a single transport because Spring AOT bakes the web-application-type into the binary. The previous text said HTTP transport was JVM-only and called native HTTP support a future enhancement. Both claims are now stale — verified end-to-end via DockerImageMcpClientStdioIntegrationTest in apache/solr-mcp. Updates: - Mention both stdio and http native variants - Show `-Pnative -Pprofile=stdio|http` build commands - Update tag suffix from `-native` to `-native-stdio` / `-native-http` - Reframe the trade-off: single Jib JVM image is dual-transport, native variants are single-transport per AOT pin Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

- Bump hero subhead from "9 tools and 2 resources" to "11 tools, 6 prompts, and 2 resources" to reflect the expanded surface. - Schema table: add add-fields and add-field-types rows (additive schema modification via Solr Schema API). - Add a paragraph below the Tool Reference noting MCP behavior hints (readOnlyHint / destructiveHint / idempotentHint) so client integrators know to read them. - Clarify that solr://{collection}/schema autocompletion is prefix-filtered, case-insensitive, and capped at 100 suggestions. - New "MCP Prompts" section listing the six workflow templates: explore-collections, setup-collection, view-schema, design-schema, index-data, search-collection. Companion to apache/solr-mcp PRs apache#131, apache#134, and the upcoming prompts and completion PRs landing at apache/solr-mcp. Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

The previous `claude mcp add -e SOLR_URL=... solr-mcp -- java -jar ...` form fails at parse time: Commander's variadic `--env <env...>` reads the next positional (`solr-mcp`) as another KEY=VALUE entry and the CLI rejects it ("Invalid environment variable format: solr-mcp"). Reorder so `--transport stdio` sits between `-e` and the server name, matching the convention in https://code.claude.com/docs/en/mcp, and add a "CLI Syntax" section documenting the general `claude mcp add [options] <name> -- <command> [args...]` form plus the `-e` placement constraint. Signed-off-by: Aditya Parikh <aditya.m.parikh@gmail.com>

Switch all `claude mcp add` examples (JAR stdio, Docker stdio, HTTP) to `claude mcp add [options] -- <name> <command> [args...]`. Placing `--` before <name> is the simplest form that works regardless of whether a variadic flag like `-e KEY=value` is present, since `--` halts option parsing before the variadic can greedily consume the name. Updates the CLI Syntax section accordingly and explains why `--` goes before <name> rather than between <name> and <command>. Verified against the live `claude` CLI: name/command/args are parsed correctly for all three transports with this form. Signed-off-by: Aditya Parikh <aditya.m.parikh@gmail.com>

The MCP documentation content now lives in apache/solr-mcp (docs/site/content) so that docs travel with the code. This repo keeps the presentation layer (Pelican templates, theme, CSS, pelicanconf) and assembles the content at build time, so the MCP pages keep the shared Solr site theme and their published URLs are unchanged. - build.sh: add fetch_mcp_docs (uses a sibling ../solr-mcp checkout when present for live preview, otherwise clones the pinned MCP_DOCS_REF) before Pelican runs. - build-pelican.yml / pr-build-pelican.yml: add a "Fetch MCP docs" step after checkout. MCP_DOCS_REF is a fixed branch (never untrusted event input). - build-pelican.yml: add a daily schedule + repository_dispatch(mcp-docs-updated) so asf-staging refreshes when solr-mcp docs change (push here won't fire). - Remove the now-sourced content/pages/mcp/** and content/doap/solr-mcp.rdf and gitignore them so there is a single source of truth. Restructures apache#175 per review: keep theme here, content in solr-mcp. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

adityamparikh · 2026-06-11T15:07:13Z

Marking this as blocked / draft:

Blocked on SOLR-17992 First version of MCP web site #160 (the foundational MCP subproject site) — this PR builds on it; it can't render until SOLR-17992 First version of MCP web site #160 lands on main.
Blocked on docs(site): host MCP documentation content in-repo, deployed to solr-site at build time solr-mcp#143 — per @janhoy's request, the MCP doc content now lives in apache/solr-mcp under docs/site/content/ and is fetched at build time. Add CVE-2024-6763 to our vex file #143 must merge first so there's content to fetch.

Just rebased onto current apache/solr-site main to clear the merge conflicts. Will move back to ready-for-review once #160 and apache/solr-mcp#143 are merged.

Sequencing: #160 → apache/solr-mcp#143 → this PR.

Presentation side for the new MCP docs page whose content lives in apache/solr-mcp (docs/site/content/pages/mcp/licensing.md): - themes/solr/templates/mcp/licensing.html: subnav template with section anchors (Overview, Where They Live, Building, Construction, Role of the SBOM), matching the page's headings. - _footer.html: add a "Licensing & Notices" link to the Resources column. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

- Add an "MCP Completions" section to the Features page documenting argument autocompletion as a first-class capability: the `{collection}` variable of the `solr://{collection}/schema` resource and the `collection` argument of the search-collection / index-data / view-schema / design-schema prompts (case-insensitive prefix, capped at 100). Update the hero subtitle to list autocompletion alongside the 11 tools / 6 prompts / 2 resources. - Fix the Configuration env-var table: HTTP mode is secured by default, so the toggle is `HTTP_SECURITY_ENABLED` (default `true`), not the non-existent `SECURITY_ENABLED` (shown defaulting to `false`). Matches application-http.properties and apache/solr-mcp#143 / apache#151. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

adityamparikh mentioned this pull request Apr 24, 2026

Add Solr MCP Server tutorial to reference guide apache/solr#4043

Closed

2 tasks

adityamparikh mentioned this pull request May 19, 2026

docs(mcp): add add-fields and add-field-types to Schema tool table adityamparikh/solr-site#1

Open

3 tasks

This was referenced Jun 11, 2026

docs(site): host MCP documentation content in-repo, deployed to solr-site at build time apache/solr-mcp#143

Open

Fix DOAP language, add resources page and nav for MCP site #174

Closed

janhoy and others added 15 commits June 11, 2026 11:04

First version of MCP web site

9965b79

Change to a green theme

ecb43f7

Add some AI generated initial content for index and features

01c23cc

Revert rename of Solr Operator menu

1834fe4

adityamparikh force-pushed the mcp-docs-restructure branch from 7761409 to 0e79fb2 Compare June 11, 2026 15:06

adityamparikh marked this pull request as draft June 11, 2026 15:07

adityamparikh changed the title ~~Restructure MCP site with full documentation content~~ [BLOCKED on #160 + apache/solr-mcp#143] Restructure MCP site with full documentation content Jun 11, 2026

adityamparikh and others added 2 commits June 11, 2026 15:33

adityamparikh mentioned this pull request Jun 14, 2026

Polish up README and other docs to get ready for 1.0.0 apache/solr-mcp#147

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[BLOCKED on #160 + apache/solr-mcp#143] Restructure MCP site with full documentation content#175

[BLOCKED on #160 + apache/solr-mcp#143] Restructure MCP site with full documentation content#175
adityamparikh wants to merge 17 commits into
apache:mainfrom
adityamparikh:mcp-docs-restructure

adityamparikh commented Apr 24, 2026 •

edited

Loading

Uh oh!

janhoy commented Jun 9, 2026

Uh oh!

adityamparikh commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

adityamparikh commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New pages

Updated pages

Fixes

Test plan

Uh oh!

janhoy commented Jun 9, 2026

Uh oh!

adityamparikh commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adityamparikh commented Apr 24, 2026 •

edited

Loading