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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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