Skip to content

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

Merged
epugh merged 10 commits into
apache:mainfrom
adityamparikh:docs/polish-readme-1.0.0-followup
Jun 15, 2026
Merged

docs: slim README to a user "how to use" guide (builds on #147; ports #95)#151
epugh merged 10 commits into
apache:mainfrom
adityamparikh:docs/polish-readme-1.0.0-followup

Conversation

@adityamparikh

@adityamparikh adityamparikh commented Jun 14, 2026

Copy link
Copy Markdown
Contributor

Builds on #147 (@epugh's 1.0.0 docs polish — its commits are included here) and finishes the job from the review of that PR. Refocuses the README on end-user "how to use" content, moves developer/operational detail into the docs that own it, ports the unique end-user content from #95, and fixes the factual errors found in #147 — which also exist in the website source pages, so they flow into #143 too (separately).

README.md — now a lean "how to use" guide

Fixes the factual errors from the #147 review

  • SECURITY_ENABLED → HTTP_SECURITY_ENABLED (the real toggle is http.security.enabled=${HTTP_SECURITY_ENABLED:true}, @ConditionalOnProperty(... matchIfMissing=true) — secured by default, not false).
  • Removed the broken solr-mcp:latest-native reference (no such tag) — the canonical native run/config now lives in DEPLOYMENT.md with :latest-native-stdio.
  • The "published images not yet on a public registry" note is correct (verified: ghcr.io/apache/solr-mcp is 404/403).

CONTRIBUTING.md

  • Bare-path references → markdown links; de-duplicated "Publishing to Maven Local" → links the dev-docs section (per CONTRIBUTING's own "no duplication" principle).

dev-docs/

  • DEPLOYMENT.md: new "Image variants — why three images" section (the matrix, run commands, why Jib builds the JVM image and Paketo the native variants and why Paketo's JVM image breaks STDIO, native Claude Desktop config) — relocated out of the README.
  • DEVELOPMENT.md: the consumer-facing SBOM content (where it ships, fetch via the actuator endpoint, scan with Trivy/Grype) now lives next to "Generating the SBOM locally".

Companion change in #143

The same fixes apply to the website source pages and are pushed to #143: clients/jetbrains.md (.junie/mcp/mcp.json), clients/vs-code.md (type: http), security.md (HTTP_SECURITY_ENABLED, secured by default).

⚠️ Sequencing

The README's docs/site/content/pages/mcp/* links resolve on main only after #143 lands (those pages live there). Recommended merge order: #143 → this PR. #143's own description also asks to land first.

Relationship to #147 / #95

🤖 Generated with Claude Code

epugh and others added 9 commits June 14, 2026 00:41
@epugh @adityamparikh
until we publish docker images.... lets show the clone
37c34dc
@epugh @adityamparikh
Move dev oritented docs on publishing to dev guide
ecf9c70
@epugh @adityamparikh
SBOM generation locally is a development task
c3dfaef
@epugh @adityamparikh
be truthful about our lack of published images
eebe9b4
@epugh @adityamparikh
keep the good parts!
a1b38f5
@epugh @adityamparikh
Add native compile docs
8872e13
@epugh @adityamparikh
consoildate all security related docs under docs/security
c67f7ee
@epugh @adityamparikh
from pr 95
ae050fa
@adityamparikh @claude
docs: slim README to a "how to use" guide; relocate build/SBOM detail
a2691ec 
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 apache#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 apache#143), security to docs/security/,
  observability to the site page, and build/Docker/native/SBOM to dev-docs.
- Fixes carried over from the apache#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 apache#143. Depends on apache#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>
adityamparikh added a commit to adityamparikh/solr-mcp that referenced this pull request Jun 14, 2026
@adityamparikh @claude
docs(site): fix client config + security accuracy in MCP pages
ebea7aa 
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 adityamparikh mentioned this pull request Jun 14, 2026
Closed
3 tasks
@adityamparikh @claude
docs: document MCP completions and Solr version compatibility
fa5c514 
- 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>
@adityamparikh adityamparikh mentioned this pull request Jun 14, 2026
Closed
epugh
epugh approved these changes Jun 15, 2026
View reviewed changes

@epugh epugh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, I'll close my oroginal one and commit this.

@epugh epugh merged commit 80a51cc into apache:main Jun 15, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@epugh epugh epugh approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@adityamparikh @epugh