Solr MCP Server

🚀 Solr MCP 服務器

這是一個基於 Spring AI 模型上下文協議（MCP）的服務器，能提供與 Apache Solr 交互的工具。藉助該服務器，像 Claude 這樣的 AI 助手可通過 MCP 協議對 Apache Solr 進行搜索、索引和管理操作。

🚀 快速開始

Solr MCP 服務器是一個允許 AI 助手與 Apache Solr 交互的工具。以下是使用該服務器的快速入門步驟：

前提條件

• Java 21 或更高版本
• Docker 和 Docker Compose（用於運行 Solr）
• Gradle（用於構建項目）

安裝和設置

1. 克隆倉庫

git clone https://github.com/yourusername/solr-mcp-server.git
cd solr-mcp-server

2. 使用 Docker Compose 啟動 Solr

docker-compose up -d

這將以 SolrCloud 模式啟動一個 Solr 實例，並創建兩個示例集合：

• books - 包含示例書籍數據的集合
• films - 包含示例電影數據的集合

3. 構建並運行 MCP 服務器

./gradlew bootRun

✨ 主要特性

• 高級搜索：可使用高級查詢選項搜索 Solr 集合。
• 文檔索引：能將 JSON 文檔索引到 Solr 集合中。
• 集合管理：可管理和監控 Solr 集合。
• 模式檢索：能檢索和分析 Solr 模式信息。

📦 安裝指南

前提條件

• Java 21 或更高版本
• Docker 和 Docker Compose（用於運行 Solr）
• Gradle（用於構建項目）

安裝步驟

1. 克隆倉庫

git clone https://github.com/yourusername/solr-mcp-server.git
cd solr-mcp-server

2. 使用 Docker Compose 啟動 Solr

docker-compose up -d

這將以 SolrCloud 模式啟動一個 Solr 實例，並創建兩個示例集合：

• books - 包含示例書籍數據的集合
• films - 包含示例電影數據的集合

3. 構建並運行 MCP 服務器

./gradlew bootRun

💻 使用示例

基礎用法

搜索書籍

I need to search for fantasy books in the Solr collection. Can you help me?

Claude 可以使用搜索工具查詢書籍集合：

I'll search for fantasy books in the Solr collection.

Using the Search tool with:
- collection: books
- query: genre_s:fantasy
- rows: 5

Here are the fantasy books I found:
1. "A Game of Thrones" by George R.R. Martin
2. "A Clash of Kings" by George R.R. Martin
...

索引新文檔

I have some new book data I'd like to add to Solr. Can you help me index it?

Claude 可以使用 index_documents 工具：

I'll help you index that book data into Solr.

Using the index_documents tool with:
- collection: books
- json: [{"id":"123456789","name":["The New Book"],"author":["Jane Author"],"genre_s":"mystery","price":[12.99]}]

The document has been successfully indexed into the books collection.

列出集合

What Solr collections are available in the system?

Claude 可以使用 listCollections 工具：

I'll check what Solr collections are available.

Using the listCollections tool.

The following collections are available:
1. books
2. films

獲取集合統計信息

Can you tell me more about the 'books' collection? I'd like to know its size and other metrics.

Claude 可以使用 getCollectionStats 工具：

I'll get statistics for the 'books' collection.

Using the getCollectionStats tool with:
- collection: books

Here are the statistics for the 'books' collection:
- Number of documents: 1,245
- Segment count: 5
- Query performance:
  - Average query time: 12ms
  - Cache hit ratio: 0.85
- Handler statistics:
  - Select handler requests: 1,532
  - Update handler requests: 245

檢查集合健康狀態

Is the 'films' collection healthy and responding properly?

Claude 可以使用 checkHealth 工具：

I'll check the health of the 'films' collection.

Using the checkHealth tool with:
- collection: films

Health status:
- Healthy: Yes
- Response time: 8ms
- Total documents: 532
- Last checked: 2023-06-15 14:32:45

檢索模式信息

