Restructure docs: end-user README, developer CONTRIBUTING#95
Closed
adityamparikh wants to merge 9 commits into
Closed
Restructure docs: end-user README, developer CONTRIBUTING#95adityamparikh wants to merge 9 commits into
adityamparikh wants to merge 9 commits into
Conversation
This was referenced Apr 24, 2026
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>
adityamparikh
force-pushed
the
docs-restructure
branch
from
064db71 to
5043cff
Compare
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>
Contributor
|
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 ( README
CONTRIBUTING
One deliberate difference: #147 keeps the Proposing we close this in favor of #147 — but please shout if there's anything from here you feel didn't make the jump. 🙏 |
Contributor
Author
|
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:
|
adityamparikh
added a commit
to adityamparikh/solr-mcp
that referenced
this pull request
Jun 14, 2026
- 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 apache#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>
epugh
added a commit
that referenced
this pull request
Jun 15, 2026
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures documentation to serve two distinct audiences:
README.md -- rewritten for end users who want to use the MCP server:
CONTRIBUTING.md -- updated for developers:
Companion to apache/solr-site#174 (website with full documentation).
Supersedes #94.
Test plan
🤖 Generated with Claude Code