From ca6834cfb71212be13adf77558627eb02eba996c Mon Sep 17 00:00:00 2001 From: adityamparikh Date: Tue, 4 Nov 2025 21:32:31 -0500 Subject: [PATCH 1/5] docs: add a tutorial --- solr-mcp-tutorial.html | 817 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 817 insertions(+) create mode 100644 solr-mcp-tutorial.html diff --git a/solr-mcp-tutorial.html b/solr-mcp-tutorial.html new file mode 100644 index 0000000..cea07d4 --- /dev/null +++ b/solr-mcp-tutorial.html @@ -0,0 +1,817 @@ + + + + + + Solr MCP Server - Usage Tutorial + + + +

Solr MCP Server - Usage Tutorial

+ +

The Solr MCP (Model Context Protocol) Server enables AI assistants like Claude to interact with Apache Solr through a + standardized protocol. This guide provides comprehensive instructions for setting up, configuring, and using the + Solr MCP Server.

+ +
+

Table of Contents

+ +
+ +

Overview

+ +

The Solr MCP Server is a Spring AI-based implementation that provides AI assistants with tools to interact with + Apache Solr. It supports both STDIO and HTTP transport modes, enabling flexible deployment options.

+ +

What's Inside

+ + +
+ Model Context Protocol (MCP)
+ MCP is an open protocol that standardizes how applications provide context to LLMs. The Solr MCP Server implements + this protocol to make Solr's capabilities accessible to AI assistants. +
+ +

Prerequisites

+ + + +
+ Quick Start with Sample Data: The repository includes a Docker Compose file to start Solr with + pre-populated collections (books, films, techproducts). Run: docker compose up -d +
+ +

Integration with MCP Clients

+ +

The Solr MCP Server can be integrated with any MCP-compatible client. Both STDIO mode and HTTP + mode are fully supported.

+ +

STDIO Mode

+ +

STDIO mode uses standard input/output for communication. This is the default mode and works with Claude Desktop, + GitHub Copilot, VSCode extensions, and other MCP clients.

+ +

Claude Desktop

+ +

Edit your configuration file:

+ + +

Using Docker:

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

