Solr MCP Server

Solr MCP 服务器

一个Spring AI模型上下文协议（MCP）服务器，它提供了与Apache Solr交互的工具。此服务器使像Claude这样的AI助手能够通过MCP协议搜索、索引和管理Solr集合。

概述

这个项目提供了一套工具，使人工智能助手能够与Apache Solr（一个强大的开源搜索平台）进行交互。通过实现Spring AI MCP协议，这些工具可以被任何兼容MCP的客户端使用，包括Claude Desktop。项目使用SolrJ（Solr的官方Java客户端）来与Solr实例进行通信。

服务器提供以下功能：

• 使用高级查询选项搜索Solr集合
• 将文档索引到Solr集合中
• 管理并监控Solr集合
• 检索并分析Solr模式信息

传输配置文件

服务器支持两种传输模式：

• STDIO（标准输入/输出） - 推荐在本地开发和生产环境中使用Claude Desktop。这是

本地部署的默认且最安全的选项。

• HTTP（可流式传输的HTTP） - 用于与MCP Inspector进行测试和远程部署。 ⚠️ 注： HTTP（超文本传输协议）

在没有额外安全措施的情况下，该模式本身是不安全的（见下文的安全考虑部分）。

先决条件

• Java 25或更高版本
• Docker 和 Docker Compose（用于运行 Solr）
• Gradle 9.1.0+（项目中包含的包装器）

安装与设置

1. 克隆仓库

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

2. 使用Docker Compose启动Solr

docker-compose up -d

这将在SolrCloud模式下启动一个带有ZooKeeper的Solr实例，并创建两个示例集合：

• books - 一个包含样本书籍数据的集合
• films - 一个包含样本电影数据的集合

3. 构建项目

这个项目使用了带有版本目录的Gradle来进行依赖管理。所有依赖项及其版本都 在中央管理下 gradle/libs.versions.toml.

# Build the project and run tests
./gradlew build

# Build without tests (faster)
./gradlew assemble

# Clean and rebuild
./gradlew clean build

构建过程会生成两个JAR文件 build/libs/：

• solr-mcp-server-0.0.1-SNAPSHOT.jar - 可执行的包含所有依赖项的JAR文件（胖JAR）
• solr-mcp-server-0.0.1-SNAPSHOT-plain.jar - 不包含依赖项的纯JAR文件

项目结构

代码库遵循一种清晰、模块化的架构，按功能进行组织：

src/main/java/org/apache/solr/mcp/server/
├── Main.java                           # Application entry point
├── config/                             # Configuration classes
│   ├── SolrConfig.java                # Solr client bean configuration
│   └── SolrConfigurationProperties.java # Solr connection properties
├── search/                             # Search functionality
│   ├── SearchService.java             # MCP tool for searching Solr
│   └── SearchResponse.java            # Search result DTOs
├── indexing/                           # Document indexing functionality
│   ├── IndexingService.java           # MCP tool for indexing documents
│   └── documentcreator/               # Document format parsers
│       ├── IndexingDocumentCreator.java    # Interface for document creators
│       ├── JsonDocumentCreator.java        # JSON document parser
│       ├── CsvDocumentCreator.java         # CSV document parser
│       ├── XmlDocumentCreator.java         # XML document parser
│       ├── SolrDocumentCreator.java        # Factory for document creators
│       ├── FieldNameSanitizer.java         # Field name sanitization utility
│       └── DocumentProcessingException.java # Indexing exceptions
└── metadata/                           # Collection management functionality
    ├── CollectionService.java         # MCP tools for collection operations
    ├── SchemaService.java             # MCP tool for schema retrieval
    ├── CollectionUtils.java           # Collection utility methods
    └── Dtos.java                      # Collection-related DTOs (records)

关键组件

• MCP 工具带有注解的服务类 @McpTool 向AI助手开放功能

- SearchService - 带有过滤、分面和分页功能的搜索查询 - IndexingService - 文档索引，支持JSON、CSV和XML格式 - CollectionService - 集合管理（列表、统计、健康检查） - SchemaService - 模式内省（或模式自省）

• 配置使用属性文件进行Spring Boot配置

- application.properties - 默认配置 - application-stdio.properties - STDIO传输配置文件 - application-http.properties - HTTP传输配置文件

