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 进行身份验证
   • 输入：
     • apiKey (字符串, 可选): Honeycomb API 密钥（如果未提供，则使用环境变量）

数据集管理

1. honeycomb_datasets_list

   • 列出所有可用的数据集
   • 不需要输入参数

2. honeycomb_dataset_get

   • 获取特定数据集的信息
   • 输入：
     • datasetSlug (字符串, 必须): 数据集的标识符

3. honeycomb_datasets_create

   • 创建一个新的数据集
   • 输入：
     • name (字符串, 必须): 数据集名称
     • description (字符串, 可选): 数据集描述

列管理

1. honeycomb_columns_list
   • 列出数据集中的所有列
   • 输入：
     • datasetSlug (字符串, 必须): 数据集的标识符

查询管理

1. honeycomb_query_create

   • 为数据集创建新的查询
   • 输入：
     • datasetSlug (字符串, 必须): 数据集的标识符
     • query (对象, 必须): 查询配置

2. honeycomb_query_result_create

   • 执行查询并返回结果
   • 输入：
     • datasetSlug (字符串, 必须): 数据集的标识符
     • query (对象, 必须): 查询配置

事件管理

1. honeycomb_event_create
   • 在数据集中创建新事件
   • 输入：
     • datasetSlug (字符串, 必须): 数据集的标识符
     • data (对象, 必须): 事件数据

仪表板管理

1. honeycomb_boards_list

   • 列出所有看板
   • 不需要输入参数

2. honeycomb_board_get

   • 获取特定看板的信息
   • 输入：
     • boardId (字符串，必填)：看板的ID

3. honeycomb_board_create

   • 创建一个新的看板
   • 输入：
     • name (字符串，必填)：看板名称
     • description (字符串，可选)：看板描述
     • query_ids (字符串数组，可选)：要在看板中包含的查询ID

4. honeycomb_board_update

   • 更新现有的看板
   • 输入：
     • boardId (字符串，必填)：要更新的看板ID
     • name (字符串，可选)：看板的新名称
     • description (字符串，可选)：看板的新描述
     • query_ids (字符串数组，可选)：要在看板中包含的新查询ID

标记管理

1. honeycomb_markers_list

   • 列出数据集的所有标记
   • 输入：
     • datasetSlug (字符串，必填)：数据集的slug

2. honeycomb_marker_create

   • 创建一个新的标记
   • 输入：
     • datasetSlug (字符串，必填)：数据集的slug
     • message (字符串，必填)：标记的消息
     • type (字符串，必填)：标记的类型
     • start_time (字符串，必填)：标记的开始时间
     • end_time (字符串，可选)：标记的结束时间
     • url (字符串，可选)：与标记关联的URL
   • 输入：
     • datasetSlug (字符串，必填)：数据集的slug
     • markerId (字符串，必填)：要删除的标记ID

示例用法

这里是一个示例，展示Claude如何使用此MCP服务器创建一个新的Honeycomb数据集并添加一个事件：

[Claude] Please create a new dataset in Honeycomb called "Application Monitoring" with a description "Monitoring for our production application".

[User] I'll help you create a new dataset in Honeycomb.

[Claude] I'll create a new dataset for you in Honeycomb. 

I'll use the honeycomb_datasets_create tool:

Input:
{
  "name": "Application Monitoring",
  "description": "Monitoring for our production application"
}

The dataset has been created successfully!

[Claude] Now, let me add an event to this dataset. I'll create an event with some sample metrics.

I'll use the honeycomb_event_create tool:

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，请帮我为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
   }
   

2. 事件调查

   [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”的数据集，描述为“监控我们的生产应用程序”...

[Claude 使用 honeycomb_datasets_create]

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

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

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

[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仪表板中查看此事件，并开始构建查询以分析你的数据。

## 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. 叉取仓库
2. 克隆你的叉取

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

3. 安装依赖

   npm install
   

4. 进行修改
5. 运行构建

   npm run build
   

6. 在本地测试你的更改

提交请求流程

1. 创建一个功能分支

   git checkout -b feat-your-feature-name
   

2. 按照 Conventional Commits 格式提交你的更改

   git commit -m "feat: add new feature"
   

3. 推送到你的叉取

   git push origin feat-your-feature-name
   

4. 打开一个 Pull Request

编码标准

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

许可

本项目采用 MIT 许可证 - 请参阅 LICENSE 文件以获取详细信息。