indexsearch

indexsearch

indexsearch を使うと、エージェントやターミナルを使うユーザーは、Elasticsearch の5つの基本ツールを利用できます。存在するインデックスの確認、インデックスのフィールドマッピングの読み取り、Query DSL での検索、ES|QL クエリの実行、シャード配置の確認ができます。すべてクラスター独自の HTTP API を経由するため、クライアントライブラリは同梱されておらず、別のクエリ言語を覚える必要もありません。

各ツール呼び出しは、まず単純な HTTP リクエスト（メソッド、パス、JSON ボディ）にマッピングされ、そのマッピングが契約のすべてです。 GET /_cat/indices?format=json、GET /{index}/_mapping、 POST /{index}/_search、POST /_query、GET /_cat/shards。 トランスポートには差し替え可能な fetch 関数を使い、テストスイートはこれを利用します。動作の検証に稼働中のクラスターは不要で、クラスターに接続できない場合やエラーが返された場合に、結果を捏造することはありません。

インストール

npx @reneturcios/indexsearch list-indices

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/indexsearch

コンテナーはデフォルトで MCP サーバーを起動します（下記参照）。CLI として使うには CLI 引数を渡し、クラスター設定は環境変数（-e ES_URL=...）として渡します。

設定

変数	意味	デフォルト
ES_URL	クラスターのベース URL	http://localhost:9200
INDEXSEARCH_URL	ES_URL が未設定の場合に使われるフォールバックのクラスターのベース URL	—
ES_API_KEY	API キー。Authorization: ApiKey <key> として送信されます	未設定（認証なし）

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

終了コード：成功時は 0、リクエストまたはクラスターのエラー時は 1（エラーには HTTP ステータスまたは接続できない URL が示されます）、使用方法のエラー時は 2 です。

インデックス名は、リクエストを行う前に検証されます。Elasticsearch のインデックス名で禁止されている文字（空白、/、*、?、"、<、>、|、,、#、:、\）を含む名前は、ローカルで拒否されます。

MCP サーバー

1つのバイナリーで、どちらの使い方にも対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/indexsearch mcp

MCP クライアントの設定：

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

ツール

ツール	必須	任意	HTTP リクエスト	機能
list_indices	—	—	GET /_cat/indices?format=json	利用可能なすべてのインデックスを一覧表示します
get_mappings	index	—	GET /{index}/_mapping	インデックスのフィールドマッピングを取得します
search	index、query（オブジェクト）	—	{ "query": ... } を指定して POST /{index}/_search	Query DSL を使って検索します
esql	query（文字列）	—	{ "query": ... } を指定して POST /_query	ES
get_shards	—	index	GET /_cat/shards[/{index}]?format=json	すべてのインデックス、または指定したインデックスのシャード情報を取得します

応答は、クラスターが解析した JSON として返されます。JSON 以外の応答は破棄せず、raw キーの下に返されます。空の応答は空のオブジェクトとして扱われます。

開発

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

リクエストの構築、検証、ヘッダーとボディの組み立て、エラーの通知、設定の解決はすべて、フェイクの fetch を使ってコアを実行し、正確なパスとボディを検証するテストでカバーされています。

ライセンス

MIT — LICENSE を参照してください。