MCP 服务器

odigo-elastic-s2l-mcp

Connects LLMs to Elasticsearch with a Semantic-to-Lexical layer that translates technical field names into business knowledge, enabling autonomous querying without hardcoded domain logic.

README

odigo-elastic-s2l-mcp

MCP Elasticsearch Server with Semantic S2L Layer

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