Indexsearch

indexsearch

indexsearch gives an agent — or you, at a terminal — the five core Elasticsearch tools: see which indices exist, read an index's field mappings, run a search in query DSL, run an ES|QL query, and inspect shard placement. Everything goes through the cluster's own HTTP API; there is no bundled client library and no second query language to learn.

Each tool call is first mapped to a plain HTTP request — method, path, and JSON body — and that mapping is the whole contract: GET /_cat/indices?format=json, GET /{index}/_mapping, POST /{index}/_search, POST /_query, GET /_cat/shards. Transport is an injectable fetch function, which is what the test suite drives; no live cluster is needed to verify behaviour, and no result is ever invented when a cluster is unreachable or answers with an error.

Install

npx @reneturcios/indexsearch list-indices

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/indexsearch

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead, and pass the cluster settings as environment variables (-e ES_URL=...).

Configuration

CLI

# List indicesindexsearch list-indices
# Read one index's field mappingsindexsearch mappings products
# Search with query DSL (a bare clause, or a full {"query": ...} body)indexsearch search products '{"match":{"name":"shoes"}}'
# Run an ES|QL queryindexsearch esql 'FROM products | SORT price DESC | LIMIT 5'
# Shard information for every index, or for oneindexsearch shardsindexsearch shards products
# Start the MCP serverindexsearch mcp
indexsearch --version

Exit codes: 0 on success, 1 when the request or the cluster fails (the error names the HTTP status or the unreachable URL), 2 for usage errors.

Index names are validated before any request is made: names carrying characters Elasticsearch forbids in index names (whitespace, /, *, ?, ", <, >, |, ,, #, :, \) are rejected locally.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/indexsearch mcp

MCP client configuration:

{  "mcpServers": {    "indexsearch": {      "command": "npx",      "args": ["-y", "@reneturcios/indexsearch", "mcp"],      "env": { "ES_URL": "http://localhost:9200" }    }  }}

Tools

Replies are returned as the cluster's parsed JSON. A non-JSON reply is returned under a raw key rather than being dropped, and an empty reply reads as an empty object.

Development

npm installnpm run build   # tsc -> dist/npm test        # node test runner over test/*.test.ts, no network, no live clusternpm run dev     # run the CLI from source via tsx

Request construction, validation, header and body assembly, error surfacing, and settings resolution are all covered by tests that drive the core through a fake fetch and assert the exact paths and bodies.

License

MIT — see LICENSE.