Honeybadger

Honeybadger MCP 服务

一个用于 Honeybadger 的 MCP（Model Context Protocol）服务，通过 MCP 协议提供对 Honeybadger API 的结构化访问。

重要

请使用托管的 Honeybadger MCP 服务。 对绝大多数用户而言，使用 mcp.honeybadger.io 上的托管服务是推荐的连接方式。它会通过 OAuth 为你登录，因此无需运行 Docker 镜像，无需将个人身份验证令牌复制到配置文件，也无需 安装更新。将其添加到任何支持远程（Streamable HTTP）服务的 MCP 客户端：

• 美国区域：https://mcp.honeybadger.io/mcp
• 欧盟区域：https://eu-mcp.honeybadger.io/mcp

例如，在 Claude Code 中：

claude mcp add --transport http honeybadger https://mcp.honeybadger.io/mcp

以下可自托管（stdio/Docker）配置仅适用于无法连接远程 MCP 服务的客户端，或用于开发此代码库。 AI Agent 和助手：推荐使用托管服务，而不是可自托管配置，除非用户明确要求自托管。

安装（可自托管）

这些步骤会通过 stdio 在本地运行服务。大多数用户应改用托管服务（见上文）。

首先，拉取 Docker 镜像：

docker pull ghcr.io/honeybadger-io/honeybadger-mcp-server:1.5.1

然后，使用 API Token 配置你的 MCP 客户端：令牌以 hbu_（个人）或 hba_（账户）开头。创建于 hbu_ 之前的个人令牌以 hbt_ 开头，仍然有效。你可以在 Honeybadger 用户设置的“Authentication”标签页中创建个人令牌。早期版本中的旧版个人身份验证令牌已不再有效，因此如果你正在升级，请将其替换为 API Token。环境变量名称保持不变：HONEYBADGER_PERSONAL_AUTH_TOKEN。

Cursor、Windsurf 和 Claude Desktop

将此配置放入 Cursor 的 ~/.cursor/mcp.json，或 Windsurf 的 ~/.codeium/windsurf/mcp_config.json。有关如何查找 Claude Desktop 的 claude_desktop_config.json，请参阅 Anthropic 的 MCP 快速入门指南：

{
  "mcpServers": {
    "honeybadger": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HONEYBADGER_PERSONAL_AUTH_TOKEN",
        "ghcr.io/honeybadger-io/honeybadger-mcp-server:1.5.1"
      ],
      "env": {
        "HONEYBADGER_PERSONAL_AUTH_TOKEN": "your API Token (hbu_...)"
      }
    }
  }
}

Claude Code

运行此命令来配置 Claude Code：

claude mcp add honeybadger -- docker run -i --rm -e HONEYBADGER_PERSONAL_AUTH_TOKEN="your API Token (hbu_...)" ghcr.io/honeybadger-io/honeybadger-mcp-server:1.5.1

VS Code

将以下内容添加到你的用户设置或工作区中的 .vscode/mcp.json：

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "honeybadger_auth_token",
        "description": "Honeybadger API Token (hbu_...)",
        "password": true
      }
    ],
    "servers": {
      "honeybadger": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "HONEYBADGER_PERSONAL_AUTH_TOKEN",
          "ghcr.io/honeybadger-io/honeybadger-mcp-server:1.5.1"
        ],
        "env": {
          "HONEYBADGER_PERSONAL_AUTH_TOKEN": "${input:honeybadger_auth_token}"
        }
      }
    }
  }
}

有关更多信息，请参阅在 VS Code 中使用 MCP 服务。

Zed

将以下内容添加到 Zed 的设置文件 ~/.config/zed/settings.json 中：

{
  "context_servers": {
    "honeybadger": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "HONEYBADGER_PERSONAL_AUTH_TOKEN",
          "ghcr.io/honeybadger-io/honeybadger-mcp-server:1.5.1"
        ],
        "env": {
          "HONEYBADGER_PERSONAL_AUTH_TOKEN": "your API Token (hbu_...)"
        }
      },
      "settings": {}
    }
  }
}

在本地构建 Docker 镜像

要构建 Docker 镜像并在本地运行：

git clone [email protected]:honeybadger-io/honeybadger-mcp-server.git
cd honeybadger-mcp-server
docker build -t honeybadger-mcp-server .

