docs(site): host MCP documentation content in-repo, deployed to solr-site at build time#143
Open
adityamparikh wants to merge 7 commits into
Open
docs(site): host MCP documentation content in-repo, deployed to solr-site at build time#143adityamparikh wants to merge 7 commits into
adityamparikh wants to merge 7 commits into
Conversation
6 tasks
Contributor
|
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
requested changes
Jun 11, 2026
janhoy
left a comment
janhoy
left a comment
Contributor
There was a problem hiding this comment.
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>
adityamparikh
force-pushed
the
feat/mcp-docs-source-in-repo
branch
from
3997ae8 to
a87d442
Compare
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>
3 tasks
- 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>
adityamparikh
added a commit
to adityamparikh/solr-site
that referenced
this pull request
Jun 14, 2026
- 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>
epugh
added a commit
that referenced
this pull request
Jun 15, 2026
…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>
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
2 participants
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
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 descriptorPlus
docs/site/README.mddescribing 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-mcpmain, so this PR should land first; then apache/solr-site#175 builds against it.Notes
docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md.🤖 Generated with Claude Code