Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This file provides guidance to AI coding assistants when working with code in th

Solr MCP Server is a Spring AI Model Context Protocol (MCP) server that enables AI assistants to interact with Apache Solr. It provides tools for searching, indexing, and managing Solr collections through the MCP protocol.

- **Status:** Apache incubating project (v0.0.2-SNAPSHOT)
- **Status:** Apache incubating project (v1.0.0)
- **Java:** 25+ (centralized in build.gradle.kts)
- **Framework:** Spring Boot 3.5.14, Spring AI 1.1.7
- **License:** Apache 2.0
Expand Down
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ A Spring AI Model Context Protocol (MCP) server that provides tools for interact
- JAR:
```bash
./gradlew build
java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
java -jar build/libs/solr-mcp-1.0.0.jar
```
- Docker:
```bash
Expand All @@ -44,7 +44,7 @@ A Spring AI Model Context Protocol (MCP) server that provides tools for interact
```
- JAR:
```bash
PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
PROFILES=http java -jar build/libs/solr-mcp-1.0.0.jar
```
- Docker:
```bash
Expand Down Expand Up @@ -83,7 +83,7 @@ Using JAR:
"command": "java",
"args": [
"-jar",
"/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"
"/absolute/path/to/solr-mcp-1.0.0.jar"
],
"env": {
"SOLR_URL": "http://localhost:8983/solr/"
Expand Down Expand Up @@ -127,7 +127,7 @@ Using JAR:
"command": "java",
"args": [
"-jar",
"/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"
"/absolute/path/to/solr-mcp-1.0.0.jar"
],
"env": {
"PROFILES": "http",
Expand All @@ -152,7 +152,7 @@ PROFILES=http ./gradlew bootRun
Running locally (JAR):

```bash
PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
PROFILES=http java -jar build/libs/solr-mcp-1.0.0.jar
```

Running via Docker:
Expand Down Expand Up @@ -192,7 +192,7 @@ claude mcp add --transport stdio solr-mcp -- docker run -i --rm ghcr.io/apache/s

Using JAR (CLI):
```bash
claude mcp add --transport stdio -e SOLR_URL=http://localhost:8983/solr/ solr-mcp -- java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar
claude mcp add --transport stdio -e SOLR_URL=http://localhost:8983/solr/ solr-mcp -- java -jar /absolute/path/to/solr-mcp-1.0.0.jar
```

Or add to your project's `.mcp.json`:
Expand Down Expand Up @@ -220,7 +220,7 @@ Using JAR:
"solr-mcp": {
"type": "stdio",
"command": "java",
"args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
"args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0.jar"],
"env": {
"SOLR_URL": "http://localhost:8983/solr/"
}
Expand All @@ -237,7 +237,7 @@ Start the server first (pick one):
PROFILES=http ./gradlew bootRun

# JAR
PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
PROFILES=http java -jar build/libs/solr-mcp-1.0.0.jar

# Docker
docker run -p 8080:8080 --rm -e PROFILES=http ghcr.io/apache/solr-mcp:latest
Expand Down
2 changes: 1 addition & 1 deletion build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ val nativeImageBuildArgs =
)

group = "org.apache.solr"
version = "1.0.0-SNAPSHOT"
version = "1.0.0"

java {
toolchain {
Expand Down
20 changes: 10 additions & 10 deletions dev-docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Build directly to your local Docker daemon (requires Docker installed):
./gradlew jibDockerBuild
```

This creates: `solr-mcp:1.0.0-SNAPSHOT`
This creates: `solr-mcp:1.0.0`

Verify:
```bash
Expand All @@ -30,7 +30,7 @@ Authenticate and push (no local Docker daemon required):
docker login

# Build and push
./gradlew jib -Djib.to.image=YOUR_DOCKERHUB_USERNAME/solr-mcp:1.0.0-SNAPSHOT
./gradlew jib -Djib.to.image=YOUR_DOCKERHUB_USERNAME/solr-mcp:1.0.0
```

### Push to GitHub Container Registry
Expand All @@ -46,7 +46,7 @@ export GITHUB_TOKEN=YOUR_GITHUB_TOKEN
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

# Build and push
./gradlew jib -Djib.to.image=ghcr.io/YOUR_GITHUB_USERNAME/solr-mcp:1.0.0-SNAPSHOT
./gradlew jib -Djib.to.image=ghcr.io/YOUR_GITHUB_USERNAME/solr-mcp:1.0.0
```

### Multi-Platform Support
Expand All @@ -62,14 +62,14 @@ Jib automatically selects the appropriate platform or builds the first specified
### STDIO Mode (Default)

```bash
docker run -i --rm solr-mcp:1.0.0-SNAPSHOT
docker run -i --rm solr-mcp:1.0.0
```

With custom Solr URL:
```bash
docker run -i --rm \
-e SOLR_URL=http://your-solr-host:8983/solr/ \
solr-mcp:1.0.0-SNAPSHOT
solr-mcp:1.0.0
```

### HTTP Mode
Expand All @@ -78,7 +78,7 @@ docker run -i --rm \
docker run -p 8080:8080 --rm \
-e PROFILES=http \
-e SOLR_URL=http://your-solr-host:8983/solr/ \
solr-mcp:1.0.0-SNAPSHOT
solr-mcp:1.0.0
```