Using JAR:

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "java",
+      "args": ["-jar", "/absolute/path/to/solr-mcp-0.0.1-SNAPSHOT.jar"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

GitHub Copilot & VSCode Extensions (Cline, Continue)

+ +

These clients use the same configuration format.

+ +

GitHub Copilot: Add to VS Code settings (settings.json)

+

Cline: Add to Cline MCP settings

+

Continue: Add to ~/.continue/config.json

+ +

Configuration (Docker):

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

Configuration (JAR):

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "java",
+      "args": ["-jar", "/absolute/path/to/solr-mcp-0.0.1-SNAPSHOT.jar"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +
+ Note: Continue uses a slightly different format with an array. Wrap the above configuration in: + {"mcpServers": [...]} +
+ +

JetBrains IDEs

+ +

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support MCP through AI Assistant settings.

+ +

Navigate to Settings → Tools → AI Assistant → Model Context Protocol and add:

+
{
+  "servers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

Alternatively, edit the MCP configuration file directly:

+ + +

MCP Inspector (STDIO)

+ +

The MCP Inspector is an official tool for testing and + debugging MCP servers.

+ +

For testing with STDIO transport:

+
# Start the server
+docker run -i --rm ghcr.io/apache/solr-mcp:latest
+
+# Or using JAR
+java -jar build/libs/solr-mcp-0.0.1-SNAPSHOT.jar
+
+# In another terminal, connect with MCP Inspector
+npx @modelcontextprotocol/inspector
+ +
+ Important: After adding or modifying MCP server configurations, completely restart your client + application (quit and reopen) for changes to take effect. +
+ +

HTTP Mode

+ +

HTTP mode uses a streamable HTTP transport. This is useful for debugging with MCP Inspector or when your client + doesn't support STDIO.

+ +

Starting the Server in HTTP Mode

+ +

Using Docker:

+
docker run -d --name solr-mcp \
+  -p 8080:8080 \
+  -e PROFILES=http \
+  -e SOLR_URL=http://localhost:8983/solr/ \
+  ghcr.io/apache/solr-mcp:latest
+ +

Using JAR:

+
PROFILES=http java -jar build/libs/solr-mcp-0.0.1-SNAPSHOT.jar
+ +

Client Configuration for HTTP Mode

+ +

All clients use the same configuration format for HTTP mode:

+ +

Claude Desktop, GitHub Copilot, Cline, Continue:

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

JetBrains IDEs:

+
{
+  "servers": {
+    "solr-mcp": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+ +

MCP Inspector (HTTP):

+
npx @modelcontextprotocol/inspector http://localhost:8080/mcp
+ +
+ Tip: Use HTTP mode with MCP + Inspector for an interactive web interface to test all available tools during development. +
+ +

Environment Variables

+ + + + + + + + + + + + + + + + + + + + + +
VariableDescriptionDefault
SOLR_URLURL of the Solr instancehttp://localhost:8983/solr/
PROFILESTransport mode (empty=STDIO, http=HTTP)(empty - STDIO mode)
+ +

Docker Network Configuration

+ +
+ Connecting to Solr from Docker: + +
+ +

Verifying Integration

+ +

Claude Desktop: Look for the 🔌 icon in the bottom-right corner. Click it to see "solr-mcp" with 6 + available tools.

+ +

Other Clients: Check your client's tools/context servers panel to confirm the connection and see + available tools.

+ +

Available MCP Tools

+ +

The Solr MCP Server provides six tools accessible to AI assistants:

+ +

1. Search

+

Search Solr collections with advanced query options.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescriptionRequired
collectionStringSolr collection to queryYes
queryStringSolr query (defaults to *:*)No
filterQueriesArrayFilter queries (fq parameter)No
facetFieldsArrayFields to facet onNo
sortClausesArraySorting criteriaNo
startIntegerStarting offset for paginationNo
rowsIntegerNumber of rows to returnNo
+ +
+ Dynamic Fields: Solr uses dynamic field suffixes: + +
+ +

2. index_json_documents

+

Index documents from a JSON string.

+
{
+  "collection": "myCollection",
+  "json": "[{\"id\":\"1\",\"title\":\"Example\"}]"
+}
+ +

3. index_csv_documents

+

Index documents from a CSV string.

+
{
+  "collection": "myCollection",
+  "csv": "id,title\n1,Example\n2,Another"
+}
+ +

4. index_xml_documents

+

Index documents from an XML string.

+
{
+  "collection": "myCollection",
+  "xml": "<docs><doc><field name=\"id\">1</field></doc></docs>"
+}
+ +

5. listCollections

+

List all available Solr collections. No parameters required.

+ +

6. getCollectionStats

+

Retrieve statistics and metrics for a collection.

+
{
+  "collection": "books"
+}
+ +

7. checkHealth

+

Check the health status of a collection.

+
{
+  "collection": "books"
+}
+ +

8. getSchema

+

Retrieve schema information for a collection.

+
{
+  "collection": "books"
+}
+ +

Usage Examples

+ +

Example 1: Basic Search

+

User: "Search for books about science in the books collection"

+

AI Assistant uses:

+
Search({
+  "collection": "books",
+  "query": "science"
+})
+ +

Example 2: Filtered Search with Facets

+

User: "Show me fantasy books with facets by author"

+

AI Assistant uses:

+
Search({
+  "collection": "books",
+  "query": "*:*",
+  "filterQueries": ["genre_s:fantasy"],
+  "facetFields": ["author"],
+  "rows": 10
+})
+ +

Example 3: Sorting and Pagination

+

User: "Show me the newest films, sorted by year descending, page 2"

+

AI Assistant uses:

+
Search({
+  "collection": "films",
+  "query": "*:*",
+  "sortClauses": [{"field": "initial_release_date", "order": "desc"}],
+  "start": 10,
+  "rows": 10
+})
+ +

Example 4: Indexing Documents

+

User: "Add a new book to the collection"

+

AI Assistant uses:

+
index_json_documents({
+  "collection": "books",
+  "json": "[{
+    \"id\": \"new-book-1\",
+    \"name\": [\"Introduction to Solr\"],
+    \"author\": [\"Jane Developer\"],
+    \"genre_s\": \"technical\",
+    \"price\": [29.99],
+    \"inStock\": [true]
+  }]"
+})
+ +

Example 5: Collection Analysis

+

User: "What collections are available and show me stats for books"

+

AI Assistant uses:

+
listCollections()
+
+getCollectionStats({
+  "collection": "books"
+})
+ +

Troubleshooting

+ +

Connection Issues

+ +
+ Problem: "Cannot connect to Solr"
+ Solutions: + +
+ +

MCP Client Issues

+ +
+ Problem: "Server not showing in client"
+ Solutions: + +
+ +

Docker Issues

+ +
+ Problem: "Container cannot access Solr"
+ Solutions: + +
+ +

Common Query Patterns

+ +
+ Query Examples: + +
+ +

Advanced Topics

+ +

Building from Source

+ +
# Clone the repository
+git clone https://github.com/apache/solr-mcp.git
+cd solr-mcp
+
+# Build with Gradle
+./gradlew build
+
+# Run tests
+./gradlew test
+
+# Build Docker image locally
+./gradlew jibDockerBuild
+ +

Custom Solr Connection

+ +

Connect to a remote Solr instance:

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "https://remote-solr.example.com:8983/solr/"
+      }
+    }
+  }
+}
+ +
+ Note: The current version supports basic Solr connections. Authentication support is planned for + future releases. +
+ +

