MCP 服务器

honeycomb-mcp-server

蜂巢-MCP-服务器 (Fēngcháo-MCP-fúwùqì)

Tools

honeycomb_slos_list

List all SLOs for a dataset

honeycomb_auth

Get authentication information and validate API key

honeycomb_datasets_list

List all datasets in the environment

honeycomb_board_update

Update an existing board

honeycomb_board_delete

Delete a board

honeycomb_markers_list

List all markers for a dataset

honeycomb_dataset_get

Get information about a specific dataset

honeycomb_datasets_create

Create a new dataset

honeycomb_marker_create

Create a new marker for a dataset

honeycomb_datasets_update

Update an existing dataset

honeycomb_marker_get

Get information about a specific marker

honeycomb_marker_update

Update an existing marker

honeycomb_columns_list

List all columns in a dataset

honeycomb_query_create

Create a new query for a dataset

honeycomb_query_get

Get information about a specific query

honeycomb_query_result_create

Create a new query result (run a query)

honeycomb_query_result_get

Get results of a specific query execution

honeycomb_event_create

Create a new event in a dataset

honeycomb_batch_event_create

Create multiple events in a dataset in a single batch

honeycomb_boards_list

List all boards

honeycomb_board_get

Get information about a specific board

honeycomb_board_create

Create a new board

honeycomb_marker_delete

Delete a marker

honeycomb_slo_get

Get information about a specific SLO

honeycomb_slo_create

Create a new SLO for a dataset

honeycomb_slo_update

Update an existing SLO

honeycomb_triggers_list

List all triggers for a dataset

honeycomb_trigger_get

Get information about a specific trigger

honeycomb_trigger_create

Create a new trigger for a dataset

honeycomb_trigger_update

Update an existing trigger

honeycomb_trigger_delete

Delete a trigger

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 文件。