Honeycomb MCP 服务器

一个用于与 Honeycomb 可观测性数据交互的 模型上下文协议 服务器。该服务器使像 Claude 这样的大语言模型 (LLM) 能够直接分析和查询您在多个环境中的 Honeycomb 数据集。

仅限 Honeycomb 企业版

目前，这仅适用于 Honeycomb 企业版客户。

工作原理

目前，这是一个您必须在自己的计算机上运行的单个服务器进程。它未经身份验证。所有信息都使用客户端和服务器之间的 STDIO。

安装

pnpm install
pnpm run build

构建产物会进入 /build 文件夹。

配置

要使用此 MCP 服务器，您需要在 MCP 配置中通过环境变量提供 Honeycomb API 密钥。

{
    "mcpServers": {
      "honeycomb": {
        "command": "node",
        "args": [
          "/fully/qualified/path/to/honeycomb-mcp/build/index.mjs"
        ],
        "env": {
          "HONEYCOMB_API_KEY": "your_api_key"
        }
      }
    }
}

对于多个环境：

{
    "mcpServers": {
      "honeycomb": {
        "command": "node",
        "args": [
          "/fully/qualified/path/to/honeycomb-mcp/build/index.mjs"
        ],
        "env": {
          "HONEYCOMB_ENV_PROD_API_KEY": "your_prod_api_key",
          "HONEYCOMB_ENV_STAGING_API_KEY": "your_staging_api_key"
        }
      }
    }
}

重要提示： 这些环境变量必须在您的 MCP 配置的 env 块中设置。

EU 配置

欧盟客户还必须设置 HONEYCOMB_API_ENDPOINT 配置，因为 MCP 默认设置为非欧盟实例。

# 可选的自定义 API 端点（默认为 https://api.honeycomb.io）
HONEYCOMB_API_ENDPOINT=https://api.eu1.honeycomb.io/

缓存配置

MCP 服务器为所有非查询 Honeycomb API 调用实现缓存，以提高性能并减少 API 使用量。可以使用以下环境变量配置缓存：

# 启用/禁用缓存（默认：true）
HONEYCOMB_CACHE_ENABLED=true

# 默认 TTL（秒）（默认：300）
HONEYCOMB_CACHE_DEFAULT_TTL=300

# 资源特定的 TTL 值（秒）（显示默认值）
HONEYCOMB_CACHE_DATASET_TTL=900    # 15 分钟
HONEYCOMB_CACHE_COLUMN_TTL=900     # 15 分钟
HONEYCOMB_CACHE_BOARD_TTL=900      # 15 分钟
HONEYCOMB_CACHE_SLO_TTL=900        # 15 分钟
HONEYCOMB_CACHE_TRIGGER_TTL=900    # 15 分钟
HONEYCOMB_CACHE_MARKER_TTL=900     # 15 分钟
HONEYCOMB_CACHE_RECIPIENT_TTL=900  # 15 分钟
HONEYCOMB_CACHE_AUTH_TTL=3600      # 1 小时

# 最大缓存大小（每个资源类型的项目数）
HONEYCOMB_CACHE_MAX_SIZE=1000

客户端兼容性

Honeycomb MCP 已经过以下客户端的测试：

• Claude Desktop
• Claude Code
• Cursor
• Windsurf
• Goose

它可能与其他客户端一起使用。

特性

• 跨多个环境查询 Honeycomb 数据集
• 运行分析查询，支持：
  • 多种计算类型（COUNT、AVG、P95 等）
  • 分解和过滤器
  • 基于时间的分析
• 监控 SLO 及其状态（仅限企业版）
• 分析列和数据模式
• 查看和分析触发器
• 访问数据集元数据和模式信息
• 通过基于 TTL 的缓存优化所有非查询 API 调用的性能

资源

使用以下格式的 URI 访问 Honeycomb 数据集： honeycomb://{environment}/{dataset}

例如：

• honeycomb://production/api-requests
• honeycomb://staging/backend-services

资源响应包括：

• 数据集名称
• 列信息（名称、类型、描述）
• 模式详细信息

工具

• list_datasets：列出环境中的所有数据集

  { "environment": "production" }
  

• get_columns：获取数据集的列信息

  {
    "environment": "production",
    "dataset": "api-requests"
  }
  

• run_query：运行具有丰富选项的分析查询

  {
    "environment": "production",
    "dataset": "api-requests",
    "calculations": [
      { "op": "COUNT" },
      { "op": "P95", "column": "duration_ms" }
    ],
    "breakdowns": ["service.name"],
    "time_range": 3600
  }
  

• analyze_columns: 通过运行统计查询并返回计算的指标来分析数据集中的特定列。

• list_slos：列出数据集的所有 SLO

  {
    "environment": "production",
    "dataset": "api-requests"
  }
  

• get_slo：获取详细的 SLO 信息

  {
    "environment": "production",
    "dataset": "api-requests",
    "sloId": "abc123"
  }
  