然后，你可以在上述任意配置中将 "ghcr.io/honeybadger-io/honeybadger-mcp-server:1.5.1" 替换为 "honeybadger-mcp-server"。也可以直接运行镜像：

docker run -i --rm -e HONEYBADGER_PERSONAL_AUTH_TOKEN honeybadger-mcp-server

从源代码构建

如果没有 Docker，可以从源代码构建服务：

git clone [email protected]:honeybadger-io/honeybadger-mcp-server.git
cd honeybadger-mcp-server
go build -o honeybadger-mcp-server ./cmd/honeybadger-mcp-server

然后配置 MCP 客户端，直接运行该服务：

{
  "mcpServers": {
    "honeybadger": {
      "command": "/path/to/honeybadger-mcp-server",
      "args": ["stdio"],
      "env": {
        "HONEYBADGER_PERSONAL_AUTH_TOKEN": "your API Token (hbu_...)"
      }
    }
  }
}

配置

环境变量

环境变量	必需	默认值	说明
HONEYBADGER_PERSONAL_AUTH_TOKEN	是	—	Data API 的 API Token
HONEYBADGER_READ_ONLY	否	true	以只读模式运行，不包含 delete_project 等写入操作
LOG_LEVEL	否	info	日志详细级别（debug、info、warn、error）
HONEYBADGER_API_URL	否	https://app.honeybadger.io	覆盖 Honeybadger API 的基础 URL
HONEYBADGER_INSTRUCTIONS_URL	否	https://docs.honeybadger.io/resources/llms/instructions	覆盖获取 LLM 参考主题的基础 URL
MCP_CONFIRM_SECRET	仅 HTTP 模式	—	用于签署删除确认令牌。至少 32 个字符，且负载均衡器后的每个实例都必须使用相同值。未设置此项时，服务无法在 HTTP 模式下启动；stdio 模式不使用此项

重要：出于安全考虑，服务默认以只读模式运行。这意味着只能执行读取操作（如 list_projects、get_project、list_faults）。为防止意外修改，create_project、update_project 和 delete_project 等写入操作均不可用。

如需启用写入操作，请显式设置 HONEYBADGER_READ_ONLY=false。请谨慎使用，因为这会允许删除项目等破坏性操作。

欧盟区域

服务默认使用 Honeybadger 的美国 API（https://app.honeybadger.io）。如果你的账户位于欧盟区域，请将 HONEYBADGER_API_URL 设为 https://eu-app.honeybadger.io，并使用欧盟用户设置中的 API Token。美国 Token 无法通过欧盟区域的身份验证，反之亦然。

例如，使用 Claude Code：

claude mcp add honeybadger-eu -- docker run -i --rm -e HONEYBADGER_PERSONAL_AUTH_TOKEN="your_eu_token" -e HONEYBADGER_API_URL="https://eu-app.honeybadger.io" ghcr.io/honeybadger-io/honeybadger-mcp-server:1.5.1

若要同时使用两个区域，请运行两个使用不同名称的服务（例如 honeybadger-us 和 honeybadger-eu），并分别使用各自的 Token 和 API URL。

命令行选项

通过 CLI 运行服务时，可以使用命令行标志进行配置：

# Run with custom configuration
./honeybadger-mcp-server stdio --auth-token your_token --log-level debug --api-url https://custom.honeybadger.io

# Enable write operations (use with caution)
./honeybadger-mcp-server stdio --auth-token your_token --read-only=false

# Get help
./honeybadger-mcp-server stdio --help

--read-only 标志默认为 true。将其设为 --read-only=false，即可启用 create_project、update_project 和 delete_project 等写入操作。

配置文件

你也可以使用位于 ~/.honeybadger-mcp-server.yaml 的配置文件：

auth-token: "your_token_here"
log-level: "info"
api-url: "https://app.honeybadger.io"
read-only: true

升级到 v3 Data API

此版本使用 Honeybadger 的 v3 Data API。如果要升级：

• 凭据：请使用 API Token（hbu_ 或 hba_；较早的个人 hbt_ Token 仍然有效）。旧版个人身份验证 Token 已不再有效。请参阅安装。

