项目介绍
Solr MCP 服务器
这是一个基于 Spring AI 模型上下文协议（MCP）的服务器，提供了与 Apache Solr 交互的工具。该服务器使像 Claude 这样的AI助手能够通过 MCP 协议搜索、索引和管理 Solr 集合。
概述
该项目提供了一组工具，允许AI助手与 Apache 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+（项目中包含 wrapper）
安装和设置
1. 克隆仓库
git clone https://github.com/yourusername/solr-mcp-server.git
cd solr-mcp-server
2. 使用 Docker Compose 启动 Solr
docker-compose up -d
这将启动一个 Solr 实例，以 SolrCloud 模式运行，并带有 ZooKeeper，创建两个示例集合：
books- 包含示例书籍数据的集合films- 包含示例电影数据的集合
3. 构建项目
此项目使用 Gradle 和版本目录进行依赖管理。所有依赖及其版本都集中管理在 gradle/libs.versions.toml 中。
# 构建项目并运行测试
./gradlew build
# 不运行测试构建（更快）
./gradlew assemble
# 清理并重新构建
./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 # 应用程序入口点
├── config/ # 配置类
│ ├── SolrConfig.java # Solr 客户端 Bean 配置
│ └── SolrConfigurationProperties.java # Solr 连接属性
├── search/ # 搜索功能
│ ├── SearchService.java # MCP 工具用于搜索 Solr
│ └── SearchResponse.java # 搜索结果 DTO
├── indexing/ # 文档索引功能
│ ├── IndexingService.java # MCP 工具用于索引文档
│ └── documentcreator/ # 文档格式解析器
│ ├── IndexingDocumentCreator.java # 文档创建者接口
│ ├── JsonDocumentCreator.java # JSON 文档解析器
│ ├── CsvDocumentCreator.java # CSV 文档解析器
│ ├── XmlDocumentCreator.java # XML 文档解析器
│ ├── SolrDocumentCreator.java # 文档创建者的工厂
│ ├── FieldNameSanitizer.java # 字段名净化工具
│ └── DocumentProcessingException.java # 索引异常
└── metadata/ # 集合管理功能
├── CollectionService.java # MCP 工具用于集合操作
├── SchemaService.java # MCP 工具用于获取架构
├── CollectionUtils.java # 集合实用方法
└── Dtos.java # 与集合相关的 DTO（记录）
关键组件
-
MCP 工具：标注了
@McpTool的服务类向 AI 助手暴露功能SearchService- 带有过滤、分面和分页的搜索查询IndexingService- 支持 JSON、CSV 和 XML 格式的文档索引CollectionService- 集合管理（列表、统计、健康检查）SchemaService- 架构内省
-
配置：使用属性文件的 Spring Boot 配置
application.properties- 默认配置application-stdio.properties- STDIO 传输配置文件application-http.properties- HTTP 传输配置文件
-
文档创建者：策略模式实现用于解析不同文档格式
- 自动净化字段名以符合 Solr 架构要求
- 支持嵌套的 JSON 结构和多值字段
-
DTO：用于不可变数据传输对象的 Java 记录（移除了 Lombok 依赖）
可用工具
服务器提供了以下工具，可供 MCP 客户端使用：
1. 搜索
使用高级查询选项搜索 Solr 集合。
工具: Search
描述: 使用查询、可选过滤器、分面、排序和分页搜索指定的 Solr 集合。
参数:
- collection: 要查询的 Solr 集合
- query: Solr q 参数（未指定时默认为 "*:*"）
- filterQueries: Solr fq 参数（可选）
- facetFields: Solr 分面字段（可选）
- sortClauses: Solr 排序参数（可选）
- start: 分页起始偏移量（可选）
- rows: 返回的行数（可选）
2. 索引文档
将 JSON 文档索引到 Solr 集合中。
工具: index_documents
描述: 将 JSON 字符串中的文档索引到 Solr 集合中
参数:
- collection: 要索引到的 Solr 集合
- json: 包含要索引文档的 JSON 字符串
3. 列出集合
列出所有可用的 Solr 集合。
工具: listCollections
描述: 列出 Solr 集合
参数: 无
4. 获取集合统计
获取 Solr 集合的详细统计和指标。
工具: getCollectionStats
描述: 获取 Solr 集合的统计/指标
参数:
- collection: 集合名称
5. 检查集合健康
检查 Solr 集合的健康状态。
工具: checkHealth
描述: 检查 Solr 集合的健康
参数:
- collection: 集合名称
6. 获取架构
检索 Solr 集合的架构。
工具: getSchema
描述: 获取 Solr 集合的架构
参数:
- collection: 集合名称
添加到 Claude Desktop
要将此 MCP 服务器添加到 Claude Desktop：
- 构建项目为独立 JAR：
./gradlew build
-
在 Claude Desktop 中，前往 设置 > 开发者 > 编辑配置
-
在您的 MCP 设置中添加以下配置：
{
"mcpServers": {
"solr-search-mcp": {
"command": "java",
"args": [
"-jar",
"/绝对路径/到/solr-mcp-server/build/libs/solr-mcp-server-0.0.1-SNAPSHOT.jar"
],
"env": {
"SOLR_URL": "http://localhost:8983/solr/",
"PROFILES": "stdio"
}
}
}
}
注意：将 /绝对路径/到/solr-mcp-server 替换为您项目的实际路径。
4. 重启 Claude Desktop 并调用
使用 MCP Inspector 测试
对于开发和测试，您可以使用 MCP Inspector：
# 安装 MCP Inspector（需要 Node.js）
➜ ~ npx @modelcontextprotocol/inspector
启动 MCP Inspector...
⚙️ 代理服务器监听 localhost:6277
🔑 会话令牌: 12345
使用此令牌来认证请求或设置 DANGEROUSLY_OMIT_AUTH=true 来禁用认证
🚀 MCP Inspector 正在运行于：
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=12345
🌐 打开浏览器...
这提供了一个 Web 界面，用于交互式地测试 MCP 工具。
HTTP 模式
./gradlew bootRun --args='--spring.profiles.active=http'
工具使用示例
这里有一些如何从像 Claude 这样的 MCP 客户端使用工具的例子：
搜索书籍
我需要在 Solr 集合中搜索奇幻类书籍。你能帮我吗？
Claude 可以使用 Search 工具查询书籍集合：
我将在 Solr 集合中搜索奇幻类书籍。
使用 Search 工具：
- collection: books
- query: genre_s:fantasy
- rows: 5
这是我找到的奇幻书籍：
1. "A Game of Thrones" by George R.R. Martin
2. "A Clash of Kings" by George R.R. Martin
...
索引新文档
我有一些新的书籍数据想要添加到 Solr。你能帮我索引它吗？
Claude 可以使用 index_documents 工具：
我将帮助您将这些书籍数据索引到 Solr 中。
使用 index_documents 工具：
- collection: books
- json: [{"id":"123456789","name":["The New Book"],"author":["Jane Author"],"genre_s":"mystery","price":[12.99]}]
该文档已成功索引到书籍集合中。
列出集合
系统中有哪些 Solr 集合？
Claude 可以使用 listCollections 工具：
我将检查有哪些 Solr 集合可用。
使用 listCollections 工具。
以下是可用的集合：
1. books
2. films
获取集合统计
你能告诉我关于 'books' 集合的更多信息吗？我想知道它的大小和其他指标。
Claude 可以使用 getCollectionStats 工具：
我将获取 'books' 集合的统计信息。
使用 getCollectionStats 工具：
- collection: books
以下是 'books' 集合的统计信息：
- 文档数量: 1,245
- 分段计数: 5
- 查询性能：
- 平均查询时间: 12ms
- 缓存命中率: 0.85
- 处理器统计：
- Select 处理器请求: 1,532
- Update 处理器请求: 245
检查集合健康
'films' 集合是否健康并且响应正常？
Claude 可以使用 checkHealth 工具：
我将检查 'films' 集合的健康状况。
使用 checkHealth 工具：
- collection: films
健康状况：
- 健康: 是
- 响应时间: 8ms
- 总文档数: 532
- 最后检查时间: 2023-06-15 14:32:45
检索架构信息
'books' 集合的架构定义了哪些字段？
Claude 可以使用 getSchema 工具：
我将检索 'books' 集合的架构。
使用 getSchema 工具：
- collection: books
'books' 集合有以下字段：
- id (string): 唯一标识符
- name (text_general): 书名
- author (text_general): 作者
- genre_s (string): 类别
- price (float): 书价
- in_stock_b (boolean): 是否有库存
- publish_date (date): 出版日期
安全考虑
STDIO 传输安全
STDIO 传输是推荐的本地部署选项，因为：
- 通过进程管道在同一台机器上进行通信
- 没有网络暴露或开放端口
- 操作系统级别的进程隔离提供了安全边界
- 凭据不会在网络上传输
HTTP 传输安全风险
⚠️ 警告：当前的 HTTP 实现如果没有额外的安全措施，在生产环境中是不安全的。
当部署 HTTP 传输而没有身份验证时，存在以下安全漏洞：
- 没有身份验证或授权：默认情况下，HTTP 端点是公开访问的，没有任何身份验证机制
- 没有传输加密：HTTP 流量是未加密的，可以被拦截（生产中使用 HTTPS）
- 没有来源验证：没有适当的来源头验证，服务器容易受到 DNS 重绑定攻击
- 网络暴露：与 STDIO 不同，HTTP 端点在网络上暴露，并且任何能够到达服务器的客户端都可以访问
保护 HTTP 部署
如果您需要使用 HTTP 传输进行远程访问部署 MCP 服务器，必须实施安全控制：
- 使用 HTTPS：始终为生产部署使用 TLS/SSL 加密
- 实现 OAuth2 身份验证：遵循 Spring AI MCP OAuth2 指南 添加身份验证
- 验证来源头：实现来源头验证以防止 DNS 重绑定攻击
- 网络隔离：部署在防火墙或 VPN 后面，限制访问可信网络
- 使用 API 网关：考虑部署在具有身份验证和速率限制的 API 网关后面
建议
- 本地开发/测试：使用 HTTP 模式与 MCP Inspector 测试，但仅限于 localhost
- Claude Desktop 集成：始终使用 STDIO 模式
- 生产远程部署：仅在使用 OAuth2 身份验证、HTTPS 和适当网络安全控制的情况下使用 HTTP
故障排除
如果遇到问题：
- 确保 Solr 正在运行并且可访问。默认情况下，服务器连接到 http://localhost:8983/solr/，但可以通过设置
SOLR_URL环境变量指向不同的 Solr 实例。 - 查看日志中的错误消息
- 使用 Solr 管理 UI 验证集合是否存在
- 如果使用 HTTP 模式，请确保服务器正在预期的端口上运行（默认：8080）
- 对于与 Claude Desktop 结合使用的 STDIO 模式，请验证配置中的 JAR 路径是绝对且正确的
许可
本项目根据 Apache 许可证 2.0 发布。
贡献
欢迎贡献！请随时提交 Pull Request。