Honeycomb MCP Server

蜂窝MCP服务器

*阅读此内容 日语*

概述

借助此MCP服务器，Claude AI可以执行检索、创建和更新Honeycomb数据集、查询、事件、板、标记、SLO和触发器等操作。

关于存储库

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

设置

先决条件

• Node.js 18或更高版本
• 蜂窝API键

安装

# Install globally
npm install -g @kajirita2002/honeycomb-mcp-server

# Or use directly with npx
npx @kajirita2002/honeycomb-mcp-server

设置环境变量

# Set environment variables
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"
  }
}

启动服务器

# Start the server
npm start

可用工具

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

认证

1. honeycomb_auth

- 使用Honeycomb API进行身份验证并验证您的API密钥 - 无需输入参数（使用环境变量）

数据集管理

1. honeycomb_datasets_list

- 列出Honeycomb环境中的所有可用数据集 - 无需输入参数

1. honeycomb_dataset_get

- 获取特定数据集的详细信息 - 输入： - datasetSlug （string，必填）：要检索的数据集的字符串

栏目管理

1. honeycomb_columns_list

- 使用可选筛选列出数据集中的所有列 - 输入： - datasetSlug （string，必填）：数据集的Slug - key_name （字符串，可选）：按特定列键名筛选

查询管理

1. honeycomb_query_create

- 为数据集创建新查询 - 输入： - datasetSlug （string，必填）：数据集的Slug - query （object，必填）：查询配置对象，包括计算、时间范围和过滤器

1. honeycomb_query_get

- 获取有关特定查询的信息 - 输入： - datasetSlug （string，必填）：数据集的Slug - queryId （字符串，必填）：要检索的查询的ID

1. honeycomb_query_result_create

- 执行查询并返回结果（运行查询） - 输入： - datasetSlug （string，必填）：数据集的Slug - queryId （字符串，必填）：要运行的查询的ID - disable_series （boolean，可选）：是否禁用序列数据 - disable_total_by_aggregate （boolean，可选）：是否禁用总聚合 - disable_other_by_aggregate （boolean，可选）：是否禁用其他聚合 - limit （整数，可选）：限制结果数量

1. honeycomb_query_result_get

- 获取以前执行的查询的结果 - 输入： - datasetSlug （string，必填）：数据集的Slug - queryResultId （string，必填）：要检索的查询结果的ID

数据集定义

1. honeycomb_dataset_definitions_list

- 列出支持分页的数据集定义 - 输入： - page （数字，可选）：页码（从1开始） - limit （数字，可选）：每页结果数（默认值：100，最大值：1000） - sort_by （字符串，可选）：要排序的字段（例如“name”、“description”） - sort_order （字符串，可选）：排序顺序（'sc'或'sec'）

董事会管理

1. honeycomb_boards_list

- 列出所有可用板 - 无需输入参数

1. honeycomb_board_get

- 获取特定电路板的详细信息 - 输入： - boardId （string，必填）：要检索的板的ID

示例用法

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

[Claude] Can you show me the available datasets in our Honeycomb environment?

[User] Sure, I'd like to see what datasets we have in Honeycomb.

[Claude] I'll list all the available datasets in your Honeycomb environment.

I'll use the honeycomb_datasets_list tool...

Here are your available datasets:
- production-metrics (slug: prod-metrics)
- staging-services (slug: staging-svc)
- application-logs (slug: app-logs)

Which dataset would you like to explore further?

[User] Let's look at the production-metrics dataset.

[Claude] I'll get details about the production-metrics dataset using honeycomb_dataset_get with the slug "prod-metrics"...

Now I'll create and run a query to show the average response time over the last 24 hours.

I'll use honeycomb_query_create and then honeycomb_query_result_create...

Here are the results showing the average response time trend:
[Query results visualization description]

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

Event created successfully! You can now see this event in the Honeycomb UI under the Application Monitoring dataset.

[Claude] I can also create a query to analyze this data. Let me create a query that shows the average duration by endpoint.

I'll use the honeycomb_query_create tool:

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

常见集成模式

1. 观测自动化

   [User] Claude, please help me set up a new SLO for API response times.

   [Claude] I can help with that. Let me create an SLO to track API response times.

   I'll use honeycomb_slo_create with these parameters:
   {
     "datasetSlug": "production-api",
     "name": "API Response Time SLO",
     "description": "Tracks response time for critical API endpoints",
     "sli": {
       "alias": "Response Time =",
           "value": 500
         }
       ],
       "breakdowns": ["service", "endpoint"],
       "time_range": 3600,
       "granularity": 60
     }
   }

创建数据集“应用程序监控”，描述为“监控我们的生产应用程序”。..

\[Claude使用honeycomb_datasets_create\]

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

您想让我在数据集中创建一个示例事件来测试它吗？

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

\[Claude\]我将向“应用程序监控”数据集中添加一个示例事件。

\[Claude使用honeycomb_event_create\]

成功！我已将一个示例事件添加到您的“应用程序监控”数据集中，其中包含以下数据： { “服务”：“api服务器”， “message”：“用户登录成功”， “持续时间_ms”：45， “状态码”：200， “endpoint”：“/api/login”， “时间戳”：“2025-03-25T14:30:00Z” }

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

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

## Error Handling

This MCP server returns error information in a consistent format. When an error occurs, the following structure is returned:

{ "error": { "message": "Detailed error description", "code": "ERROR_CODE" } }

### 常见错误代码

- `AUTH_ERROR`：身份验证失败。检查您的API密钥。
- `NOT_FOUND`：找不到请求的资源。
- `INVALID_PARAMETER`：一个或多个参数无效。
- `RATE_LIMIT`：已达到蜂窝API费率限制。
- `SERVER_ERROR`：发生内部服务器错误。

### 故障排除提示

1. **身份验证问题**

   - 确保您的 `HONEYCOMB_API_KEY` 设置正确
   - 验证API密钥是否具有适当的权限

1. **未找到数据集**

   - 确认数据集段符正确（检查拼写错误）
   - 确保数据集存在于您的Honeycomb帐户中

1. **查询执行问题**

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

## 贡献

欢迎为Honeycomb MCP服务器捐款！以下是您如何做出贡献：

### 开发设置

1. 分叉存储库
1. 克隆你的叉子

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

1. 安装依赖项

npm install

1. 进行更改
1. 运行构建

npm run build

1. 在本地测试您的更改

### 拉取请求流程

1. 创建要素分支

git checkout -b feat-your-feature-name

1. 在以下情况下提交您的更改 [常规承诺](https://www.conventionalcommits.org/) 格式

git commit -m "feat: add new feature"

1. 推你的叉子

git push origin feat-your-feature-name

1. 打开拉取请求

### 编码标准

- 对所有新代码使用TypeScript
- 遵循现有代码样式
- 为公共API添加评论
- 为新功能编写测试

## 许可证

此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。