• 文档创建者解析不同文档格式的策略模式实现

- 自动对字段名进行清理，以符合Solr模式要求 - 支持嵌套JSON结构和多值字段

• DTOs（Data Transfer Objects，数据传输对象）Java 中用于不可变数据传输对象的记录（已移除 Lombok 依赖）

可用工具

服务器提供了以下工具，供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 build

1. 在Claude Desktop中，前往设置 > 开发者 > 编辑配置

1. 在您的MCP设置中添加以下配置：

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

注： 替换 /absolute/path/to/solr-mcp-server 替换为您项目目录的实际路径。

4. 重启Claude桌面版并调用

claude-stdio.png

使用MCP Inspector进行测试

为了开发和测试，您可以使用 MCP Inspector（中文可译为）：MCP（最小变化差）检测器/监察器：

# Install the MCP Inspector (requires Node.js)
➜  ~ npx @modelcontextprotocol/inspector

Starting MCP inspector...
⚙️ Proxy server listening on localhost:6277
🔑 Session token: 12345
   Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth

🚀 MCP Inspector is up and running at:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=12345

🌐 Opening browser...

这提供了一个网页界面，用于交互式测试MCP工具。 mcp-inspector-stdio.png

HTTP 模式

mcp-inspector-http.png

./gradlew bootRun --args='--spring.profiles.active=http'

工具使用示例

以下是一些如何使用像Claude这样的MCP客户端工具的例子：

寻找书籍

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

克劳德可以使用搜索工具来查询书籍收藏：

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?

克劳德可以使用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?

克劳德可以使用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.

克劳德可以使用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?

克劳德可以使用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?

克劳德可以使用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

安全考量

STDIO 传输安全

STDIO传输是本地部署的推荐选项，因为：

• 在同一台机器内，通过进程管道进行通信
• 无网络暴露或开放端口
• 操作系统级别的进程隔离提供了安全边界
• 凭证不会在网络中暴露

HTTP传输安全风险

⚠️ 警告当前的HTTP实现是 不安全的 用于生产，无需额外安全措施 措施。

在未部署认证的情况下，HTTP传输存在以下安全漏洞：

1. 无身份验证或授权默认情况下，HTTP 端点是公开可访问的，无需任何（额外设置/权限）

认证机制

1. 无传输加密HTTP流量未加密，可能会被拦截（生产环境中请使用HTTPS）
2. 无来源验证如果没有对来源头部进行适当的验证，服务器将容易受到DNS劫持攻击
3. 网络暴露与STDIO不同，HTTP端点通过网络暴露，并且任何能够（访问的客户端）都可以访问

连接到服务器

确保HTTP部署的安全性

如果您需要部署带有HTTP传输的MCP服务器以进行远程访问，您 必须 实施安全措施 控制：

1. 使用HTTPS在生产环境中始终使用TLS/SSL加密
2. 实现OAuth2认证跟随

这个（或那个，根据上下文确定具体指代） Spring AI MCP OAuth2 指南 添加身份验证

1. 验证Origin头部信息实施Origin头部验证以防止DNS重绑定攻击
2. 网络隔离部署在防火墙或VPN之后，限制访问仅限于受信任的网络
3. 使用API网关考虑在具备身份验证和速率限制的API网关后部署

建议

• 本地开发/测试使用MCP Inspector进行测试时，请采用HTTP模式，但仅限于本地主机（localhost）
• Claude Desktop 集成始终使用STDIO模式
• 远程生产部署仅使用带有OAuth2认证的HTTP、HTTPS以及适当的网络安全措施

控制装置/控制器

故障排除

如果您遇到问题：

1. 确保Solr正在运行且可访问。默认情况下，服务器连接到http://localhost:8983/solr/，但您可以设置（连接地址） SOLR_URL 环境变量指向另一个 Solr 实例。
2. 检查日志中的任何错误信息
3. 使用 Solr 管理界面验证集合是否存在
4. 如果使用HTTP模式，请确保服务器在预期的端口上运行（默认：8080）
5. 对于Claude Desktop的STDIO模式，请在配置中验证JAR路径是否为绝对路径且正确

许可证

此项目遵循Apache License 2.0协议授权。

贡献；做出贡献

欢迎贡献！请随时提交拉取请求。