项目概览与系统架构

1. 项目定位与目标

mcp-server-elasticsearch 是 Elastic 官方维护的一个 Model Context Protocol (MCP) 服务器 库,采用 Rust 实现,旨在将 Elasticsearch 的查询与管理能力以"工具 (tools)"的形式暴露给兼容 MCP 协议的 LLM 客户端(如 Claude Desktop、VS Code Copilot、Amazon Q、n8n 等)。项目本身被声明为 beta 生命周期,归属于 devtools-team 团队,并通过 Backstage 进行管理。

资料来源：catalog-info.yaml:1-9

主要设计目标包括:

• 多传输协议支持:同时支持 stdio 与基于 HTTP 的传输(包含可流式 HTTP 与 SSE),覆盖本地进程内通信与远程容器化部署两种典型场景。
• 统一的工具抽象:通过 rmcp 框架将 Elasticsearch 的常见 API 封装为可发现、可调用的 MCP 工具。
• 可配置且环境变量友好:配置文件支持 JSON5 语法,内部可使用 ${VAR} 与 ${VAR:default} 形式的插值,便于容器化与 CI 环境注入凭据。
• 认证灵活性:同时支持 API Key 与基本认证 (Basic Auth),并允许在容器模式下重写 localhost 主机名。

2. 整体系统架构

下图展示了从 CLI 启动到 MCP 工具调用、再到 Elasticsearch 集群的端到端组件关系。

graph TD
    A[CLI 入口: clap] --> B{子命令}
    B -->|stdio| C[StdioCommand]
    B -->|http| D[HttpCommand]
    C --> E[lib.rs 启动 stdio 循环]
    D --> F[protocol/http.rs<br/>启动 axum + rmcp 传输]
    E --> G[servers/elasticsearch/mod.rs<br/>new_with_config]
    F --> G
    G --> H[EsBaseTools<br/>+ CustomTools]
    H --> I[rmcp 工具路由]
    I --> J[Elasticsearch Rust Client]
    J --> K[(Elasticsearch 集群)]
    L[配置文件 + 环境变量] --> M[utils/interpolator.rs]
    M --> G
    N[Backstage + Buildkite] -.-> O[CI/CD 与 Docker 发布]

2.1 分层职责

3. 入口与启动流程

3.1 CLI 入口

CLI 通过 clap 派生宏定义两个子命令:

• Stdio:提供 --config 参数,选择可选的配置文件路径。
• Http:除了 --config 外,还支持 --address(由 HTTP_ADDRESS 环境变量后备)与 --sse(可选开启 /sse 路由)。

资料来源：src/cli.rs:24-39

在 src/cli.rs 顶部还保留了若干 MCP 客户端配置示例的参考链接(VS Code Copilot、Claude Desktop、Amazon Q 等),便于用户理解如何把本服务注册到不同宿主中。

3.2 库主入口

src/lib.rs 中提供的默认配置模板已包含 ES_URL、ES_API_KEY、ES_USERNAME、ES_PASSWORD、ES_SSL_SKIP_VERIFY 等环境变量占位符,启动流程为:

1. 读取(可选的)配置文件,缺失时使用内置默认 JSON5 模板。
2. 调用 interpolator::interpolate_from_env 将 ${VAR} 与 ${VAR:default} 形式的占位符替换为实际环境变量值。
3. 使用 serde_json5 解析为强类型 Configuration,对错误位置(行/列)进行友好提示。
4. 调用 ElasticsearchMcp::new_with_config 完成最终装配。

资料来源：src/lib.rs:57-87

4. 协议层设计

4.1 stdio 传输

stdio 传输的实现集中在 src/protocol/stdio.rs 中,目前该模块保持为空,真正的循环与消息分发在 src/lib.rs 中处理。这一设计为将来把 stdio 行为完整迁移到 protocol/stdio.rs 留出了占位。

4.2 HTTP 传输

HTTP 传输由 src/protocol/http.rs 实现,基于 axum 路由器,关键点如下:

• 同时支持 streamable HTTP 与 SSE:使用 rmcp::transport::StreamableHttpService 与 rmcp::transport::SseServer,可由 --sse 标志同时启动。
• 路由结构:
• / 文本介绍页,显示服务器版本。
• /ping 健康探测。
• /mcp 挂载 streamable HTTP 服务。
• /mcp/sse 挂载 SSE 服务(若启用)。
• /_health/ready 与 /_health/live 标准的 Kubernetes 风格探针。
• 会话管理:默认使用 LocalSessionManager,在 HttpServerConfig 中以泛型参数注入,便于替换为分布式会话后端。

资料来源：src/protocol/http.rs:18-118

