本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 MCP 应用程序实现代理可观察性
<a name="opensearch-observability-mcp-app"></a>

OpenSearch 通过 MCP Apps 提供代理可观测性体验，将可观测性工作流程引入您的代理 IDE 中，MCP App 呈现的可视化效果可供您验证。这种体验增强了 OpenSearch 用户界面（日志、跟踪、指标、警报）上基于网页的可观察性体验。您的 AI 代理可以使用存储在 OpenSearch 域和集合中的数据来调查事件。在 MCP Apps 中，每个 MCP 工具调用都会返回文本摘要供代理推理，还会返回交互式可视化供您在同一个对话话题中进行验证。

**主题**
+ [MCP 应用程序示例](#opensearch-observability-mcp-app-examples)
+ [重要概念](#opensearch-observability-mcp-app-concepts)
+ [先决条件](#opensearch-observability-mcp-app-prerequisites)
+ [设置 MCP 服务器](#opensearch-observability-mcp-app-setup)
+ [可用的 MCP 应用程序可实现代理可观测性](#opensearch-observability-mcp-app-available)
+ [mcpb 文件验证](#opensearch-observability-mcp-app-verification)

## MCP 应用程序示例
<a name="opensearch-observability-mcp-app-examples"></a>

以下示例显示了调查事件时，MCP 应用程序如何在兼容的代理 IDE 中呈现交互式可视化效果。

**警报**-查看和分类跨数据源的触发警报。警报视图显示一段时间内的触发活动、严重性细分和每个警报的详细信息，并可以选择开始调查。以下屏幕截图显示了带有触发活动的警报视图。

![MCP App 警报视图显示了射击活动直方图以及按严重性、状态和来源筛选的警报列表。](http://docs.aws.amazon.com/zh_cn/opensearch-service/latest/developerguide/images/mcp-app-alerts.png)


**可观察性报告**-查看汇总结果，例如按服务划分的错误计数，以及基础查询和 AI-generated 根本原因分析。以下屏幕截图显示了可观测性报告。

![MCP App 可观察性报告显示了按服务划分的错误计数条形图、根本原因表和分析摘要。](http://docs.aws.amazon.com/zh_cn/opensearch-service/latest/developerguide/images/mcp-app-report.png)


**追踪调查**-浏览分布式追踪的跨度层次结构和时间表，检查单个跨度详细信息，并阅读对故障起源的分析。以下屏幕截图显示了跟踪调查视图。

![MCP App 跟踪调查显示了跨度层次结构时间表，其中包含跨度详细信息和 AI 分析。](http://docs.aws.amazon.com/zh_cn/opensearch-service/latest/developerguide/images/mcp-app-trace.png)


**服务地图** — 将服务依赖关系可视化为呼叫图，其中边缘宽度反映呼叫量，颜色反映错误率，以了解事件的爆炸半径。下图显示了服务地图。

![MCP App 服务地图显示了包含每项服务的错误率和依赖边缘的调用图。](http://docs.aws.amazon.com/zh_cn/opensearch-service/latest/developerguide/images/mcp-app-service-map.png)


**指标可视化** — 将 PromQL 查询结果呈现为交互式折线图、条形图、面积图或指标图，并包含结果序列和指标行为分析。以下屏幕截图显示了指标可视化。

![MCP App 指标可视化显示 PromQL 折线图，其中包含结果系列和指标值表。](http://docs.aws.amazon.com/zh_cn/opensearch-service/latest/developerguide/images/mcp-app-visualization.png)


## 重要概念
<a name="opensearch-observability-mcp-app-concepts"></a>

OpenSearch 用户界面  
OpenSearch 用户界面是一种基于云的托管控制面板和运营分析体验，适用于亚马逊 OpenSearch 服务。它提供了一个统一的单端点接口，用于探索、查询和可视化多个数据源中的数据。通过 MCP 应用程序生成的可视化效果来自您的 OpenSearch UI 应用程序。

本地 MCP 服务器  
本地 MCP 服务器是直接在您的计算机上运行的程序，它充当代理 IDE 和 OpenSearch UI 应用程序之间的安全双向桥梁。MCP 服务器包含多种可供您的 AI 代理使用的工具，包括在兼容 IDE 中呈现 UI 的 MCP 应用程序工具。按照以下各节中的说明安装具有 MCP 应用程序功能的本地 MCP 服务器。

MCP 应用程序  
在 Claude Desktop 等 MCP 主机中呈现的交互式 UI 应用程序。在 OpenSearch 代理可观测性体验中，MCP 应用程序是一个可组合单元，用于执行单个可观测性作业，例如显示有关 SLO 或轨迹的可视化。

双重响应  
借助 MCP Apps，在兼容 IDE 中调用一个工具即可同时返回两个输出：一个是您期望从可观测性代理那里得到的紧凑文本摘要，以及在同一个对话中呈现的交互式可视化效果，便于您轻松查看和验证结果。

## 先决条件
<a name="opensearch-observability-mcp-app-prerequisites"></a>
+ 一款[OpenSearch 用户界面应用程序](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/application.html)，其可观察性工作空间已创建并连接到至少一个数据源（OpenSearch 域、集合或 Amazon Managed Prometheus）
+ [支持 MCP 应用程序的代理 IDE（Claude Desktop](https://modelcontextprotocol.io/extensions/client-matrix#support-matrix)、VS Code C GitHub opilot、Goose、ChatGPT、Cursor）
+ 基本熟悉可观测性概念（日志、跟踪、指标）和 IDE 用法
+ Node.js 在本地计算机上安装了 22 或更高版本
+ AWS 凭据配置了访问您的 OpenSearch UI 应用程序的权限。凭据必须允许`es:ESHttpGet`和`es:ESHttpPost`操作。
+ （可选）如果您想在没有生产数据的情况下进行测试，则使用示例数据部署的 OpenTelemetry 演示应用程序

## 设置 MCP 服务器
<a name="opensearch-observability-mcp-app-setup"></a>

**使用 mcpb 文件设置 MCP 服务器**

1. [下载](https://d373kuglijqwic.cloudfront.net/opensearch-observability-stack-mcp.zip) OpenSearch 可观测性 MCP 服务器文件。或者，您也可以下载[签名文件进行验证](https://d373kuglijqwic.cloudfront.net/opensearch-observability-stack-mcp.zip.asc)。

1. 解压下载的 文件。

1. 打开 mcpb 文件以触发兼容的 IDE 启动配置流程。按照页面中的说明进行操作。

或者，如果无法打开 mcpb 文件，则可以使用 server.js 文件作为参考，然后在 IDE 的扩展中手动配置 MCP 服务器。

**手动配置 MCP 服务器**

1. 打开您选择的 IDE（确保它与 MCP 应用程序兼容），然后导航到扩展或 MCP 部分。选择 “**添加新配置”**。

1. 在配置页面中，更新以下值：
   + 将 “args” 值替换为实际的 server.js 文件路径。
   + 将 OS\_UI\_ENDPOINT 替换为您的 OpenSearch UI 应用程序的 URL。
   + 将该区域替换为 OpenSearch UI 应用程序的区域。

以下示例显示了 MCP 服务器的配置。

```
{
  "mcpServers": {
    "opensearch-observability-stack-mcp": {
      "command": "node",
      "args": ["/path/to/opensearch-observability-stack-mcp/server/server.js"],
      "env": {
        "OS_UI_ENDPOINT": "application-foo-bar.us-west-2.opensearch.amazonaws.com",
        "AWS_REGION": "us-west-2",
        "AWS_PROFILE": "my-profile"
      }
    }
  }
}
```
+ `/path/to/opensearch-observability-stack-mcp/server/server.js`— 替换为 server.js 文件的路径。
+ `OS_UI_ENDPOINT`— 替换为您的 OpenSearch UI 应用程序 URL。
+ `AWS_REGION`— 替换为你所在 AWS 的地区。
+ `AWS_PROFILE`— 用您的 AWS 个人资料名称替换。如果您尚未配置配置文件，请按照此[说明](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)进行操作。

配置 MCP 服务器后，通过在 IDE 中输入问题（例如 “列出可用的可观测性数据源”）来验证连接。如果您收到错误消息，请按照说明修复配置。

## 可用的 MCP 应用程序可实现代理可观测性
<a name="opensearch-observability-mcp-app-available"></a>
+ 分类和响应-警报关联、事件时间表
+ 日志调查-模式搜索、日志聚类
+ 轨迹调查 — 轨迹查找器、跨度详情、延迟细分
+ 指标调查 — PromQL 探索、阈值分析
+ 服务性能 — RED 指标、服务级别视图
+ 拓扑-服务地图、依赖关系图
+ 可视化-动态可视化
+ 数据集和相关性 — 跨信号连接、数据摘要
+ AI 和代理可观察性 — LLM 呼叫跟踪、代理跟踪图和摘要
+ Stack Health — 集群状态、分片分配
+ [仪器分数](https://github.com/instrumentation-score/spec) — 使用遥测来检测仪器缺陷

## mcpb 文件验证
<a name="opensearch-observability-mcp-app-verification"></a>

（可选）要验证已下载对象的签名，请导入[公共签名密钥](https://d373kuglijqwic.cloudfront.net/opensearch-mcp-signing-public.asc)并运行以下命令。

```
# 1. Import the public signing key (one-time)
curl -s https://d373kuglijqwic.cloudfront.net/opensearch-mcp-signing-public.asc | gpg --import

# 2. Download the artifact and its signature
curl -O https://d373kuglijqwic.cloudfront.net/opensearch-observability-stack-mcp.zip
curl -O https://d373kuglijqwic.cloudfront.net/opensearch-observability-stack-mcp.zip.asc

# 3. Verify
gpg --verify opensearch-observability-stack-mcp.zip.asc opensearch-observability-stack-mcp.zip
```

如果验证成功，则输出包括`Good signature from "OpenSearch MCP <aos-observability-mcp-releases@amazon.com>"`。