• 已移除 get_project_report：v3 不提供项目报告。请使用 query_insights 查询相同内容，因为每次错误发生都是项目内部流中的一个 notice 事件。使用 ts 设置时间窗口（例如 P7D），并添加 | filter environment::str == "production" 将结果限定为一个环境：

  旧报告	BadgerQL
  notices_by_class	filter event_type::str == "notice" | stats count() as notices by klass::str as klass | sort notices desc
  notices_by_user	filter event_type::str == "notice" | stats count() as notices by user::str as user | sort notices desc
  notices_per_day	filter event_type::str == "notice" | stats count() as notices by bin(1d) as day | sort day
  notices_by_location	Notice 事件没有 component 或 action。最接近的分组方式是按顶部回溯文件分组：filter event_type::str == "notice" | stats count() as notices by file::str as file | sort notices desc

• v3 无法支持的参数会被拒绝，而不是忽略：account_id（账户信息来自凭据）、list_fault_notices 中的 created_after/created_before、list_streams 中的 query，以及集成的 filter_events、filter_queries、all_sites 和 all_check_ins（现在使用 filters，并将 site_ids/check_in_ids 设为 null）。

工具

删除工具（delete_project、delete_dashboard、delete_alarm、delete_check_in、delete_fault_comment、delete_integration、delete_ingestion_key、delete_site）需要调用两次。第一次调用不会删除任何内容：它会返回将要删除内容的预览和一个 confirm Token。只有再次使用相同参数和该 Token 调用工具时，才会执行删除；该 Token 在 10 分钟后过期，且仅对相同资源和调用者有效。Token 不是一次性的：在过期前，即使用户拒绝了对应的删除操作，该 Token 仍然有效。

参考文档

• get_reference - 返回供 LLM 使用的 Honeybadger 参考文档，按互不重叠的主题组织：badgerql（查询语言）、queries（Insights 查询基础）、charts（可视化视图、chart_config）、dashboards（小组件架构、网格布局）、alarms（trigger_config 架构、状态、模式）和 errors（fault/notice 模型、错误搜索语法）。主题从文档站点获取并缓存在内存中。工具描述会声明所需的主题。
  • topics：要获取的参考主题，例如 ["badgerql", "charts"]。使用 ["all"] 获取全部主题；省略此参数则返回主题索引（字符串数组，可选）

项目

• list_projects - 列出所有 Honeybadger 项目

  • name：精确的项目名称；只返回该项目（字符串，可选）

• get_project - 按 ID 获取单个项目的详细信息

  • id：要获取的项目 ID（字符串，必填）

• create_project - 创建新的 Honeybadger 项目 （需要 read-only=false）

  • name：新项目的名称（字符串，必填）
  • resolve_errors_on_deploy：记录部署时是否将所有未解决的故障标记为已解决（布尔值，可选）
  • disable_public_links：是否允许通过故障详情页面上的按钮公开分享故障详情（布尔值，可选）
  • user_url：一种 URL 格式，例如 'http://example.com/admin/users/[user_id]'，将显示在故障详情页面上（字符串，可选）
  • source_url：一种 URL 格式，例如 'https://gitlab.com/username/reponame/blob/[sha]/[file]#L[line]'，用于将回溯中的代码行链接到 Git 浏览器（字符串，可选）
  • purge_days：数据保留天数（最多为订阅方案允许的天数）（数字，可选）
  • user_search_field：错误上下文中提供的字段，例如 'context.user_email'（字符串，可选）

• update_project - 更新现有的 Honeybadger 项目 （需要 read-only=false）

  • id：要更新的项目 ID（字符串，必填）
  • name：项目名称（字符串，可选）
  • resolve_errors_on_deploy：记录部署时是否将所有未解决的故障标记为已解决（布尔值，可选）
  • disable_public_links：是否允许通过故障详情页面上的按钮公开分享故障详情（布尔值，可选）
  • user_url：一种 URL 格式，例如 'http://example.com/admin/users/[user_id]'，将显示在故障详情页面上（字符串，可选）
  • source_url：一种 URL 格式，例如 'https://gitlab.com/username/reponame/blob/[sha]/[file]#L[line]'，用于将回溯中的代码行链接到 Git 浏览器（字符串，可选）
  • purge_days：数据保留天数（最多为订阅方案允许的天数）（数字，可选）
  • user_search_field：错误上下文中提供的字段，例如 'context.user_email'（字符串，可选）