graph LR
    Client[MCP 客户端] -->|/mcp| Streamable[StreamableHttpService]
    Client -->|/mcp/sse| Sse[SseServer]
    Client -->|/_health/ready| Ready[Ready Handler]
    Client -->|/_health/live| Live[Live Handler]
    Streamable --> RMCP[rmcp Service 层]
    Sse --> RMCP
    RMCP --> Tools[Elasticsearch 工具]

社区方面,Issue #17 曾指出早期版本"仅支持 stdio 服务端模式",而现在 streamable HTTP 已经落地,呼应 MCP 官方对 SSE 弃用后推荐的传输方案。

5. 服务器与工具装配

5.1 `ElasticsearchMcp` 装配

src/servers/elasticsearch/mod.rs 中的 ElasticsearchMcp 是一个空的标记结构体,真正的装配逻辑放在其 new_with_config 关联函数中:

1. 凭据解析:优先 api_key,其次 username + password,最终构造 Credentials::EncodedApiKey 或 Credentials::Basic。
2. URL 处理:为空时直接报错;若 container_mode 为真,则对 localhost 进行主机名重写(适用于容器内部署,需要把 localhost 改为宿主可达地址)。
3. 传输构造:使用 SingleNodeConnectionPool 与 TransportBuilder,在存在凭据时调用 .auth(creds),并通过 cert::CertificateValidation 控制 TLS 校验。
4. 返回 EsBaseTools:将客户端封装为 EsClientProvider 并交给 base_tools.rs 注册工具路由。

资料来源：src/servers/elasticsearch/mod.rs:90-131

5.2 工具与自定义扩展

Tools 结构体支持两层自定义:

• incl_excl: Option<IncludeExclude>:通过 src/servers/mod.rs 中的 is_included 与 filter 方法按名过滤内置工具。
• custom: HashMap<String, CustomTool>:目前支持的 CustomTool 变体为 Esql(EsqlTool) 与 SearchTemplate(SearchTemplateTool),分别用于扩展 ES|QL 查询与搜索模板能力。

pub enum CustomTool {
    Esql(EsqlTool),
    SearchTemplate(SearchTemplateTool),
}

资料来源：src/servers/elasticsearch/mod.rs:5-13

5.3 基础工具集

src/servers/elasticsearch/base_tools.rs 使用 rmcp_macros 提供的 #[tool] / #[tool_router] / #[tool_handler] 派生宏,集中实现以下工具(部分以源码中可见的工具名/参数为依据):

资料来源：src/servers/elasticsearch/base_tools.rs:56-205

实现上,search 工具在返回时会判断 aggregations 是否为空,仅在不是"纯聚合"结果时才附带 total 统计信息——这正是社区 Issue #45 中反馈"聚合结果被排除"问题的源头,在新版本中应被进一步覆盖。

服务器声明的项目括:

• 协议版本:ProtocolVersion::V_2025_03_26
• 能力位:tools 已启用
• 指令文本:"Provides access to Elasticsearch"

资料来源：src/servers/elasticsearch/base_tools.rs:8-21

6. 工具调用时序

下图给出一个典型 search 调用的端到端时序,涵盖身份认证、查询转发与结果处理。

sequenceDiagram
    participant C as MCP 客户端
    participant R as rmcp 传输层
    participant S as EsBaseTools
    participant E as Elasticsearch Client
    participant ES as Elasticsearch 集群

    C->>R: tools/call (search)
    R->>S: search(req_ctx, params)
    S->>E: search(SearchParts::Index)
    E->>ES: HTTP POST /<index>/_search
    ES-->>E: JSON 响应
    E-->>S: SearchResult (hits, aggregations)
    S-->>R: CallToolResult (text + json content)
    R-->>C: 工具结果

7. 配置系统

7.1 默认配置模板

在 src/lib.rs 中,默认配置以 JSON5 字符串形式提供,关键字段如下:

资料来源：src/lib.rs:50-66

7.2 环境变量插值

src/utils/interpolator.rs 实现了 ${VAR} 与 ${VAR:default} 两种语法。${VAR} 在未定义时返回错误,${VAR:default} 在未定义时回落到默认值。good_extrapolation 单元测试覆盖了多变量、跨行等场景。

资料来源：src/utils/interpolator.rs:36-67