Performance Optimization

+ + + +

Security Best Practices

+ + + +

Additional Resources

+ + + +
+ +

This guide was created for Solr MCP Server version 0.0.1-SNAPSHOT. Last updated: November 2025.

+ +

License: Apache License 2.0

+ + \ No newline at end of file From 8115b97d2bac8d9ade0fd14d5c33b4dbc8593336 Mon Sep 17 00:00:00 2001 From: adityamparikh Date: Tue, 4 Nov 2025 21:32:31 -0500 Subject: [PATCH 2/5] docs: add a tutorial --- solr-mcp-tutorial.html | 817 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 817 insertions(+) create mode 100644 solr-mcp-tutorial.html diff --git a/solr-mcp-tutorial.html b/solr-mcp-tutorial.html new file mode 100644 index 0000000..cea07d4 --- /dev/null +++ b/solr-mcp-tutorial.html @@ -0,0 +1,817 @@ + + + + + + Solr MCP Server - Usage Tutorial + + + +

Solr MCP Server - Usage Tutorial

+ +

The Solr MCP (Model Context Protocol) Server enables AI assistants like Claude to interact with Apache Solr through a + standardized protocol. This guide provides comprehensive instructions for setting up, configuring, and using the + Solr MCP Server.

+ +
+

Table of Contents

+ +
+ +

Overview

+ +

The Solr MCP Server is a Spring AI-based implementation that provides AI assistants with tools to interact with + Apache Solr. It supports both STDIO and HTTP transport modes, enabling flexible deployment options.

+ +

What's Inside

+ + +
+ Model Context Protocol (MCP)
+ MCP is an open protocol that standardizes how applications provide context to LLMs. The Solr MCP Server implements + this protocol to make Solr's capabilities accessible to AI assistants. +
+ +

Prerequisites

+ + + +
+ Quick Start with Sample Data: The repository includes a Docker Compose file to start Solr with + pre-populated collections (books, films, techproducts). Run: docker compose up -d +
+ +

Integration with MCP Clients

+ +

The Solr MCP Server can be integrated with any MCP-compatible client. Both STDIO mode and HTTP + mode are fully supported.

+ +

STDIO Mode

+ +

STDIO mode uses standard input/output for communication. This is the default mode and works with Claude Desktop, + GitHub Copilot, VSCode extensions, and other MCP clients.

+ +

Claude Desktop

+ +

Edit your configuration file:

+ + +

Using Docker:

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

