Metadata-Version: 2.4
Name: elasticsearch-client-mcp-py
Version: 1.0.5
Summary: MCP Server for Elasticsearch - schema discovery, search, CRUD operations
Author: dong_tech
License: MIT
Keywords: elasticsearch,mcp,model-context-protocol
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.10
Requires-Dist: elasticsearch<8.0.0,>=7.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Elasticsearch Client MCP

MCP Server for Elasticsearch - 支持 ES 6/7/8 版本，连接管理，搜索和 CRUD 操作。

## 配置

### MCP 配置（~/.claude/settings.json）

在 `mcpServers` 中配置连接信息：

```json
{
  "mcpServers": {
    "elasticsearch-client": {
      "command": "uvx",
      "args": ["elasticsearch-client-mcp-py"],
      "env": {
        "ES_CONNECTIONS": "[{\"name\":\"my_es\",\"env\":\"prod\",\"url\":\"http://your-es-host:9200\",\"username\":\"elastic\",\"password\":\"your_password\"}]"
      },
      "type": "stdio"
    }
  }
}
```

**ES_CONNECTIONS 格式：**
```json
[
  {
    "name": "连接名称",
    "env": "环境(dev/prod/test)",
    "description": "可选描述",
    "url": "http://es-host:9200",
    "username": "elastic",
    "password": "密码",
    "safety": {
      "read_only": false,
      "max_search_size": 100,
      "confirm_delete": false,
      "allow_delete_index": true,
      "allow_create_index": true
    }
  }
]
```

### profile.json - 权限配置

权限配置存储在 `~/.config/elasticsearch-client-mcp/profile.json`：

```json
{
  "_last_connection": "prod_finance",
  "_connection_cache": {},
  "_envs": {
    "prod": {
      "safety": {
        "read_only": true,
        "max_search_size": 50,
        "confirm_delete": true,
        "allow_delete_index": false,
        "allow_create_index": false,
        "risk_check": true
      }
    },
    "dev": {
      "safety": {
        "read_only": false,
        "max_search_size": 100,
        "confirm_delete": false,
        "allow_delete_index": true,
        "allow_create_index": true,
        "risk_check": true
      }
    }
  }
}
```

**safety 配置说明：**
- `read_only`: 只读模式，拒绝写操作
- `max_search_size`: 最大搜索条数
- `confirm_delete`: 删除时需要确认
- `allow_delete_index`: 是否允许删除索引
- `allow_create_index`: 是否允许创建索引

**优先级：**
1. MCP env 中的 `safety` 配置（优先）
2. profile.json 中对应 env 的 safety

## Tools

- `list_connections` - 列出所有连接
- `get_current_connection` - 获取当前连接
- `select_connection` - 选择连接
- `es_search` - 搜索文档 (from/size 分页)
- `es_scroll` - 滚动查询
- `es_scroll_next` - 滚动下一页
- `es_scroll_clear` - 清除滚动
- `es_index_doc` - 索引文档
- `es_update_doc` - 更新文档
- `es_delete_doc` - 删除文档
- `es_bulk` - 批量操作
- `es_create_index` - 创建索引
- `es_delete_index` - 删除索引
- `es_index_exists` - 检查索引是否存在
- `es_get_index_mapping` - 获取索引 mapping
- `es_list_indices` - 列出所有索引

## 版本兼容

自动检测 ES 版本 (6/7/8)，适配对应的 API。

### 版本检测流程

```
select_connection()
    │
    ├─→ HTTP 直接获取 / → 解析 version.number
    │   (兼容所有版本，不依赖 elasticsearch-py)
    │
    └─→ 缓存到 profile.json
            │
            └─→ _session_state.es_version
```

### 版本路由架构

```
create_ops(config, es_version)
    │
    ├─→ ES 6 → ES6Ops (原生 HTTP)
    │           不依赖 elasticsearch-py 库
    │
    ├─→ ES 7 → ES7Ops (elasticsearch-py 7.x)
    │
    └─→ ES 8+ → ES8Ops (elasticsearch-py 8.x)
```

### 版本差异处理

| 操作 | ES 6 | ES 7 | ES 8+ |
|------|------|------|-------|
| _type | 已废弃，搜索时删除 | 支持 | 移除 |
| 认证 | http_auth | http_auth | basic_auth |
| Content-Type | application/json | application/json | application/json |
| 搜索实现 | 原生 HTTP | elasticsearch-py | elasticsearch-py |

### 核心文件

```
src/elasticsearch_client_mcp/
├── client.py              # 版本操作类 ES6Ops/ES7Ops/ES8Ops
├── tools/
│   ├── connections.py     # 连接管理、版本路由
│   └── es_operations.py   # 统一操作入口
└── config/
    └── config.py          # 配置加载、版本缓存
```

## 安装

```bash
uv pip install -e .
```
