solr-mcp-server

longkeyy/solr-mcp-server

3.1

If you are the rightful owner of solr-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Solr MCP Server is a comprehensive toolset designed to facilitate interaction between LLMs and the Apache Solr search engine.

Tools
5
Resources
0
Prompts
0

Solr MCP Server

Go Version

Apache Solr MCP (Model Context Protocol) Server - 为 LLM 提供与 Apache Solr 搜索引擎交互的完整工具集。

🚀 特性

🔄 智能模式检测

  • 自动识别 Solr 部署模式: 智能检测 SolrCloud 模式或传统 Core 模式
  • 无缝回退机制: 当 SolrCloud API 不可用时，自动回退到 Core API
  • 统一接口体验: 无论底层模式如何，提供一致的工具接口

📋 集合管理

  • list_collections: 列出所有可用的 Solr 集合（自动检测 SolrCloud 或 Core 模式）
  • get_collection_info: 获取集合的详细信息（状态、模式、字段等，支持按需获取）

🔍 查询功能

  • search: 执行灵活的 Solr 查询（支持关键字、过滤器、返回字段、排序等）
  • facet_search: 执行带分面统计的查询
  • suggest: 获取查询建议和自动补全

📝 索引操作

  • add_document: 添加单个文档到集合
  • add_documents: 批量添加文档到集合
  • update_document: 原子更新文档
  • delete_document: 删除指定文档
  • delete_by_query: 根据查询条件批量删除文档
  • commit: 提交索引更改（支持软提交和硬提交）

📊 分析工具

  • get_terms: 获取字段中的词条统计信息
  • analyze_field: 分析文本在指定字段中的处理过程

⚙️ 管理功能

  • optimize: 优化索引性能
  • reload_collection: 重新加载集合配置

🔧 工作模式

Solr MCP Server 支持三种工作模式，可根据不同需求选择合适的功能集：

📋 完整模式 (Complete)

  • 功能: 包含所有功能，包括索引管理功能
  • 适用场景: 完整的 Solr 管理和开发环境
  • 可用工具: 查询、索引操作、集合管理、分析工具、管理功能

🔍 轻量模式 (Lightweight)

  • 功能: 仅开放索引检索功能
  • 适用场景: 生产环境的只读查询、数据分析
  • 可用工具: search、facet_search、suggest
  • 特点: 所有查询工具中的 collection 参数都会显示可用集合列表

🚀 高级模式 (Advanced)

  • 功能: 包括文档的添加删除功能
  • 适用场景: 需要文档操作但不需要集合管理的场景
  • 可用工具: 查询功能 + 文档操作（add_document、add_documents、update_document、delete_document、delete_by_query）

配置工作模式

在配置文件中指定工作模式：

# 工作模式 (complete, lightweight, advanced)
work_mode: "lightweight"

# 默认返回行数（可配置）
default_rows: 10

或通过环境变量：

export SOLR_MCP_WORK_MODE="lightweight"
export SOLR_MCP_DEFAULT_ROWS=20

📦 安装

前置条件

  • Go 1.22 或更高版本
  • Apache Solr 服务器（7.0+ 推荐）

从源码构建

# 克隆项目
git clone https://github.com/solrcn/solr-mcp-server.git
cd solr-mcp-server

# 安装依赖
make deps

# 构建项目
make build

# 安装到系统
make install

预构建二进制文件

从 Releases 页面下载适合您系统的预构建版本。

⚙️ 配置

配置文件

复制示例配置文件并根据需要修改：

cp config.yaml.example config.yaml

# Solr 服务器配置
solr_url: "http://localhost:8983/solr"

# 认证信息（可选）
username: "admin"
password: "password"

# 连接设置
timeout: 30
max_retries: 3

# 日志级别
log_level: "info"

# 工作模式 (complete, lightweight, advanced)
work_mode: "complete"

# 默认返回行数
default_rows: 10

环境变量

您也可以使用环境变量进行配置：

export SOLR_MCP_SOLR_URL="http://localhost:8983/solr"
export SOLR_MCP_DEFAULT_COLLECTION="documents"
export SOLR_MCP_USERNAME="admin"
export SOLR_MCP_PASSWORD="password"
export SOLR_MCP_TIMEOUT=30
export SOLR_MCP_MAX_RETRIES=3
export SOLR_MCP_LOG_LEVEL="info"
export SOLR_MCP_WORK_MODE="lightweight"
export SOLR_MCP_DEFAULT_ROWS=10

🚀 使用方法

命令行启动

# 基本启动（使用默认配置）
./solr-mcp-server

# 指定 Solr 服务器和集合
./solr-mcp-server -u http://localhost:8983/solr -c documents

# 使用认证
./solr-mcp-server -u http://solr:8983/solr -U admin -P password

# 调试模式
./solr-mcp-server -v debug -u http://localhost:8983/solr

# 指定配置文件
./solr-mcp-server --config /etc/solr-mcp/config.yaml

# 显示帮助信息
./solr-mcp-server --help

# 显示版本信息
./solr-mcp-server --version

命令行参数说明

参考 Apache Solr 的启动参数设计，支持以下主要参数：

短参数长参数说明默认值
-u--solr-urlSolr 服务器 URLhttp://localhost:8983/solr
-c--collection默认集合名称无
-U--usernameSolr 用户名无
-P--passwordSolr 密码无
-t--timeout请求超时时间（秒）30
-r--max-retries最大重试次数3
-v--verbose日志级别info
--config配置文件路径自动搜索

配置文件启动

