elasticsearch7-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

MCP (Model Context Protocol) server that exposes an Elasticsearch cluster as tools to MCP clients (Claude Desktop, Cursor). Published as elasticsearch7-mcp; also distributed via Smithery and Docker. Communicates over stdio only — never write to stdout outside the MCP protocol; diagnostics go to console.error.

This is a renamed fork of @awesome-ai/elasticsearch-mcp, retargeted at Elasticsearch 7.x. See docs/superpowers/specs/2026-08-24-elasticsearch-7x-compat-design.md for the migration design and the verified facts behind it.

Commands

nvm use               # Node 24.19.0 (.nvmrc) — the active LTS, which @types/node tracks
pnpm install          # pnpm ONLY — see the lockfile note below
pnpm run build        # tsc + chmod +x dist/*.js
pnpm test             # vitest run — 345 tests, mocked at the client connection layer
pnpm run test:watch   # vitest in watch mode
pnpm run typecheck    # tsc --strict over src, test and root files (vitest does NOT type-check)
pnpm run watch        # tsc --watch

# The image, as CI builds and checks it:
docker build -t elasticsearch7-mcp:dev .
printf '%s' "$HANDSHAKE" | docker run --rm -i -e ES_HOST=http://localhost:9200 elasticsearch7-mcp:dev

# Runtime verification against a real 7.x cluster (read-only by default):
ES_HOST=http://localhost:9200 ES_API_KEY=your-key pnpm run smoke

# What one tool call costs the caller's context, at cluster scale:
pnpm run build && pnpm run measure
ES_HOST=http://localhost:9200 node scripts/smoke.mjs --write smoke-test   # also write tools

# Interactive debugging:
ES_HOST=http://localhost:9200 ES_API_KEY=your-key pnpm run inspector

There is no linter and no formatter. Three layers of checking, all run in CI:

1. pnpm run typecheck — tsc --strict. Note the split: pnpm run build uses tsconfig.json, which covers only root files plus whatever index.ts reaches; tsconfig.test.json adds test/** and src/** explicitly. vitest transpiles without type-checking, so a test file's type errors are invisible until typecheck runs.
2. pnpm test — vitest against @elastic/elasticsearch-mock, intercepting at the client's connection layer. That layer matters: the tests assert the request that actually goes on the wire, so they fail when the query DSL is not nested under body — a faked client object would accept it silently. Verified by mutation: removing the body nesting or reading docsCount instead of docs.count makes 6 tests fail.
3. pnpm run smoke — the only check that talks to a real cluster; requires pnpm run build first, since it imports the built output.