Honeycomb MCP

⚠️ 已弃用: 此自托管的MCP服务器已被弃用。请迁移到托管的Honeycomb模型上下文协议（MCP）解决方案，详情请参阅Honeycomb MCP文档。

一个用于与Honeycomb可观测性数据交互的模型上下文协议服务器。此服务器使像Claude这样的大语言模型可以直接分析和查询您的Honeycomb数据集，跨越多个环境。

要求

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

Honeycomb MCP实际上是一个完整的替代接口到Honeycomb，因此您需要广泛的API权限。

仅限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块中设置。

欧洲区配置

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

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

缓存配置

MCP服务器实现了缓存机制，以提高性能并减少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桌面
• Claude代码
• Cursor
• Windsurf
• Goose

很可能与其他客户端兼容。

功能

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

资源

使用URI格式访问Honeycomb数据集： honeycomb://{环境}/{数据集}

例如：

• honeycomb://生产/api-请求
• honeycomb://预发布/后端服务

资源响应包括：

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

工具

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

  { "环境": "生产" }
  

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

  {
    "环境": "生产",
    "数据集": "api-请求"
  }
  

• run_query: 执行丰富的选项分析查询

  {
    "环境": "生产",
    "数据集": "api-请求",
    "计算": [
      { "操作": "COUNT" },
      { "操作": "P95", "列": "持续时间_ms" }
    ],
    "细分": ["服务名"],
    "时间范围": 3600
  }
  

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

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

  {
    "环境": "生产",
    "数据集": "api-请求"
  }
  

• get_slo: 获取详细的SLO信息

  {
    "环境": "生产",
    "数据集": "api-请求",
    "sloId": "abc123"
  }
  

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

  {
    "环境": "生产",
    "数据集": "api-请求"
  }
  

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

  {
    "环境": "生产",
    "数据集": "api-请求",
    "triggerId": "xyz789"
  }
  

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

• get_instrumentation_help: 提供OpenTelemetry仪器指导

  {
    "语言": "python",
    "文件路径": "app/services/payment_processor.py"
  }
  

使用Claude的示例查询

向Claude询问如下问题：

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

优化工具响应

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

• 列出数据集：仅返回名称、别名和描述
• 获取列：返回精简的列信息，重点是名称、类型和描述
• 执行查询：
  • 包括实际结果和必要的元数据
  • 自动计算汇总统计数据
  • 仅包含热图查询的系列数据
  • 省略冗长的元数据、链接和执行细节
• 分析列：
  • 返回顶级值、计数和关键统计数据
  • 在适当情况下自动计算数值指标
• SLO信息：简化为关键状态指示器和性能指标
• 触发器信息：专注于触发器状态、条件和通知目标

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

run_query的查询规范

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

• 计算：要执行的操作数组

  • 支持的操作：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不需要列
  • 示例：{"操作": "HEATMAP", "列": "持续时间_ms"}

• 过滤器：过滤条件数组

  • 支持的操作符：=、!=、>、>=、<、<=、starts-with、does-not-start-with、exists、does-not-exist、contains、does-not-contain、in、not-in
  • 示例：{"列": "错误", "操作": "=", "值": true}

• 过滤组合："AND"或"OR"（默认为"AND"）

• 细分：用于分组结果的列数组

  • 示例：["服务名", "http.status_code"]

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

  • 必须引用细分或计算中的列
  • HEATMAP操作不能用于排序
  • 示例：{"操作": "COUNT", "排序": "降序"}

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

  • 可以与start_time或end_time之一结合使用，但不能同时使用两者

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

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

  • 示例：{"计算操作": "COUNT", "操作": ">", "值": 100}

示例查询

这里是一些实际的示例查询：

寻找慢速API调用

{
  "环境": "生产",
  "数据集": "api-请求",
  "计算": [
    {"列": "持续时间_ms", "操作": "HEATMAP"},
    {"列": "持续时间_ms", "操作": "MAX"}
  ],
  "过滤器": [
    {"列": "trace.parent_id", "操作": "does-not-exist"}
  ],
  "细分": ["http.target", "名称"],
  "排序": [
    {"列": "持续时间_ms", "操作": "MAX", "排序": "降序"}
  ]
}

数据库调用分布（上周）

{
  "环境": "生产",
  "数据集": "api-请求",
  "计算": [
    {"列": "持续时间_ms", "操作": "HEATMAP"}
  ],
  "过滤器": [
    {"列": "db.statement", "操作": "exists"}
  ],
  "细分": ["db.statement"],
  "时间范围": 604800
}

异常计数按异常和调用者

{
  "环境": "生产",
  "数据集": "api-请求",
  "计算": [
    {"操作": "COUNT"}
  ],
  "过滤器": [
    {"列": "exception.message", "操作": "exists"},
    {"列": "parent_name", "操作": "exists"}
  ],
  "细分": ["exception.message", "parent_name"],
  "排序": [
    {"操作": "COUNT", "排序": "降序"}
  ]
}

开发

pnpm install
pnpm run build

许可证

MIT