# odigo-elastic-s2l-mcp

**MCP Elasticsearch Server with Semantic S2L Layer**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.11+-green.svg)](https://www.python.org/)
[![Elasticsearch](https://img.shields.io/badge/Elasticsearch-8.10.4+-yellow.svg)](https://www.elastic.co/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)

Copyright 2025 Odigo SAS — Developed by Régis BEGUIN (regis.beguin@odigo.com)

A generic [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects LLMs to Elasticsearch, with a **Semantic-to-Lexical (S2L) layer** that translates technical field names into business knowledge — without hardcoding any domain logic in the server itself.

---

## How it works

The S2L layer is a simple JSON file (`field_descriptions.json`) that provides:
- **Field descriptions**: human-readable explanations of each Elasticsearch field
- **Business rules**: mandatory filters, billing criteria, error codes, timezone handling, index patterns — anything the LLM needs to build correct queries autonomously

The LLM reads this semantic layer via `get_field_descriptions()` and builds Query DSL or ES|QL queries on its own. No business logic is hardcoded in the server.

```
LLM ──► get_field_descriptions() ──► reads business rules from JSON
LLM ──► get_mappings()           ──► reads enriched schema
LLM ──► search() / esql()        ──► executes autonomous queries
```

---

## Available Tools

| Tool | Description |
|------|-------------|
| `cluster_info` | Cluster info and available features (version, ES\|QL support) |
| `list_indices` | List available indices |
| `get_mappings` | Index schema enriched with S2L field descriptions |
| `get_field_descriptions` | Field descriptions + business rules from `field_descriptions.json` |
| `search` | Query DSL search |
| `esql` | ES\|QL query (Elasticsearch >= 8.11.0 only) |
| `get_shards` | Shard information |

---

## Requirements

- Python 3.11+
- Elasticsearch >= 8.10.4
- Docker or Podman

---

## Quick Start

### 1. Configure your S2L layer

Edit `src/field_descriptions.json` to describe your Elasticsearch fields and business rules:

```json
{
  "_business_rules": {
    "_mandatory_filter": "All queries must include: { 'term': { 'status': 'active' } }",
    "_index_pattern": "Target index pattern: my_data_index_*",
    "_timezone": "Timestamps are stored in UTC."
  },
  "my_field": "Description of what this field means in your domain.",
  "my_status_field": "Status: '0' = success, '1' = failure."
}
```

### 2. Build the Docker image

```bash
chmod +x build.sh
./build.sh
```

Or with Podman:
```bash
CONTAINER_TOOL=podman ./build.sh
```

### 3. Configure Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "elastic-s2l-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "-e", "ES_URL=http://your-elasticsearch-host:9200",
        "-e", "ES_API_KEY=YOUR_API_KEY",
        "elastic-s2l-mcp:latest"
      ]
    }
  }
}
```

### 4. Or run directly with Python

```bash
pip install -r requirements.txt
ES_URL=http://localhost:9200 ES_API_KEY=YOUR_KEY python src/server.py
```

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ES_URL` | Elasticsearch URL | `http://localhost:9200` |
| `ES_API_KEY` | Elasticsearch API key | *(empty — no auth)* |
| `FIELD_DESCRIPTIONS_PATH` | Path to the S2L JSON config file | `src/field_descriptions.json` |

---

## Project Structure

```
odigo-elastic-s2l-mcp/
├── src/
│   ├── server.py                # MCP server (generic, no business logic)
│   └── field_descriptions.json  # S2L semantic layer (your domain knowledge)
├── Dockerfile
├── requirements.txt
├── build.sh
├── lance_mcp.sh
├── export_image.sh
├── LICENSE
└── README.md
```

---

## About

This project was developed as part of an R&D initiative at [Odigo](https://www.odigo.com), a leading European cloud contact center software company.

**Author**: Régis BEGUIN — Revenue Assurance Engineer, Odigo  
**Contact**: regis.beguin@odigo.com

---

## License

Copyright 2025 Odigo SAS
Developed by Régis BEGUIN (regis.beguin@odigo.com)

Licensed under the [Apache License, Version 2.0](LICENSE).