• delete_project - 删除 Honeybadger 项目 （需要 read-only=false）

  • id：要删除的项目 ID（字符串，必填）
  • confirm：首次调用返回的预览中的确认令牌（字符串，可选）

• get_project_occurrence_counts - 获取所有项目或指定项目的发生次数

  • project_id：要获取其发生次数的指定项目 ID（字符串，可选）
  • period：报告时间范围：'hour'（61 个一分钟区间）、'day'（25 个小时区间）、'week'（8 个日区间）或 'month'（31 个日区间）。默认为 'hour'（字符串，可选）
  • environment：用于筛选结果的环境名称（字符串，可选）

• list_ingestion_keys - 列出项目的 Ingestion Keys：应用使用这些 hbp_ 密钥向 Honeybadger 发送错误和事件，并在客户端配置中将其设为 ingestion_key（旧版客户端中为 api_key）。Ingestion Key 不是机密，不能调用 Data API；调用该 API 需要 API Token。

  • project_id：要列出其 Ingestion Keys 的项目 ID（字符串，必填）

• create_ingestion_key - 为项目创建新的 Ingestion Key；密钥将在响应中返回 （需要 read-only=false）

  • project_id：要在其中创建 Ingestion Key 的项目 ID（字符串，必填）
  • label：便于人类识别的密钥名称（字符串，可选）

• update_ingestion_key - 更新 Ingestion Key 的标签 （需要 read-only=false）

  • project_id：Ingestion Key 所属项目的 ID（字符串，必填）
  • ingestion_key_id：要更新的 Ingestion Key 的 ID（字符串，必填）
  • label：密钥的新标签（字符串，必填）

• delete_ingestion_key - 删除摄取密钥；使用该密钥发送数据的应用将被拒绝 (需要 read-only=false)

  • project_id ：摄取密钥所属项目的 ID（字符串，必填）
  • ingestion_key_id ：要删除的摄取密钥的 ID（字符串，必填）
  • confirm ：首次调用返回的预览中的确认令牌（字符串，可选）

• get_project_integrations - 获取 Honeybadger 项目的集成（渠道）列表

  • project_id ：要获取集成的项目 ID（字符串，必填）

• get_integration - 获取单个通知集成

  • project_id ：集成所属项目的 ID（字符串，必填）
  • integration_id ：集成的 ID（字符串，必填）

• create_integration - 创建通知集成 (需要 read-only=false)

  • project_id ：要在其中创建集成的项目 ID（字符串，必填）
  • type ：集成类型，例如 WebHook、Email、PagerDutyV2 或 Slack。OAuth 类型初始时未连接；用户可通过结果中的 links.web 进行连接，并且这些类型可以从一开始就处于启用状态（字符串，必填）
  • config ：该类型专属设置的 JSON 对象，例如 WebHook 的 {"url": "https://example.com/hook"}（字符串，可选）
  • active、events、rate、threshold、notification_limit、site_ids、check_in_ids、alarm_alert_ids、alarm_ok_ids、included_environments、excluded_environments、filters ：所有类型通用的设置，需作为独立参数传入，而非放在 config 中。filters 是由 {"event", "query"} 对象组成的有序列表（event 可以是 all）。site_ids/check_in_ids 设为 null 表示跟踪所有站点或签到项，包括之后添加的项目（创建时的默认值）；设为 [] 表示不跟踪任何项目，也可设为列表（可选）

• update_integration - 更新通知集成 (需要 read-only=false)

  • project_id、integration_id ：指定要更新的集成（字符串，必填）
  • config 和通用设置与 create_integration 相同；仅修改已提供的设置，且不能更改类型（可选）

• delete_integration - 删除通知集成及其工单 (需要 read-only=false)

  • project_id、integration_id ：指定要删除的集成（字符串，必填）
  • confirm ：首次调用返回的预览中的确认令牌（字符串，可选）