### Linux Host Networking
Expand All @@ -89,7 +89,7 @@ On Linux, to connect to Solr on the host machine:
docker run -i --rm \
--add-host=host.docker.internal:host-gateway \
-e SOLR_URL=http://host.docker.internal:8983/solr/ \
solr-mcp:1.0.0-SNAPSHOT
solr-mcp:1.0.0
```

## GitHub Actions CI/CD
Expand All @@ -107,13 +107,13 @@ To publish images, use Jib from your local machine or set up your own workflow:
- Docker Hub:
```bash
docker login
./gradlew jib -Djib.to.image=DOCKERHUB_USERNAME/solr-mcp:1.0.0-SNAPSHOT
./gradlew jib -Djib.to.image=DOCKERHUB_USERNAME/solr-mcp:1.0.0
```
- GitHub Container Registry (GHCR):
```bash
export GITHUB_TOKEN=YOUR_GITHUB_TOKEN
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
./gradlew jib -Djib.to.image=ghcr.io/YOUR_GITHUB_USERNAME/solr-mcp:1.0.0-SNAPSHOT
./gradlew jib -Djib.to.image=ghcr.io/YOUR_GITHUB_USERNAME/solr-mcp:1.0.0
```

### MCP Registry Publishing
Expand Down Expand Up @@ -162,7 +162,7 @@ The `server.json` file defines MCP registry metadata:
{
"registryType": "docker",
"identifier": "ghcr.io/apache/solr-mcp",
"version": "1.0.0-SNAPSHOT",
"version": "1.0.0",
"transport": {
"type": "stdio"
}
Expand Down
10 changes: 5 additions & 5 deletions dev-docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ This project uses Gradle with version catalogs for dependency management. All de

The build produces an executable JAR in `build/libs/`:

- `solr-mcp-1.0.0-SNAPSHOT.jar` — Spring Boot executable (fat) JAR
- `solr-mcp-1.0.0.jar` — Spring Boot executable (fat) JAR

## Running Locally

Expand All @@ -59,7 +59,7 @@ This starts a Solr instance in SolrCloud mode with ZooKeeper and creates two sam

Or using the JAR:
```bash
java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
java -jar build/libs/solr-mcp-1.0.0.jar
```

#### HTTP Mode
Expand Down Expand Up @@ -169,7 +169,7 @@ The project generates build metadata at build time via the Spring Boot Gradle pl
- `build.artifact`: Artifact name (e.g., "solr-mcp")
- `build.group`: Group ID (e.g., "org.apache.solr")
- `build.name`: Project name
- `build.version`: Version (e.g., "1.0.0-SNAPSHOT")
- `build.version`: Version (e.g., "1.0.0")
- `build.time`: Build timestamp

This metadata is used by:
Expand All @@ -189,7 +189,7 @@ See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed Docker build instructions.
./gradlew jibDockerBuild

# Run the image
docker run -i --rm solr-mcp:1.0.0-SNAPSHOT
docker run -i --rm solr-mcp:1.0.0
```

### Docker Executable Configuration
Expand Down Expand Up @@ -302,7 +302,7 @@ Use Java Flight Recorder:

```bash
java -XX:StartFlightRecording=duration=60s,filename=recording.jfr \
-jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
-jar build/libs/solr-mcp-1.0.0.jar
```

Analyze with Java Mission Control.
Expand Down
12 changes: 6 additions & 6 deletions dev-docs/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Common issues and solutions when working with the Solr MCP Server.
```bash
docker run -i --rm \
--add-host=host.docker.internal:host-gateway \
solr-mcp:1.0.0-SNAPSHOT
solr-mcp:1.0.0
```

### Collection not found
Expand Down Expand Up @@ -143,7 +143,7 @@ Jib automatically builds for the local platform or the first specified platform.
"mcpServers": {
"solr-search-mcp": {
"command": "java",
"args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"]
"args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0.jar"]
}
}
}
Expand All @@ -167,7 +167,7 @@ Jib automatically builds for the local platform or the first specified platform.
1. **Test server manually**
```bash
# STDIO mode - should start without errors
java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
java -jar build/libs/solr-mcp-1.0.0.jar

# HTTP mode
curl http://localhost:8080/actuator/health
Expand Down Expand Up @@ -330,12 +330,12 @@ rm -rf .gradle
1. **Increase JVM heap**
```bash
export JAVA_OPTS="-Xmx2g -Xms512m"
java $JAVA_OPTS -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
java $JAVA_OPTS -jar build/libs/solr-mcp-1.0.0.jar
```

2. **Docker container limits**
```bash
docker run -m 2g --rm solr-mcp:1.0.0-SNAPSHOT
docker run -m 2g --rm solr-mcp:1.0.0
```

3. **Check for memory leaks**
Expand Down Expand Up @@ -379,7 +379,7 @@ rm -rf .gradle
lsof -ti:8080 | xargs kill -9

# Or change port
java -Dserver.port=8081 -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
java -Dserver.port=8081 -jar build/libs/solr-mcp-1.0.0.jar
```

## Getting Help
Expand Down
4 changes: 2 additions & 2 deletions server.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
{
"registryType": "docker",
"identifier": "ghcr.io/apache/solr-mcp-server",
"version": "1.0.0-SNAPSHOT",
"version": "1.0.0",
"transport": {
"type": "stdio"
},
Expand All @@ -28,7 +28,7 @@
{
"registryType": "docker",
"identifier": "ghcr.io/apache/solr-mcp-server",
"version": "1.0.0-SNAPSHOT",
"version": "1.0.0",
"transport": {
"type": "streamable-http",
"url": "http://localhost:8080/mcp"
Expand Down