社区反馈(Issue #170):在 Docker 容器中即便环境变量设置正确,仍可能遇到 401 Unauthorized。常见原因包括:

- 容器内到宿主 ES 的网络不通(必要时可启用 container_mode 让 localhost 被改写);

- 凭据优先级问题:api_key 存在时不会回落到 username/password;

- TLS 校验未关闭且证书不被信任,导致握手失败,表现为 401 而非更明确的错误。

8. 发布与运维

catalog-info.yaml 描述了项目的发布工程:

• 组件:类型 library,生命周期 beta,拥有者 devtools-team。
• CI 流水线:buildkite-pipeline-mcp-server-elasticsearch,对应仓库内的 .buildkite/pipeline.yml。
• Docker 发布流水线:mcp-server-elasticsearch-docker,对应 .buildkite/docker.yml,仅在打 tag 时触发,并启用 cancel_intermediate_builds。

社区 Issue #191 指出"缺少 Linux arm64 二进制",目前仓库只发布 macOS 与 Windows 的 arm64 版本;Docker 多架构镜像的发布由 mcp-server-elasticsearch-docker 流水线负责,可作为追踪该问题进展的入口。

9. 已知限制与社区关注点

10. See Also

• README.md:项目使用与安装说明。
• Cargo.toml:依赖与构建配置。
• MCP 官方传输规范:modelcontextprotocol.io/docs/concepts/transports
• Issue #17 Streamable HTTP 支持讨论。
• Issue #170 Basic Auth 401 排查。
• Issue #45 聚合结果增强请求。

概述

Elasticsearch MCP Server 实现了 Model Context Protocol (MCP)，允许 AI 智能体通过自然语言与 Elasticsearch 集群进行交互。服务器向 MCP 客户端暴露一组工具（tools），每个工具对应一个特定的 Elasticsearch 操作或查询能力。

[!CAUTION]

该 MCP 服务器已被弃用（deprecated），后续仅接收关键安全更新。推荐迁移至 Elastic Agent Builder 的 MCP 端点（Elastic 9.2.0+ 及 Elasticsearch Serverless 项目可用）。详见 README.md。

工具集合在代码中分为两类：

• Base Tools（基础工具）：内置的通用 Elasticsearch 操作工具，所有部署默认启用
• Custom Tools（自定义工具）：用户通过配置文件自定义的扩展工具，包括 ES|QL 自定义工具和 Search Template 工具

资料来源：src/servers/elasticsearch/mod.rs

工具总体架构

类结构与组织

工具定义与实现位于 src/servers/elasticsearch/ 目录下，其中：

• mod.rs 定义服务器配置结构体 ElasticsearchMcpConfig、客户端提供者 EsClientProvider 和自定义工具类型
• base_tools.rs 实现了五个基础工具以及它们的请求/响应类型
• EsBaseTools 结构体承载所有基础工具，通过 #[tool_router] 宏注册到 MCP 路由器

资料来源：src/servers/elasticsearch/base_tools.rs

工具注册流程

graph TD
    A[启动服务器] --> B[加载配置]
    B --> C{解析 config.toml}
    C --> D[创建 Elasticsearch 客户端]
    D --> E[构建 EsBaseTools]
    E --> F[通过 tool_router 宏注册工具]
    F --> G[启动 stdio / streamable-HTTP 传输]
    G --> H[MCP 客户端发现工具]
    H --> I[智能体调用工具]
    I --> J[EsClientProvider.get 注入凭证]
    J --> K[调用 Elasticsearch 集群]
    K --> L[返回 CallToolResult]

基础工具列表

服务器默认暴露以下五个基础工具，所有工具均声明为只读（read_only_hint = true），适合 AI 智能体的安全调用。

资料来源：README.md 与 src/servers/elasticsearch/base_tools.rs

基础工具详解

list_indices

使用 Elasticsearch Cat API 的 indices 端点列出匹配指定模式的索引信息。

参数：

返回内容：

工具返回包含两段内容的 CallToolResult：

1. 文本说明："Found {N} indices:"
2. JSON 数组，每个元素为 CatIndexResponse 结构体：

pub struct CatIndexResponse {
    pub index: String,
    pub status: String,
    pub doc_count: u64, // deserialize_number_from_string
}

资料来源：src/servers/elasticsearch/base_tools.rs

get_mappings

获取某个 Elasticsearch 索引的字段映射定义。

参数：

返回内容包含文本前缀与映射 JSON 对象。社区报告在某些远程调用场景下会出现 get_mapping returns the following... 错误（参见 issue #173），错误信息通常反映 Elasticsearch 集群侧权限或索引状态问题，而非 MCP 工具本身逻辑。

资料来源：src/servers/elasticsearch/base_tools.rs

search

执行完整的 Elasticsearch 查询 DSL 搜索，是最复杂的工具。

参数：

字段注入逻辑：

当 fields 存在时，工具会修改 query_body：

• 如果 _source 已是数组，则将字段追加到该数组
• 否则在 query_body 中插入 _source 键

返回内容：

返回 SearchResult 类型，包含 hits（命中数据）与 aggregations（聚合结果）：

pub struct SearchResult {
    pub hits: Hits,
    pub aggregations: IndexMap<String, Value>,
}

重要提示（针对 issue #45）：当响应仅包含聚合结果且 hits 为空时，工具仍会发送聚合数据。代码中通过 if response.aggregations.is_empty() || !response.hits.hits.is_empty() 条件决定是否发送统计信息，确保聚合结果不会被排除，从而让 LLM 能完整回答聚合查询。

资料来源：src/servers/elasticsearch/base_tools.rs

esql

执行 ES|QL（Elasticsearch Query Language）查询。

参数：

ES|QL 是 Elasticsearch 8.x/9.x 提供的统一查询语言，相较 DSL 更易于 LLM 生成和解析。

资料来源：README.md 与 src/servers/elasticsearch/base_tools.rs

get_shards

获取所有或特定索引的分片分布信息。

参数：

返回字段（Cat API 头）：

index, shard, prirep, state, docs, store, node

返回类型为 Vec<CatShardsResponse>，每个元素包含 index、shard、prirep、state 等字段。社区报告中该工具工作正常，是少数无已知问题的工具之一。

资料来源：src/servers/elasticsearch/base_tools.rs

自定义工具（Custom Tools）

除了内置基础工具外，服务器支持通过配置文件注册自定义工具。在 mod.rs 中定义了 CustomTool 枚举，标识为 tag = "type"，目前支持两种类型：

类型总览

graph LR
    A[CustomTool] -->|type=esql| B[EsqlTool]
    A -->|type=search_template| C[SearchTemplateTool]
    B --> D[ToolBase + query + format]
    C --> E[ToolBase + SearchTemplate]
    E -->|TemplateId| F[String]
    E -->|Template| G[serde_json::Value]

EsqlTool

pub struct EsqlTool {
    base: ToolBase,
    query: String,
    format: EsqlResultFormat,
}

EsqlResultFormat 枚举支持以下输出格式：

资料来源：src/servers/elasticsearch/mod.rs

SearchTemplateTool

pub struct SearchTemplateTool {
    base: ToolBase,
    template: SearchTemplate,
}

pub enum SearchTemplate {
    TemplateId(String),        // 引用已注册的模板 ID
    Template(serde_json::Value), // 内联模板
}

通过扁平序列化（#[serde(flatten)]），模板参数将直接合并到工具的 JSON Schema 中。

资料来源：src/servers/elasticsearch/mod.rs

工具过滤机制

Tools 结构体支持通过 IncludeExclude 模式控制工具的启用与排除：

pub struct Tools {
    pub incl_excl: Option<IncludeExclude>,
    pub custom: HashMap<String, CustomTool>,
}

ToolBase 是所有自定义工具共享的基础元数据：

pub struct ToolBase {
    pub description: String,
    pub parameters: IndexMap<String, schemars::schema::SchemaObject>,
    pub annotations: Option<ToolAnnotations>,
}

资料来源：src/servers/elasticsearch/mod.rs

凭证管理与请求上下文

EsClientProvider 设计

EsClientProvider 包装了官方 Elasticsearch Rust 客户端。其核心方法 get() 接受 RequestContext<RoleServer>，检查传入 HTTP 请求的 Authorization 头，如果存在则覆盖默认凭证。这一设计使得 streamable-HTTP 模式下每个请求可以使用不同凭证进行身份验证。

sequenceDiagram
    participant Agent as AI 智能体
    participant MCP as MCP Server
    participant CP as EsClientProvider
    participant ES as Elasticsearch

    Agent->>MCP: 调用工具 (含 Authorization 头)
    MCP->>CP: es_client.get(req_ctx)
    CP->>CP: 检查 Authorization 头
    alt 存在头
        CP->>CP: 用头中的凭证创建客户端
    else 不存在
        CP->>CP: 用配置中的默认凭证
    end
    CP->>ES: 执行 API 调用
    ES-->>CP: 响应
    CP-->>MCP: 返回结果
    MCP-->>Agent: CallToolResult

默认凭证来源

默认凭证按以下优先级在 new_with_config() 中确定：

1. config.api_key → Credentials::EncodedApiKey
2. config.username + config.password → Credentials::Basic
3. 均为空时 → None（不进行认证，依赖 Elasticsearch 端安全配置）

社区提示（针对 issue #170）：当 ES_USERNAME 与 ES_PASSWORD 环境变量存在但仍然返回 401 时，请检查：

1. 配置文件中 elasticsearch.username 与 elasticsearch.password 字段是否被正确读取（注意 none_if_empty_string 反序列化器会将空字符串视为 None）

2. 是否同时设置了 ES_API_KEY，导致优先级更高的 API key 覆盖了基本认证

3. Elasticsearch 集群侧是否启用了安全特性且用户具备访问权限

资料来源：src/servers/elasticsearch/mod.rs

服务器能力与协议版本

MCP 协议能力声明

EsBaseTools 通过 ServerHandler trait 声明服务器能力：

fn get_info(&self) -> ServerInfo {
    ServerInfo {
        protocol_version: ProtocolVersion::V_2025_03_26,
        capabilities: ServerCapabilities::builder().enable_tools().build(),
        server_info: Implementation::from_build_env(),
        instructions: Some("Provides access to Elasticsearch".to_string()),
    }
}

服务器当前仅启用 tools 能力，未启用 resources 或 prompts 能力（注意 mod.rs 中 prompts 字段已预留但功能未实现）。

资料来源：src/servers/elasticsearch/base_tools.rs

支持的传输协议

通过 cli.rs 中的 Command 枚举选择传输方式：

Note： Server-Sent Events (SSE) 已被 MCP 规范标记为 deprecated，建议改用 streamable-HTTP。社区 issue #17 推动了 streamable HTTP 的支持实现。

HttpServerConfig 配置项：

资料来源：src/cli.rs 与 src/protocol/http.rs

容器模式下的本地地址重写

当 container_mode = true 时，new_with_config() 会调用 rewrite_localhost() 重写 URL。这是因为在 Docker 容器中，localhost 指向容器自身而非宿主机的 Elasticsearch 实例。

该机制与 README 中描述的 Docker 部署流程配合使用，确保用户在容器内配置 http://localhost:9200 也能正确连接到宿主机的 Elasticsearch。

资料来源：src/servers/elasticsearch/mod.rs

已知问题与限制

来自社区的反馈

常见失败模式

1. 认证失败（401）：检查凭证传递链，参考上文凭证优先级
2. 空聚合结果：早期版本问题，现已通过 response.aggregations 字段保留
3. 远程 HTTP 调用错误：当通过 streamable-HTTP 暴露 MCP 服务器并由智能体访问时，可能出现工具返回错误而非友好提示，建议在 docker logs 中查看详细堆栈

健康检查与监控

内置端点

streamable-HTTP 模式下，服务器暴露 /ping 健康检查端点：

curl http://<host>:8080/ping
# 返回 "pong"

容器状态检查

docker ps | grep elasticsearch-mcp-server
docker logs <container-id>

资料来源：README.md

项目元信息

• 所有者团队：devtools-team（参见 catalog-info.yaml）
• 生命周期阶段：beta
• 构建管道：Buildkite（buildkite-pipeline-mcp-server-elasticsearch 与 mcp-server-elasticsearch-docker）
• 依赖更新：使用 Renovate 调度为周一凌晨 1 点后
• 版权：Copyright 2025 Elasticsearch B.V.（参见 NOTICE.txt）
• 最新版本：v0.4.6（已添加弃用通知）

See Also

• Server Configuration and Startup Modes — 服务器配置结构与传输模式详解
• Authentication and Credential Management — 凭证传递链与 401 错误排查
• HTTP Transport and SSE Compatibility — streamable-HTTP 与 SSE 迁移指南
• Custom Tools Configuration — 自定义 ES|QL 与 Search Template 工具编写

概述

本页面系统化地说明 mcp-server-elasticsearch 的部署方式、配置模型、支持的传输协议 (Transport) 以及安全机制。该项目是 Model Context Protocol (MCP) 的一种服务器实现，充当 AI Agent 与 Elasticsearch 集群之间的桥梁。

[!CAUTION]

该 MCP 服务器已弃用，后续将只接收关键安全更新。它已被 Elastic Agent Builder 的 MCP 端点 取代，后者自 Elastic 9.2.0+ 与 Elasticsearch Serverless 项目起可用。

资料来源：README.md:1-7

整体项目采用 Rust 实现，提供两种二进制入口:

• elasticsearch-mcp-server（包内默认名称，stdio 模式）
• start_http（HTTP 模式，详见 src/bin/start_http.rs）

部署层面主要支持两种传输协议：stdio 和 streamable-HTTP。早期版本支持的 SSE 传输已被弃用，但仍可通过 HttpCommand::sse 标志打开以做向后兼容。

graph TD
    Client[MCP 客户端<br/>Claude Desktop / Cursor / VS Code] -->|stdio| StdioServer[elasticsearch-mcp-server]
    Client -->|streamable-HTTP| HttpServer[start_http / 8080]
    StdioServer --> EsClient[Elasticsearch 客户端]
    HttpServer --> EsClient
    EsClient --> EsCluster[(Elasticsearch 集群<br/>8.x / 9.x)]
    HttpServer -.->|/ready, /live| HealthProbe[健康探针]

部署

Docker 镜像

README 推荐的部署路径是 Docker 容器镜像，发布在 AWS Marketplace。 资料来源：README.md:11-50

执行模式有两种：

二进制发布

mcp-server-elasticsearch 通过 Buildkite 流水线发布多平台二进制（参见 catalog-info.yaml 中定义的 buildkite-pipeline-mcp-server-elasticsearch 与 mcp-server-elasticsearch-docker）。

社区关注 #191 指出目前缺少 Linux arm64 正式发行版，仅发布 macOS 与 Windows 的 arm64。资料来源：Issue #191

CI/CD 与发布

• 仓库使用 Renovate Bot 自动更新依赖，配置位于 renovate.json，计划任务为「Monday 凌晨 1 点之后」。
• Docker 镜像构建/发布由独立的 Buildkite 流水线 .buildkite/docker.yml 负责，仅在打标签 (build_tags: true) 时构建，不为 PR/分支构建镜像。
• 版权信息：Copyright 2025 Elasticsearch B.V.，见 NOTICE.txt。

传输协议 (Transports)

CLI 命令结构

CLI 入口在 src/cli.rs 中定义，使用 clap 派生：

#[derive(Debug, Subcommand)]
pub enum Command {
    Stdio(StdioCommand),
    Http(HttpCommand),
}

两种子命令的参数表：

资料来源：src/cli.rs:10-30

stdio 传输

std 子命令直接以标准输入/输出与 MCP 客户端通信。客户端会通过 command 启动服务器进程，二者形成父子进程关系。 资料来源：src/cli.rs:30-37 与 src/cli.rs:55-67（Stdio 配置结构）

streamable-HTTP 传输

HTTP 模式在 src/protocol/http.rs 中实现。

graph TD
    Bind[bind SocketAddr<br/>默认 127.0.0.1:8080] --> Router[Axum Router]
    Router --> Root[GET / - hello/version]
    Router --> Ping[GET /ping]
    Router --> Mcp[POST /mcp - Streamable HTTP]
    Router --> Sse["GET /mcp/sse - SSE<br/>(可选)"]
    Router --> Health["GET /_health/{ready,live}"]
    Mcp --> ShService[StreamableHttpService]
    Sse --> SseService[SseServer]
    ShService --> Provider[ServerProvider]
    SseService --> Provider
    Provider --> Tools[EsBaseTools]
    Tools --> EsClient[Elasticsearch Client]

HttpServerConfig 的字段如下：

资料来源：src/protocol/http.rs:14-30

SSE（已弃用但仍可启用）

社区问题 #17 中明确反馈：自 SSE 弃用后，社区要求支持 streamable-HTTP。 资料来源：Issue #17

当前实现通过 HttpCommand::sse 标志在 /mcp/sse 路径额外暴露 SSE 端点。README 同时强调：

Note: Server-Sent Events (SSE) is deprecated. Use streamable-HTTP instead.

资料来源：README.md:53-55

McpServer 配置枚举也体现了这一过渡：

pub enum McpServer {
    Sse(Http),
    StreamableHttp(Http),
    Stdio(Stdio),
}

资料来源：src/cli.rs:69-79

HTTP 端点清单

配置

配置文件结构

CLI 解析的根 Configuration 结构（位于 src/cli.rs）：

pub struct Configuration {
    pub elasticsearch: elasticsearch::ElasticsearchMcpConfig,
    #[serde(default)]
    pub mcp_servers: HashMap<String, McpServer>,
}

它同时承载 MCP 服务器自身的 Elasticsearch 连接配置 和 MCP 客户端希望使用的下游 MCP 服务器列表（用于工具编排）。

Elasticsearch 连接配置

ElasticsearchMcpConfig 在 src/servers/elasticsearch/mod.rs 中定义：

空字符串会被规整为 None：

#[serde(default, deserialize_with = "none_if_empty_string")]
pub api_key: Option<String>,

资料来源：src/servers/elasticsearch/mod.rs:18-44

自定义工具/模板

Tools 结构支持通过配置文件注入搜索模板与 ES|QL 工具：

pub struct Tools {
    pub incl_excl: Option<IncludeExclude>,
    pub custom: HashMap<String, CustomTool>,
}

pub enum CustomTool {
    Esql(EsqlTool),
    SearchTemplate(SearchTemplateTool),
}

EsqlResultFormat 支持 json 与 value（单属性对象时仅返回值）。资料来源：src/servers/elasticsearch/mod.rs:50-110

默认配置字符串与 JSON5 解析

src/lib.rs 内置了一个默认配置字符串，演示了 ES_URL、ES_API_KEY、ES_USERNAME、ES_PASSWORD、ES_SSL_SKIP_VERIFY 五个环境变量的引用形式：

{
    "elasticsearch": {
        "url": "${ES_URL}",
        "api_key": "${ES_API_KEY:}",
        "username": "${ES_USERNAME:}",
        "password": "${ES_PASSWORD:}",
        "ssl_skip_verify": "${ES_SSL_SKIP_VERIFY:false}"
    }
}

读取流程：

graph TD
    Input[配置文件路径 / 默认字符串] --> Interp[interpolate_from_env]
    Interp --> Json5[serde_json5::from_str]
    Json5 --> Config[Configuration]
    Config --> McpInit[ElasticsearchMcp::new_with_config]
    McpInit --> Ready[已就绪服务器]

资料来源：src/lib.rs:30-55

环境变量插值

src/utils/interpolator.rs 实现了 ${VAR} 与 ${VAR:default} 形式的占位符展开。语法规则：

实现要点：

资料来源：src/utils/interpolator.rs:1-80

• 按行扫描，使用 ${ / } 包裹；
• 缺失变量且无默认值时，抛出 env variable 'xxx' not defined 错误；
• 默认值支持空字符串。

测试用例覆盖了组合插值与多行场景（good_extrapolation），可作为使用参考。资料来源：src/utils/interpolator.rs:60-100

README 推荐的 stdio 环境变量

Set the following environment variables:

- ES_URL: The URL of your Elasticsearch cluster

- For authentication: API key 或 username/password

资料来源：README.md:60-70

容器部署时，常将上述变量通过 docker run -e ES_URL=... -e ES_USERNAME=... 传入。

安全

身份认证模式

ElasticsearchMcp::new_with_config 在 src/servers/elasticsearch/mod.rs 中按以下优先级装配凭证：

graph TD
    Start[读取配置] --> Key{api_key 非空?}
    Key -- 是 --> Enc[Credentials::EncodedApiKey]
    Key -- 否 --> User{username 非空?}
    User -- 是 --> Pwd{password 存在?}
    Pwd -- 否 --> Err[anyhow::Error: missing password]
    Pwd -- 是 --> Basic[Credentials::Basic]
    User -- 否 --> None[无凭证]
    Enc --> Transport[TransportBuilder::new]
    Basic --> Transport
    None --> Transport
    Transport --> Pool[SingleNodeConnectionPool]
    Pool --> Client[Elasticsearch 客户端]

资料来源：src/servers/elasticsearch/mod.rs:110-140

每请求凭据透传

当通过 HTTP 模式工作时，EsClientProvider 会在每个请求上下文中检查传入的 Authorization 请求头，并将其透传到下游 Elasticsearch 调用：

/// If the incoming request is an http request and has an `Authorization` header,
/// use it to authenticate to the remote ES instance.
pub fn get(&self, context: ...) -> ...

该机制允许在 MCP 服务器端不持有长期凭证，而由客户端按需提供。

常见身份认证失败

社区问题 #170 报告了一个高频的「Basic auth failed - 401 Unauthorized」问题：在容器中确认 ES_USERNAME、ES_PASSWORD 都已设置，但认证仍然失败。 资料来源：Issue #170

排查思路（结合源码）：

资料来源：src/servers/elasticsearch/mod.rs:113-122

资料来源：src/servers/elasticsearch/mod.rs:120-130

1. 配置优先级：api_key 优先于 username/password；若同时设置了 ES_API_KEY 与 ES_USERNAME/PASSWORD，服务器会忽略 Basic Auth。
2. 空字符串语义：api_key、username、password 都使用 none_if_empty_string，空字符串等价于 None；但 ES_USERNAME 等环境变量若拼写错误（如误写为 ES_lOGIN，见 issue 中描述）则不会被解析。
3. 容器模式 URL 重写：当 container_mode = true 时，rewrite_localhost 会把 localhost/127.0.0.1 改写为 host.docker.internal（或等价主机名），避免容器内连接本地 ES。
4. TLS 与代理：当 ES 启用自签证书时，需要将 ssl_skip_verify 设为 true，或由客户端透传 Authorization 头并保持默认 TLS 行为。

TLS / SSL 配置

通过环境变量设置示例：

ES_SSL_SKIP_VERIFY=true

资料来源：src/servers/elasticsearch/mod.rs:32-34 与 src/lib.rs:38-44

弃用与迁移到 Elastic Agent Builder

最新发布 v0.4.6 仅添加了弃用说明。README 顶部明确指出：

This MCP server is deprecated and will only receive critical security updates going forward.

It has been superseded by the Elastic Agent Builder MCP endpoint, available in Elastic 9.2.0+ and Elasticsearch Serverless projects.

资料来源：README.md:1-7

对于仍在使用本项目的用户，应当关注：

• 升级到 Elastic 9.2.0+ 后改用 Agent Builder 内置 MCP；
• 现有容器化部署建议继续打补丁直到迁移完成。

健康检查与生命周期

HttpProtocol::serve_with_config 内部使用 tokio::net::TcpListener + axum::serve，并以 CancellationToken 实现优雅停机：

let server = axum::serve(listener, main_router).with_graceful_shutdown({
    let ct = ct.clone();
    async move {
        ct.cancelled().await;
        tracing::info!("http server cancelled");
    }
});

健康端点由独立的 health_router 处理：

let health_router = Router::new()
    .route("/ready", get(async || (StatusCode::OK, "Ready\n")))
    .route("/live", get(async || "Alive\n"));

建议 Kubernetes/ECS 部署将：

• /_health/ready（或 http://host:port/ping）映射至 readiness probe；
• /_health/live 映射至 liveness probe。

资料来源：src/protocol/http.rs:45-90

社区关注的限制与改进

端到端配置示例

下列示例展示了一个同时承载 elasticsearch 配置和下游 mcp_servers 的 JSON5 配置文件骨架，结合 src/lib.rs 的默认字符串与 src/cli.rs 的结构生成：

{
    "elasticsearch": {
        "url": "${ES_URL}",
        "api_key": "${ES_API_KEY:}",
        "username": "${ES_USERNAME:}",
        "password": "${ES_PASSWORD:}",
        "ssl_skip_verify": "${ES_SSL_SKIP_VERIFY:false}",
        "tools": {
            // 可选：自定义 ES|QL 或 SearchTemplate 工具
        }
    },
    "mcp_servers": {
        // 客户端使用的其他 MCP 服务器
        "docs": {
            "type": "streamable-http",
            "url": "https://example.com/mcp",
            "headers": {
                "Authorization": "Bearer xxx"
            }
        }
    }
}

运行命令：

# stdio 模式
elasticsearch-mcp-server stdio -c ./config.json5

# HTTP / streamable-HTTP 模式，并启用 SSE
start_http -c ./config.json5 --address 0.0.0.0:8080 --sse

See Also

• README.md — 官方入门、Docker 部署与协议选择
• src/cli.rs — CLI 入口与 McpServer/Configuration 数据模型
• src/lib.rs — 默认配置、JSON5 解析、环境变量插值调度
• src/protocol/http.rs — HTTP/streamable-HTTP/SSE 路由与健康探针
• src/servers/elasticsearch/mod.rs — ElasticsearchMcpConfig、客户端装配、EsClientProvider
• src/servers/elasticsearch/base_tools.rs — 工具实现与 SearchResult（包含 aggregations）
• src/utils/interpolator.rs — ${VAR} / ${VAR:default} 占位符展开
• Model Context Protocol 官方文档 — MCP 概念与传输协议规范

运维、故障排查与迁移至 Agent Builder

概述

Elasticsearch MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，它将 AI 代理（agent）连接到 Elasticsearch 集群，使代理能够以自然语言查询、分析和检索数据，而无需编写自定义 API 调用。该项目目前处于 beta 生命周期阶段，由 devtools-team 团队负责维护 catalog-info.yaml:3-9。

本页面聚焦于三个密切相关的主题：

1. 运维 (Operations)：如何配置、部署和监控 MCP 服务器。
2. 故障排查 (Troubleshooting)：社区用户在实际部署中遇到的高频问题及其解决方法。
3. 迁移至 Agent Builder (Migration to Agent Builder)：v0.4.6 引入的弃用公告以及推荐的替代方案。

重要提示：自 v0.4.6 起，本 MCP 服务器已被弃用，仅会接收关键的安全更新。其继任者是 Elastic Agent Builder 的 MCP 端点，可在 Elastic 9.2.0+ 及 Elasticsearch Serverless 项目中使用。资料来源：README.md:3-6。

Pitfall Log / 踩坑日志

项目：elastic/mcp-server-elasticsearch

摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

1. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -i --rm -e ES_URL -e ES_API_KEY docker.elastic.co/mcp/elasticsearch stdio
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -i --rm -e ES_URL -e ES_API_KEY docker.elastic.co/mcp/elasticsearch stdio
• 证据：identity.distribution | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | docker run -i --rm -e ES_URL -e ES_API_KEY docker.elastic.co/mcp/elasticsearch stdio

2. 安装坑 · 来源证据：Dependency Dashboard

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/elastic/mcp-server-elasticsearch/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | host_targets=mcp_host, claude, cursor

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：get_mappings tool fails with "error decoding response body" when nested type is omitted in properties

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：get_mappings tool fails with "error decoding response body" when nested type is omitted in properties
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/elastic/mcp-server-elasticsearch/issues/185 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:953992846 | https://github.com/elastic/mcp-server-elasticsearch | release_recency=unknown