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

adityamparikh · 2026-06-11T02:37:44Z

Summary

Makes solr-mcp the source of truth for the MCP documentation content, so docs travel with the code — every feature PR can update its docs in the same review. This addresses @janhoy's request on apache/solr-site#175: "Ideally I'd like the mcp docs to live in the same repo as code, but be deployed to solr site."

Adds under docs/site/content/:

pages/mcp/** — the MCP documentation Markdown pages (Quick Start, per-client setup, Security, Observability, Features, Resources, …)
doap/solr-mcp.rdf — the DOAP project descriptor

Plus docs/site/README.md describing the content/presentation split and the build-time assembly contract.

How it gets deployed

Content here is plain Pelican Markdown (front-matter selects a template: mcp/*). The presentation layer (Pelican templates, theme, CSS, pelicanconf.py) stays in apache/solr-site, so the MCP pages keep the shared Solr site look and their published URLs (https://solr.apache.org/mcp/...) are unchanged.

At site-build time, solr-site fetches this directory into its Pelican content/ tree before rendering — mirroring how the Solr Reference Guide content is assembled into the site. That wiring (build.sh + Pelican CI + removal of the now-sourced content) is the companion change in apache/solr-site#175.

Sequencing

The solr-site fetch pulls from apache/solr-mcp main, so this PR should land first; then apache/solr-site#175 builds against it.

Notes

Design doc: docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md.
No code or build changes — documentation content only.

🤖 Generated with Claude Code

janhoy · 2026-06-11T08:13:07Z

I'm tempted to disable the feature that "intelligently" converts SOLR-NNN in text to JIRA links, as that feature is not intelligent at all.

janhoy

This branch contains also the LICENSE/NOTICE commit. Please remove.

Important clarifications

Are we not going to have versioned documentation with each release?
What is "project" site and what is "product" docs? They seem conflated here now.

Let's continue on dev@ list these discussions

Move the MCP documentation pages (Markdown) and the DOAP descriptor into docs/site/content/ so that documentation travels with the code: every feature PR can update its docs in the same review. The Solr site's presentation layer (Pelican templates, theme, CSS, pelicanconf) stays in apache/solr-site; at build time solr-site fetches this content into its Pelican content/ tree before rendering, so the MCP pages keep the shared site theme and their published URLs are unchanged. See docs/site/README.md. Companion to the apache/solr-site change that adds the fetch step to build.sh and the Pelican CI workflows and removes the now-sourced-here content. Also adds the design doc covering this and the binary LICENSE/NOTICE tooling. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

…approach The Deliverable 1 section described the earlier jk1 dependency-license-report plan (plugin appendix + hand-kept SolrJ supplement + checkLicense). Update it to what shipped in PR apache#138: the appendix is derived from the CycloneDX SBOM (apache#142), implemented as the org.apache.solr.mcp.license-notice convention plugin in buildSrc with typed, unit-tested GenerateBinaryLicense/GenerateBinaryNotice tasks and a config/license-policy.json (allowedLicenses + overrides) gate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

…-is) Match PR apache#138: removed config/license-policy.json and the allow-list/override gate; the appendix now discloses SBOM-reported licenses verbatim with a completeness-only gate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

New MCP docs-site page covering the project's LICENSE/NOTICE: the source vs binary split, where the binary files live (the executable JAR's META-INF and the Docker images built from it), how to build them, how they're constructed (the SBOM-derived LICENSE appendix and the aggregated dependency NOTICE), and the role of the CycloneDX SBOM as the complementary machine-readable inventory. Linked from the Resources page Guides list. The page template lives in apache/solr-site (themes/solr/templates/mcp/licensing.html) per the content/presentation split. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Three factual fixes surfaced while reviewing the README polish (apache#147/apache#151), which the website source pages share: - clients/jetbrains.md: Junie's project MCP config lives at `.junie/mcp/mcp.json` (nested `mcp/` dir), not `.junie/mcp.json`. - clients/vs-code.md: the `/mcp` endpoint is Streamable HTTP, so the VS Code server entry needs `"type": "http"`, not the legacy `"sse"`. - security.md: HTTP mode is **secured by default** (`http.security.enabled` defaults to true). Corrected the "disabled by default" framing and removed the non-existent `SECURITY_ENABLED` toggle; the issuer (`OAUTH2_ISSUER_URI`) is what you set to use auth, and `HTTP_SECURITY_ENABLED=false` disables it for local dev. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

- clients/claude-code.md: the `claude mcp add` CLI examples and the explanation were wrong. Per `claude mcp add --help`, the form is `claude mcp add [options] <name> <commandOrUrl> [args...]` — the server name comes first and, for STDIO, `--` goes AFTER the name and any `-e` options (`-e` stops at the `--`). HTTP needs no `--`. Corrected all three examples (`solr-mcp ... -- <command>`; `--transport http solr-mcp <url>`) and rewrote the misleading "`--` before the name / `-e` is greedy" note. - security.md & resources.md: the Auth0/Keycloak/Architecture/Development links pointed at `docs/development/*` (the abandoned apache#95 layout, which never existed on main). Repointed to the real 1.0.0 locations: `docs/security/auth0.md`, `docs/security/keycloak.md`, `dev-docs/ARCHITECTURE.md`, `dev-docs/DEVELOPMENT.md`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Brings the website source to parity with the README/dev-docs fixes: - clients/{cursor,jetbrains,claude-code,mcp-inspector}.md: add the Linux `--add-host=host.docker.internal:host-gateway` note to their Docker examples (Claude Desktop already had it) so the container can reach a host Solr on Linux. - quick-start.md: note Solr version compatibility (8.11–10, tested matrix) in Prerequisites, and add a Tip that MCP completions autocomplete collection names for the schema resource and the prompt arguments. Note: the rendered Features page lists tools/resources/prompts from the `mcp/features` template in apache/solr-site; adding a "Completions" entry there is a parallel solr-site change. 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>

…95) (#151) * until we publish docker images.... lets show the clone * Move dev oritented docs on publishing to dev guide * SBOM generation locally is a development task * be truthful about our lack of published images * keep the good parts! * Add native compile docs * consoildate all security related docs under docs/security * from pr 95 * docs: slim README to a "how to use" guide; relocate build/SBOM detail Refocuses README.md on end-user "how to use" content and moves developer/operational detail into the docs that own it, so the README stays scannable and the deep material has a single home. README.md - Lean structure: value prop -> Quick start (start Solr, build, connect a client, try it) -> Example prompts -> tools/resources/prompts tables -> essential config -> documentation hub -> community. - Ports the unique end-user content from #95: sample-data blurb (films/books) and the categorized Example prompts. - Defers the full per-client matrix to the in-repo site pages under docs/site/content/pages/mcp/ (from #143), security to docs/security/, observability to the site page, and build/Docker/native/SBOM to dev-docs. - Fixes carried over from the #147 review: HTTP_SECURITY_ENABLED (secured by default), not the non-existent SECURITY_ENABLED. CONTRIBUTING.md - Convert bare-path references to markdown links for consistency. - De-duplicate "Publishing to Maven Local" -> link the dev-docs section (CONTRIBUTING's own principle is "no duplication; detail lives in dev-docs"). dev-docs/DEPLOYMENT.md - New "Image variants — why three images" section receiving the rationale moved out of the README: the image x mode matrix, run commands, why Jib builds the JVM image and Paketo the native variants (and why Paketo's JVM image breaks STDIO), and the native Claude Desktop config (latest-native-stdio). dev-docs/DEVELOPMENT.md - Move the consumer-facing SBOM content (where it ships, fetch via the actuator endpoint, scan with Trivy/Grype) here next to "Generating the SBOM locally", replacing the now-removed README section it linked to. Companion website-page fixes (.junie/mcp/mcp.json, VS Code type: http, HTTP_SECURITY_ENABLED) flow into #143. Depends on #143 for the docs/site/* links to resolve on main. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> * docs: document MCP completions and Solr version compatibility - README: add a "Completions" subsection (the `{collection}` resource argument and the search-collection/index-data/view-schema/design-schema prompt arguments all autocomplete to live collection names), and a one-line Solr compatibility note linking the dev-docs section. - dev-docs/DEVELOPMENT.md: add "Solr Version Compatibility" under Testing — the `-Dsolr.test.image` override, the tested-version matrix (8.11, 9.4, 9.9, 9.10, 10), and the Solr 10 caveats (mbeans removed → null cache/handler stats; SolrJ 10.x not yet on Maven Central). Ported from AGENTS.md so it lives in the developer docs, not just the agent guide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> --------- Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> Co-authored-by: Eric Pugh <epugh@opensourceconnections.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

adityamparikh · 2026-06-19T16:06:08Z

Thanks for the review @janhoy.

LICENSE/NOTICE commit — done. I force-pushed to drop the commit that modified the repo-root LICENSE/NOTICE files, so this PR no longer touches any root license file (git diff main --name-only confirms docs-content only). The only license-related material left is content/design, not the repo NOTICE: a licensing.md doc page and the design spec under docs/superpowers/specs/. Happy to split those out as well if you'd prefer this PR carry zero licensing material.

Versioned docs per release and "project site" vs "product docs" — agreed these are the larger design questions rather than something to settle in this diff; let's continue them on dev@ as you suggested.

While here I also tightened up accuracy in the MCP pages: corrected the claude mcp add syntax and per-client config, fixed broken doc links, added the Linux Docker note across clients, refreshed the supported Solr versions, and documented completions.

adityamparikh mentioned this pull request Jun 11, 2026

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

Draft

6 tasks

janhoy requested changes Jun 11, 2026

View reviewed changes

adityamparikh mentioned this pull request Jun 11, 2026

feat(build): binary-release LICENSE/NOTICE derived from the SBOM #138

Merged

adityamparikh requested a review from janhoy June 13, 2026 19:37

adityamparikh and others added 4 commits June 13, 2026 23:50

adityamparikh force-pushed the feat/mcp-docs-source-in-repo branch from 3997ae8 to a87d442 Compare June 14, 2026 03:51

adityamparikh mentioned this pull request Jun 14, 2026

docs: slim README to a user "how to use" guide (builds on #147; ports #95) #151

Merged

adityamparikh mentioned this pull request Jun 14, 2026

Restructure docs: end-user README, developer CONTRIBUTING #95

Closed

3 tasks

adityamparikh and others added 2 commits June 14, 2026 01:02

adityamparikh mentioned this pull request Jun 14, 2026

Polish up README and other docs to get ready for 1.0.0 #147

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

docs(site): host MCP documentation content in-repo, deployed to solr-site at build time#143
adityamparikh wants to merge 7 commits into
apache:mainfrom
adityamparikh:feat/mcp-docs-source-in-repo

adityamparikh commented Jun 11, 2026

Uh oh!

janhoy commented Jun 11, 2026

Uh oh!

janhoy left a comment

Uh oh!

adityamparikh commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

adityamparikh commented Jun 11, 2026

Summary

How it gets deployed

Sequencing

Notes

Uh oh!

janhoy commented Jun 11, 2026

Uh oh!

janhoy left a comment

Choose a reason for hiding this comment

Important clarifications

Uh oh!

adityamparikh commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants