Restructure docs: end-user README, developer CONTRIBUTING by adityamparikh · Pull Request #95 · apache/solr-mcp

adityamparikh · 2026-04-24T18:29:32Z

Summary

Restructures documentation to serve two distinct audiences:

README.md -- rewritten for end users who want to use the MCP server:

Natural language intro showing the value proposition
Features table with all MCP tools and resources
Quick Start guide (Docker + Claude Desktop in 2 minutes)
Per-client setup in collapsible sections (Claude Desktop, Claude Code, VS Code/Copilot, Cursor, JetBrains, MCP Inspector)
Configuration reference (environment variables table)
Example prompts organized by category (search, index, manage)
Community links (website, Slack, mailing lists)

CONTRIBUTING.md -- updated for developers:

Added security setup links (Auth0, Keycloak)
Added community channels (Slack, mailing lists)
Apache Code of Conduct reference

Companion to apache/solr-site#174 (website with full documentation).

Supersedes #94.

Test plan

README renders correctly on GitHub with collapsible sections
All links resolve correctly
CONTRIBUTING links to existing dev-docs/ files

🤖 Generated with Claude Code

README.md: Rewritten for end users with: - Natural language intro showing the value proposition - Features table with all MCP tools and resources - Quick Start guide (Docker + Claude Desktop in 2 minutes) - Per-client setup with collapsible sections (Claude Desktop, Claude Code, VS Code, Cursor, JetBrains, MCP Inspector) - Configuration reference (environment variables) - Example prompts by category - Community links (website, Slack, mailing lists) CONTRIBUTING.md: Updated with: - Security setup links (Auth0, Keycloak) - Community channels (Slack, issues, discussions, mailing lists) - Apache Code of Conduct reference Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Reorder all client configs to show JAR setup first (ATR release path) and local Docker images second. Remove all ghcr.io references — use solr-mcp:latest built locally via ./gradlew jibDockerBuild. Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Content covered by the observability page on the website (solr.apache.org/mcp/observability.html). Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Move dev-docs/ and security-docs/ into docs/development/ for a single organized docs structure: docs/ development/ (ARCHITECTURE, DEVELOPMENT, DEPLOYMENT, etc.) specs/ (graalvm-native-image) Fix CONTRIBUTING.md to use clickable markdown links instead of plain text paths. Update all cross-references in WORKFLOWS.md. Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Link to Apache License 2.0 URL instead of non-existent file. Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> # Conflicts: # README.md

…safety README: - Add `add-fields` and `add-field-types` to the Tools table (PR apache#131). - Add a sentence on MCP behavior hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so client integrators know to read them (PR apache#134). - Add an "MCP Prompts" section listing the six workflow prompts introduced in the prompts PR. - Clarify that `solr://{collection}/schema` autocompletion is prefix-filtered, case-insensitive, capped at 100 — describing the behavior shipped with the completion PR. CONTRIBUTING: - Add a "Null safety" subsection covering the project-wide `@NullMarked` contract and NullAway enforcement (PR apache#133). These docs land alongside the corresponding feature PRs at apache/main. Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Resolve README.md conflict: keep the restructured branch's HTTP Mode heading. Schema modification tools added in PR apache#131 are already documented in the restructured tools table (lines 38-42); the upstream table rows would have duplicated that content inside the Cursor setup section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

epugh · 2026-06-13T20:19:37Z

Thanks for this restructure, @adityamparikh — it's solid work and we've pulled the best of it forward.

We're consolidating the docs effort into #147 (polish_up_readme), which now supersedes this PR. Rather than land two competing README rewrites and two doc-folder schemes, #147 absorbs the strongest pieces of #95 on top of its existing structure. What carried over:

README

Natural-language intro hook + website nav links
Available MCP Prompts section
Tool behavior-hints note (readOnlyHint / destructiveHint / idempotentHint)
Collapsible setup for VS Code/Copilot, Cursor, JetBrains, and MCP Inspector
Configuration env-var table
Community section (Slack + Apache mailing lists)

CONTRIBUTING

Null-safety subsection (NullAway/JSpecify)
Publishing to Maven Local
Security Setup (HTTP Mode) links
Slack + mailing lists, and the Apache Code of Conduct reference

One deliberate difference: #147 keeps the dev-docs/ + docs/security/ layout rather than moving everything under docs/development/, so the security guides stay grouped separately.

Proposing we close this in favor of #147 — but please shout if there's anything from here you feel didn't make the jump. 🙏

adityamparikh · 2026-06-14T04:48:45Z

Superseded — closing in favor of #151 (a slim, user-focused README that builds on @epugh's #147) together with #143 (the in-repo website docs source).

The content unique to this PR has been carried forward:

The categorized Example prompts and the sample-data blurb (films 1,100+ / books) → ported into docs: slim README to a user "how to use" guide (builds on #147; ports #95) #151.
The per-client setup, security, and observability detail now live as linked pages in docs(site): host MCP documentation content in-repo, deployed to solr-site at build time #143, with the accuracy fixes (.junie/mcp/mcp.json, VS Code type: http, HTTP_SECURITY_ENABLED / secured-by-default) applied there.

Thanks — the restructure goal lives on in #151 + #143.

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

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

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

This was referenced Apr 24, 2026

[BLOCKED on #160 + apache/solr-mcp#143] Restructure MCP site with full documentation content apache/solr-site#175

Draft

Add website, community links, and ref-guide pointer to README #94

Closed

adityamparikh and others added 6 commits May 2, 2026 12:48

Remove non-existent GitHub Discussions links

72f4299

Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

Fix LICENSE link — no LICENSE file in repo

5043cff

Link to Apache License 2.0 URL instead of non-existent file. Signed-off-by: Aditya Parikh <adityamparikh@gmail.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com>

adityamparikh force-pushed the docs-restructure branch from 064db71 to 5043cff Compare May 2, 2026 16:48

adityamparikh and others added 3 commits May 8, 2026 17:19

Merge remote-tracking branch 'upstream/main' into docs-restructure

ed2af52

Signed-off-by: adityamparikh <aditya.m.parikh@gmail.com> # Conflicts: # README.md

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

adityamparikh closed this Jun 14, 2026

adityamparikh mentioned this pull request Jun 14, 2026

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

Closed

Navigation Menu

Uh oh!

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

Restructure docs: end-user README, developer CONTRIBUTING#95
adityamparikh wants to merge 9 commits into
apache:mainfrom
adityamparikh:docs-restructure

adityamparikh commented Apr 24, 2026 •

edited by janhoy

Loading

Uh oh!

epugh commented Jun 13, 2026

Uh oh!

adityamparikh commented Jun 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

adityamparikh commented Apr 24, 2026 • edited by janhoy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

epugh commented Jun 13, 2026

Uh oh!

adityamparikh commented Jun 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adityamparikh commented Apr 24, 2026 •

edited by janhoy

Loading