蜂巢 MCP 服务器

阅读日语版本

概述

该服务器是一个使用模型上下文协议(MCP)的接口，使Claude AI能够与蜂巢API进行交互。

通过这个MCP服务器，Claude AI可以执行诸如检索、创建和更新蜂巢数据集、查询、事件、看板、标记、SLO和触发器等操作。

关于本仓库

本仓库提供了蜂巢MCP服务器的独立实现。它将Claude AI与蜂巢集成，以简化可观测性和监控工作流程。

安装

前提条件

• Node.js 18或更高版本
• 蜂巢API密钥

安装

# 全局安装
npm install -g @kajirita2002/honeycomb-mcp-server

# 或者直接使用npx
npx @kajirita2002/honeycomb-mcp-server

设置环境变量

# 设置环境变量
export HONEYCOMB_API_KEY="你的蜂巢API密钥"

MCP配置示例

如果你使用这个MCP服务器，在你的mcp_config.json文件中添加以下配置：

"honeycomb": {
  "command": "npx",
  "args": ["-y", "@kajirita2002/honeycomb-mcp-server"],
  "env": {
    "HONEYCOMB_API_KEY": "你的蜂巢API密钥"
  }
}

启动服务器

# 启动服务器
npm start

可用工具

这个MCP服务器提供以下工具：

认证

1. honeycomb_auth
   • 使用蜂巢API进行认证并验证你的API密钥
   • 不需要输入参数（使用环境变量）

数据集管理

1. honeycomb_datasets_list

   • 列出你蜂巢环境中所有可用的数据集
   • 不需要输入参数

2. honeycomb_dataset_get

   • 获取特定数据集的详细信息
   • 输入：
     • datasetSlug（字符串，必需）：要检索的数据集的别名

列管理

1. honeycomb_columns_list
   • 列出数据集中的所有列，可选择过滤
   • 输入：
     • datasetSlug（字符串，必需）：数据集的别名
     • key_name（字符串，可选）：按特定列键名过滤

查询管理

1. honeycomb_query_create

   • 为数据集创建新查询
   • 输入：
     • datasetSlug（字符串，必需）：数据集的别名
     • query（对象，必需）：包含计算、时间范围和过滤器的查询配置对象

2. honeycomb_query_get

   • 获取特定查询的信息
   • 输入：
     • datasetSlug（字符串，必需）：数据集的别名
     • queryId（字符串，必需）：要检索的查询ID

3. honeycomb_query_result_create

   • 执行查询并返回结果（运行查询）
   • 输入：
     • datasetSlug（字符串，必需）：数据集的别名
     • queryId（字符串，必需）：要运行的查询ID
     • disable_series（布尔值，可选）：是否禁用系列数据
     • disable_total_by_aggregate（布尔值，可选）：是否禁用总计聚合
     • disable_other_by_aggregate（布尔值，可选）：是否禁用其他聚合
     • limit（整数，可选）：结果数量的限制

4. honeycomb_query_result_get

   • 获取之前执行的查询的结果
   • 输入：
     • datasetSlug（字符串，必需）：数据集的别名
     • queryResultId（字符串，必需）：要检索的查询结果ID

数据集定义

1. honeycomb_dataset_definitions_list
   • 列出数据集定义，支持分页
   • 输入：
     • page（数字，可选）：页码（从1开始）
     • limit（数字，可选）：每页结果数（默认：100，最大：1000）
     • sort_by（字符串，可选）：排序字段（例如'name'、'description'）
     • sort_order（字符串，可选）：排序顺序（'asc'或'desc'）

看板管理

1. honeycomb_boards_list

   • 列出所有可用的看板
   • 不需要输入参数

2. honeycomb_board_get

   • 获取特定看板的详细信息
   • 输入：
     • boardId（字符串，必需）：要检索的看板ID

使用示例

以下是Claude使用这个MCP服务器列出数据集并运行查询的示例：

[Claude] 你能向我们展示蜂巢环境中可用的数据集吗？

[用户] 当然，我想看看我们在蜂巢中有哪些数据集。

[Claude] 我将列出你蜂巢环境中所有可用的数据集。

我将使用honeycomb_datasets_list工具...

这是你的可用数据集：
- 生产指标（别名：prod-metrics）
- 预发布服务（别名：staging-svc）
- 应用日志（别名：app-logs）

你想进一步探索哪个数据集？

[用户] 让我们看看生产指标数据集。

[Claude] 我将使用honeycomb_dataset_get和别名"prod-metrics"获取生产指标数据集的详细信息...

现在我将创建并运行一个查询，以显示过去24小时的平均响应时间。

我将使用honeycomb_query_create，然后使用honeycomb_query_result_create...