• list_faults - 获取项目的故障列表，可选择筛选和排序。获取 errors 参考主题（通过 get_reference），了解故障/通知模型和 q 搜索语法。

  • project_id ：要获取故障的项目 ID（字符串，必填）
  • q ：用于筛选故障的搜索字符串（字符串，可选）
  • created_after ：筛选此时间之后创建的故障：RFC 3339 时间戳或日期（UTC 午夜）（字符串，可选）
  • occurred_after ：筛选此时间之后发生的故障：RFC 3339 时间戳或日期（UTC 午夜）（字符串，可选）
  • occurred_before ：筛选此时间之前发生的故障：RFC 3339 时间戳或日期（UTC 午夜）（字符串，可选）
  • limit ：返回的故障数量上限（最多 25 条）（数字，可选）
  • order ：按 'recent' 或 'frequent' 排序结果（字符串，可选）
  • page ：分页页码（数字，可选）

• get_fault - 获取项目中特定故障的详细信息

  • project_id ：包含该故障的项目 ID（字符串，必填）
  • fault_id ：要检索的故障 ID（字符串，必填）

• update_fault - 更新故障的已解决、已忽略、受理人或部署时解决状态。仅更改提供的字段。

  • project_id：包含该故障的项目 ID（字符串，必填）
  • fault_id：要更新的故障 ID（字符串，必填）
  • resolved：故障是否已解决（布尔值，可选）
  • ignored：故障是否已忽略（布尔值，可选）
  • assignee_id：要将故障指派给的项目成员的公开 ID；设为 null 可移除当前受理人；省略则保持不变（字符串或 null，可选）
  • resolve_on_deploy：将故障标记为在下次部署时自动解决（布尔值，可选）

• get_fault_counts - 获取项目的故障数量统计，可选筛选条件。通过 get_reference 获取 errors 参考主题，了解 q 搜索语法。

  • project_id：要获取故障数量的项目 ID（字符串，必填）
  • q：用于筛选故障的搜索字符串（字符串，可选）
  • created_after：筛选此时间之后创建的故障：RFC 3339 时间戳或日期（UTC 午夜）（字符串，可选）
  • occurred_after：筛选此时间之后发生的故障：RFC 3339 时间戳或日期（UTC 午夜）（字符串，可选）
  • occurred_before：筛选此时间之前发生的故障：RFC 3339 时间戳或日期（UTC 午夜）（字符串，可选）

• list_fault_notices - 获取特定故障的通知（单个错误事件）列表

  • project_id：包含该故障的项目 ID（字符串，必填）
  • fault_id：要获取通知的故障 ID（字符串，必填）
  • before：较早通知的游标：上一次响应中的 time_series.oldest_cursor（字符串，可选）
  • after：较新通知的游标：上一次响应中的 time_series.newest_cursor（字符串，可选）
  • limit：要返回的通知最大数量（最多 25 个）（数字，可选）

• list_fault_affected_users - 获取受特定故障影响的用户列表及其发生次数。最多返回 500 个用户，无论是否提供 q。

  • project_id：包含该故障的项目 ID（字符串，必填）
  • fault_id：要获取受影响用户的故障 ID（字符串，必填）
  • q：用于筛选受影响用户的搜索字符串（字符串，可选）

故障评论

• list_fault_comments - 列出故障的所有评论，按时间从新到旧排序。

  • project_id ：包含该故障的项目 ID（字符串，必填）
  • fault_id ：故障的 ID（字符串，必填）

• get_fault_comment - 按 ID 获取故障的一条评论。

  • project_id ：包含该故障的项目 ID（字符串，必填）
  • fault_id ：故障的 ID（字符串，必填）
  • comment_id ：评论的 ID（字符串，必填）

• create_fault_comment - 为故障添加评论。

  • project_id ：包含该故障的项目 ID（字符串，必填）
  • fault_id ：故障的 ID（字符串，必填）
  • body ：非空白评论文本（字符串，必填）

• update_fault_comment - 替换现有故障评论的正文。返回存储的评论。

  • project_id ：包含该故障的项目 ID（字符串，必填）
  • fault_id ：故障的 ID（字符串，必填）
  • comment_id ：评论的 ID（字符串，必填）
  • body ：非空白评论文本（字符串，必填）

• delete_fault_comment - 删除故障的现有评论。

  • project_id ：包含该故障的项目 ID（字符串，必填）
  • fault_id ：故障的 ID（字符串，必填）
  • comment_id ：评论的 ID（字符串，必填）
  • confirm ：首次调用返回的预览中的确认令牌（字符串，可选）