# 使用默认配置文件位置
./solr-mcp-server

# 指定配置文件
./solr-mcp-server --config /path/to/config.yaml

环境变量启动

# 使用环境变量
export SOLR_MCP_SOLR_URL="http://localhost:8983/solr"
export SOLR_MCP_DEFAULT_COLLECTION="documents"
export SOLR_MCP_USERNAME="admin"
export SOLR_MCP_PASSWORD="password"
./solr-mcp-server

子命令

# 启动服务器（默认行为）
./solr-mcp-server start

# 显示当前配置
./solr-mcp-server config show

# 测试 Solr 连接
./solr-mcp-server test -u http://localhost:8983/solr

配置优先级

配置参数的优先级（从高到低）：

  1. 命令行参数
  2. 环境变量
  3. 配置文件
  4. 默认值

开发模式

# 开发模式运行
make dev

# 或者直接使用 go run
go run . -v debug -u http://localhost:8983/solr

与 MCP 客户端集成

Solr MCP Server 通过标准输入输出与 MCP 客户端通信。您可以在支持 MCP 的应用程序中使用它：

  1. Claude Desktop: 在设置中添加 MCP 服务器配置
  2. 其他 MCP 客户端: 按照各客户端的文档进行配置

示例 MCP 客户端配置：

{
  "mcpServers": {
    "solr": {
      "command": "/path/to/solr-mcp-server",
      "env": {
        "SOLR_MCP_SOLR_URL": "http://localhost:8983/solr"
      }
    }
  }
}

🔧 工具使用示例

列出集合/核心（智能模式检测）

{
  "tool": "list_collections",
  "arguments": {}
}

SolrCloud 模式响应示例:

检测到 SolrCloud 模式，找到 3 个集合:
["documents", "products", "logs"]

Core 模式响应示例:

检测到 Core 模式，找到 2 个核心:
["collection1", "core2"]

获取集合信息（统一工具）

{
  "tool": "get_collection_info",
  "arguments": {
    "collection": "documents",
    "info_type": "status"
  }
}

支持的信息类型:

  • status - 获取集合状态信息
  • schema - 获取完整模式定义
  • fields - 获取字段列表
  • all - 获取所有信息（默认）

查询文档

{
  "tool": "search",
  "arguments": {
    "collection": "documents",
    "query": "title:机器学习",
    "filter": ["category:技术", "publish_date:[2023-01-01T00:00:00Z TO *]"],
    "fields": ["id", "title", "content", "score"],
    "sort": "score desc",
    "start": 0,
    "rows": 10
  }
}

添加文档

{
  "tool": "add_document",
  "arguments": {
    "collection": "documents", 
    "document": {
      "id": "doc123",
      "title": "Solr 使用指南",
      "content": "这是一个关于 Apache Solr 的详细使用指南...",
      "category": "技术",
      "author": "张三"
    },
    "commit": true
  }
}

分面查询

{
  "tool": "facet_search",
  "arguments": {
    "collection": "documents",
    "query": "*:*",
    "facet_fields": ["category", "author", "publish_year"],
    "filter": ["status:published"]
  }
}

🧪 开发

项目结构

solr-mcp-server/
├── main.go                 # 主入口点
├── internal/
│   ├── config/             # 配置管理
│   ├── client/             # Solr HTTP 客户端
│   ├── logger/             # 日志系统
│   ├── server/             # MCP 服务器
│   └── tools/              # MCP 工具实现
├── pkg/
│   └── types/              # 共享类型定义
├── config.yaml.example     # 配置文件示例
├── Makefile               # 构建脚本
└── README.md              # 项目文档

开发命令

# 格式化代码
make fmt

# 代码检查
make vet

# 运行 linter
make lint

# 运行测试
make test

# 测试覆盖率
make test-coverage

# 构建
make build

# 完整 CI 检查
make ci

添加新工具

  1. 在 internal/tools/ 中创建新的工具文件
  2. 实现 MCP 工具接口
  3. 在相应的 Register*Tools 函数中注册新工具
  4. 更新文档和测试

测试

# 运行所有测试
make test

# 生成覆盖率报告
make test-coverage

# 运行性能测试
make benchmark

🐳 Docker 支持

# 构建 Docker 镜像
make docker-build

# 运行 Docker 容器
make docker-run

# 或者使用 docker compose
docker-compose up

📊 性能

  • 并发支持: 支持多个并发 MCP 请求
  • 连接池: 自动管理 HTTP 连接池
  • 重试机制: 自动重试失败的请求
  • 超时控制: 可配置的请求超时时间
  • 资源优化: 最小内存占用和 CPU 使用

🛡️ 安全

  • 认证支持: 支持基本身份认证
  • HTTPS: 支持 SSL/TLS 加密连接
  • 输入验证: 严格的参数验证和清理
  • 错误处理: 安全的错误信息处理

🤝 贡献

我们欢迎各种形式的贡献！

  1. Fork 本项目
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 创建 Pull Request

请确保：

  • 遵循现有的代码风格
  • 添加适当的测试
  • 更新相关文档

📄 许可证

本项目基于 MIT 许可证开源。详见 文件。

🙋‍♂️ 支持

🏗️ 路线图

  • 支持 Solr Cloud 模式
  • GraphQL 查询支持
  • 实时推荐功能
  • 性能监控面板
  • 插件系统
  • 更多数据格式支持

📈 状态

本项目正在积极开发中。当前版本：v1.0.0

注意: 请确保您的 Solr 服务器已正确配置并运行，然后再使用本 MCP 服务器。