内容
# Easysearch MCP Server
Easysearch MCP Server，基于 Model Context Protocol (MCP) SDK 实现，提供 130+ 个工具覆盖 Easysearch 全功能。
## 技术栈
- Go 1.26.5
- github.com/elastic/go-elasticsearch/v7 v7.10.0
- github.com/modelcontextprotocol/go-sdk v1.4.1
- go.uber.org/zap v1.28.0
- github.com/spf13/cobra
- github.com/sony/gobreaker/v2
## 功能特性
| 模块 | 工具数 | 说明 |
|------|--------|------|
| 集群管理 | 8 | 健康检查、状态查看、设置更新、分片分配、路由重分配 |
| 索引管理 | 32 | 创建/删除/映射/设置/别名/克隆/拆分/收缩/滚动/冻结/重建 |
| 文档操作 | 6 | 写入/获取/更新/删除/批量/批量获取 |
| 基础搜索 | 5 | 关键词搜索/模板搜索/计数/多搜索/字段能力 |
| 高级搜索 | 5 | DSL 搜索/聚合/聚合简化/SQL 查询/KNN |
| 滚动搜索 | 3 | 滚动初始/继续/清除 |
| 监控 CAT | 19 | 节点/索引/分片/线程池/段/恢复/插件/快照/字段/模板/任务 |
| 节点管理 | 5 | 节点信息/统计/热点线程/使用统计 |
| 快照管理 | 7 | 仓库 CRUD/快照 CRUD+恢复 |
| 快照生命周期 | 4 | SLM 策略 CRUD+执行 |
| 任务管理 | 3 | 任务列表/详情/取消 |
| Ingest Pipeline | 4 | Pipeline CRUD+模拟 |
| 索引生命周期 | 5 | ILM 解释/状态/启停 |
| 搜索管道 | 4 | 搜索管道 CRUD + 设置索引默认管道 |
| 向量搜索 | 5 | embedding 生成/向量搜索/语义搜索（自动向量化）/混合搜索（RRF）/向量化 Pipeline |
| 安全管理 | 11 | 用户 CRUD/角色 CRUD/API Key CRUD+作废 |
| 跨集群复制 | 6 | Follow/Pause/Resume/Unfollow/状态/统计 |
| 监控告警 | 7 | Watch CRUD+执行+确认 |
| 数据转换 | 6 | Transform 启停+状态+CRUD |
## 快速开始
### 配置
复制 `config.yaml.example` 为 `config.yaml`：
```yaml
server:
url: http://localhost:9200
username: admin
password: your_password
verify_ssl: true
transport: http # stdio | http
host: 0.0.0.0
port: 8080
api_key: "" # HTTP 模式下的 API Key 认证（设置后需在请求头携带 Authorization: Bearer <api_key>）
timeout: 30 # 请求超时时间（秒）
log:
level: info
file_path: logs/easysearch-mcp.log
```
### 运行
```bash
# 本地编译运行
go build -o easysearch-mcp-server ./cmd/easysearch-mcp-server
./easysearch-mcp-server start -c config.yaml
# 或使用交叉编译部署到 Linux 服务器
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -ldflags="-s -w" -o easysearch-mcp-server ./cmd/easysearch-mcp-server
```
### 命令行子命令
| 命令 | 说明 |
|------|------|
| `start` | 启动 MCP 服务器 |
| `check` | 检查配置文件和 Easysearch 连通性 |
| `migrate` | 数据迁移工具（跨集群索引迁移，支持 scroll+bulk 和 dry-run） |
| `version` | 显示版本信息 |
```bash
# 检查配置和连通性
./easysearch-mcp-server check -c config.yaml
# 显示版本
./easysearch-mcp-server version
```
### 传输模式
- **stdio**：通过标准输入输出与 MCP 客户端通信
- **http**（Streamable HTTP）：监听 `host:port`，支持远程连接
### 认证与安全
当 `transport` 设置为 `http` 或 `sse` 时，可通过 `api_key` 配置启用 API Key 认证：
```bash
curl -X POST http://localhost:8080 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_api_key_here" \
-d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"cluster_health"}}'
```
### 健康检查
HTTP 模式下提供分级健康检查端点：
```bash
# 完整健康检查（包含 Elasticsearch、内存、磁盘、goroutine 检查）
curl http://localhost:8080/health
# 存活探针（liveness）
curl http://localhost:8080/health/live
# 就绪探针（readiness）
curl http://localhost:8080/health/ready
```
### Docker 部署
项目提供 Dockerfile 和 docker-compose.yml：
```bash
# 构建并启动
docker compose up -d
# 指定版本构建
VERSION=1.0.0 docker compose build
# 通过环境变量覆盖配置
EASYSEARCH_URL=http://192.168.1.100:9200 \
OLLAMA_URL=http://192.168.1.100:11434/api/embeddings \
docker compose up -d
```
环境变量：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `EASYSEARCH_URL` | `http://host.docker.internal:9200` | Easysearch 地址 |
| `EASYSEARCH_USERNAME` | 空 | ES 用户名 |
| `EASYSEARCH_PASSWORD` | 空 | ES 密码 |
| `EASYSEARCH_TRANSPORT` | `http` | 传输模式 |
| `OLLAMA_URL` | `http://host.docker.internal:11434/api/embeddings` | Ollama 地址 |
| `OLLAMA_MODEL` | `bge-large-zh-v1.5` | Embedding 模型 |
| `LOG_LEVEL` | `info` | 日志级别 |
## 文档
详细架构说明见 [`docs/项目架构.md`](docs/项目架构.md)。
## 向量搜索示例
通过 MCP 工具调用 Easysearch 向量检索功能。
### 1. 创建向量索引
向量字段类型为 `knn_dense_float_vector`，支持 LSH 或 exact 模型：
```json
{
"index": "my_vector_index",
"mappings": {
"properties": {
"title": { "type": "text" },
"content": { "type": "text" },
"content_vector": {
"type": "knn_dense_float_vector",
"knn": {
"dims": 1024,
"model": "lsh",
"similarity": "cosine",
"L": 99,
"k": 1
}
}
}
}
}
```
### 2. 生成向量嵌入
调用 Ollama 将文本转为向量：
```
embedding_generate text="向量搜索测试" model="quentinz/bge-large-zh-v1.5:latest" \
url="http://192.168.1.87:11434/api/embeddings"
```
返回 1024 维浮点数数组。
### 3. 向量搜索
使用 `knn_nearest_neighbors` 查询按相似度排序：
```
vector_search index="my_vector_index" field="content_vector" \
query_text="向量搜索测试" size=10
```
支持 `query_text` 模式（自动调用 Ollama 生成 embedding），也可直接传入 `query_vector`。可选参数 `model`（默认 lsh）、`similarity`（默认 cosine）、`candidates`（默认 size×10）。
### 4. 混合搜索（向量 + 全文）
使用官方 Search Pipeline + `hybrid` 查询类型 + RRF（倒数排序融合）实现混合搜索。
**第一步：创建搜索管道**
```json
{
"pipeline_id": "hybrid-pipeline",
"body": {
"rewrite_processors": [{
"semantic_query_enricher": {
"tag": "hybrid",
"url": "http://localhost:11434/v1/embeddings",
"vendor": "openai",
"api_key": "ollama",
"default_model_id": "quentinz/bge-large-zh-v1.5:latest",
"vector_field_model_id": { "content_vector": "quentinz/bge-large-zh-v1.5:latest" }
}
}],
"rerank_processors": [{
"hybrid_ranker_processor": {
"combination": { "technique": "rrf", "rank_constant": 60 }
}
}],
"enrich_processors": [{ "hybrid_score_explanation": {} }]
}
}
```
**第二步：设置索引默认管道**
```
search_pipeline_set_default index="my_vector_index" pipeline_id="hybrid-pipeline"
```
**第三步：执行混合搜索**
```
hybrid_search index="my_vector_index" query="搜索关键词" \
vector_field="content_vector" \
text_fields=["title","content"] \
title_boost=2.0 content_boost=1.0
```
可选参数 `pipeline_id`（不传则使用索引默认管道）、`candidates`（默认 size×10）、`query_strategy`（默认 LSH_COSINE）。
### 5. 语义搜索（文本自动向量化）
使用 `semantic` 查询类型，查询文本由 pipeline 的 `semantic_query_enricher` 服务端自动转为向量，无需客户端生成 embedding：
```
semantic_search index="my_vector_index" query_text="搜索关键词" \
vector_field="content_vector" size=10
```
需要预先创建含 `semantic_query_enricher` 的搜索管道并设为索引默认管道（参见第 4 节）。
### 6. 自动向量化 Pipeline
创建 Ingest Pipeline，写入文档时自动调用外部 embedding 服务生成向量：
```
vector_pipeline_create pipeline_id="text_to_vector" \
url="http://192.168.1.87:11434/api/embeddings" \
vendor="ollama" model_id="quentinz/bge-large-zh-v1.5:latest" dims=1024
```
之后写入文档只需提供 `content` 字段，Pipeline 自动填充 `content_vector`。
## 集成 OpenCode
### 远程模式
配置 `~/.config/opencode/opencode.json`：
```json
{
"mcp": {
"easysearch": {
"type": "remote",
"url": "http://<server>:8080"
}
}
}
```
### 本地模式
```json
{
"mcp": {
"easysearch": {
"type": "local",
"command": ["/path/to/easysearch-mcp-server"],
"env": {
"EASYSEARCH_URL": "http://localhost:9200",
"EASYSEARCH_USER": "admin",
"EASYSEARCH_PASSWORD": "your_password"
}
}
}
}
```
### 多环境配置
支持按环境加载配置文件，优先级：默认值 < `config.yaml` < `config.{env}.yaml` < 环境变量
```bash
# 通过 EASYSEARCH_ENV 指定环境
export EASYSEARCH_ENV=production
./easysearch-mcp-server start -c config.yaml
# 将自动加载 config.production.yaml 覆盖基础配置
```
### API 文档
启动 HTTP/SSE 模式后，访问以下端点查看 API 文档：
- `/docs` - Swagger UI 交互式文档
- `/openapi.json` - OpenAPI 3.0 规范
## 项目结构
```
cmd/easysearch-mcp-server/ 启动入口（Cobra CLI）
├── main.go 根命令
├── start.go start 子命令：启动服务
├── check.go check 子命令：配置检查
├── migrate.go migrate 子命令：数据迁移
└── version.go version 子命令：版本信息
internal/
├── api/ OpenAPI 文档生成
├── auth/ 认证中间件（API Key/Basic/JWT/Mixed）
├── breaker/ 熔断器（gobreaker 封装）
├── cache/ 响应缓存
├── client/ Easysearch HTTP 客户端
│ ├── client.go ESClient 接口与实现（重试/熔断/缓存/追踪）
│ └── mock_client.go 测试 Mock
├── config/ 配置加载（YAML + 环境变量 + fsnotify 热重载）
├── di/ 依赖注入容器
├── health/ 健康检查（ES/内存/磁盘/goroutine）
├── lifecycle/ 生命周期管理器（有序启停）
├── logger/ 日志封装（zap + lumberjack 轮转）
├── metrics/ Prometheus 指标采集
├── middleware/ HTTP 中间件链
├── pool/ goroutine 池
├── rate/ 令牌桶限流
├── security/ 安全中间件（CORS / Host 校验 / 响应头）
├── server/ HTTP 服务器 & MCP 集成
│ └── server.go EasysearchMCPServer 主结构
├── tools/ 工具实现（19 模块）
│ ├── tools.go Module 定义 & AddToolWithMetrics
│ ├── register.go 模块统一注册入口
│ ├── responses.go 统一响应格式 ToolResponse
│ ├── ollama_client.go Ollama Embedding HTTP 客户端
│ ├── cluster.go 集群管理（8 工具）
│ ├── indices.go 索引管理（32 工具）
│ ├── documents.go 文档操作（6 工具）
│ ├── search_basic.go 基础搜索（5 工具）
│ ├── search_advanced.go 高级搜索（5 工具）
│ ├── search_scroll.go 滚动搜索（3 工具）
│ ├── search_pipeline.go 搜索管道（4 工具）
│ ├── cat.go CAT API（19 工具）
│ ├── nodes.go 节点管理（5 工具）
│ ├── snapshot.go 快照管理（7 工具）
│ ├── slm.go 快照生命周期（4 工具）
│ ├── tasks.go 任务管理（3 工具）
│ ├── ingest.go Ingest Pipeline（4 工具）
│ ├── ilm.go 索引生命周期（5 工具）
│ ├── vector.go 向量搜索与混合搜索（5 工具）
│ ├── security.go 安全管理（11 工具）
│ ├── ccr.go 跨集群复制（6 工具）
│ ├── transform.go 数据转换（6 工具）
│ └── watch.go 监控告警（7 工具）
├── tracing/ 链路追踪（X-Trace-ID / X-Span-ID）
└── validator/ 请求体大小校验
docs/
├── 项目架构.md 详细架构说明
integration/ 集成测试（端到端）
benchmark/ 性能基准测试
```
## 开发
```bash
go build ./...
go vet ./...
```
### 静态代码检查
项目使用 [golangci-lint](https://golangci-lint.run/) 进行静态代码分析，配置文件位于 `.golangci.yml`，启用了 errcheck、gosimple、govet、staticcheck、bodyclose、revive 等检查器。
```bash
# 安装 golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
# 运行静态检查
golangci-lint run ./...
# 自动修复可修复的问题
golangci-lint run --fix ./...
```
### 测试
```bash
# 运行全部单元测试
go test ./...
# 运行测试并显示覆盖率
go test ./internal/... -cover -count=1
# 运行集成测试
go test ./integration/ -count=1
# 运行基准测试
go test -bench=. -benchmem -run=^$ ./benchmark/
```
### 测试覆盖率
| 模块 | 覆盖率 |
|------|--------|
| cache | 100% |
| pool | 98.3% |
| api | 97.8% |
| tracing | 97.6% |
| middleware | 92.3% |
| breaker | 90.9% |
| lifecycle | 90.4% |
| rate | 89.7% |
| metrics | 89.3% |
| security | 83.6% |
| health | 81.0% |
| config | 78.2% |
| logger | 67.3% |
| client | 65.9% |
| di | 61.7% |
| server | 26.5% |
| auth | 30.7% |
| validator | 14.1% |
| tools | 13.6% |
# 参考
https://github.com/cloudsmithy/easysearch-mcp-server
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器