# Easysearch MCP Server
<p align="center">
<a href="https://github.com/cloudsmithy/easysearch-mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python"></a>
</p>
让 AI Agent 能够操作 [INFINI Easysearch](https://infinilabs.com/products/easysearch/)（兼容 Elasticsearch/OpenSearch API）的 MCP 服务器。
## 特性
- 🔧 **121 个工具** - 覆盖集群、索引、文档、搜索、监控等全部功能
- 🔌 **即插即用** - 支持 Kiro、Claude Desktop 等 MCP 客户端
- 🔒 **安全连接** - 支持 HTTPS 和基础认证
- ⚡ **高性能** - 基于 httpx 异步 HTTP 客户端
## 安装
```bash
# 克隆仓库
git clone https://github.com/cloudsmithy/easysearch-mcp-server.git
cd easysearch-mcp-server
# 安装依赖
pip install -e .
```
## 快速开始
### 1. 配置 MCP 客户端
**Kiro** (`.kiro/settings/mcp.json`):
```json
{
"mcpServers": {
"easysearch": {
"command": "python3",
"args": ["-m", "easysearch_mcp.server"],
"cwd": "/path/to/easysearch-mcp-server/src",
"env": {
"EASYSEARCH_URL": "https://localhost:9200",
"EASYSEARCH_USER": "admin",
"EASYSEARCH_PASSWORD": "your-password",
"PYTHONPATH": "/path/to/easysearch-mcp-server/src"
}
}
}
}
```
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"easysearch": {
"command": "python3",
"args": ["-m", "easysearch_mcp.server"],
"cwd": "/path/to/easysearch-mcp-server/src",
"env": {
"EASYSEARCH_URL": "https://localhost:9200",
"EASYSEARCH_USER": "admin",
"EASYSEARCH_PASSWORD": "your-password",
"PYTHONPATH": "/path/to/easysearch-mcp-server/src"
}
}
}
}
```
> 注意：将 `/path/to/easysearch-mcp-server` 替换为实际的项目路径
### 2. 开始使用
配置完成后，AI Agent 就可以直接操作 Easysearch 了：
- "查看集群健康状态"
- "创建一个 products 索引"
- "搜索价格大于 100 的商品"
- "统计每个分类的订单数量"
## 工具列表
### 集群管理 (8)
| 工具 | 说明 |
|------|------|
| `cluster_health` | 集群健康状态 |
| `cluster_stats` | 集群统计信息 |
| `cluster_state` | 集群状态详情 |
| `cluster_settings` | 获取集群设置 |
| `cluster_update_settings` | 更新集群设置 |
| `cluster_pending_tasks` | 待处理任务 |
| `cluster_allocation_explain` | 分片分配解释 |
| `cluster_reroute` | 手动路由分片 |
### 索引管理 (25)
| 工具 | 说明 |
|------|------|
| `index_create` | 创建索引 |
| `index_delete` | 删除索引 |
| `index_exists` | 检查索引是否存在 |
| `index_get` | 获取索引详情 |
| `index_get_mapping` | 获取映射 |
| `index_put_mapping` | 更新映射 |
| `index_get_settings` | 获取设置 |
| `index_put_settings` | 更新设置 |
| `index_open` | 打开索引 |
| `index_close` | 关闭索引 |
| `index_refresh` | 刷新索引 |
| `index_flush` | 刷盘 |
| `index_forcemerge` | 强制合并段 |
| `index_clear_cache` | 清除缓存 |
| `index_stats` | 索引统计 |
| `index_segments` | 段信息 |
| `index_recovery` | 恢复状态 |
| `index_shard_stores` | 分片存储信息 |
| `index_set_readonly` | 设置只读（clone/split/shrink 前置条件）|
| `index_prepare_for_shrink` | 准备收缩（shrink 前置条件）|
| `index_create_with_write_alias` | 创建带可写别名的索引（rollover 前置条件）|
| `index_clone` | 克隆索引 |
| `index_split` | 拆分索引 |
| `index_shrink` | 收缩索引 |
| `index_rollover` | 滚动索引 |
### 别名管理 (4)
| 工具 | 说明 |
|------|------|
| `alias_get` | 获取别名 |
| `alias_create` | 创建别名 |
| `alias_delete` | 删除别名 |
| `alias_actions` | 批量别名操作 |
### 模板管理 (3)
| 工具 | 说明 |
|------|------|
| `template_get` | 获取模板 |
| `template_create` | 创建模板 |
| `template_delete` | 删除模板 |
### 文档操作 (11)
| 工具 | 说明 |
|------|------|
| `doc_index` | 写入文档 |
| `doc_get` | 获取文档 |
| `doc_exists` | 检查文档是否存在 |
| `doc_delete` | 删除文档 |
| `doc_update` | 更新文档 |
| `doc_bulk` | 批量操作 |
| `doc_bulk_simple` | 简化批量写入 |
| `doc_mget` | 批量获取 |
| `doc_source` | 获取文档源 |
| `doc_delete_by_query` | 按查询删除 |
| `doc_update_by_query` | 按查询更新 |
### 搜索功能 (15)
| 工具 | 说明 |
|------|------|
| `search` | DSL 搜索 |
| `search_simple` | 简单关键词搜索 |
| `search_template` | 模板搜索 |
| `msearch` | 多重搜索 |
| `count` | 文档计数 |
| `validate_query` | 验证查询 |
| `explain` | 解释评分 |
| `aggregate` | 聚合查询 |
| `aggregate_simple` | 简化聚合 |
| `scroll_start` | 开始滚动搜索 |
| `scroll_next` | 获取下一批 |
| `scroll_clear` | 清除滚动上下文 |
| `field_caps` | 字段能力 |
| `knn_search` | 向量搜索 |
| `sql_query` | SQL 查询 |
### CAT API (19)
| 工具 | 说明 |
|------|------|
| `cat_health` | 集群健康 |
| `cat_nodes` | 节点列表 |
| `cat_indices` | 索引列表 |
| `cat_shards` | 分片分布 |
| `cat_allocation` | 磁盘分配 |
| `cat_thread_pool` | 线程池状态 |
| `cat_master` | 主节点信息 |
| `cat_segments` | 段信息 |
| `cat_count` | 文档计数 |
| `cat_recovery` | 恢复状态 |
| `cat_pending_tasks` | 待处理任务 |
| `cat_aliases` | 别名列表 |
| `cat_templates` | 模板列表 |
| `cat_plugins` | 插件列表 |
| `cat_fielddata` | Fielddata 使用 |
| `cat_nodeattrs` | 节点属性 |
| `cat_repositories` | 快照仓库 |
| `cat_snapshots` | 快照列表 |
| `cat_tasks` | 任务列表 |
### 节点管理 (5)
| 工具 | 说明 |
|------|------|
| `nodes_info` | 节点信息 |
| `nodes_stats` | 节点统计 |
| `nodes_hot_threads` | 热点线程 |
| `nodes_usage` | 功能使用统计 |
| `nodes_reload_secure_settings` | 重载安全设置 |
### 快照管理 (10)
| 工具 | 说明 |
|------|------|
| `snapshot_repo_create` | 创建仓库 |
| `snapshot_repo_get` | 获取仓库 |
| `snapshot_repo_delete` | 删除仓库 |
| `snapshot_repo_verify` | 验证仓库 |
| `snapshot_create` | 创建快照 |
| `snapshot_get` | 获取快照 |
| `snapshot_status` | 快照状态 |
| `snapshot_delete` | 删除快照 |
| `snapshot_restore` | 恢复快照 |
| `snapshot_clone` | 克隆快照 |
### 快照生命周期管理 SLM (6)
| 工具 | 说明 |
|------|------|
| `slm_policy_create` | 创建策略 |
| `slm_policy_get` | 获取策略 |
| `slm_policy_delete` | 删除策略 |
| `slm_policy_explain` | 解释策略 |
| `slm_policy_start` | 启动策略 |
| `slm_policy_stop` | 停止策略 |
### 任务管理 (3)
| 工具 | 说明 |
|------|------|
| `tasks_list` | 任务列表 |
| `tasks_get` | 任务详情 |
| `tasks_cancel` | 取消任务 |
### Ingest Pipeline (6)
| 工具 | 说明 |
|------|------|
| `pipeline_get` | 获取 Pipeline |
| `pipeline_create` | 创建 Pipeline |
| `pipeline_delete` | 删除 Pipeline |
| `pipeline_simulate` | 模拟 Pipeline |
| `ingest_stats` | Ingest 统计 |
| `ingest_processor_grok` | Grok 模式列表 |
### ILM 索引生命周期管理 (5)
| 工具 | 说明 |
|------|------|
| `ilm_policy_get` | 获取 ILM 策略 |
| `ilm_policy_create` | 创建 ILM 策略 |
| `ilm_policy_delete` | 删除 ILM 策略 |
| `ilm_add_policy` | 给索引绑定 ILM 策略 |
| `ilm_remove_policy` | 从索引移除 ILM 策略 |
### 其他 (1)
| 工具 | 说明 |
|------|------|
| `reindex` | 重建索引 |
## 使用示例
### 集群监控
```
查看集群健康状态
→ cluster_health()
查看所有节点
→ cat_nodes()
查看线程池状态
→ cat_thread_pool()
按大小排序查看索引
→ cat_indices(sort_by="store.size", order="desc")
```
### 索引操作
```
创建索引
→ index_create("products",
mappings={"properties": {"name": {"type": "text"}, "price": {"type": "float"}}},
settings={"number_of_shards": 3})
写入文档
→ doc_index("products", {"name": "iPhone", "price": 999})
批量写入
→ doc_bulk_simple("products", [
{"name": "iPad", "price": 799},
{"name": "MacBook", "price": 1299}
])
```
### 搜索查询
```
简单搜索
→ search_simple("products", "iPhone")
DSL 搜索
→ search("products", query={
"bool": {
"must": [{"match": {"name": "phone"}}],
"filter": [{"range": {"price": {"lte": 1000}}}]
}
})
聚合统计
→ aggregate("orders", aggs={
"by_status": {"terms": {"field": "status"}},
"avg_amount": {"avg": {"field": "amount"}}
})
SQL 查询
→ sql_query("SELECT * FROM products WHERE price > 500 ORDER BY price DESC")
```
### 索引克隆/拆分/收缩
```
# 克隆索引（需要先设置只读）
→ index_set_readonly("my-index", True)
→ index_clone("my-index", "my-index-clone")
→ index_set_readonly("my-index", False)
# 收缩索引（需要准备）
→ index_prepare_for_shrink("my-index")
→ index_shrink("my-index", "my-index-shrunk", {"index.number_of_shards": 1})
# 滚动索引（需要可写别名）
→ index_create_with_write_alias("logs-000001", "logs")
→ index_rollover("logs", conditions={"max_docs": 1000000})
```
## 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `EASYSEARCH_URL` | Easysearch 地址 | `https://localhost:9200` |
| `EASYSEARCH_USER` | 用户名 | `admin` |
| `EASYSEARCH_PASSWORD` | 密码 | - |
## 开发
```bash
# 克隆仓库
git clone https://github.com/cloudsmithy/easysearch-mcp-server.git
cd easysearch-mcp-server
# 安装依赖
pip install -e .
# 运行测试
pytest
# 代码格式化
black src/
ruff check src/
```
## 兼容性测试
所有 121 个工具已在 INFINI Easysearch 上完成测试验证：
| 分类 | 工具数 | 状态 |
|------|--------|------|
| 集群管理 | 8 | ✅ 全部通过 |
| 索引管理 | 25 | ✅ 全部通过 |
| 别名管理 | 4 | ✅ 全部通过 |
| 模板管理 | 3 | ✅ 全部通过 |
| 文档操作 | 11 | ✅ 全部通过 |
| 搜索功能 | 15 | ✅ 全部通过 |
| CAT API | 19 | ✅ 全部通过 |
| 节点管理 | 5 | ✅ 全部通过 |
| 快照管理 | 10 | ✅ 全部通过 |
| SLM | 6 | ✅ 全部通过 |
| 任务管理 | 3 | ✅ 全部通过 |
| Ingest Pipeline | 6 | ✅ 全部通过 |
| ILM | 5 | ✅ 全部通过 |
| 其他 | 1 | ✅ 全部通过 |
注意：快照和 SLM 功能需要服务器配置 `path.repo` 才能创建仓库。
## 许可证
MIT License