创建、更新和删除评论需要写入权限（stdio 模式下使用 --read-only=false，或 HTTP 模式下使用 write 作用域）。使用账户级 API Token（hba_）时，新评论会归属于该令牌的名称；由于只有评论作者才能编辑评论，更新操作会被拒绝并返回 access_denied；删除操作则需要管理项目的权限。

洞察

• query_insights - 对 Insights 数据执行 BadgerQL 查询
  • project_id ：要查询其洞察数据的项目 ID（字符串，必填）
  • query ：要对 Insights 数据执行的 BadgerQL 查询字符串（字符串，必填）
  • ts ：时间范围，可使用 'today'、'week' 等快捷方式或 ISO 8601 时长（例如 'PT3H'）。默认为 PT3H（字符串，可选）
  • timezone ：用于解析时间戳的 IANA 时区标识符（例如 'America/New_York'）（字符串，可选）
  • stream_ids ：将查询限制为特定 Insights 数据流的流 ID 列表。使用 list_streams 查找项目的数据流 ID。省略此项则查询所有数据流（字符串数组，可选）

数据流

• list_streams - 列出项目的 Insights 数据流
  • project_id ：要列出数据流的项目 ID（字符串，必填）

仪表板

• list_dashboards - 列出项目的所有 Insights 仪表板

  • project_id ：要列出仪表板的项目 ID（字符串，必填）

• get_dashboard - 按 ID 获取单个 Insights 仪表板

  • project_id ：仪表板所属项目的 ID（字符串，必填）
  • dashboard_id ：要获取的仪表板 ID（字符串，必填）

• create_dashboard - 创建新的 Insights 仪表板 （需要 read-only=false）

  • project_id ：要在其中创建仪表板的项目 ID（字符串，必填）
  • title ：仪表板的标题（字符串，必填）
  • widgets ：由 widget 对象组成的 JSON 数组。dashboards 参考主题包含完整的 widget 结构和示例。每个 widget 都需要一个 type（insights_vis、alarms、errors、deployments、checkins、uptime），还可选填 grid（{x,y,w,h}）、presentation（{title, subtitle}）和 config（特定于类型的设置）（字符串，必填）
  • default_ts ：仪表板的默认时间范围。ISO 8601 时长（例如 P1D、PT3H）或关键字（today、yesterday、week、month）（字符串，可选）

• update_dashboard - 更新现有 Insights 仪表板 （需要 read-only=false）

  • project_id ：仪表板所属项目的 ID（字符串，必填）
  • dashboard_id ：要更新的仪表板 ID（字符串，必填）
  • title ：新标题（字符串，可选）
  • widgets ：用于替换仪表板 widget 的 JSON 数组；保留每个 widget 的 id 以保持其标识（字符串，可选）
  • default_ts ：仪表板的默认时间范围；空字符串会清除该值（字符串，可选）

  只会更改提供的字段，因此重命名只需提供 title。

• delete_dashboard - 删除 Insights 仪表板 （需要 read-only=false）

  • project_id ：仪表板所属项目的 ID（字符串，必填）
  • dashboard_id ：要删除的仪表板 ID（字符串，必填）
  • confirm ：首次调用返回的预览中的确认令牌（字符串，可选）

警报

• list_alarms - 列出项目的所有 Insights 警报

  • project_id：要列出警报的项目 ID（字符串，必填）

• get_alarm - 按 ID 获取单个 Insights 警报

  • project_id：警报所属项目的 ID（字符串，必填）
  • alarm_id：要获取的警报 ID（字符串，必填）

• create_alarm - 创建新的 Insights 警报 (需要 read-only=false)。首先获取参考主题 alarms、queries 和 badgerql（通过 get_reference），以了解 trigger_config 架构和查询指南。

  • project_id：要在其中创建警报的项目 ID（字符串，必填）
  • name：警报名称（字符串，必填）
  • query：警报的 BadgerQL 查询。警报系统会自动包装查询以统计结果数量（字符串，必填）
  • evaluation_period：警报的评估频率（例如，5m、1h、1d）。最短为 1m（字符串，必填）
  • trigger_config：定义何时触发警报的 JSON 对象，例如 {"type": "alert_result_count", "config": {"operator": "gt", "value": 10}}（字符串，必填）
  • lookback_lag：评估前的延迟时间，以便数据能够到达（例如，1m；若无延迟则为 0s）（字符串，必填）
  • description：警报的可选描述（字符串，可选）
  • stream_ids：要查询的流 ID 的 JSON 数组，至少指定一个；空数组会被拒绝。省略此参数则查询所有当前流（字符串，可选）