Using JAR:

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "java",
+      "args": ["-jar", "/absolute/path/to/solr-mcp-0.0.1-SNAPSHOT.jar"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

GitHub Copilot & VSCode Extensions (Cline, Continue)

+ +

These clients use the same configuration format.

+ +

GitHub Copilot: Add to VS Code settings (settings.json)

+

Cline: Add to Cline MCP settings

+

Continue: Add to ~/.continue/config.json

+ +

Configuration (Docker):

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

Configuration (JAR):

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "java",
+      "args": ["-jar", "/absolute/path/to/solr-mcp-0.0.1-SNAPSHOT.jar"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +
+ Note: Continue uses a slightly different format with an array. Wrap the above configuration in: + {"mcpServers": [...]} +
+ +

JetBrains IDEs

+ +

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support MCP through AI Assistant settings.

+ +

Navigate to Settings → Tools → AI Assistant → Model Context Protocol and add:

+
{
+  "servers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+ +

Alternatively, edit the MCP configuration file directly:

+ + +

MCP Inspector (STDIO)

+ +

The MCP Inspector is an official tool for testing and + debugging MCP servers.

+ +

For testing with STDIO transport:

+
# Start the server
+docker run -i --rm ghcr.io/apache/solr-mcp:latest
+
+# Or using JAR
+java -jar build/libs/solr-mcp-0.0.1-SNAPSHOT.jar
+
+# In another terminal, connect with MCP Inspector
+npx @modelcontextprotocol/inspector
+ +
+ Important: After adding or modifying MCP server configurations, completely restart your client + application (quit and reopen) for changes to take effect. +
+ +

HTTP Mode

+ +

HTTP mode uses a streamable HTTP transport. This is useful for debugging with MCP Inspector or when your client + doesn't support STDIO.

+ +

Starting the Server in HTTP Mode

+ +

Using Docker:

+
docker run -d --name solr-mcp \
+  -p 8080:8080 \
+  -e PROFILES=http \
+  -e SOLR_URL=http://localhost:8983/solr/ \
+  ghcr.io/apache/solr-mcp:latest
+ +

Using JAR:

+
PROFILES=http java -jar build/libs/solr-mcp-0.0.1-SNAPSHOT.jar
+ +

Client Configuration for HTTP Mode

+ +

All clients use the same configuration format for HTTP mode:

+ +

Claude Desktop, GitHub Copilot, Cline, Continue:

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

JetBrains IDEs:

+
{
+  "servers": {
+    "solr-mcp": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+ +

MCP Inspector (HTTP):

+
npx @modelcontextprotocol/inspector http://localhost:8080/mcp
+ +
+ Tip: Use HTTP mode with MCP + Inspector for an interactive web interface to test all available tools during development. +
+ +

Environment Variables

+ + + + + + + + + + + + + + + + + + + + + +
VariableDescriptionDefault
SOLR_URLURL of the Solr instancehttp://localhost:8983/solr/
PROFILESTransport mode (empty=STDIO, http=HTTP)(empty - STDIO mode)
+ +

Docker Network Configuration

+ +
+ Connecting to Solr from Docker: +
    +
  • macOS/Windows: Use host.docker.internal instead of localhost
    • +
  • Linux: Add --network host to docker run command
    • +
  • Alternative: Link containers using Docker networks
    • +
+
+ +

Verifying Integration

+ +

Claude Desktop: Look for the 🔌 icon in the bottom-right corner. Click it to see "solr-mcp" with 6 + available tools.

+ +

Other Clients: Check your client's tools/context servers panel to confirm the connection and see + available tools.

+ +

Available MCP Tools

+ +

The Solr MCP Server provides six tools accessible to AI assistants:

+ +

1. Search

+

Search Solr collections with advanced query options.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescriptionRequired
collectionStringSolr collection to queryYes
queryStringSolr query (defaults to *:*)No
filterQueriesArrayFilter queries (fq parameter)No
facetFieldsArrayFields to facet onNo
sortClausesArraySorting criteriaNo
startIntegerStarting offset for paginationNo
rowsIntegerNumber of rows to returnNo
+ +
+ Dynamic Fields: Solr uses dynamic field suffixes: +
    +
  • _s - String field (exact matching)
    • +
  • _i - Integer field
    • +
  • _l - Long field
    • +
  • _f - Float field
    • +
  • _d - Double field
    • +
  • _dt - Date field
    • +
  • _b - Boolean field
    • +
  • _t - Text field (tokenized)
    • +
+
+ +

2. index_json_documents

+

Index documents from a JSON string.

+
{
+  "collection": "myCollection",
+  "json": "[{\"id\":\"1\",\"title\":\"Example\"}]"
+}
+ +

3. index_csv_documents

+

Index documents from a CSV string.

+
{
+  "collection": "myCollection",
+  "csv": "id,title\n1,Example\n2,Another"
+}
+ +

4. index_xml_documents

+

Index documents from an XML string.

+
{
+  "collection": "myCollection",
+  "xml": "<docs><doc><field name=\"id\">1</field></doc></docs>"
+}
+ +

5. listCollections

+

List all available Solr collections. No parameters required.

+ +

6. getCollectionStats

+

Retrieve statistics and metrics for a collection.

+
{
+  "collection": "books"
+}
+ +

7. checkHealth

+

Check the health status of a collection.

+
{
+  "collection": "books"
+}
+ +

8. getSchema

+

Retrieve schema information for a collection.

+
{
+  "collection": "books"
+}
+ +

Usage Examples

+ +

Example 1: Basic Search

+

User: "Search for books about science in the books collection"

+

AI Assistant uses:

+
Search({
+  "collection": "books",
+  "query": "science"
+})
+ +

Example 2: Filtered Search with Facets

+

User: "Show me fantasy books with facets by author"

+

AI Assistant uses:

+
Search({
+  "collection": "books",
+  "query": "*:*",
+  "filterQueries": ["genre_s:fantasy"],
+  "facetFields": ["author"],
+  "rows": 10
+})
+ +

Example 3: Sorting and Pagination

+

User: "Show me the newest films, sorted by year descending, page 2"

+

AI Assistant uses:

+
Search({
+  "collection": "films",
+  "query": "*:*",
+  "sortClauses": [{"field": "initial_release_date", "order": "desc"}],
+  "start": 10,
+  "rows": 10
+})
+ +

Example 4: Indexing Documents

+

User: "Add a new book to the collection"

+

AI Assistant uses:

+
index_json_documents({
+  "collection": "books",
+  "json": "[{
+    \"id\": \"new-book-1\",
+    \"name\": [\"Introduction to Solr\"],
+    \"author\": [\"Jane Developer\"],
+    \"genre_s\": \"technical\",
+    \"price\": [29.99],
+    \"inStock\": [true]
+  }]"
+})
+ +

Example 5: Collection Analysis

+

User: "What collections are available and show me stats for books"

+

AI Assistant uses:

+
listCollections()
+
+getCollectionStats({
+  "collection": "books"
+})
+ +

Troubleshooting

+ +

Connection Issues

+ +
+ Problem: "Cannot connect to Solr"
+ Solutions: +
    +
  • Verify Solr is running: curl http://localhost:8983/solr/
    • +
  • Check SOLR_URL environment variable
    • +
  • For Docker on Linux, use --network host
    • +
  • For Docker on macOS/Windows, use host.docker.internal instead of localhost
    • +
+
+ +

MCP Client Issues

+ +
+ Problem: "Server not showing in client"
+ Solutions: +
    +
  • Verify JSON configuration syntax (use a JSON validator)
    • +
  • Use absolute paths for JAR files
    • +
  • Completely restart the client application (quit, don't just close window)
    • +
  • Check client logs for error messages
    • +
+
+ +

Docker Issues

+ +
+ Problem: "Container cannot access Solr"
+ Solutions: +
    +
  • On macOS/Windows: Set SOLR_URL=http://host.docker.internal:8983/solr/
    • +
  • On Linux: Add --network host to docker run command
    • +
  • Alternative: Create a Docker network and connect both containers
    • +
+
+ +

Common Query Patterns

+ +
+ Query Examples: +
    +
  • All documents: *:*
    • +
  • Exact match: field:"exact phrase"
    • +
  • Wildcards: field:test*
    • +
  • Range: price:[10 TO 20]
    • +
  • Boolean: field1:value1 AND field2:value2
    • +
+
+ +

Advanced Topics

+ +

Building from Source

+ +
# Clone the repository
+git clone https://github.com/apache/solr-mcp.git
+cd solr-mcp
+
+# Build with Gradle
+./gradlew build
+
+# Run tests
+./gradlew test
+
+# Build Docker image locally
+./gradlew jibDockerBuild
+ +

Custom Solr Connection

+ +

Connect to a remote Solr instance:

+
{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
+      "env": {
+        "SOLR_URL": "https://remote-solr.example.com:8983/solr/"
+      }
+    }
+  }
+}
+ +
+ Note: The current version supports basic Solr connections. Authentication support is planned for + future releases. +
+ +

Performance Optimization

+ + + +

Security Best Practices

+ + + +

Additional Resources

+ + + +
+ +

This guide was created for Solr MCP Server version 0.0.1-SNAPSHOT. Last updated: November 2025.

+ +

License: Apache License 2.0

+ + \ No newline at end of file From 20cdc990a66a3ae2b0180f57f18bb89c38240a33 Mon Sep 17 00:00:00 2001 From: adityamparikh Date: Sat, 15 Nov 2025 10:19:27 -0500 Subject: [PATCH 3/5] deps: update dependency versions for spring-boot and spring-ai to 1.1.0 GA increment project version to 0.0.2-SNAPSHOT --- build.gradle.kts | 14 ++++++++++---- gradle/libs.versions.toml | 4 ++-- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index 7eadfe0..ee35acf 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -310,11 +310,17 @@ jib { dockerClient { executable = System.getenv("DOCKER_EXECUTABLE") ?: when { // macOS with Docker Desktop - org.gradle.internal.os.OperatingSystem.current().isMacOsX -> "/usr/local/bin/docker" + org.gradle.internal.os.OperatingSystem + .current() + .isMacOsX -> "/usr/local/bin/docker" // Linux (most distributions) - org.gradle.internal.os.OperatingSystem.current().isLinux -> "/usr/bin/docker" + org.gradle.internal.os.OperatingSystem + .current() + .isLinux -> "/usr/bin/docker" // Windows with Docker Desktop - org.gradle.internal.os.OperatingSystem.current().isWindows -> "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe" + org.gradle.internal.os.OperatingSystem + .current() + .isWindows -> "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe" // Fallback to PATH lookup else -> "docker" } @@ -385,7 +391,7 @@ jib { "org.opencontainers.image.vendor" to "Apache Software Foundation", "org.opencontainers.image.licenses" to "Apache-2.0", // MCP Registry annotation for server discovery - "io.modelcontextprotocol.server.name" to "io.github.apache/solr-mcp" + "io.modelcontextprotocol.server.name" to "io.github.apache/solr-mcp", ), ) } diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 2c1fce4..579b0c3 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -1,13 +1,13 @@ [versions] # Build plugins -spring-boot = "3.5.6" +spring-boot = "3.5.7" spring-dependency-management = "1.1.7" errorprone-plugin = "4.2.0" jib = "3.4.5" spotless = "7.0.2" # Main dependencies -spring-ai = "1.1.0-M3" +spring-ai = "1.1.0" solr = "9.9.0" commons-csv = "1.10.0" jspecify = "1.0.0" From 202d134faa90f2c6ee794c2824aa6d47542ac0ce Mon Sep 17 00:00:00 2001 From: adityamparikh Date: Sat, 15 Nov 2025 10:28:35 -0500 Subject: [PATCH 4/5] deps: update dependency versions for spring-boot and spring-ai to 1.1.0 GA increment project version to 0.0.2-SNAPSHOT --- solr-mcp-tutorial.html | 817 ----------------------------------------- 1 file changed, 817 deletions(-) delete mode 100644 solr-mcp-tutorial.html diff --git a/solr-mcp-tutorial.html b/solr-mcp-tutorial.html deleted file mode 100644 index cea07d4..0000000 --- a/solr-mcp-tutorial.html +++ /dev/null @@ -1,817 +0,0 @@ - - - - - - Solr MCP Server - Usage Tutorial - - - -

Solr MCP Server - Usage Tutorial

- -

The Solr MCP (Model Context Protocol) Server enables AI assistants like Claude to interact with Apache Solr through a - standardized protocol. This guide provides comprehensive instructions for setting up, configuring, and using the - Solr MCP Server.

- -
-

Table of Contents

- -
- -

Overview

- -

The Solr MCP Server is a Spring AI-based implementation that provides AI assistants with tools to interact with - Apache Solr. It supports both STDIO and HTTP transport modes, enabling flexible deployment options.

- -

What's Inside

-
    -
  • 🔍 Search - Search Solr collections with filtering, faceting, and pagination
    • -
  • 📝 Indexing - Index documents in JSON, CSV, and XML formats
    • -
  • 📊 Collection Management - List collections and view statistics
    • -
  • 🔧 Schema Inspection - Retrieve schema information
    • -
  • 📡 Transport Options - STDIO (Claude Desktop) and HTTP (MCP Inspector)
    • -
  • 🐳 Docker Support - Pre-built images with Jib
    • -
- -
- Model Context Protocol (MCP)
- MCP is an open protocol that standardizes how applications provide context to LLMs. The Solr MCP Server implements - this protocol to make Solr's capabilities accessible to AI assistants. -
- -

Prerequisites

- -
    -
  • Apache Solr - A running Solr instance (default: http://localhost:8983/solr/)
    • -
  • Docker (Recommended) - For running the MCP server
    • -
  • Java 21+ (Alternative) - For running from JAR file
    • -
  • MCP Client - Claude Desktop, Cline, Zed, or any MCP-compatible client
    • -
- -
- Quick Start with Sample Data: The repository includes a Docker Compose file to start Solr with - pre-populated collections (books, films, techproducts). Run: docker compose up -d -
- -

Integration with MCP Clients

- -

The Solr MCP Server can be integrated with any MCP-compatible client. Both STDIO mode and HTTP - mode are fully supported.

- -

STDIO Mode

- -

STDIO mode uses standard input/output for communication. This is the default mode and works with Claude Desktop, - GitHub Copilot, VSCode extensions, and other MCP clients.

- -

Claude Desktop

- -

Edit your configuration file:

-
    -
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • -
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • -
- -

Using Docker:

-
{
-  "mcpServers": {
-    "solr-mcp": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
-      "env": {
-        "SOLR_URL": "http://localhost:8983/solr/"
-      }
-    }
-  }
-}
- -

Using JAR:

-
{
-  "mcpServers": {
-    "solr-mcp": {
-      "command": "java",
-      "args": ["-jar", "/absolute/path/to/solr-mcp-0.0.1-SNAPSHOT.jar"],
-      "env": {
-        "SOLR_URL": "http://localhost:8983/solr/"
-      }
-    }
-  }
-}
- -

GitHub Copilot & VSCode Extensions (Cline, Continue)

- -

These clients use the same configuration format.

- -

GitHub Copilot: Add to VS Code settings (settings.json)

-

Cline: Add to Cline MCP settings

-

Continue: Add to ~/.continue/config.json

- -

Configuration (Docker):

-
{
-  "mcpServers": {
-    "solr-mcp": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
-      "env": {
-        "SOLR_URL": "http://localhost:8983/solr/"
-      }
-    }
-  }
-}
- -

Configuration (JAR):

-
{
-  "mcpServers": {
-    "solr-mcp": {
-      "command": "java",
-      "args": ["-jar", "/absolute/path/to/solr-mcp-0.0.1-SNAPSHOT.jar"],
-      "env": {
-        "SOLR_URL": "http://localhost:8983/solr/"
-      }
-    }
-  }
-}
- -
- Note: Continue uses a slightly different format with an array. Wrap the above configuration in: - {"mcpServers": [...]} -
- -

JetBrains IDEs

- -

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support MCP through AI Assistant settings.

- -

Navigate to Settings → Tools → AI Assistant → Model Context Protocol and add:

-
{
-  "servers": {
-    "solr-mcp": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
-      "env": {
-        "SOLR_URL": "http://localhost:8983/solr/"
-      }
-    }
-  }
-}
- -

Alternatively, edit the MCP configuration file directly:

-
    -
  • macOS: ~/Library/Application Support/JetBrains/[IDE]/mcp_config.json
    • -
  • Windows: %APPDATA%\JetBrains\[IDE]\mcp_config.json
    • -
  • Linux: ~/.config/JetBrains/[IDE]/mcp_config.json
    • -
- -

MCP Inspector (STDIO)

- -

The MCP Inspector is an official tool for testing and - debugging MCP servers.

- -

For testing with STDIO transport:

-
# Start the server
-docker run -i --rm ghcr.io/apache/solr-mcp:latest
-
-# Or using JAR
-java -jar build/libs/solr-mcp-0.0.1-SNAPSHOT.jar
-
-# In another terminal, connect with MCP Inspector
-npx @modelcontextprotocol/inspector
- -
- Important: After adding or modifying MCP server configurations, completely restart your client - application (quit and reopen) for changes to take effect. -
- -

HTTP Mode

- -

HTTP mode uses a streamable HTTP transport. This is useful for debugging with MCP Inspector or when your client - doesn't support STDIO.

- -

Starting the Server in HTTP Mode

- -

Using Docker:

-
docker run -d --name solr-mcp \
-  -p 8080:8080 \
-  -e PROFILES=http \
-  -e SOLR_URL=http://localhost:8983/solr/ \
-  ghcr.io/apache/solr-mcp:latest
- -

Using JAR:

-
PROFILES=http java -jar build/libs/solr-mcp-0.0.1-SNAPSHOT.jar
- -

Client Configuration for HTTP Mode

- -

All clients use the same configuration format for HTTP mode:

- -

Claude Desktop, GitHub Copilot, Cline, Continue:

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

JetBrains IDEs:

-
{
-  "servers": {
-    "solr-mcp": {
-      "url": "http://localhost:8080/mcp"
-    }
-  }
-}
- -

MCP Inspector (HTTP):

-
npx @modelcontextprotocol/inspector http://localhost:8080/mcp
- -
- Tip: Use HTTP mode with MCP - Inspector for an interactive web interface to test all available tools during development. -
- -

Environment Variables

- - - - - - - - - - - - - - - - - - - - - -
VariableDescriptionDefault
SOLR_URLURL of the Solr instancehttp://localhost:8983/solr/
PROFILESTransport mode (empty=STDIO, http=HTTP)(empty - STDIO mode)
- -

Docker Network Configuration

- -
- Connecting to Solr from Docker: -
    -
  • macOS/Windows: Use host.docker.internal instead of localhost
    • -
  • Linux: Add --network host to docker run command
    • -
  • Alternative: Link containers using Docker networks
    • -
-
- -

Verifying Integration

- -

Claude Desktop: Look for the 🔌 icon in the bottom-right corner. Click it to see "solr-mcp" with 6 - available tools.

- -

Other Clients: Check your client's tools/context servers panel to confirm the connection and see - available tools.

- -

Available MCP Tools

- -

The Solr MCP Server provides six tools accessible to AI assistants:

- -

1. Search

-

Search Solr collections with advanced query options.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterTypeDescriptionRequired
collectionStringSolr collection to queryYes
queryStringSolr query (defaults to *:*)No
filterQueriesArrayFilter queries (fq parameter)No
facetFieldsArrayFields to facet onNo
sortClausesArraySorting criteriaNo
startIntegerStarting offset for paginationNo
rowsIntegerNumber of rows to returnNo
- -
- Dynamic Fields: Solr uses dynamic field suffixes: -
    -
  • _s - String field (exact matching)
    • -
  • _i - Integer field
    • -
  • _l - Long field
    • -
  • _f - Float field
    • -
  • _d - Double field
    • -
  • _dt - Date field
    • -
  • _b - Boolean field
    • -
  • _t - Text field (tokenized)
    • -
-
- -

2. index_json_documents

-

Index documents from a JSON string.

-
{
-  "collection": "myCollection",
-  "json": "[{\"id\":\"1\",\"title\":\"Example\"}]"
-}
- -

3. index_csv_documents

-

Index documents from a CSV string.

-
{
-  "collection": "myCollection",
-  "csv": "id,title\n1,Example\n2,Another"
-}
- -

4. index_xml_documents

-

Index documents from an XML string.

-
{
-  "collection": "myCollection",
-  "xml": "<docs><doc><field name=\"id\">1</field></doc></docs>"
-}
- -

5. listCollections

-

List all available Solr collections. No parameters required.

- -

6. getCollectionStats

-

Retrieve statistics and metrics for a collection.

-
{
-  "collection": "books"
-}
- -

7. checkHealth

-

Check the health status of a collection.

-
{
-  "collection": "books"
-}
- -

8. getSchema

-

Retrieve schema information for a collection.

-
{
-  "collection": "books"
-}
- -

Usage Examples

- -

Example 1: Basic Search

-

User: "Search for books about science in the books collection"

-

AI Assistant uses:

-
Search({
-  "collection": "books",
-  "query": "science"
-})
- -

Example 2: Filtered Search with Facets

-

User: "Show me fantasy books with facets by author"

-

AI Assistant uses:

-
Search({
-  "collection": "books",
-  "query": "*:*",
-  "filterQueries": ["genre_s:fantasy"],
-  "facetFields": ["author"],
-  "rows": 10
-})
- -

Example 3: Sorting and Pagination

-

User: "Show me the newest films, sorted by year descending, page 2"

-

AI Assistant uses:

-
Search({
-  "collection": "films",
-  "query": "*:*",
-  "sortClauses": [{"field": "initial_release_date", "order": "desc"}],
-  "start": 10,
-  "rows": 10
-})
- -

Example 4: Indexing Documents

-

User: "Add a new book to the collection"

-

AI Assistant uses:

-
index_json_documents({
-  "collection": "books",
-  "json": "[{
-    \"id\": \"new-book-1\",
-    \"name\": [\"Introduction to Solr\"],
-    \"author\": [\"Jane Developer\"],
-    \"genre_s\": \"technical\",
-    \"price\": [29.99],
-    \"inStock\": [true]
-  }]"
-})
- -

Example 5: Collection Analysis

-

User: "What collections are available and show me stats for books"

-

AI Assistant uses:

-
listCollections()
-
-getCollectionStats({
-  "collection": "books"
-})
- -

Troubleshooting

- -

Connection Issues

- -
- Problem: "Cannot connect to Solr"
- Solutions: -
    -
  • Verify Solr is running: curl http://localhost:8983/solr/
    • -
  • Check SOLR_URL environment variable
    • -
  • For Docker on Linux, use --network host
    • -
  • For Docker on macOS/Windows, use host.docker.internal instead of localhost
    • -
-
- -

MCP Client Issues

- -
- Problem: "Server not showing in client"
- Solutions: -
    -
  • Verify JSON configuration syntax (use a JSON validator)
    • -
  • Use absolute paths for JAR files
    • -
  • Completely restart the client application (quit, don't just close window)
    • -
  • Check client logs for error messages
    • -
-
- -

Docker Issues

- -
- Problem: "Container cannot access Solr"
- Solutions: -
    -
  • On macOS/Windows: Set SOLR_URL=http://host.docker.internal:8983/solr/
    • -
  • On Linux: Add --network host to docker run command
    • -
  • Alternative: Create a Docker network and connect both containers
    • -
-
- -

Common Query Patterns

- -
- Query Examples: -
    -
  • All documents: *:*
    • -
  • Exact match: field:"exact phrase"
    • -
  • Wildcards: field:test*
    • -
  • Range: price:[10 TO 20]
    • -
  • Boolean: field1:value1 AND field2:value2
    • -
-
- -

Advanced Topics

- -

Building from Source

- -
# Clone the repository
-git clone https://github.com/apache/solr-mcp.git
-cd solr-mcp
-
-# Build with Gradle
-./gradlew build
-
-# Run tests
-./gradlew test
-
-# Build Docker image locally
-./gradlew jibDockerBuild
- -

Custom Solr Connection

- -

Connect to a remote Solr instance:

-
{
-  "mcpServers": {
-    "solr-mcp": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/apache/solr-mcp:latest"],
-      "env": {
-        "SOLR_URL": "https://remote-solr.example.com:8983/solr/"
-      }
-    }
-  }
-}
- -
- Note: The current version supports basic Solr connections. Authentication support is planned for - future releases. -
- -

Performance Optimization

- -
    -
  • Large Result Sets: Use pagination (start and rows)
    • -
  • Faceting: Limit facet fields to essential ones
    • -
  • Filtering: Use filter queries (fq) for better caching
    • -
  • Field Selection: Request only needed fields with fl parameter
    • -
- -

Security Best Practices

- -
    -
  • Do not expose Solr directly to the internet
    • -
  • Use firewall rules to restrict access
    • -
  • Consider using Solr's built-in authentication when available
    • -
  • Run the MCP server with minimal required permissions
    • -
  • Keep Solr and MCP server versions up to date
    • -
- -

Additional Resources

- - - -
- -

This guide was created for Solr MCP Server version 0.0.1-SNAPSHOT. Last updated: November 2025.

- -

License: Apache License 2.0

- - \ No newline at end of file From 62bb7d7316a77eb3a98f9ee90f2609530add63a2 Mon Sep 17 00:00:00 2001 From: adityamparikh Date: Sat, 15 Nov 2025 10:29:28 -0500 Subject: [PATCH 5/5] deps: update dependency versions for spring-boot and spring-ai to 1.1.0 GA increment project version to 0.0.2-SNAPSHOT --- build.gradle.kts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.gradle.kts b/build.gradle.kts index ee35acf..991aa13 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -28,7 +28,7 @@ plugins { } group = "org.apache.solr" -version = "0.0.1-SNAPSHOT" +version = "0.0.2-SNAPSHOT" java { toolchain {