odigo-elastic-s2l-mcp

MCP Elasticsearch Server with Semantic S2L Layer

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

A generic Model Context Protocol (MCP) 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:

{
  "_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

chmod +x build.sh
./build.sh

Or with Podman:

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):

{
  "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

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, 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.