• update_alarm - 更新现有的 Insights 警报 (需要 read-only=false)。首先获取参考主题 alarms、queries 和 badgerql（通过 get_reference）。

  • project_id：警报所属项目的 ID（字符串，必填）
  • alarm_id：要更新的警报 ID（字符串，必填）
  • name：警报的新名称（字符串，可选）
  • description：警报的新描述；空字符串会清除描述（字符串，可选）
  • query：新的 BadgerQL 查询（字符串，可选）
  • evaluation_period：新的评估窗口，使用简洁的时长格式，例如 5m 或 1h（字符串，可选）
  • lookback_lag：新的回溯延迟，例如 1m（字符串，可选）
  • stream_ids：替换当前集合的流 ID 的 JSON 数组（至少一个）；null 会将警报重置为查询所有当前流（字符串，可选）
  • trigger_config：替换整个触发器的 JSON 对象，格式与 create_alarm 接受的格式相同（字符串，可选）

  至少提供一个字段。

• delete_alarm - 删除 Insights 警报 (需要 read-only=false)

  • project_id：警报所属项目的 ID（字符串，必填）
  • alarm_id：要删除的警报 ID（字符串，必填）
  • confirm：首次调用返回的预览中的确认令牌（字符串，可选）

• get_alarm_history - 获取 Insights 警报的触发历史

  • project_id：警报所属项目的 ID（字符串，必填）
  • alarm_id：要获取其历史记录的警报 ID（字符串，必填）
  • page：页码，从 1 开始（默认值：1）。每页包含 25 条记录；links.next 非 null 表示还有更多记录（数字，可选）

检查点

• list_check_ins - 列出项目的检查点（cron/计划任务监控）。按分页返回所有检查点

  • project_id：要列出检查点的项目 ID（字符串，必填）

• get_check_in - 根据 ID 获取单个检查点

  • project_id：检查点所属项目的 ID（字符串，必填）
  • check_in_id：要获取的检查点 ID（字符串，必填）

• create_check_in - 为项目创建新的检查点 （需要 read-only=false）

  • project_id：要在其中创建检查点的项目 ID（字符串，必填）
  • name：检查点名称；未命名的检查点会显示其 ID（字符串，可选）
  • schedule_type：计划类型：simple（每隔固定时间报告）或 cron（按 cron 计划报告）（字符串，必填）
  • slug：用于报告检查点的可选 URL 友好标识符，例如 nightly-backups（字符串，可选）
  • report_period：预期的检查点报告频率，例如 1 day、30 minutes。简单计划必填（字符串，可选）
  • grace_period：迟报后触发警报前的宽限时间，例如 5 minutes（字符串，可选）
  • cron_schedule：定义检查点预期报告时间的 Cron 表达式，例如 0 5 * * *。Cron 计划必填（字符串，可选）
  • cron_timezone：Cron 计划的时区（默认为 UTC）（字符串，可选）

• update_check_in - 更新现有检查点；仅更改提供的字段，字段设置后无法清空。创建后无法更改计划类型 （需要 read-only=false）

  • project_id：检查点所属项目的 ID（字符串，必填）
  • check_in_id：要更新的检查点 ID（字符串，必填）
  • name：检查点名称（字符串，可选）
  • slug：用于报告检查点的 URL 友好标识符（字符串，可选）
  • report_period：检查点的预期报告频率。用于简单计划（字符串，可选）
  • grace_period：迟报后触发警报前的宽限时间（字符串，可选）
  • cron_schedule：定义检查点预期报告时间的 Cron 表达式。用于 Cron 计划（字符串，可选）
  • cron_timezone：Cron 计划的时区（字符串，可选）

• delete_check_in - 删除检查点及其报告历史记录 （需要 read-only=false）

  • project_id：检查点所属项目的 ID（字符串，必填）
  • check_in_id：要删除的检查点 ID（字符串，必填）
  • confirm：首次调用返回的预览中的确认令牌（字符串，可选）

