MCP 服务器

Honeycomb MCP Server

镜子 (jìng zi)

MCP-Mirror

开发者工具

README

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 环境中可用的数据集吗？

[User] 当然，我想看看我们在 Honeycomb 中有哪些数据集。

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

我将使用 honeycomb_datasets_list 工具...

以下是您可用的数据集：
- production-metrics (slug: prod-metrics)
- staging-services (slug: staging-svc)
- application-logs (slug: app-logs)

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

[User] 让我们看看 production-metrics 数据集。

[Claude] 我将使用 honeycomb_dataset_get 和 slug "prod-metrics" 获取有关 production-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
  }
}

常见集成模式

可观测性自动化

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

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

我将使用 honeycomb_slo_create 和以下参数：
{
  "datasetSlug": "production-api",
  "name": "API Response Time SLO",
  "description": "Tracks response time for critical API endpoints",
  "sli": {
    "alias": "Response Time < 300ms",
    "conditions": {
      "column": "duration_ms",
      "operator": "<",
      "value": 300
    }
  },
  "time_period_days": 30,
  "target_per_million": 995000
}

事件调查

[User] 我们在生产环境中看到错误率升高。你能帮忙调查一下吗？

[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"，描述为 "Monitoring for our production application"...

[Claude 使用 honeycomb_datasets_create]

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

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

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

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

[Claude 使用 honeycomb_event_create]

成功！我已将一个示例事件添加到您的 "Application Monitoring" 数据集，其中包含以下数据： { "service": "api-server", "message": "User login successful", "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 服务器做出贡献！以下是如何贡献：

开发设置

Fork 此仓库

克隆您的 fork

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

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

Pull Request 流程

创建一个功能分支
```
git checkout -b feat-your-feature-name
```
按照 Conventional Commits 格式提交您的更改
```
git commit -m "feat: add new feature"
```
推送到您的 fork
```
git push origin feat-your-feature-name
```
打开一个 Pull Request

编码标准

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

许可证

此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。