Polish up README and other docs to get ready for 1.0.0 by epugh · Pull Request #147 · apache/solr-mcp

epugh · 2026-06-13T18:33:32Z

No description provided.

Copilot

Pull request overview

Documentation polish in preparation for a 1.0.0 release, focusing on clarifying Docker image usage/building, consolidating developer workflows into the Development Guide, and de-duplicating contributor docs.

Changes:

Update README Docker examples to use locally built images and link SBOM generation instructions to the Development Guide.
Add Maven Local publishing + local SBOM generation instructions to dev-docs/DEVELOPMENT.md.
Remove duplicated Maven Local publishing section from CONTRIBUTING.md.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
README.md	Switches Docker examples to `solr-mcp:latest`, adds a “build locally first” note, and links SBOM local generation to dev docs.
dev-docs/DEVELOPMENT.md	Adds Maven Local publishing instructions and a dedicated section for generating the CycloneDX SBOM locally.
CONTRIBUTING.md	Removes the Maven Local publishing section to avoid duplication (now covered in the Development Guide).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.


 ## Get started (users)

+> **Note:** Published container images are not yet available on a public registry. The `docker run` examples below use a **locally built** image — build it first with `./gradlew jibDockerBuild` (produces `solr-mcp:latest`), or use the JAR path instead. See [Building Docker images](#building-docker-images).


        - Docker:
          ```bash
-          docker run -i --rm ghcr.io/apache/solr-mcp:latest
+          docker run -i --rm solr-mcp:latest


        - Docker:
          ```bash
-          docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest
+          docker run -p 8080:8080 --rm -e PROFILES=http solr-mcp:latest



 ```bash
-docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest
+docker run -p 8080:8080 --rm -e PROFILES=http solr-mcp:latest


 Using Docker (CLI):
 ```bash
-claude mcp add --transport stdio solr-mcp -- docker run -i --rm ghcr.io/apache/solr-mcp:latest
+claude mcp add --transport stdio solr-mcp -- docker run -i --rm solr-mcp:latest



 # Docker
-docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest
+docker run -p 8080:8080 --rm -e PROFILES=http solr-mcp:latest


+This is useful when:
+- Testing the library locally before publishing to a remote repository
+- Sharing artifacts between local projects during development


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>

adityamparikh · 2026-06-14T05:36:43Z

Thanks for kicking off the 1.0.0 docs polish, @epugh — I built a follow-up on top of this PR and a couple of companion changes. Summary so the threads are linked:

#151 — builds on this PR (your commits are bundled in). It finishes the review of #147 and:

Slims the README to a user-focused "how to use" guide; moves build/Docker/native/SBOM detail into dev-docs/, and defers the full per-client matrix to the website source pages.
Fixes the factual issues found here: SECURITY_ENABLED → HTTP_SECURITY_ENABLED (HTTP mode is secured by default, matchIfMissing=true); drops the non-existent solr-mcp:latest-native tag; keeps your (correct) "images not yet on a public registry" note.
Adds the Completions + Solr version-compatibility docs and ports the unique content from Restructure docs: end-user README, developer CONTRIBUTING #95.
CONTRIBUTING: bare paths → markdown links, de-duplicated "Publishing to Maven Local".

You can either merge #151 as the consolidated 1.0.0 docs PR, or merge this PR first and I'll rebase #151 down to just the delta.

Companion changes (same fixes, other surfaces):

#143 — the in-repo website source (docs/site/content/pages/mcp/**): client-config accuracy (.junie/mcp/mcp.json, VS Code type: http, claude mcp add syntax), security HTTP_SECURITY_ENABLED, broken docs/development/* links, the Linux --add-host note, Solr versions, and a completions tip.
apache/solr-site#175 — the rendered Features page template now lists Completions as a first-class capability and fixes the same env-var bug.

Merge order: #143 → #151 (the README links into #143's pages), and solr-site #175 fetches #143's content at build time.

#95 is now closed as superseded by #151 + #143.

…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>

epugh · 2026-06-15T15:51:08Z

Close in favour of #151

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>

…site at build time (#143) * docs(site): add MCP documentation content as source of truth 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> * docs(spec): update LICENSE/NOTICE design to the SBOM-driven buildSrc 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 #138: the appendix is derived from the CycloneDX SBOM (#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> * docs(spec): drop license-policy from LICENSE design (disclose SBOM as-is) Match PR #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> * docs(site): add a Licensing & Notices page 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> * docs(site): fix client config + security accuracy in MCP pages Three factual fixes surfaced while reviewing the README polish (#147/#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> * docs(site): fix `claude mcp add` syntax and broken doc links - 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 #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> * docs(site): Linux Docker note on all clients; Solr versions; completions 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> --------- Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

epugh added 4 commits June 13, 2026 14:19

until we publish docker images.... lets show the clone

19216a5

Move dev oritented docs on publishing to dev guide

2a7012d

SBOM generation locally is a development task

4eb8bae

be truthful about our lack of published images

15a5e1b

epugh requested a review from Copilot June 13, 2026 18:33

Copilot started reviewing on behalf of epugh June 13, 2026 18:34 View session

Copilot AI reviewed Jun 13, 2026

View reviewed changes

epugh added 3 commits June 13, 2026 14:38

keep the good parts!

74f1391

Add native compile docs

5604952

consoildate all security related docs under docs/security

fa2a0e5

epugh mentioned this pull request Jun 13, 2026

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

Closed

3 tasks

from pr 95

c204064

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

epugh closed this Jun 15, 2026

Navigation Menu

Uh oh!

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

Polish up README and other docs to get ready for 1.0.0#147
epugh wants to merge 8 commits into
apache:mainfrom
epugh:polish_up_readme

epugh commented Jun 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

adityamparikh commented Jun 14, 2026

Uh oh!

epugh commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Get started (users)

		> Note: Published container images are not yet available on a public registry. The `docker run` examples below use a locally built image — build it first with `./gradlew jibDockerBuild` (produces `solr-mcp:latest`), or use the JAR path instead. See [Building Docker images](#building-docker-images).

Uh oh!

Conversation

epugh commented Jun 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

adityamparikh commented Jun 14, 2026

Uh oh!

epugh commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants