indexsearch

indexsearch

indexsearch 为 Agent（或在终端中操作的你）提供五种核心 Elasticsearch 工具：查看现有索引、读取索引的字段映射、使用查询 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 服务

同一个可执行文件支持两种用途。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	使用查询 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。