Honeycomb MCP Server 使用说明

项目简介

Honeycomb MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在桥接大型语言模型 (LLM) 与 Honeycomb 这款强大的可观测性数据平台。通过此服务器，LLM 如 Claude 可以直接访问和分析存储在 Honeycomb 中的监控数据，极大地扩展了 LLM 在运维和数据分析领域的应用能力。

主要功能点

连接 Honeycomb 数据： 安全连接到您的 Honeycomb 账户，支持多环境配置（如生产环境、测试环境）。
数据集资源访问： 通过标准化的 URI 格式 'honeycomb://{environment}/{dataset}' 访问 Honeycomb 数据集，获取数据集的元数据和结构信息。
强大的分析工具： 提供一系列工具，允许 LLM 执行复杂的 Honeycomb 数据分析操作，包括：
- 数据查询： 检索指定环境和数据集中的数据集列表、列信息。
- 指标分析： 运行各种分析查询，支持 COUNT, AVG, P95 等多种计算类型，以及 breakdowns（分组）、filters（过滤）和 time-based analysis（时间范围分析）。
- SLO 监控： 查看和分析服务级别目标 (SLO) 及其状态。
- 触发器分析： 查看和分析在 Honeycomb 中配置的 Triggers (告警触发器)。
标准 MCP 协议： 遵循 Model Context Protocol 标准，易于与任何兼容 MCP 协议的客户端（如 Claude）集成。

安装步骤

安装 Node.js 和 pnpm: 确保您的系统已安装 Node.js (版本 16+) 和包管理器 pnpm。
下载代码: 从 GitHub 仓库 https://github.com/austinlparker/hny-mcp 克隆或下载代码。
安装依赖: 在项目根目录下运行命令安装项目依赖：
```
pnpm install
```
构建项目: 运行命令构建项目，生成可执行代码：
```
pnpm run build
```

服务器配置

Honeycomb MCP Server 需要配置文件来连接到您的 Honeycomb 账户。

创建配置文件: 在以下位置之一创建名为 '.mcp-honeycomb.json' 的配置文件：
- 当前工作目录
- 用户Home目录 ('~/.mcp-honeycomb.json')
- 通过环境变量 'MCP_HONEYCOMB_CONFIG' 指定的路径

配置 Honeycomb API 密钥: 编辑 '.mcp-honeycomb.json' 文件，填入您的 Honeycomb API 密钥。您需要为每个需要访问的 Honeycomb 环境配置 API 密钥。

配置文件示例 ('.mcp-honeycomb.json'):

{
  "environments": [
    {
      "name": "production",  // 环境名称，例如：production, staging, dev 等，客户端会使用此名称来指定环境
      "apiKey": "your_prod_api_key" // 您的 Production 环境的 Honeycomb API 密钥
    },
    {
      "name": "staging",     // 另一个环境名称
      "apiKey": "your_staging_api_key" // 您的 Staging 环境的 Honeycomb API 密钥
    }
  ]
}

注意: 请替换 'your_prod_api_key' 和 'your_staging_api_key' 为您真实的 Honeycomb API 密钥。API 密钥需要具备 Query (查询), Read access for SLOs and Triggers (读取 SLO 和 Trigger) 以及 Environment-level access for dataset operations (数据集操作) 的权限。

MCP 客户端配置 (以 JSON 格式提供): MCP 客户端 (如 Claude) 需要以下配置信息来连接到 Honeycomb MCP Server。

{
  "serverName": "honeycomb-mcp-server",  // MCP 服务器的名称，可以自定义
  "command": "pnpm",                     // 启动服务器的命令，这里使用 pnpm
  "args": [                               // 命令参数
    "run",
    "start"                               // 运行 "start" 脚本，package.json 中应配置 start 脚本为 'node dist/index.js'
  ]
}

参数注释:

'serverName': 为您的 MCP 服务器指定一个易于识别的名称。
'command': 指定用于启动服务器进程的命令。通常是 Node.js 包管理器 (如 'pnpm', 'npm', 'yarn') 或 Node.js 解释器 ('node').
'args': 一个字符串数组，包含传递给 'command' 的参数。根据 'package.json' 中的 scripts 配置，这里使用 'run start' 来执行 'start' 脚本启动服务器。实际执行的命令可能是 'node dist/index.js'。

基本使用方法

启动服务器: 在项目根目录下运行命令启动 Honeycomb MCP Server：
```
pnpm run start
```
服务器成功启动后，会在终端输出 'Honeycomb MCP Server running on stdio'。
在 MCP 客户端中使用: 配置您的 MCP 客户端 (如 Claude)，连接到 Honeycomb MCP Server。
- 资源访问: 使用 'honeycomb://{environment}/{dataset}' 格式的 URI 访问 Honeycomb 数据集。例如：
  - 'honeycomb://production/api-requests' 访问 production 环境下的 'api-requests' 数据集。
- 工具调用: 使用提供的工具名称和参数来执行数据分析操作。例如，使用 'list_datasets' 工具列出 production 环境下的所有数据集：
```
{ "tool_code": "list_datasets", "tool_input": { "environment": "production" } }
```
  更多工具的使用方法和参数，请参考仓库 README.md 文档的 "Usage" 部分。
示例查询: 您可以向 Claude 或其他 MCP 客户端提出类似以下的问题，利用 Honeycomb MCP Server 分析您的 Honeycomb 数据：
- "What datasets are available in the production environment?" (production 环境下有哪些数据集？)
- "Show me the P95 latency for the API service over the last hour" (展示 API 服务过去一小时的 P95 延迟)
- "What's the error rate broken down by service name?" (错误率按服务名称 breakdown 是多少？)
- "Are there any SLOs close to breaching their budget?" (是否有 SLO 接近超出预算？)
- "Show me all active triggers in the staging environment" (展示 staging 环境下所有激活的 triggers)
- "What columns are available in the production API dataset?" (production 环境 API 数据集有哪些列可用？)

通过以上步骤，您就可以利用 Honeycomb MCP Server 将 LLM 与 Honeycomb 可观测性数据连接起来，实现更智能化的数据分析和监控。

关键词