docs: slim README to a user "how to use" guide (builds on #147; ports #95) by adityamparikh · Pull Request #151 · apache/solr-mcp

adityamparikh · 2026-06-14T04:42:03Z

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

Value prop → Quick start (start Solr, build, connect a client, try it) → Example prompts → tools/resources/prompts tables → essential config → documentation hub → community.
Ports from Restructure docs: end-user README, developer CONTRIBUTING #95: the sample-data blurb (films 1,100+/books) and the categorized Example prompts.
Defers the full per-client matrix to the in-repo site pages (docs/site/content/pages/mcp/, from docs(site): host MCP documentation content in-repo, deployed to solr-site at build time #143), security to docs/security/, observability to the site page, and build/Docker/native/SBOM to dev-docs/.
README.md: −537 / +~50 lines.

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

Supersedes Polish up README and other docs to get ready for 1.0.0 #147 (its commits are bundled here) — or merge Polish up README and other docs to get ready for 1.0.0 #147 first and I'll rebase this to delta-only.
Supersedes Restructure docs: end-user README, developer CONTRIBUTING #95 (CONFLICTING; its unique content is ported here) — to be closed.

🤖 Generated with Claude Code

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

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>

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

epugh

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

…#144 conflicts) Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> Conflicts: README.md: kept main's slimmed flat tools table (PR apache#151) and added the index-markdown-documents row in its concise style src/main/java/org/apache/solr/mcp/server/indexing/documentcreator/IndexingDocumentCreator.java: kept both the markdownDocumentCreator field and main's constructor Javadoc, extended with the markdownDocumentCreator @param

…guides Five client guides linked to https://github.com/apache/solr-mcp#running-the-server, an anchor for a README section that no longer exists (removed by the apache#151 slim-down). Absolute self-links also dodge relative-link checkers, which is how this survived the sweep. - claude-desktop.md: point the built-JAR reference at the README's Quick start section via a relative link - claude-code/cursor/vs-code/jetbrains: inline the HTTP-mode start command instead of linking (the current README has no HTTP-mode startup section to link to) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

The README merged in apache#151 links into docs/site/content/pages/mcp/, a tree that only exists on the unmerged apache#143 branch, so every documentation link on main 404s. Restore the linked content from the apache#143 branch into locations that exist on main today, adapted for plain GitHub rendering (Pelican frontmatter converted to headings, site-absolute links repointed): - per-client setup guides (Claude Desktop, Claude Code, VS Code/Copilot, Cursor, JetBrains, MCP Inspector) under docs/clients/ - observability guide at docs/observability.md and repoint the README links there; the Quick start link now targets the README's own section. Also fix three pre-existing broken links found by a repo-wide sweep: - docs/security/http.md and docs/security/stdio.md referenced ../specs/graalvm-native-image.md, which moved to dev-docs/ - docs/security/keycloak.md TOC listed a 'User Federation (LDAP/AD)' section that does not exist This does not preempt the apache#143 discussion about where website source should live; when that lands these files can move wherever dev@ decides. Fixes apache#168 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

…guides Five client guides linked to https://github.com/apache/solr-mcp#running-the-server, an anchor for a README section that no longer exists (removed by the apache#151 slim-down). Absolute self-links also dodge relative-link checkers, which is how this survived the sweep. - claude-desktop.md: point the built-JAR reference at the README's Quick start section via a relative link - claude-code/cursor/vs-code/jetbrains: inline the HTTP-mode start command instead of linking (the current README has no HTTP-mode startup section to link to) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

epugh and others added 9 commits June 14, 2026 00:41

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

37c34dc

Move dev oritented docs on publishing to dev guide

ecf9c70

SBOM generation locally is a development task

c3dfaef

be truthful about our lack of published images

eebe9b4

keep the good parts!

a1b38f5

Add native compile docs

8872e13

consoildate all security related docs under docs/security

c67f7ee

from pr 95

ae050fa

adityamparikh mentioned this pull request Jun 14, 2026

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

Closed

3 tasks

adityamparikh mentioned this pull request Jun 14, 2026

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

Closed

epugh approved these changes Jun 15, 2026

View reviewed changes

epugh merged commit 80a51cc into apache:main Jun 15, 2026
1 check passed

adityamparikh mentioned this pull request Jun 24, 2026

feat: Spring Boot 4.1.0 + Spring AI 2.0.0 GA (2.0.0 release line) adityamparikh/solr-mcp#92

Merged

3 tasks

This was referenced Jul 16, 2026

Merge upstream main to resolve apache/solr-mcp#144 conflicts shahzadarain/solr-mcp#1

Merged

feat(indexing): add markdown document indexing #144

Open

adityamparikh mentioned this pull request Jul 31, 2026

docs: fix broken documentation links in README #171

Open

Navigation Menu

Uh oh!

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

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

adityamparikh commented Jun 14, 2026

Uh oh!

epugh left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

adityamparikh commented Jun 14, 2026

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

Fixes the factual errors from the #147 review

CONTRIBUTING.md

dev-docs/

Companion change in #143

⚠️ Sequencing

Relationship to #147 / #95

Uh oh!

epugh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants