This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr-mcp.git
The following commit(s) were added to refs/heads/main by this push:
new e460042 docs(site): host MCP documentation content in-repo, deployed
to solr-site at build time (#143)
e460042 is described below
commit e460042b0471bbc96510921fb2a7b26b05f1f091
Author: Aditya Parikh <[email protected]>
AuthorDate: Fri Sep 11 09:53:55 2026 -0400
docs(site): host MCP documentation content in-repo, deployed to solr-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) <[email protected]>
Signed-off-by: adityamparikh <[email protected]>
* 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) <[email protected]>
Signed-off-by: adityamparikh <[email protected]>
* 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) <[email protected]>
Signed-off-by: adityamparikh <[email protected]>
* 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) <[email protected]>
Signed-off-by: adityamparikh <[email protected]>
* 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) <[email protected]>
Signed-off-by: adityamparikh <[email protected]>
* 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) <[email protected]>
Signed-off-by: adityamparikh <[email protected]>
* 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) <[email protected]>
Signed-off-by: adityamparikh <[email protected]>
---------
Signed-off-by: adityamparikh <[email protected]>
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
---
docs/site/README.md | 55 +++++++
docs/site/content/doap/solr-mcp.rdf | 52 ++++++
docs/site/content/pages/mcp/clients/claude-code.md | 114 ++++++++++++++
.../content/pages/mcp/clients/claude-desktop.md | 110 +++++++++++++
docs/site/content/pages/mcp/clients/cursor.md | 75 +++++++++
docs/site/content/pages/mcp/clients/jetbrains.md | 78 +++++++++
.../content/pages/mcp/clients/mcp-inspector.md | 59 +++++++
docs/site/content/pages/mcp/clients/vs-code.md | 85 ++++++++++
docs/site/content/pages/mcp/community.md | 42 +++++
docs/site/content/pages/mcp/downloads.md | 5 +
docs/site/content/pages/mcp/features.md | 4 +
docs/site/content/pages/mcp/index.md | 4 +
docs/site/content/pages/mcp/licensing.md | 98 ++++++++++++
docs/site/content/pages/mcp/observability.md | 114 ++++++++++++++
docs/site/content/pages/mcp/quick-start.md | 132 ++++++++++++++++
docs/site/content/pages/mcp/resources.md | 48 ++++++
docs/site/content/pages/mcp/security.md | 175 +++++++++++++++++++++
...-06-09-license-notice-and-docs-deploy-design.md | 161 +++++++++++++++++++
18 files changed, 1411 insertions(+)
diff --git a/docs/site/README.md b/docs/site/README.md
new file mode 100644
index 0000000..99de379
--- /dev/null
+++ b/docs/site/README.md
@@ -0,0 +1,55 @@
+# Solr MCP documentation site content
+
+This directory is the **source of truth** for the Apache Solr MCP
documentation that
+is published on the Solr website at <https://solr.apache.org/mcp/>.
+
+Keeping the content here means every feature PR can update its documentation
alongside
+the code change, in the same review.
+
+## What lives here
+
+```
+docs/site/content/
+├── pages/mcp/** Markdown pages (one file per published page)
+└── doap/solr-mcp.rdf DOAP project descriptor
+```
+
+These are plain [Pelican](https://getpelican.com/) content files. Each page
carries
+front-matter that selects a template, e.g.:
+
+```
+Title: Quick Start
+URL: mcp/quick-start.html
+save_as: mcp/quick-start.html
+template: mcp/quick-start
+```
+
+## How it gets published (assembly at build time)
+
+The **presentation layer** (Pelican templates, theme, CSS, `pelicanconf.py`)
lives in
+the [`apache/solr-site`](https://github.com/apache/solr-site) repository, not
here, so
+the MCP pages share the rest of the Solr site's look and feel.
+
+At site-build time, `solr-site` fetches this directory at a pinned ref and
copies it
+into its Pelican `content/` tree before running `pelican content -o output`:
+
+- `content/pages/mcp/**` ← `docs/site/content/pages/mcp/**`
+- `content/doap/solr-mcp.rdf` ← `docs/site/content/doap/solr-mcp.rdf`
+
+This is wired in `solr-site`'s `build.sh` (local preview) and its Pelican
GitHub
+Actions workflows (`build-pelican.yml`, `pr-build-pelican.yml`). The published
URLs are
+unchanged from when the content lived in `solr-site` directly.
+
+## Editing and previewing
+
+- **Edit** the Markdown here; that is all most doc changes require.
+- **Preview** with the full Solr theme by running `solr-site`'s `./build.sh
-l` with a
+ sibling `solr-mcp` checkout — the build picks up
`../solr-mcp/docs/site/content`
+ automatically when present, otherwise it clones the pinned ref.
+
+## Why content here, theme there
+
+A standalone build in this repo would have to vendor the Solr Pelican theme
and would
+drift from the rest of the site. Splitting **content (here)** from
**presentation
+(`solr-site`)** keeps a single themed build while letting documentation travel
with the
+code — mirroring how the Solr Reference Guide is assembled into the site.
diff --git a/docs/site/content/doap/solr-mcp.rdf
b/docs/site/content/doap/solr-mcp.rdf
new file mode 100644
index 0000000..40faa36
--- /dev/null
+++ b/docs/site/content/doap/solr-mcp.rdf
@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl"?>
+<rdf:RDF xml:lang="en"
+ xmlns="http://usefulinc.com/ns/doap#";
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#";
+ xmlns:asfext="http://projects.apache.org/ns/asfext#";
+ xmlns:foaf="http://xmlns.com/foaf/0.1/";>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <Project rdf:about="https://solr.apache.org/mcp";>
+ <created>2025-10-26</created>
+ <license rdf:resource="https://spdx.org/licenses/Apache-2.0"; />
+ <name>Apache Solr MCP Server</name>
+ <homepage rdf:resource="https://solr.apache.org/mcp"; />
+ <asfext:pmc rdf:resource="https://solr.apache.org"; />
+ <shortdesc>Model Context Protocol server for Apache Solr</shortdesc>
+ <bug-database rdf:resource="https://github.com/apache/solr-mcp/issues"; />
+ <mailing-list
rdf:resource="https://solr.apache.org/community.html#mailing-lists-chat"; />
+ <download-page rdf:resource="https://solr.apache.org/mcp/downloads.html"; />
+ <programming-language>Java</programming-language>
+ <category rdf:resource="https://projects.apache.org/category/cloud"; />
+ <category rdf:resource="https://projects.apache.org/category/search"/>
+ <category rdf:resource="https://projects.apache.org/category/java"/>
+ <repository>
+ <GitRepository>
+ <location
rdf:resource="https://gitbox.apache.org/repos/asf/solr-mcp.git"/>
+ <browse
rdf:resource="https://gitbox.apache.org/repos/asf?p=solr-mcp.git"/>
+ </GitRepository>
+ </repository>
+ <maintainer>
+ <foaf:Person>
+ <foaf:name>Apache Solr Team</foaf:name>
+ <foaf:mbox rdf:resource="mailto:[email protected]"/>
+ </foaf:Person>
+ </maintainer>
+ <!-- NOTE: please insert releases in numeric order, NOT chronologically.
-->
+ </Project>
+</rdf:RDF>
diff --git a/docs/site/content/pages/mcp/clients/claude-code.md
b/docs/site/content/pages/mcp/clients/claude-code.md
new file mode 100644
index 0000000..decf18b
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/claude-code.md
@@ -0,0 +1,114 @@
+Title: Claude Code
+URL: mcp/clients/claude-code.html
+save_as: mcp/clients/claude-code.html
+template: mcp/client
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's
CLI tool for Claude. It supports MCP servers via the `claude mcp add` command
or a `.mcp.json` project file.
+
+***
+
+## CLI Syntax ##
+
+The general form of `claude mcp add` is (see [Claude Code MCP
docs](https://code.claude.com/docs/en/mcp)):
+
+```bash
+claude mcp add [options] <name> <commandOrUrl> [args...]
+```
+
+The server `<name>` comes first. For a **STDIO** server, pass any `-e
KEY=value` options (repeatable) after the name, then `--`, then the launch
command. The `--` stops Claude Code from reparsing the server's own flags as
its own options, and `-e` stops consuming tokens at the `--`:
+
+```bash
+claude mcp add <name> -e KEY=value -- <command> [args...]
+```
+
+For an **HTTP** server, no `--` is needed — pass the URL with `--transport
http`:
+
+```bash
+claude mcp add --transport http <name> <url>
+```
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### CLI ###
+
+```bash
+# JAR
+claude mcp add solr-mcp \
+ -e SOLR_URL=http://localhost:8983/solr/ \
+ -- java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Docker (local image — build first with ./gradlew jibDockerBuild)
+claude mcp add solr-mcp \
+ -- docker run -i --rm -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+### `.mcp.json` ###
+
+Add to your project root:
+
+**JAR:**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/"; }
+ }
+ }
+}
+```
+
+**Docker (local image):**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the
`args` array.
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the
Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+### CLI ###
+
+```bash
+claude mcp add --transport http solr-mcp http://localhost:8080/mcp
+```
+
+### `.mcp.json` ###
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "type": "http",
+ "url": "http://localhost:8080/mcp";
+ }
+ }
+}
+```
+
+### Secured HTTP (OAuth2) ###
+
+Claude Code detects the OAuth2 challenge from the server and initiates the
authorization flow automatically. The configuration is the same as unsecured
HTTP.
+
+See [Security](/mcp/security.html) for server-side OAuth2 setup.
diff --git a/docs/site/content/pages/mcp/clients/claude-desktop.md
b/docs/site/content/pages/mcp/clients/claude-desktop.md
new file mode 100644
index 0000000..e849131
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/claude-desktop.md
@@ -0,0 +1,110 @@
+Title: Claude Desktop
+URL: mcp/clients/claude-desktop.html
+save_as: mcp/clients/claude-desktop.html
+template: mcp/client
+
+[Claude Desktop](https://claude.ai/download) is Anthropic's desktop
application for Claude. It supports MCP servers via STDIO and HTTP transports.
+
+### Configuration File
+
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Restart Claude Desktop after any configuration change.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+STDIO mode communicates via stdin/stdout. This is the simplest setup for local
use.
+
+### JAR ###
+
+Requires Java 25+ and a [built
JAR](https://github.com/apache/solr-mcp#running-the-server) (`./gradlew build`).
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": {
+ "SOLR_URL": "http://localhost:8983/solr/";
+ }
+ }
+ }
+}
+```
+
+### Docker (local image) ###
+
+Build the image first: `./gradlew jibDockerBuild`
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the
`args` array.
+
+***
+
+## HTTP Mode ##
+
+HTTP mode connects to a running MCP server via REST endpoints. Start the
server first, then configure Claude Desktop to connect using `mcp-remote`.
+
+### Start the Server ###
+
+```bash
+# JAR
+PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Or Gradle
+PROFILES=http ./gradlew bootRun
+
+# Or Docker (local image)
+docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+### Configure Claude Desktop ###
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "npx",
+ "args": ["mcp-remote", "http://localhost:8080/mcp";]
+ }
+ }
+}
+```
+
+### Secured HTTP (OAuth2) ###
+
+When OAuth2 is enabled on the server, `mcp-remote` handles the authorization
flow automatically—it discovers the authorization server and opens a
browser for consent.
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "npx",
+ "args": ["mcp-remote", "http://localhost:8080/mcp";, "--allow-http"]
+ }
+ }
+}
+```
+
+The `--allow-http` flag is needed for `http://` URLs (development). Omit it in
production with HTTPS.
+
+See [Security](/mcp/security.html) for server-side OAuth2 setup.
diff --git a/docs/site/content/pages/mcp/clients/cursor.md
b/docs/site/content/pages/mcp/clients/cursor.md
new file mode 100644
index 0000000..73a420f
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/cursor.md
@@ -0,0 +1,75 @@
+Title: Cursor
+URL: mcp/clients/cursor.html
+save_as: mcp/clients/cursor.html
+template: mcp/client
+
+[Cursor](https://cursor.sh/) supports MCP servers natively via project
configuration files or the Cursor Settings UI.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### Project Configuration (`.cursor/mcp.json`) ###
+
+Create `.cursor/mcp.json` in your project root:
+
+**JAR:**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/"; }
+ }
+ }
+}
+```
+
+**Docker (local image — build first with `./gradlew jibDockerBuild`):**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the
`args` array.
+
+### Cursor Settings UI ###
+
+1. Open **Cursor Settings** (gear icon or <kbd>Cmd+,</kbd> / <kbd>Ctrl+,</kbd>)
+2. Navigate to **Features** > **MCP Servers**
+3. Click **Add New MCP Server**
+4. Enter:
+ * **Name**: `solr-mcp`
+ * **Type**: `command`
+ * **Command**: `java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the
Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "url": "http://localhost:8080/mcp";
+ }
+ }
+}
+```
+
+The configuration is the same for secured and unsecured HTTP. Cursor handles
the MCP OAuth2 flow automatically.
+
+See the [Cursor MCP
documentation](https://docs.cursor.com/context/model-context-protocol) for the
latest configuration format.
diff --git a/docs/site/content/pages/mcp/clients/jetbrains.md
b/docs/site/content/pages/mcp/clients/jetbrains.md
new file mode 100644
index 0000000..db42ce8
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/jetbrains.md
@@ -0,0 +1,78 @@
+Title: JetBrains IDEs
+URL: mcp/clients/jetbrains.html
+save_as: mcp/clients/jetbrains.html
+template: mcp/client
+
+[JetBrains IDEs](https://www.jetbrains.com/) (IntelliJ IDEA, WebStorm,
PyCharm, etc.) support MCP servers through the AI Assistant plugin.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### Project Configuration (`.junie/mcp/mcp.json`) ###
+
+Create `.junie/mcp/mcp.json` in your project root:
+
+**JAR:**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/"; }
+ }
+ }
+}
+```
+
+**Docker (local image — build first with `./gradlew jibDockerBuild`):**
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the
`args` array.
+
+### IDE Settings ###
+
+1. Open **Settings** (<kbd>Cmd+,</kbd> / <kbd>Ctrl+Alt+S</kbd>)
+2. Navigate to **Tools** > **AI Assistant** > **MCP Servers**
+3. Click **Add** (`+`)
+4. Configure:
+ * **Name**: `solr-mcp`
+ * **Transport**: `STDIO`
+ * **Command**: `java`
+ * **Arguments**: `-jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the
Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "url": "http://localhost:8080/mcp";
+ }
+ }
+}
+```
+
+Or in IDE Settings, select **SSE** transport and enter
`http://localhost:8080/mcp` as the URL.
+
+The configuration is the same for secured and unsecured HTTP. JetBrains IDEs
handle the MCP OAuth2 flow automatically.
+
+MCP support requires the AI Assistant plugin. See the [JetBrains MCP
documentation](https://www.jetbrains.com/help/idea/model-context-protocol.html)
for the latest configuration format.
diff --git a/docs/site/content/pages/mcp/clients/mcp-inspector.md
b/docs/site/content/pages/mcp/clients/mcp-inspector.md
new file mode 100644
index 0000000..5dc72f6
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/mcp-inspector.md
@@ -0,0 +1,59 @@
+Title: MCP Inspector
+URL: mcp/clients/mcp-inspector.html
+save_as: mcp/clients/mcp-inspector.html
+template: mcp/client
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a
web-based tool for testing and debugging MCP servers. It lets you browse
available tools, invoke them interactively, and inspect responses.
+
+### Install ###
+
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+This starts the Inspector UI at `http://localhost:6274`.
+
+***
+
+## STDIO Mode ##
+
+1. In MCP Inspector, select **STDIO** transport
+2. **Command**: `java`
+3. **Arguments**: `-jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
+4. Click **Connect**
+
+***
+
+## HTTP Mode ##
+
+1. Start the server in HTTP mode:
+
+ # JAR
+ PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
+
+ # Or Gradle
+ PROFILES=http ./gradlew bootRun
+
+ # Or Docker (local image — build first with ./gradlew jibDockerBuild)
+ docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+
+2. In MCP Inspector, enter: `http://localhost:8080/mcp`
+3. Click **Connect**
+
+**Linux users** (Docker option): add
`--add-host=host.docker.internal:host-gateway` to the `docker run` command.
+
+***
+
+## OAuth2 ##
+
+When OAuth2 is enabled on the server, configure the Inspector's OAuth settings
before connecting:
+
+1. Click the **OAuth** settings in the Inspector
+2. Enter your provider's Authorization URL, Token URL, Client ID, and Redirect
URI (`http://localhost:6274/oauth/callback`)
+3. Complete the OAuth flow
+4. The Inspector will include the Bearer token in all subsequent requests
+
+See [Security](/mcp/security.html) for server-side OAuth2 setup with Auth0 and
Keycloak.
diff --git a/docs/site/content/pages/mcp/clients/vs-code.md
b/docs/site/content/pages/mcp/clients/vs-code.md
new file mode 100644
index 0000000..081cff2
--- /dev/null
+++ b/docs/site/content/pages/mcp/clients/vs-code.md
@@ -0,0 +1,85 @@
+Title: VS Code / GitHub Copilot
+URL: mcp/clients/vs-code.html
+save_as: mcp/clients/vs-code.html
+template: mcp/client
+
+[VS Code](https://code.visualstudio.com/) supports MCP servers through
built-in MCP support (VS Code 1.99+). Solr MCP tools are available in GitHub
Copilot Chat when using Agent mode.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### Workspace Configuration (`.vscode/mcp.json`) ###
+
+Create `.vscode/mcp.json` in your project root:
+
+**JAR:**
+
+```json
+{
+ "servers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/"; }
+ }
+ }
+}
+```
+
+**Docker (local image — build first with `./gradlew jibDockerBuild`):**
+
+```json
+{
+ "servers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+### User Settings (`settings.json`) ###
+
+Open VS Code Settings (JSON) and add:
+
+```json
+{
+ "mcp": {
+ "servers": {
+ "solr-mcp": {
+ "type": "stdio",
+ "command": "java",
+ "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/"; }
+ }
+ }
+ }
+}
+```
+
+***
+
+## HTTP Mode ##
+
+Start the server first (see [Running the
Server](https://github.com/apache/solr-mcp#running-the-server)), then:
+
+```json
+{
+ "servers": {
+ "solr-mcp": {
+ "type": "http",
+ "url": "http://localhost:8080/mcp";
+ }
+ }
+}
+```
+
+The configuration is the same for secured and unsecured HTTP. VS Code handles
the MCP OAuth2 flow automatically.
+
+See the [VS Code MCP
documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for
the latest configuration format.
diff --git a/docs/site/content/pages/mcp/community.md
b/docs/site/content/pages/mcp/community.md
new file mode 100644
index 0000000..e2e5b9a
--- /dev/null
+++ b/docs/site/content/pages/mcp/community.md
@@ -0,0 +1,42 @@
+Title: Community
+URL: mcp/community.html
+save_as: mcp/community.html
+template: mcp/community
+
+## Support ##
+
+The Solr MCP community provides user support for free through the [users
mailing list](#mailing-lists-chat) and [slack channels](#slack).
+
+## Mailing Lists & Chat ##
+
+The Solr MCP server shares mailing lists with its parent project, Apache Solr.
+Available lists can be [found
here]({filename}/pages/community.md#mailing-lists-chat).
+
+#### Slack ####
+
+* The project's main Slack channel is `#solr-mcp` in the `the-asf`
organization.
+ Link: <https://the-asf.slack.com/archives/C09TVG3BM1P>
+
+## Issue tracker ##
+
+The Solr MCP Server uses [Github
issues](https://github.com/apache/solr-mcp/issues) in its repository for issue
tracking.
+
+## How To Contribute ##
+
+Looking to contribute to the Solr MCP Server? Read the
[CONTRIBUTING.md](https://github.com/apache/solr-mcp/blob/main/CONTRIBUTING.md)
instructions and join us.
+
+## Code of Conduct ##
+
+For a large and diverse community like ours to be friendly, welcoming and
respectful, we recognize the need for some guidelines. The project follows
[Apache's Code of Conduct
statement](https://www.apache.org/foundation/policies/conduct). Please take
some time to read and understand it.
+
+If you feel there has been a violation of this code, please point out your
concerns publicly in a friendly and matter of fact manner. Nonverbal
communication is prone to misinterpretation and misunderstanding. Everyone has
bad days and sometimes says things they regret later. Someone else's
communication style may clash with yours, but the difference can be amicably
resolved. After pointing out your concerns please be generous upon receiving an
apology.
+
+Should there be repeated instances of code of conduct violations, or if there
is an obvious and severe violation, the Solr PMC may become involved.
+
+### The Apache Way
+
+As an Apache project we strive to follow [The Apache
Way](http://theapacheway.com/). If you are new to the community or to open
source in general, you may benefit from understanding our core values as a
community, and why we operate the way we do.
+
+## Version Control ##
+
+The project's Git repository is found at https://github.com/apache/solr-mcp or
the mirror at https://gitbox.apache.org/repos/asf/solr-mcp.git
diff --git a/docs/site/content/pages/mcp/downloads.md
b/docs/site/content/pages/mcp/downloads.md
new file mode 100644
index 0000000..8e59896
--- /dev/null
+++ b/docs/site/content/pages/mcp/downloads.md
@@ -0,0 +1,5 @@
+Title: Downloads
+URL: mcp/downloads.html
+save_as: mcp/downloads.html
+template: mcp/downloads
+
diff --git a/docs/site/content/pages/mcp/features.md
b/docs/site/content/pages/mcp/features.md
new file mode 100644
index 0000000..6e96e5e
--- /dev/null
+++ b/docs/site/content/pages/mcp/features.md
@@ -0,0 +1,4 @@
+Title: Features
+URL: mcp/features.html
+save_as: mcp/features.html
+template: mcp/features
diff --git a/docs/site/content/pages/mcp/index.md
b/docs/site/content/pages/mcp/index.md
new file mode 100644
index 0000000..b9d9a79
--- /dev/null
+++ b/docs/site/content/pages/mcp/index.md
@@ -0,0 +1,4 @@
+Title: Welcome
+URL: mcp/index.html
+save_as: mcp/index.html
+template: mcp/index
diff --git a/docs/site/content/pages/mcp/licensing.md
b/docs/site/content/pages/mcp/licensing.md
new file mode 100644
index 0000000..d1bcb8f
--- /dev/null
+++ b/docs/site/content/pages/mcp/licensing.md
@@ -0,0 +1,98 @@
+Title: Licensing & Notices
+URL: mcp/licensing.html
+save_as: mcp/licensing.html
+template: mcp/licensing
+
+## Overview ##
+
+Apache Solr MCP Server is licensed under the **Apache License 2.0**. Because
the project is distributed in two different forms, it ships two different pairs
of `LICENSE` and `NOTICE` files, each describing what is actually in that form:
+
+| Form | Artifacts | Contains | LICENSE / NOTICE |
+|------|-----------|----------|------------------|
+| **Source** | the source tree, `-sources` / `-javadoc` jars | only
Apache-authored code | the base Apache-2.0 `LICENSE` + a minimal `NOTICE` |
+| **Binary** | the executable (fat) JAR and the Docker images built from it |
Apache code **plus** every bundled third-party dependency | the base files
**extended** with each bundled dependency's license and the notices those
dependencies require |
+
+This split follows the [ASF licensing
how-to](https://infra.apache.org/licensing-howto.html): a binary that bundles
other projects' code must tell recipients the license of every bundled
component, and must carry forward the attribution notices those components
require. The source release, which contains only Apache-authored code, needs
only the base files.
+
+***
+
+## Where the Files Live ##
+
+The **binary** `LICENSE` and `NOTICE` are bundled inside the executable JAR's
`META-INF/` directory, so they travel with every distribution:
+
+* **Executable JAR** — `META-INF/LICENSE` and `META-INF/NOTICE` inside
`solr-mcp-<version>.jar`.
+* **Docker images** — the same files, since both the Jib JVM image and
the native images package the JAR's contents. They are present on the classpath
at `META-INF/` in the running container.
+
+To read them straight out of a built artifact:
+
+```bash
+unzip -p solr-mcp-<version>.jar META-INF/LICENSE
+unzip -p solr-mcp-<version>.jar META-INF/NOTICE
+```
+
+The **source** `LICENSE` and `NOTICE` are the files at the root of the [source
repository](https://github.com/apache/solr-mcp) and are bundled, unchanged,
into the thin `jar`, `-sources`, and `-javadoc` artifacts.
+
+***
+
+## Building the Files ##
+
+The binary `LICENSE` and `NOTICE` are **generated during the build** —
they are not checked in, so they always match the exact set of dependencies
that ship. Any normal build produces them:
+
+```bash
+./gradlew build # full build (tests + the executable JAR)
+./gradlew bootJar # just the executable JAR
+```
+
+To generate only the two files for inspection, without assembling the JAR:
+
+```bash
+./gradlew generateBinaryLicense generateBinaryNotice
+```
+
+They are written to:
+
+```text
+build/generated/license/LICENSE
+build/generated/license/NOTICE
+```
+
+… and bundled into `META-INF/` of the executable JAR. The build
**fails** if a bundled dependency cannot be accounted for (see [How They Are
Constructed](#how-they-are-constructed)), so an incomplete `LICENSE` can never
be released by accident.
+
+***
+
+## How They Are Constructed ##
+
+Both files are assembled by a small Gradle convention plugin
(`org.apache.solr.mcp.license-notice`, in `buildSrc/`) from two tasks.
+
+### LICENSE ###
+
+`generateBinaryLicense` writes the full Apache-2.0 license text, followed by a
**third-party dependency appendix**. Each dependency that ships in the binary
is listed with the license it is distributed under and a link to that license's
text, for example:
+
+```text
+- org.apache.solr:solr-solrj:<version>
+ License: Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html
+- ch.qos.logback:logback-classic:<version>
+ License: EPL-2.0 — https://spdx.org/licenses/EPL-2.0.html
+ License: GNU Lesser General Public License —
https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+```
+
+The license for each dependency is taken from the project's
[SBOM](#role-of-the-sbom). Licenses are listed exactly as the SBOM reports
them: the appendix is a disclosure rather than a policy, so it applies no
allow-list and no manual corrections, and a few upstream labels may be
imprecise (they are always permissive). The link next to each entry points to
the authoritative license text.
+
+### NOTICE ###
+
+`generateBinaryNotice` writes the project's own `NOTICE`, followed by the
`NOTICE` files of the bundled dependencies that ship one — copied
**verbatim**, de-duplicated, and each attributed to the dependency it came
from. This satisfies the Apache-2.0 requirement to carry forward the
attribution notices of redistributed code, so the notices from bundled Apache
projects such as SolrJ are preserved automatically. It is intentionally limited
to **required** notices; it is not a general [...]
+
+***
+
+## Role of the SBOM ##
+
+The project also publishes a **CycloneDX Software Bill of Materials (SBOM)**
— a machine-readable inventory of every bundled component, with versions,
hashes, and licenses. It is generated by the `cyclonedxBom` task, embedded in
the executable JAR at `META-INF/sbom/application.cdx.json`, and served at
`/actuator/sbom/application` in HTTP mode.
+
+The SBOM and the `LICENSE`/`NOTICE` files play complementary roles:
+
+* The **SBOM** is the machine-readable inventory, designed for supply-chain
and security tooling — *what is in here, at which versions, under which
licenses?*
+* The **`LICENSE` and `NOTICE`** files are the human-readable legal artifacts
that the Apache License and ASF release policy require.
+
+They are connected: the binary `LICENSE` appendix is **generated from the
SBOM**, so the two never drift apart, and the appendix includes a pointer back
to the SBOM for the full machine-readable detail. The SBOM does **not** replace
`LICENSE`/`NOTICE` — in particular it has no concept of a `NOTICE` file,
so the required attribution notices are aggregated directly from the
dependencies instead.
+
+Unlike Apache Solr's main distribution, this project does **not** maintain a
per-dependency `licenses/` folder; the SBOM plus the generated appendix cover
the same ground with nothing to hand-maintain.
diff --git a/docs/site/content/pages/mcp/observability.md
b/docs/site/content/pages/mcp/observability.md
new file mode 100644
index 0000000..46da40b
--- /dev/null
+++ b/docs/site/content/pages/mcp/observability.md
@@ -0,0 +1,114 @@
+Title: Observability
+URL: mcp/observability.html
+save_as: mcp/observability.html
+template: mcp/observability
+
+## Overview ##
+
+When running in **HTTP mode**, the Solr MCP Server exports telemetry data via
OpenTelemetry to the **LGTM stack** (Loki, Grafana, Tempo, Mimir) for full
observability.
+
+| Signal | Backend | What it shows |
+|--------|---------|---------------|
+| **Traces** | Tempo | Distributed traces for every MCP tool invocation, Solr
query, and HTTP request |
+| **Metrics** | Mimir/Prometheus | JVM stats, HTTP request rates, Solr query
latencies, cache hit ratios |
+| **Logs** | Loki | Structured application logs correlated with trace IDs |
+
+Every MCP tool invocation creates a trace span: search, indexing (JSON, CSV,
XML), collection operations (list, stats, health, create), and schema
retrieval. All incoming HTTP requests and outgoing Solr calls are automatically
traced.
+
+***
+
+## Setup ##
+
+### Start the LGTM Stack ###
+
+The project's `compose.yaml` includes a Grafana OTEL LGTM all-in-one container:
+
+```bash
+docker compose up -d
+```
+
+This starts:
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| Grafana | http://localhost:3000 | Dashboards and exploration (no auth
required) |
+| OTLP gRPC | localhost:4317 | Trace/metric/log ingestion (gRPC) |
+| OTLP HTTP | localhost:4318 | Trace/metric/log ingestion (HTTP) |
+
+### Run the Server with Observability ###
+
+```bash
+PROFILES=http ./gradlew bootRun
+```
+
+The server auto-configures OTLP export when the LGTM stack is running. Default
configuration:
+
+```properties
+management.tracing.sampling.probability=1.0 # 100% sampling (dev)
+otel.exporter.otlp.endpoint=http://localhost:4317
+otel.exporter.otlp.protocol=grpc
+```
+
+***
+
+## Grafana ##
+
+Open [http://localhost:3000](http://localhost:3000) and click **Explore** in
the left sidebar.
+
+### View Traces (Tempo) ###
+
+1. Select **Tempo** as the data source
+2. Use TraceQL to search:
+
+ {.service.name="solr-mcp"}
+
+3. Click on a trace to see the span waterfall—each MCP tool invocation,
Solr query, and HTTP request is a separate span
+
+### View Logs (Loki) ###
+
+1. Select **Loki** as the data source
+2. Use LogQL to search:
+
+ {service_name="solr-mcp"} |= "search"
+
+3. Logs are automatically correlated with trace IDs—click a log line to
jump to its trace
+
+### View Metrics (Prometheus) ###
+
+1. Select **Prometheus** as the data source
+2. Example queries:
+
+ # HTTP request rate
+ rate(http_server_requests_seconds_count[5m])
+
+ # JVM memory usage
+ jvm_memory_used_bytes
+
+ # Request latency (p99)
+ histogram_quantile(0.99, rate(http_server_requests_seconds_bucket[5m]))
+
+***
+
+## Actuator Endpoints ##
+
+The following health and metrics endpoints are exposed in HTTP mode:
+
+```bash
+curl http://localhost:8080/actuator/health # Health check
+curl http://localhost:8080/actuator/info # Build info
+curl http://localhost:8080/actuator/metrics # Available metrics
+curl http://localhost:8080/actuator/prometheus # Prometheus scrape endpoint
+curl http://localhost:8080/actuator/loggers # Logger levels
+```
+
+***
+
+## Production Configuration ##
+
+For production, reduce the sampling rate and configure the OTLP endpoint for
your collector:
+
+```bash
+export OTEL_SAMPLING_PROBABILITY=0.1 # 10% sampling
+export OTEL_TRACES_URL=https://otel-collector.example.com:4317
+PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
+```
diff --git a/docs/site/content/pages/mcp/quick-start.md
b/docs/site/content/pages/mcp/quick-start.md
new file mode 100644
index 0000000..f31f06c
--- /dev/null
+++ b/docs/site/content/pages/mcp/quick-start.md
@@ -0,0 +1,132 @@
+Title: Quick Start
+URL: mcp/quick-start.html
+save_as: mcp/quick-start.html
+template: mcp/quick-start
+
+## Prerequisites ##
+
+* Java 25+ ([Eclipse Temurin](https://adoptium.net/) recommended)
+* [Docker](https://docs.docker.com/get-docker/) and Docker Compose
+* Apache Solr **8.11–10** (the bundled sample stack runs Solr 9; the server is
tested against 8.11, 9.4, 9.9, 9.10, and 10)
+* An MCP client — this guide uses [Claude
Desktop](https://claude.ai/download), but any MCP-compatible client works. See
[Adding to AI Clients](/mcp/clients/claude-desktop.html) for other options.
+
+## Start Solr with Sample Data ##
+
+Clone the repository and start Solr in SolrCloud mode:
+
+```bash
+git clone https://github.com/apache/solr-mcp.git
+cd solr-mcp
+docker compose up -d
+```
+
+This starts Solr with ZooKeeper and creates two sample collections pre-loaded
with data:
+
+* **films** — 1,100+ movie records with titles, directors, genres, and
release dates
+* **books** — empty collection ready for indexing
+
+Wait ~30 seconds for Solr to fully initialize. Verify at
[http://localhost:8983/solr/](http://localhost:8983/solr/).
+
+## Build the Server ##
+
+```bash
+./gradlew build
+```
+
+This produces `build/libs/solr-mcp-1.0.0-SNAPSHOT.jar`.
+
+## Configure Your MCP Client ##
+
+Add the following to your Claude Desktop configuration file:
+
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "java",
+ "args": ["-jar",
"/absolute/path/to/solr-mcp/build/libs/solr-mcp-1.0.0-SNAPSHOT.jar"],
+ "env": { "SOLR_URL": "http://localhost:8983/solr/"; }
+ }
+ }
+}
+```
+
+Restart Claude Desktop after saving.
+
+**Alternatively**, you can use a local Docker image:
+
+```bash
+./gradlew jibDockerBuild
+```
+
+Then configure Claude Desktop with:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest"]
+ }
+ }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the
args array.
+
+## Native Image (experimental) ##
+
+Opt-in GraalVM native image builds are available for both **STDIO** and
**HTTP** transports. Native binaries start in milliseconds and use
substantially less memory than the JVM image. Spring AOT bakes a
profile-specific bean graph at build time, so each native image is
single-transport — pick the one that matches your client.
+
+```bash
+# Build the native STDIO image
+./gradlew bootBuildImage -Pnative
+# Produces: solr-mcp:1.0.0-SNAPSHOT-native-stdio (also tagged
:latest-native-stdio)
+
+# Build the native HTTP image
+./gradlew bootBuildImage -Pnative -Pprofile=http
+# Produces: solr-mcp:1.0.0-SNAPSHOT-native-http (also tagged
:latest-native-http)
+```
+
+Configure Claude Desktop with the native STDIO image:
+
+```json
+{
+ "mcpServers": {
+ "solr-mcp": {
+ "command": "docker",
+ "args": ["run", "-i", "--rm",
+ "-e", "SOLR_URL=http://host.docker.internal:8983/solr/";,
+ "solr-mcp:latest-native-stdio"]
+ }
+ }
+}
+```
+
+For dual-transport support from a single image (e.g. switch between modes via
`PROFILES` env var without rebuilding), use the JVM Jib image above. The JVM
image trades startup time and memory footprint for transport flexibility.
+
+## Try It Out ##
+
+Open Claude Desktop and try these prompts:
+
+* *"Search the films collection for movies directed by Steven Spielberg"*
+* *"What collections are available in Solr?"*
+* *"Show me the schema for the films collection"*
+* *"Find all sci-fi movies released after 2000 and show the genre breakdown"*
+* *"Index this JSON into the books collection: [{"id": "1", "title": "The
Great Gatsby", "author": "F. Scott Fitzgerald"}]"*
+
+**Tip:** clients that support MCP completions autocomplete collection names —
for the `{collection}` in the `solr://{collection}/schema` resource and for the
`collection` argument of the `search-collection`, `index-data`, `view-schema`,
and `design-schema` prompts.
+
+***
+
+## Next Steps ##
+
+* **[Adding to AI Clients](/mcp/clients/claude-desktop.html)** —
configure Claude Code, VS Code, Cursor, JetBrains, or MCP Inspector
+* **[Features](/mcp/features.html)** — explore all available tools and
resources
+* **[Security](/mcp/security.html)** — set up OAuth2 authentication for
HTTP mode
+* **[Observability](/mcp/observability.html)** — enable tracing,
metrics, and logging
diff --git a/docs/site/content/pages/mcp/resources.md
b/docs/site/content/pages/mcp/resources.md
new file mode 100644
index 0000000..a64b238
--- /dev/null
+++ b/docs/site/content/pages/mcp/resources.md
@@ -0,0 +1,48 @@
+Title: Resources
+URL: mcp/resources.html
+save_as: mcp/resources.html
+template: mcp/resources
+
+## Guides ##
+
+* **[Quick Start](/mcp/quick-start.html)** — get from zero to a working
AI + Solr integration in under 2 minutes
+* **[Security (OAuth2)](/mcp/security.html)** — Auth0 and Keycloak setup
for HTTP mode
+* **[Observability](/mcp/observability.html)** — traces, metrics, and
logs via the LGTM stack
+* **[Licensing & Notices](/mcp/licensing.html)** — where the binary
LICENSE/NOTICE live, how they are built, and the role of the SBOM
+
+## Documentation ##
+
+* [README](https://github.com/apache/solr-mcp#readme) — quick start,
client configurations, and usage overview
+* [CONTRIBUTING](https://github.com/apache/solr-mcp/blob/main/CONTRIBUTING.md)
— pull request process and commit conventions
+*
[Architecture](https://github.com/apache/solr-mcp/blob/main/dev-docs/ARCHITECTURE.md)
— project structure and design decisions
+* [Development
Guide](https://github.com/apache/solr-mcp/blob/main/dev-docs/DEVELOPMENT.md)
— build system, testing, and IDE setup
+* [Auth0
Setup](https://github.com/apache/solr-mcp/blob/main/docs/security/auth0.md)
— detailed OAuth2 setup with Auth0
+* [Keycloak
Setup](https://github.com/apache/solr-mcp/blob/main/docs/security/keycloak.md)
— detailed OAuth2 setup with Keycloak
+
+***
+
+## References ##
+
+### MCP Protocol ###
+
+* [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
+* [MCP GitHub Organization](https://github.com/modelcontextprotocol)
+* [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+
+### Spring AI MCP ###
+
+* [Spring AI MCP Server (Spring
Boot)](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot.html)
+* [Spring AI MCP Project](https://spring.io/projects/spring-ai)
+* [Spring AI Community MCP
Security](https://github.com/spring-ai-community/mcp-security)
+
+### Apache Solr ###
+
+* [Apache Solr Documentation](https://solr.apache.org/guide/)
+* [SolrJ Client
Library](https://solr.apache.org/guide/solr/latest/deployment-guide/solrj.html)
+
+### Tools and Libraries ###
+
+* [Jib (Docker image builder)](https://github.com/GoogleContainerTools/jib)
+* [Testcontainers](https://www.testcontainers.org/)
+* [OpenTelemetry](https://opentelemetry.io/)
+* [Grafana LGTM Stack](https://github.com/grafana/docker-otel-lgtm)
diff --git a/docs/site/content/pages/mcp/security.md
b/docs/site/content/pages/mcp/security.md
new file mode 100644
index 0000000..e9e399e
--- /dev/null
+++ b/docs/site/content/pages/mcp/security.md
@@ -0,0 +1,175 @@
+Title: Security
+URL: mcp/security.html
+save_as: mcp/security.html
+template: mcp/security
+
+## Overview ##
+
+When running in HTTP mode, the Solr MCP Server supports **OAuth2
authentication** with JWT token validation. Security is **enabled by default**
in HTTP mode — point it at an OAuth2 issuer to use it, or disable it for
local development.
+
+* **Protocol**: OAuth2 Resource Server with JWT validation
+* **Supported providers**: Auth0, Keycloak, Okta, or any OAuth2/OIDC provider
+* **STDIO mode**: Security is not applicable (OS-level process isolation)
+* **HTTP mode**: **Secured by default** — set `OAUTH2_ISSUER_URI` to
wire up a provider; disable for local dev only with
`HTTP_SECURITY_ENABLED=false`
+
+### Configure Security ###
+
+HTTP mode is secured by default — you only need to point it at an OAuth2
issuer:
+
+```bash
+export PROFILES=http
+export OAUTH2_ISSUER_URI=https://your-provider.example.com/
+./gradlew bootRun
+```
+
+Or with Docker (local image — build first with `./gradlew
jibDockerBuild`):
+
+```bash
+docker run -p 8080:8080 --rm \
+ -e PROFILES=http \
+ -e OAUTH2_ISSUER_URI=https://your-provider.example.com/ \
+ -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+ solr-mcp:latest
+```
+
+To turn authentication **off** for local development, set
`HTTP_SECURITY_ENABLED=false`.
+
+***
+
+## Auth0 ##
+
+### 1. Create Auth0 Application ###
+
+1. Go to [Auth0 Dashboard](https://manage.auth0.com/) > **Applications** >
**Create Application**
+2. Name: `Solr MCP Server`
+3. Type: **Machine to Machine Applications**
+4. Note your **Domain**, **Client ID**, and **Client Secret**
+
+### 2. Create Auth0 API ###
+
+1. Navigate to **Applications** > **APIs** > **Create API**
+2. Name: `Solr MCP API`
+3. Identifier (audience): `https://solr-mcp-api`
+4. Signing Algorithm: **RS256**
+
+### 3. Configure Callback URLs ###
+
+In your application settings, add to **Allowed Callback URLs**:
+
+
http://localhost:6274/oauth/callback,http://localhost:3334/oauth/callback,http://localhost:8080/login/oauth2/code/auth0
+
+Each callback URL serves a different client:
+
+* `http://localhost:6274/oauth/callback` — MCP Inspector
+* `http://localhost:3334/oauth/callback` — `mcp-remote` (Claude Desktop,
VS Code, Cursor, JetBrains in HTTP mode)
+* `http://localhost:8080/login/oauth2/code/auth0` — Direct server OAuth2
code flow
+
+### 4. Run the Server ###
+
+```bash
+export PROFILES=http
+export OAUTH2_ISSUER_URI=https://your-tenant.auth0.com/
+./gradlew bootRun
+```
+
+### 5. Get an Access Token ###
+
+```bash
+curl --request POST \
+ --url https://your-tenant.auth0.com/oauth/token \
+ --header 'content-type: application/json' \
+ --data '{
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "audience": "https://solr-mcp-api";,
+ "grant_type": "client_credentials"
+ }'
+```
+
+Or use the convenience script:
+
+```bash
+./scripts/get-auth0-token.sh \
+ --domain your-tenant.auth0.com \
+ --client-id YOUR_CLIENT_ID \
+ --client-secret YOUR_CLIENT_SECRET \
+ --audience https://solr-mcp-api
+```
+
+### 6. Use the Token ###
+
+```bash
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+ http://localhost:8080/mcp
+```
+
+For the full step-by-step guide, see [Auth0 Setup
Guide](https://github.com/apache/solr-mcp/blob/main/docs/security/auth0.md).
+
+***
+
+## Keycloak ##
+
+### 1. Start Keycloak ###
+
+```bash
+docker run -d --name keycloak \
+ -p 8180:8080 \
+ -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+ -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
+ quay.io/keycloak/keycloak:26.0 start-dev
+```
+
+Access the admin console at `http://localhost:8180` (login: `admin` / `admin`).
+
+### 2. Create Realm and Client ###
+
+1. Create realm: `solr-mcp`
+2. Create client:
+ * Client ID: `solr-mcp-client`
+ * Client type: OpenID Connect
+ * Client authentication: OFF (public client)
+ * Valid redirect URIs: `http://localhost:6274/*`,
`http://localhost:3334/*`, `http://localhost:8080/*`
+ * Web origins: `*`
+
+### 3. Create Test User ###
+
+1. Navigate to **Users** > **Add user**
+2. Username: `testuser`, Email verified: ON
+3. Set password in **Credentials** tab
+
+### 4. Run the Server ###
+
+```bash
+export PROFILES=http
+export OAUTH2_ISSUER_URI=http://localhost:8180/realms/solr-mcp
+./gradlew bootRun
+```
+
+### 5. Get a Token ###
+
+```bash
+curl -X POST
"http://localhost:8180/realms/solr-mcp/protocol/openid-connect/token"; \
+ -H "Content-Type: application/x-www-form-urlencoded" \
+ -d "client_id=solr-mcp-client" \
+ -d "username=testuser" \
+ -d "password=yourpassword" \
+ -d "grant_type=password"
+```
+
+For the full guide including role-based access control and production
deployment, see [Keycloak Setup
Guide](https://github.com/apache/solr-mcp/blob/main/docs/security/keycloak.md).
+
+***
+
+## How OAuth2 Works with MCP Clients ##
+
+When a client connects to a secured Solr MCP Server:
+
+1. Client connects to `/mcp`
+2. Server responds with `401` + OAuth2 metadata
+3. Client discovers the authorization server from
`/.well-known/oauth-authorization-server`
+4. Client opens a browser for login/consent
+5. Client receives an authorization code, exchanges it for an access token
(JWT)
+6. Client attaches the Bearer token to all subsequent MCP requests
+7. Server validates the JWT with the OAuth2 provider
+
+Most MCP clients handle this flow transparently—the configuration is the
same for secured and unsecured HTTP servers. See the individual [client setup
pages](/mcp/clients/claude-desktop.html) for details.
diff --git
a/docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md
b/docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md
new file mode 100644
index 0000000..5d4712d
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-09-license-notice-and-docs-deploy-design.md
@@ -0,0 +1,161 @@
+# Design: Binary-release LICENSE/NOTICE tooling + docs-in-code-repo deploy
+
+Date: 2026-06-09
+Author: adityamparikh (with Claude)
+Addresses:
+- apache/solr-mcp#138 review comment
[`r3361858982`](https://github.com/apache/solr-mcp/pull/138#discussion_r3361858982)
+ follow-up `r3383830232`
+- apache/solr-site#175 comment
[`4664039372`](https://github.com/apache/solr-site/pull/175#issuecomment-4664039372)
+
+These are two independent deliverables tracked in one spec because they were
raised together.
+
+---
+
+## Deliverable 1 — Binary-release LICENSE/NOTICE (solr-mcp)
+
+### Problem
+
+PR #138 adds the base Apache-2.0 `LICENSE` and a minimal `NOTICE`, and bundles
them
+into the `META-INF/` of every jar. Per
+[infra.apache.org/licensing-howto](https://infra.apache.org/licensing-howto.html):
+
+- For the **source release**, those base files are correct — the source tree
contains
+ only ASF-authored code under Apache-2.0.
+- For a **binary release**, the artifact bundles third-party bytecode, so:
+ - `LICENSE` must additionally enumerate every bundled non-Apache dependency
and
+ point to its license (a link, not the full license text).
+ - `NOTICE` must lift the relevant NOTICE snippets of bundled
**Apache-licensed**
+ dependencies (notably other ASF projects such as SolrJ).
+
+The project's binary artifact is the Spring Boot fat jar (`bootJar`) — it
embeds every
+runtime dependency. There is no tgz/`distZip`/`installDist` packaging, so
"binary
+release" == the `bootJar`. (An SBOM was added on a separate branch; per JanHoy
it is
+complementary, not a substitute for LICENSE/NOTICE.)
+
+### Approach — SBOM-driven, in a buildSrc convention plugin
+
+> **As shipped (PR #138).** An earlier draft generated the appendix with the
+> `com.github.jk1.dependency-license-report` plugin plus a hand-kept
supplement for the
+> Gradle-module-metadata-only ASF artifacts (SolrJ) that the POM-only plugin
silently
+> drops. We instead **derive the appendix from the CycloneDX SBOM** (PR #142),
which
+> already resolves a license for every component including SolrJ — so no
supplement is
+> needed and there is a single source of dependency data. PR #138 is therefore
stacked
+> on #142.
+
+Implemented as the `org.apache.solr.mcp.license-notice` convention plugin under
+`buildSrc/`, with two typed tasks. The root `build.gradle.kts` only applies
the plugin.
+
+1. **`GenerateBinaryLicense`.** Reads the CycloneDX SBOM
+ (`build/reports/application.cdx.json`, the same SBOM embedded in the
bootJar at
+ `META-INF/sbom/application.cdx.json`), indexes each component's licenses by
+ `group:name(:version)`, and emits the binary `LICENSE` = base Apache-2.0 +
an appendix
+ of every shipped dependency and a link to its license. "Shipped" = the
resolved
+ `productionRuntimeClasspath` (excludes test/compile-only and
`developmentOnly` deps).
+2. **`GenerateBinaryNotice`.** Builds the binary `NOTICE` = base NOTICE + the
+ `META-INF/NOTICE` files lifted verbatim and de-duplicated from the bundled
jars (the
+ Maven-Shade `ApacheNoticeResourceTransformer` approach), so ASF dependency
notices are
+ carried and stay current with no hand-maintained snippets.
+3. **`metaInf` wiring.** The `bootJar` bundles the generated LICENSE/NOTICE;
the plain
+ `jar`, sources, and javadoc jars keep the source-form base files.
+4. **Licenses are disclosed as-reported.** The appendix is a disclosure, not a
license
+ policy. Licenses are listed exactly as the SBOM declares them — **no
allow-list and no
+ corrections** — so a few imprecise-but-permissive upstream labels appear
as-is
+ (`mcp-server-security` → `Apache-1.0`; ANTLR `ST4`/`antlr-runtime` →
+ `BSD-4-Clause`/`BSD licence`); the preamble notes this and links each
license. apache/solr
+ itself keeps no allow-list (it uses a per-dependency `solr/licenses/`
folder, which
+ JanHoy said not to replicate), so neither do we.
+5. **Completeness gate.** The only gate: `generateBinaryLicense` runs as part
of
+ `check`/`build` and **fails if a shipped dependency is absent from the
SBOM**, so a
+ dependency can never be silently omitted from the LICENSE. This is JanHoy's
"check that
+ newly added deps are accounted for"; it makes no judgement about license
acceptability.
+6. **Tests.** The two tasks are unit-tested with `ProjectBuilder`
+ (`buildSrc/src/test/kotlin/.../LicenseNoticeTasksTest.kt`): appendix
listing, SBOM
+ name/URL handling, the completeness gate, and NOTICE de-duplication.
`buildSrc`'s
+ `test` runs in `./gradlew build`.
+6. **Verify.** `./gradlew build`, then
+ `unzip -p build/libs/solr-mcp-<v>.jar META-INF/LICENSE` / `...
META-INF/NOTICE`
+ to confirm the appendix and lifted notices are present in the fat jar.
+
+### Out of scope (YAGNI)
+
+- No Solr-style per-dependency `licenses/` folder — JanHoy explicitly said the
rigid
+ version is unnecessary.
+- No tgz packaging — the project does not ship one; "binary release" == the
`bootJar`.
+- The source-form `LICENSE`/`NOTICE` are already correct and unchanged.
+
+### Files touched
+
+- `buildSrc/` — the `org.apache.solr.mcp.license-notice` convention plugin and
the
+ `GenerateBinaryLicense` / `GenerateBinaryNotice` typed tasks (+ their unit
tests).
+- `build.gradle.kts` — applies `id("org.apache.solr.mcp.license-notice")`
(after the
+ Spring Boot + CycloneDX plugins).
+- `AGENTS.md` — "Release LICENSE / NOTICE" section.
+- Depends on PR #142 (CycloneDX SBOM) for the `cyclonedxBom` task and plugin.
+
+---
+
+## Deliverable 2 — Docs source in code repo, deployed to site (solr-mcp +
solr-site)
+
+### Problem
+
+JanHoy wants the MCP docs to live in the **solr-mcp** repo (so every feature
PR carries
+its documentation update) but still be **deployed to the Solr site**. The Solr
ref guide
+does this by building the static site elsewhere and copying the output into a
location
+mounted into the web server via `.htaccess`.
+
+### Constraint discovered
+
+solr-site is a **Pelican** site (`pelican content -o output`, published via ASF
+`.asf.yaml` — `main`/`production` protected branches, `asf-staging`). PR #175
splits
+cleanly into two layers:
+
+- **Content** (the docs *source*): `content/pages/mcp/*.md`,
+ `content/pages/mcp/clients/*.md`, `content/doap/solr-mcp.rdf` — plain
markdown with
+ Pelican front-matter.
+- **Presentation** (the site's rendering layer):
`themes/solr/templates/mcp/*.html`,
+ `themes/solr/static/css/mcp.css`, `pelicanconf.py`, shared header/index
edits.
+
+The content reuses the solr-site theme. A fully standalone build inside
solr-mcp would
+have to vendor that theme and drift from the rest of the site.
+
+### Approach — solr-site pulls content from solr-mcp at build time
+
+Keep one themed Pelican build in solr-site; make solr-mcp the source of truth
for the
+**content** layer only.
+
+1. **solr-mcp** owns the markdown. Move the content layer into
+ `solr-mcp/docs/site/content/` (markdown + DOAP). Feature PRs edit docs here
alongside
+ code. A `docs/site/README.md` explains that these files are assembled into
the Solr
+ site at build time.
+2. **solr-site** keeps the presentation layer (templates, CSS,
`pelicanconf.py`).
+3. **Assembly at build time.** solr-site's `build.sh` (and the CI build)
fetches the
+ `docs/site/content/` tree from solr-mcp at a **pinned ref** (a release tag,
falling
+ back to `main`) and copies it into `content/pages/mcp/` (and the DOAP into
+ `content/doap/`) before running Pelican. Implemented as a `fetch_mcp_docs`
step:
+ shallow `git clone --depth 1 --branch <ref>` of solr-mcp into a temp dir,
`rsync`
+ the content into place. The pinned ref lives in one variable in `build.sh` /
+ `pelicanconf.py` so bumping the published docs version is a one-line change.
+4. **Remove** the moved markdown from solr-site so there is a single source of
truth;
+ leave a short note in solr-site explaining where MCP content now comes from.
+
+This mirrors the ref-guide model (content built/owned elsewhere, assembled
into the
+site) while keeping the shared theme and a single Pelican build.
+
+### Rejected alternative
+
+**solr-mcp pushes built static HTML** into a `/mcp/` subdir of solr-site's
`production`
+branch via a release Action. Closest literal match to the `.htaccess`-mounted
ref-guide
+output, but requires vendoring the Pelican theme in solr-mcp (drift) and a
cross-repo
+push token. Rejected in favor of the pull model.
+
+### Files touched
+
+- **solr-mcp:** add `docs/site/content/**` (moved markdown + DOAP),
`docs/site/README.md`.
+- **solr-site:** `build.sh` (+ CI workflow) gains a `fetch_mcp_docs` step;
remove
+ `content/pages/mcp/**` and `content/doap/solr-mcp.rdf`; keep
theme/templates/CSS/
+ `pelicanconf.py`; add a note documenting the source-of-truth.
+
+### Sequencing / review
+
+This spans two repos and changes how an in-review PR (#175) is structured, so
the
+mechanism is proposed to JanHoy (reply on #175) and the cross-repo changes are
staged on
+branches for review — nothing is pushed to the public PRs without maintainer
sign-off.
