docs(site): host MCP documentation content in-repo, deployed to solr-site at build time

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.

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:dev@solr.apache.org"/>
+      </foaf:Person>
+    </maintainer>
+    <!-- NOTE: please insert releases in numeric order, NOT chronologically. -->
+  </Project>
+</rdf:RDF>

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.

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.