Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
epugh wants to merge 8 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
19216a5
until we publish docker images.... lets show the clone
epugh Jun 13, 2026
2a7012d
Move dev oritented docs on publishing to dev guide
epugh Jun 13, 2026
4eb8bae
SBOM generation locally is a development task
epugh Jun 13, 2026
15a5e1b
be truthful about our lack of published images
epugh Jun 13, 2026
74f1391
keep the good parts!
epugh Jun 13, 2026
5604952
Add native compile docs
epugh Jun 13, 2026
fa2a0e5
consoildate all security related docs under docs/security
epugh Jun 13, 2026
c204064
from pr 95
epugh Jun 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ We use Spotless for code formatting and style enforcement. CI enforces `spotless
- Include unit tests for new features
- Keep methods focused and concise

### Null safety

Every package is `@NullMarked` via `package-info.java`. Methods, parameters, and return types are non-null by default — mark legitimate null surfaces with `@Nullable` (`org.jspecify.annotations.Nullable`). [NullAway](https://github.com/uber/NullAway) enforces the contract on `compileJava`; new code that violates it fails the build. Reference: [JSpecify](https://jspecify.dev/).

## Testing

To keep this document concise, please see the Development Guide for all testing workflows and tips:
Expand Down Expand Up @@ -137,15 +141,23 @@ For implementation details and examples, see the Development Guide:
- Dependencies and version catalogs: dev-docs/DEVELOPMENT.md#build-system
- Documentation practices: dev-docs/DEVELOPMENT.md#modifying-configuration

## Security Setup (HTTP Mode)

For OAuth2 configuration with supported providers:

- [Auth0 Setup Guide](docs/security/auth0.md)
- [Keycloak Setup Guide](docs/security/keycloak.md)

## Questions or Need Help?

- Open an issue for bugs or feature requests
- Start a discussion for questions or ideas
- Check existing issues and discussions first
- **Slack:** [`#solr-mcp`](https://the-asf.slack.com/archives/C09TVG3BM1P) in the `the-asf` workspace
- **Issues:** [GitHub Issues](https://github.com/apache/solr-mcp/issues) for bugs or feature requests
- **Discussions:** [GitHub Discussions](https://github.com/apache/solr-mcp/discussions) for questions or ideas
- **Mailing lists:** Shared with Apache Solr — see [mailing lists](https://solr.apache.org/community.html#mailing-lists-chat)

## Code of Conduct

Be respectful, inclusive, and professional. We're all here to build something great together.
As an Apache project, we follow the [Apache Code of Conduct](https://www.apache.org/foundation/policies/conduct).

## License

Expand Down
216 changes: 193 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,24 @@

# Solr MCP Server

A Spring AI Model Context Protocol (MCP) server that provides tools for interacting with Apache Solr. Enables AI assistants like Claude to search, index, and manage Solr collections through the MCP protocol.
Search, index, and manage [Apache Solr](https://solr.apache.org/) collections using **natural language** — no need to hand-craft Solr queries, build filter expressions, or memorize the admin API.

Instead of writing:

```
q=title:"star wars" AND genre_s:"sci-fi"&fq=year_i:[2000 TO *]&facet=true&facet.field=genre_s&sort=score desc&rows=10
```

Just ask your AI assistant:

> *"Find sci-fi movies with 'star wars' in the title released after 2000, show me the genre breakdown, and sort by relevance."*

This Spring AI [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) server exposes Solr operations as tools that any MCP-compatible AI client (Claude Desktop, Claude Code, VS Code/Copilot, Cursor, JetBrains) can invoke.

**[Website](https://solr.apache.org/mcp)** ·
**[Quick Start](https://solr.apache.org/mcp/quick-start.html)** ·
**[Client Setup](https://solr.apache.org/mcp/clients/claude-desktop.html)** ·
**[Features](https://solr.apache.org/mcp/features.html)**

## What's inside

Expand All @@ -13,11 +30,17 @@ A Spring AI Model Context Protocol (MCP) server that provides tools for interact
- 🔧 Inspect schema
- 🔌 Transports: STDIO (Claude Desktop) and HTTP (MCP Inspector)
- 🔐 OAuth2 security with Auth0 (HTTP mode only)
- 🐳 Docker images built with Jib
- 🐳 Docker images built locally with Jib (JVM) and Paketo (native)

## Get started (users)

> **Note:** Published container images are not yet available on a public registry. The `docker run` examples below use a **locally built** image — build it first with `./gradlew jibDockerBuild` (produces `solr-mcp:latest`), or use the JAR path instead. See [Building Docker images](#building-docker-images).

- Prerequisites: Java 25+, Docker (and Docker Compose), Git
- Clone the repo:
```bash
git clone https://github.com/apache/solr-mcp.git && cd solr-mcp
```
- Start Solr with sample data:
```bash
docker compose up -d
Expand All @@ -35,7 +58,7 @@ A Spring AI Model Context Protocol (MCP) server that provides tools for interact
```
- Docker:
```bash
docker run -i --rm ghcr.io/apache/solr-mcp:latest
docker run -i --rm solr-mcp:latest
```
- **HTTP mode**:
- Gradle:
Expand All @@ -48,10 +71,10 @@ A Spring AI Model Context Protocol (MCP) server that provides tools for interact
```
- Docker:
```bash
docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest
docker run -p 8080:8080 --rm -e PROFILES=http solr-mcp:latest
```

For more options (custom SOLR_URL, Linux host networking) see the Deployment Guide: docs/DEPLOYMENT.md
For more options (custom SOLR_URL, Linux host networking) see the [Deployment Guide](dev-docs/DEPLOYMENT.md).

### Claude Desktop

Expand All @@ -65,7 +88,7 @@ Using Docker:
"mcpServers": {
"solr-mcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
"args": ["run", "-i", "--rm", "solr-mcp:latest"],
"env": {
"SOLR_URL": "http://localhost:8983/solr/"
}
Expand Down Expand Up @@ -107,7 +130,7 @@ Using Docker:
"-p",
"8080:8080",
"--rm",
"ghcr.io/apache/solr-mcp:latest"
"solr-mcp:latest"
],
"env": {
"PROFILES": "http",
Expand Down Expand Up @@ -158,7 +181,7 @@ PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
Running via Docker:

```bash
docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest
docker run -p 8080:8080 --rm -e PROFILES=http solr-mcp:latest
```

Then add to your `claude_desktop_config.json`:
Expand Down Expand Up @@ -187,7 +210,7 @@ Add Solr MCP to [Claude Code](https://docs.anthropic.com/en/docs/claude-code) us

Using Docker (CLI):
```bash
claude mcp add --transport stdio solr-mcp -- docker run -i --rm ghcr.io/apache/solr-mcp:latest
claude mcp add --transport stdio solr-mcp -- docker run -i --rm solr-mcp:latest
```

Using JAR (CLI):
Expand All @@ -204,7 +227,7 @@ Using Docker:
"solr-mcp": {
"type": "stdio",
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
"args": ["run", "-i", "--rm", "solr-mcp:latest"],
"env": {
"SOLR_URL": "http://localhost:8983/solr/"
}
Expand Down Expand Up @@ -240,7 +263,7 @@ PROFILES=http ./gradlew bootRun
PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar

# Docker
docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest
docker run -p 8080:8080 --rm -e PROFILES=http solr-mcp:latest
```

Then add to Claude Code:
Expand All @@ -260,6 +283,139 @@ Or add to `.mcp.json`:
}
```

### Other clients

<details>
<summary><strong>VS Code / GitHub Copilot</strong></summary>

Create `.vscode/mcp.json` in your project root:

**STDIO mode** (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/" }
}
}
}
```

**HTTP mode:**

```json
{
"servers": {
"solr-mcp": {
"type": "sse",
"url": "http://localhost:8080/mcp"
}
}
}
```

After adding the configuration, Solr MCP tools are available in GitHub Copilot Chat (Agent mode).

</details>

<details>
<summary><strong>Cursor</strong></summary>

Create `.cursor/mcp.json` in your project root:

**STDIO mode** (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/" }
}
}
}
```

**HTTP mode:**

```json
{
"mcpServers": {
"solr-mcp": {
"url": "http://localhost:8080/mcp"
}
}
}
```

Or use **Cursor Settings > Features > MCP Servers > Add New MCP Server**.

</details>

<details>
<summary><strong>JetBrains IDEs</strong></summary>

Create `.junie/mcp.json` in your project root:

**STDIO mode** (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/" }
}
}
}
```

**HTTP mode:**

```json
{
"mcpServers": {
"solr-mcp": {
"url": "http://localhost:8080/mcp"
}
}
}
```

Or use **Settings > Tools > AI Assistant > MCP Servers > Add**.

</details>

<details>
<summary><strong>MCP Inspector</strong></summary>

```bash
npx @modelcontextprotocol/inspector
```

**HTTP:** connect to `http://localhost:8080/mcp`

**STDIO:** command `java`, arguments `-jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`

</details>

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `SOLR_URL` | Solr base URL | `http://localhost:8983/solr/` |
| `PROFILES` | Transport mode: `stdio` or `http` | `stdio` |
| `SECURITY_ENABLED` | Enable OAuth2 authentication (HTTP only) | `false` |
| `OAUTH2_ISSUER_URI` | OAuth2 issuer URL (Auth0, Keycloak, Okta) | — |
| `OTEL_SAMPLING_PROBABILITY` | Tracing sampling rate (0.0–1.0) | `1.0` |
| `OTEL_TRACES_URL` | OTLP collector endpoint | `http://localhost:4317` |

## Security (OAuth2)

The Solr MCP server supports OAuth2 authentication when running in HTTP mode, providing secure access control for your
Expand All @@ -274,7 +430,7 @@ MCP tools.

### Quick Setup

1. **Configure Auth0** (see detailed guide: [security-docs/AUTH0_SETUP.md](security-docs/AUTH0_SETUP.md))
1. **Configure Auth0** (see detailed guide: [docs/security/auth0.md](docs/security/auth0.md))
- Create an Auth0 Application (Machine to Machine)
- Create an Auth0 API with your audience identifier
- Note your Domain, Client ID, Client Secret, and Audience
Expand Down Expand Up @@ -304,7 +460,7 @@ MCP tools.
http://localhost:8080/mcp
```

For complete setup instructions, see [security-docs/AUTH0_SETUP.md](security-docs/AUTH0_SETUP.md)
For complete setup instructions, see [docs/security/auth0.md](docs/security/auth0.md)

## Available MCP tools

Expand Down Expand Up @@ -339,6 +495,8 @@ For complete setup instructions, see [security-docs/AUTH0_SETUP.md](security-doc
| `add-fields` | Add one or more fields to a Solr collection schema (additive only; existing fields cannot be modified) |
| `get-schema` | Retrieve schema information for a collection |

Every tool advertises MCP behavior hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients can build sensible approval UX — `search` and the metadata tools are read-only, indexing is destructive but idempotent, schema modification is additive.

## Available MCP Resources

MCP Resources provide a way to expose data that can be read by MCP clients. The Solr MCP Server provides the following resources:
Expand All @@ -356,6 +514,19 @@ The `solr://{collection}/schema` resource supports autocompletion for the `{coll

![MCP Inspector Resource Completion](images/mcp-inspector-resource-completion.png)

## Available MCP Prompts

Slash-command-style workflow templates. The framework wraps each prompt's return value as a single user-role `PromptMessage` directing the LLM through a canonical Solr workflow.

| Prompt | Arguments | Purpose |
|---|---|---|
| `explore-collections` | — | Read-only walkthrough: list collections and characterise each by stats and health |
| `setup-collection` | `name`, `purpose` (optional) | Validate a name, pick configset / shards / replication factor, create the collection, verify it |
| `view-schema` | `collection` | Read-only schema walkthrough |
| `design-schema` | `collection`, `datasetDescription`, `sampleDocument` (optional) | Inspect schema, choose field types, apply additive schema changes |
| `index-data` | `collection`, `format` (`json` / `csv` / `xml`), `sample` (optional) | Verify the target schema, pick the right indexing tool, confirm the result |
| `search-collection` | `collection`, `question` | Translate a natural-language question into a Solr query |

## Screenshots

- Claude Desktop (STDIO):
Expand Down Expand Up @@ -472,12 +643,7 @@ From a running HTTP-mode server:
curl -s http://localhost:8080/actuator/sbom/application > application.cdx.json
```

From the local build (no server required):

```bash
./gradlew cyclonedxBom
cat build/reports/application.cdx.json
```
To generate the SBOM locally from source, see [dev-docs/DEVELOPMENT.md#generating-the-sbom-locally](dev-docs/DEVELOPMENT.md#generating-the-sbom-locally).

### Scan the SBOM

Expand All @@ -493,7 +659,8 @@ Both tools natively consume CycloneDX 1.6 and report CVEs against the listed com

## Documentation

- [Auth0 Setup (OAuth2 configuration)](security-docs/AUTH0_SETUP.md)
- Security model: [STDIO transport](docs/security/stdio.md) · [HTTP transport](docs/security/http.md)
- OAuth2 provider setup: [Auth0](docs/security/auth0.md) · [Keycloak](docs/security/keycloak.md)
- [GraalVM native image spec](docs/specs/graalvm-native-image.md)

## Contributing
Expand All @@ -502,10 +669,13 @@ We welcome contributions!

- Start here: [CONTRIBUTING.md](CONTRIBUTING.md)

## Support
## Community

- Issues: https://github.com/apache/solr-mcp/issues
- Discussions: https://github.com/apache/solr-mcp/discussions
- **Website:** https://solr.apache.org/mcp
- **Slack:** [`#solr-mcp`](https://the-asf.slack.com/archives/C09TVG3BM1P) in the `the-asf` workspace
- **Mailing lists:** Shared with Apache Solr — see [mailing lists](https://solr.apache.org/community.html#mailing-lists-chat)
- **Issues:** https://github.com/apache/solr-mcp/issues
- **Discussions:** https://github.com/apache/solr-mcp/discussions

## License

Expand Down
Loading
Loading