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.

@PARAM

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

* docs: fix broken documentation links in README (#168) The README merged in #151 links into docs/site/content/pages/mcp/, a tree that only exists on the unmerged #143 branch, so every documentation link on main 404s. Restore the linked content from the #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 #143 discussion about where website source should live; when that lands these files can move wherever dev@ decides. Fixes #168 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> * docs(clients): fix dead 'running-the-server' README anchor in client 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 #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> * docs: apply review suggestions — JetBrains transport, dead links, clients index - jetbrains.md: the IDE Settings transport is HTTP, not SSE — AI Assistant connects via streamable HTTP, which is what this server implements (stateless streamable, POST /mcp); the legacy SSE transport is not served. Verified against the current JetBrains AI Assistant MCP documentation, and repointed the guide's doc link there (help/idea/model-context-protocol.html now 404s). - README: spec.modelcontextprotocol.io is a dead host (TLS failure; retired spec subdomain) — point the MCP link at modelcontextprotocol.io. All other external links in the PR's files verified 200. - Add docs/clients/README.md so the README's 'Client setup' directory link lands on an index instead of a bare file listing. Co-Authored-By: Claude Fable 5 <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 Fable 5 <noreply@anthropic.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>

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

Merged

adityamparikh mentioned this pull request Jul 31, 2026

docs: fix broken documentation links in README #171

Merged

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