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 indices

indexsearch list-indices

Read one index's field mappings

indexsearch mappings products

Search with query DSL (a bare clause, or a full {"query": ...} body)

indexsearch search products '{"match":{"name":"shoes"}}'

Run an ES|QL query

indexsearch esql 'FROM products | SORT price DESC | LIMIT 5'

Shard information for every index, or for one

indexsearch shards indexsearch shards products

Start the MCP server

indexsearch 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 install

npm run build # tsc -> dist/ npm test # node test runner over test/*.test.ts, no network, no live cluster npm 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.