• list_triggers：列出数据集的所有触发器

  {
    "environment": "production",
    "dataset": "api-requests"
  }
  

• get_trigger：获取详细的触发器信息

  {
    "environment": "production",
    "dataset": "api-requests",
    "triggerId": "xyz789"
  }
  

• get_trace_link: 生成指向 Honeycomb UI 中特定跟踪的深层链接

• get_instrumentation_help: 提供 OpenTelemetry instrumentation 指导

  {
    "language": "python",
    "filepath": "app/services/payment_processor.py"
  }
  

Claude 的示例查询

向 Claude 询问以下问题：

• "生产环境中有哪些数据集可用？"
• "显示过去一小时 API 服务的 P95 延迟"
• "按服务名称分解的错误率是多少？"
• "是否有任何 SLO 接近超出其预算？"
• "显示暂存环境中的所有活动触发器"
• "生产 API 数据集中有哪些列可用？"

优化的工具响应

所有工具响应都经过优化，以减少上下文窗口的使用，同时保持基本信息：

• 列出数据集：仅返回名称、slug 和描述
• 获取列：返回简化的列信息，重点关注名称、类型和描述
• 运行查询：
  • 包括实际结果和必要的元数据
  • 添加自动计算的摘要统计信息
  • 仅包括热图查询的序列数据
  • 省略详细的元数据、链接和执行详细信息
• 分析列：
  • 返回最高值、计数和关键统计信息
  • 在适当的时候自动计算数值指标
• SLO 信息：简化为关键状态指标和性能指标
• 触发器信息：重点关注触发器状态、条件和通知目标

这种优化确保响应简洁但完整，允许 LLM 在上下文限制内处理更多数据。

run_query 的查询规范

run_query 工具支持全面的查询规范：

• calculations：要执行的操作数组

  • 支持的操作：COUNT、CONCURRENCY、COUNT_DISTINCT、HEATMAP、SUM、AVG、MAX、MIN、P001、P01、P05、P10、P25、P50、P75、P90、P95、P99、P999、RATE_AVG、RATE_SUM、RATE_MAX
  • 某些操作（如 COUNT 和 CONCURRENCY）不需要列
  • 示例：{"op": "HEATMAP", "column": "duration_ms"}

• filters：过滤器条件数组

  • 支持的运算符：=, !=, >, >=, <, <=, starts-with, does-not-start-with, exists, does-not-exist, contains, does-not-contain, in, not-in
  • 示例：{"column": "error", "op": "=", "value": true}

• filter_combination："AND" 或 "OR"（默认为 "AND"）

• breakdowns：用于对结果进行分组的列数组

  • 示例：["service.name", "http.status_code"]

• orders：指定如何对结果进行排序的数组

  • 必须引用分解或计算中的列
  • HEATMAP 操作不能在 order 中使用
  • 示例：{"op": "COUNT", "order": "descending"}

• time_range：相对时间范围（秒）（例如，3600 表示过去一小时）

  • 可以与 start_time 或 end_time 组合使用，但不能同时使用

• start_time 和 end_time：绝对时间范围的 UNIX 时间戳

• having：根据计算值过滤结果

  • 示例：{"calculate_op": "COUNT", "op": ">", "value": 100}

示例查询

以下是一些真实世界的示例查询：

查找慢速 API 调用

{
  "environment": "production",
  "dataset": "api-requests",
  "calculations": [
    {"column": "duration_ms", "op": "HEATMAP"},
    {"column": "duration_ms", "op": "MAX"}
  ],
  "filters": [
    {"column": "trace.parent_id", "op": "does-not-exist"}
  ],
  "breakdowns": ["http.target", "name"],
  "orders": [
    {"column": "duration_ms", "op": "MAX", "order": "descending"}
  ]
}

DB 调用的分布（上周）

{
  "environment": "production",
  "dataset": "api-requests",
  "calculations": [
    {"column": "duration_ms", "op": "HEATMAP"}
  ],
  "filters": [
    {"column": "db.statement", "op": "exists"}
  ],
  "breakdowns": ["db.statement"],
  "time_range": 604800
}

按异常和调用者统计异常计数

{
  "environment": "production",
  "dataset": "api-requests",
  "calculations": [
    {"op": "COUNT"}
  ],
  "filters": [
    {"column": "exception.message", "op": "exists"},
    {"column": "parent_name", "op": "exists"}
  ],
  "breakdowns": ["exception.message", "parent_name"],
  "orders": [
    {"op": "COUNT", "order": "descending"}
  ]
}

开发

pnpm install
pnpm run build

要求

• Node.js 16+
• 具有适当权限的 Honeycomb API 密钥：
  • 用于分析的查询访问权限
  • 用于 SLO 和触发器的读取访问权限
  • 用于数据集操作的环境级别访问权限

许可证

MIT