这是显示平均响应时间趋势的结果：
[查询结果可视化描述]

输入：
{
  "datasetSlug": "应用监控",
  "data": {
    "service": "api网关",
    "duration_ms": 45.2,
    "status_code": 200,
    "endpoint": "/users",
    "method": "GET"
  }
}

事件创建成功！你现在可以在蜂巢UI的应用监控数据集中查看此事件。

[Claude] 我还可以创建一个查询来分析这些数据。让我创建一个显示按端点划分的平均持续时间的查询。

我将使用honeycomb_query_create工具：

输入：
{
  "datasetSlug": "应用监控",
  "query": {
    "calculations": [
      {
        "op": "AVG",
        "column": "duration_ms"
      }
    ],
    "breakdowns": ["endpoint"],
    "time_range": 3600
  }
}

常见集成模式

1. 可观测性自动化

   [用户] Claude，请帮我设置一个新的API响应时间SLO。
   
   [Claude] 我可以帮忙。让我创建一个SLO来跟踪API响应时间。
   
   我将使用honeycomb_slo_create和以下参数：
   {
     "datasetSlug": "生产API",
     "name": "API响应时间SLO",
     "description": "跟踪关键API端点的响应时间",
     "sli": {
       "alias": "响应时间 < 300ms",
       "conditions": {
         "column": "duration_ms",
         "operator": "<",
         "value": 300
       }
     },
     "time_period_days": 30,
     "target_per_million": 995000
   }
   

2. 事件调查

   [用户] 我们在生产环境中看到错误率升高。你能帮忙调查吗？
   
   [Claude] 我将帮助调查升高的错误率。让我查询最近的错误数据。
   
   首先，我将使用honeycomb_query_result_create：
   {
     "datasetSlug": "生产",
     "query": {
       "calculations": [
         {
           "op": "COUNT"
         }
       ],
       "filters": [
         {
           "column": "status_code",
           "operator": ">=",
           "value": 500
         }
       ],
       "breakdowns": ["service", "endpoint"],
       "time_range": 3600,
       "granularity": 60
     }
   }
   

创建名为"应用监控"的数据集，描述为"我们生产应用的监控"...

[Claude使用honeycomb_datasets_create]

数据集已成功创建！现在我们可以向其中添加事件。

你想让我在数据集中创建一个示例事件进行测试吗？

[用户] 是的，请添加一个示例事件。

[Claude] 我将向"应用监控"数据集添加一个示例事件。

[Claude使用honeycomb_event_create]

成功！我已向你的"应用监控"数据集添加了一个示例事件，数据如下： { "service": "api服务器", "message": "用户登录成功", "duration_ms": 45, "status_code": 200, "endpoint": "/api/login", "timestamp": "2025-03-25T14:30:00Z" }

此事件表示一个成功的用户登录操作，耗时45毫秒完成。

你现在可以在蜂巢仪表板中查看此事件，并开始构建查询来分析你的数据。

## 错误处理

此MCP服务器以一致的格式返回错误信息。当发生错误时，将返回以下结构：

```json
{
  "error": {
    "message": "详细的错误描述",
    "code": "错误代码"
  }
}

常见错误代码

• AUTH_ERROR：认证失败。检查你的API密钥。
• NOT_FOUND：请求的资源未找到。
• INVALID_PARAMETER：一个或多个参数无效。
• RATE_LIMIT：已达到蜂巢API的速率限制。
• SERVER_ERROR：发生了内部服务器错误。

故障排除提示

1. 认证问题

   • 确保你的HONEYCOMB_API_KEY设置正确
   • 验证API密钥具有适当的权限

2. 数据集未找到

   • 确认数据集别名正确（检查拼写）
   • 确保数据集存在于你的蜂巢账户中

3. 查询执行问题

   • 验证查询参数格式是否正确
   • 检查查询中的列名是否与数据集中的列名匹配

贡献

欢迎对蜂巢MCP服务器做出贡献！以下是你可以贡献的方式：

开发设置

1. 分叉仓库
2. 克隆你的分叉

   git clone https://github.com/你的用户名/honeycomb-mcp-server.git
   

3. 安装依赖项

   npm install
   

4. 进行更改
5. 运行构建

   npm run build
   

6. 在本地测试你的更改

拉取请求流程

1. 创建功能分支

   git checkout -b feat-your-feature-name
   

2. 按照约定式提交格式提交更改

   git commit -m "feat: 添加新功能"
   

3. 推送到你的分叉

   git push origin feat-your-feature-name
   

4. 打开拉取请求

编码标准

• 对所有新代码使用TypeScript
• 遵循现有的代码风格
• 为公共API添加注释
• 为新功能编写测试

许可证

此项目根据MIT许可证授权 - 详情请参阅LICENSE文件。