Honeycomb MCP Server

Honeycomb MCP 服务

阅读日语版

概述

此服务是一个接口，使用 Model Context Protocol (MCP) 让 Claude AI 能够与 Honeycomb API 交互。

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

关于此仓库

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

设置

前提条件

• Node.js 18 或更高版本
• Honeycomb 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 环境中的所有可用数据集
   • 无需输入参数

2. honeycomb_dataset_get

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

列管理

1. honeycomb_columns_list
   • 列出数据集中的所有列，并支持可选筛选
   • 输入：
     • datasetSlug（字符串，必填）：数据集的 Slug
     • key_name（字符串，可选）：按指定的列键名筛选

查询管理

1. honeycomb_query_create

   • 为数据集创建新查询
   • 输入：
     • datasetSlug（字符串，必填）：数据集的 Slug
     • query（对象，必填）：查询配置对象，包含计算方式、时间范围和筛选条件

2. honeycomb_query_get

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

3. honeycomb_query_result_create

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

4. honeycomb_query_result_get

   • 获取之前执行的查询结果
   • 输入：
     • datasetSlug（字符串，必填）：数据集的 Slug
     • 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] 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 < 300ms",
       "conditions": {
         "column": "duration_ms",
         "operator": "<",
         "value": 300
       }
     },
     "time_period_days": 30,
     "target_per_million": 995000
   }
   

2. 事件调查

   [User] We're seeing elevated error rates in production. Can you help investigate?
   
   [Claude] I'll help investigate the elevated error rates. Let me query the recent error data.
   
   First, I'll use 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]

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

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

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

[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" }

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

现在，你可以在 Honeycomb 控制面板中查看此事件，并开始构建查询来分析数据。

## Error Handling

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

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

常见错误代码

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

故障排除提示

1. 身份验证问题

   • 确保正确设置了 HONEYCOMB_API_KEY
   • 确认 API 密钥具有适当的权限

2. 未找到数据集

   • 确认数据集 slug 正确（检查是否有拼写错误）
   • 确保 Honeycomb 账户中存在该数据集

3. 查询执行问题

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

参与贡献

欢迎为 Honeycomb MCP 服务做出贡献！以下是参与方式：

开发环境设置

1. Fork 仓库
2. 克隆你的 fork

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

3. 安装依赖项

   npm install
   

4. 修改代码
5. 运行构建

   npm run build
   

6. 在本地测试你的修改

Pull Request 流程

1. 创建功能分支

   git checkout -b feat-your-feature-name
   

2. 按照 Conventional Commits 格式提交修改

   git commit -m "feat: add new feature"
   

3. 推送到你的 fork

   git push origin feat-your-feature-name
   

4. 发起 Pull Request

编码规范

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

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。