• list_check_in_events - 按时间倒序列出检查点历史记录：每次报告、缺失或暂停的记录

  • project_id：检查点所属项目的 ID（字符串，必填）
  • check_in_id：检查点 ID（字符串，必填）
  • limit：返回的事件数量上限，最多 100 个（数字，可选）
  • created_before：向前翻页：原样传入上一次响应中的 next_created_before（数字，可选）

正常运行时间站点

• list_sites - 列出项目的正常运行时间站点及其当前状态

  • project_id：项目 ID（字符串，必填）

• get_site - 获取正常运行时间站点的 URL、检查设置和状态

  • project_id：项目 ID（字符串，必填）
  • site_id：站点 ID，UUID（字符串，必填）

• create_site - 开始监控 URL 的正常运行时间 （需要 read-only=false）

  • project_id：项目 ID（字符串，必填）
  • url：要检查的 URL，以 http:// 或 https:// 开头（字符串，必填）
  • name、frequency（1、2、5 或 15 分钟）、locations（Virginia、Oregon、London、Frankfurt、Singapore；所有位置使用 [] 或 null）、match_type（success、exact、include、exclude、jmespath）、match、request_method、request_body、request_headers、timeout、outage_threshold、validate_ssl、active：检查设置（可选）

• update_site - 更改正常运行时间站点的设置；将设置设为 null 可恢复其默认值 （需要 read-only=false）

  • project_id、site_id（必填），以及 create_site 接受的 url 和任意设置（可选）

• delete_site - 停止监控正常运行时间站点并将其删除 （需要 read-only=false）

  • project_id、site_id（字符串，必填）
  • confirm：首次调用返回的预览中的确认令牌（字符串，可选）

• list_site_outages - 列出站点的故障，按时间从新到旧排列，并显示失败检查的状态和原因

  • project_id、site_id（字符串，必填）
  • limit、created_before：分页参数，与 list_check_in_events 相同（数字，可选）

• list_uptime_checks - 列出站点的单次检查，按时间从新到旧排列：位置、响应状态和持续时间

  • project_id、site_id（字符串，必填）
  • limit、created_before：分页参数，与 list_check_in_events 相同（数字，可选）

部署

• list_deploys - 列出项目的部署，按时间从新到旧排列

  • project_id：项目 ID（字符串，必填）
  • environment：仅列出部署到此环境的记录（字符串，可选）
  • local_username：仅列出以此用户名记录的部署（字符串，可选）
  • limit：返回的部署数量上限，最多为 100（数字，可选）
  • before / after：来自上一个响应的 time_series.oldest_cursor / newest_cursor 的游标（字符串，可选）

• get_deploy - 按 ID 获取部署，例如 deployed 事件或故障的 last_notice_deploy 中提到的部署

  • project_id：项目 ID（字符串，必填）
  • deploy_id：部署 ID（字符串，必填）

工具搜索

• search_tools - 按名称或描述搜索可用的 Honeybadger 工具。调用工具前可使用此功能来查找工具。在只读模式下，只会返回只读工具。
  • query：用于匹配工具名称和描述的搜索词（字符串，必填）

开发

本地开发环境设置

此项目使用 api-go 库与 API 交互。进行本地开发时，需要设置 Go 工作区，以便同时使用这两个仓库。

在同时包含 honeybadger-mcp-server 和 api-go 的父目录中：

# Initialize the workspace (if not already done)
go work init
go work use ./honeybadger-mcp-server
go work use ./api-go

# The go.work file is gitignored and won't be committed

现在，你可以同时处理这两个仓库；对 api-go 的更改会立即反映到 MCP 服务中。

使用依赖项

使用工作区时，Go 会使用本地 api-go 目录，而不是从 GitHub 获取依赖项。不过，go.sum 仍必须包含已发布的 api-go 模块的校验和，以支持：

• CI/CD 构建（这些构建没有工作区）
• 仅克隆此仓库的开发者
• Docker 构建

何时使用 GOWORK=off：

# Update dependencies and go.sum with published module checksums
GOWORK=off go mod tidy

# Install a specific version of a dependency
GOWORK=off go get github.com/some/[email protected]

# Test the build as if no workspace exists (simulates CI/end-user builds)
GOWORK=off go build ./...
GOWORK=off go test ./...

GOWORK=off 标志会临时禁用工作区，确保 go.sum 包含已发布模块的正确校验和。

运行测试

go test ./...

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add my amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

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