What fields are defined in the 'books' collection schema?

Claude 可以使用 getSchema 工具：

I'll retrieve the schema for the 'books' collection.

Using the getSchema tool with:
- collection: books

The 'books' collection has the following fields:
- id (string): Unique identifier
- name (text_general): Book title
- author (text_general): Book author
- genre_s (string): Genre
- price (float): Book price
- in_stock_b (boolean): Whether the book is in stock
- publish_date (date): Publication date

📚 詳細文檔

可用工具

服務器提供了以下可供 MCP 客戶端使用的工具：

1. 搜索

使用高級查詢選項搜索 Solr 集合。

Tool: Search
Description: Search specified Solr collection with query, optional filters, facets, sorting, and pagination.
Parameters:
  - collection: Solr collection to query
  - query: Solr q parameter (defaults to "*:*" if not specified)
  - filterQueries: Solr fq parameter (optional)
  - facetFields: Solr facet fields (optional)
  - sortClauses: Solr sort parameter (optional)
  - start: Starting offset for pagination (optional)
  - rows: Number of rows to return (optional)

2. 索引文檔

將 JSON 文檔索引到 Solr 集合中。

Tool: index_documents
Description: Index documents from JSON string into Solr collection
Parameters:
  - collection: Solr collection to index into
  - json: JSON string containing documents to index

3. 列出集合

列出所有可用的 Solr 集合。

Tool: listCollections
Description: List solr collections
Parameters: None

4. 獲取集合統計信息

獲取 Solr 集合的詳細統計信息和指標。

Tool: getCollectionStats
Description: Get stats/metrics on a Solr collection
Parameters:
  - collection: Name of the collection

5. 檢查集合健康狀態

檢查 Solr 集合的健康狀態。

Tool: checkHealth
Description: Check health of a Solr collection
Parameters:
  - collection: Name of the collection

6. 獲取模式

檢索 Solr 集合的模式。

Tool: getSchema
Description: Get schema for a Solr collection
Parameters:
  - collection: Name of the collection

添加到 Claude Desktop

要將此 MCP 服務器添加到 Claude Desktop，請按照以下步驟操作：

1. 將項目構建為獨立的 JAR 文件：

./gradlew bootJar

2. 在 Claude Desktop 中，轉到“設置”>“工具”>“添加工具”。

3. 選擇“MCP 服務器”作為工具類型。

4. 配置工具：

   • 名稱：Solr MCP 服務器
   • 描述：與 Apache Solr 交互的工具
   • 命令：java -jar /path/to/solr-mcp-server-0.0.1-SNAPSHOT.jar
   • 工作目錄：/path/to/solr-mcp-server

5. 點擊“添加工具”

或者，你可以將以下配置添加到 MCP 客戶端配置文件中：

"solr-search-mcp": {
  "command": "~/.sdkman/candidates/java/current/bin/java",
  "args": [
    "-jar",
    "~/solr-mcp-server/build/libs/solr-mcp-server-0.0.1-SNAPSHOT.jar"
  ],
  "env": {
    "SOLR_URL": "http://localhost:8983/solr/"
  }
}

注意：請調整路徑以匹配你的 Java 安裝位置和項目位置。

🔧 技術細節

該項目實現了 Spring AI MCP 協議，使用 SolrJ（Solr 的官方 Java 客戶端）與 Solr 實例進行通信。服務器提供了一系列工具，允許 MCP 客戶端與 Solr 進行交互，包括搜索、索引、管理和監控 Solr 集合，以及檢索和分析 Solr 模式信息。

📄 許可證

本項目採用 Apache 許可證 2.0 進行許可。

💡 使用建議

• 若遇到問題，要確保 Solr 正在運行且可訪問。默認情況下，服務器連接到 http://localhost:8983/solr/，你也可以設置 SOLR_URL 環境變量指向其他 Solr 實例。
• 查看日誌，以獲取可能存在的錯誤信息。
• 利用 Solr 管理界面驗證集合是否存在。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。