蜂巢-MCP服务器

Name: 蜂巢-MCP服务器
Author: kajirita2002

作者：kajirita20022 星标更新：2025-03-28

安装使用来源：spider==github.com

项目介绍

Honeycomb MCP 服务器

阅读此文档的日语版

概述

该服务器使用模型上下文协议（MCP），使 Claude AI 能够与 Honeycomb API 进行交互。

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

关于仓库

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

设置

先决条件

Node.js 18 或更高版本
Honeycomb API 密钥

安装

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

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

设置环境变量

# 设置环境变量
export HONEYCOMB_API_KEY="your_honeycomb_api_key"

MCP 配置示例

如果您正在使用此 MCP 服务器，请在您的 mcp_config.json 文件中添加以下配置：

"honeycomb": {
  "command": "npx",
  "args": ["-y", "@kajirita2002/honeycomb-mcp-server"],
  "env": {
    "HONEYCOMB_API_KEY": "your_honeycomb_api_key"
  }
}

启动服务器

# 启动服务器
npm start

可用工具

此 MCP 服务器提供了以下工具：

认证

honeycomb_auth
- 使用 Honeycomb API 进行认证并验证您的 API 密钥
- 不需要输入参数（使用环境变量）

数据集管理

honeycomb_datasets_list
- 列出您 Honeycomb 环境中的所有可用数据集
- 不需要输入参数
honeycomb_dataset_get
- 获取特定数据集的详细信息
- 输入：
  - datasetSlug (字符串，必需)：要检索的数据集的 slug

列管理

honeycomb_columns_list
- 列出数据集中所有列，并可选地进行过滤
- 输入：
  - datasetSlug (字符串，必需)：数据集的 slug
  - key_name (字符串，可选)：按特定列键名过滤

查询管理

honeycomb_query_create
- 为数据集创建新的查询
- 输入：
  - datasetSlug (字符串，必需)：数据集的 slug
  - query (对象，必需)：包含计算、时间范围和过滤器的查询配置对象
honeycomb_query_get
- 获取特定查询的信息
- 输入：
  - datasetSlug (字符串，必需)：数据集的 slug
  - queryId (字符串，必需)：要检索的查询的 ID
honeycomb_query_result_create
- 执行查询并返回结果（运行查询）
- 输入：
  - datasetSlug (字符串，必需)：数据集的 slug
  - queryId (字符串，必需)：要运行的查询的 ID
  - disable_series (布尔值，可选)：是否禁用序列数据
  - disable_total_by_aggregate (布尔值，可选)：是否禁用总计聚合
  - disable_other_by_aggregate (布尔值，可选)：是否禁用其他聚合
  - limit (整数，可选)：结果数量限制
honeycomb_query_result_get
- 获取之前执行查询的结果
- 输入：
  - datasetSlug (字符串，必需)：数据集的 slug
  - queryResultId (字符串，必需)：要检索的查询结果的 ID

数据集定义

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

看板管理

honeycomb_boards_list
- 列出所有可用的看板
- 不需要输入参数
honeycomb_board_get
- 获取特定看板的详细信息
- 输入：
  - boardId (字符串，必需)：要检索的看板的 ID

示例用法

这里是一个示例，展示 Claude 如何使用此 MCP 服务器列出数据集并运行查询：

[Claude] 你能给我看看我们 Honeycomb 环境中的可用数据集吗？

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

[Claude] 我会列出您 Honeycomb 环境中的所有可用数据集。

我将使用 honeycomb_datasets_list 工具...

这里是您的可用数据集：
- 生产指标 (slug: prod-metrics)
- 预发布服务 (slug: staging-svc)
- 应用日志 (slug: app-logs)

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

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

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

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

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

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

输入：
{
  "datasetSlug": "application-monitoring",
  "data": {
    "service": "api-gateway",
    "duration_ms": 45.2,
    "status_code": 200,
    "endpoint": "/users",
    "method": "GET"
  }
}

事件已成功创建！您现在可以在 Honeycomb UI 的 Application Monitoring 数据集中看到此事件。

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

我将使用 honeycomb_query_create 工具：

输入：
{
  "datasetSlug": "application-monitoring",
  "query": {
    "calculations": [
      {
        "op": "AVG",
        "column": "duration_ms"
      }
    ],
    "breakdowns": ["endpoint"],
    "time_range": 3600
  }
}

常见集成模式

可观测性自动化

[用户] Claude，请帮我设置一个新的 API 响应时间 SLO。

[Claude] 我可以帮助您。让我创建一个 SLO 来跟踪 API 响应时间。

我将使用 honeycomb_slo_create 并使用这些参数：
{
  "datasetSlug": "production-api",
  "name": "API 响应时间 SLO",
  "description": "跟踪关键 API 端点的响应时间",
  "sli": {
    "alias": "响应时间 < 300ms",
    "conditions": {
      "column": "duration_ms",
      "operator": "<",
      "value": 300
    }
  },
  "time_period_days": 30,
  "target_per_million": 995000
}

事故调查

[用户] 我们在生产环境中看到了较高的错误率。你能帮忙调查一下吗？

[Claude] 我会帮助调查较高的错误率。让我查询最近的错误数据。

首先，我将使用 honeycomb_query_result_create：
{
  "datasetSlug": "production",
  "query": {
    "calculations": [
      {
        "op": "COUNT"
      }
    ],
    "filters": [
      {
        "column": "status_code",
        "operator": ">=",
        "value": 500
      }
    ],
    "breakdowns": ["service", "endpoint"],
    "time_range": 3600,
    "granularity": 60
  }
}

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

[Claude 使用 honeycomb_datasets_create]

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

您希望我在这个数据集中创建一个示例事件来测试吗？

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

[Claude] 我将在 "Application Monitoring" 数据集中添加一个示例事件。

[Claude 使用 honeycomb_event_create]

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

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

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


## 错误处理

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

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

常见错误代码

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

故障排除提示

认证问题
- 确保您的 HONEYCOMB_API_KEY 设置正确
- 验证 API 密钥具有适当的权限
数据集未找到
- 确认数据集 slug 正确（检查拼写）
- 确保数据集存在于您的 Honeycomb 账户中
查询执行问题
- 验证查询参数格式正确
- 检查查询中的列名是否与数据集中的列名匹配

贡献

欢迎对 Honeycomb MCP 服务器进行贡献！这是您可以贡献的方式：

开发设置

分叉仓库

克隆您的分叉

git clone https://github.com/your-username/honeycomb-mcp-server.git

安装依赖项
```
npm install
```
进行更改
运行构建
```
npm run build
```
在本地测试您的更改

拉取请求过程

创建功能分支
```
git checkout -b feat-your-feature-name
```
根据常规提交格式提交更改
```
git commit -m "feat: 添加新功能"
```
推送到您的分叉
```
git push origin feat-your-feature-name
```
打开拉取请求

编码标准

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

许可证

本项目根据 MIT 许可证发布 - 查看 LICENSE 文件了解详情。