内容
# Bugsink MCP 服务器
一款用于与 [Bugsink](https://www.bugsink.com/) 错误跟踪系统交互的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，通过大型语言模型（LLMs）。
该服务器使 [Claude](https://www.anthropic.com/claude)、[Cursor](https://cursor.sh/) 等 AI 助手以及其他兼容 MCP 的工具能够查询和分析 Bugsink 实例中的错误。
> **本项目是 [j-shelfwood/bugsink-mcp](https://github.com/j-shelfwood/bugsink-mcp) 的一个分支**，由 Joris Schelfhout 创建，他构建了原始的 v0.1 / v0.2 服务器（基本读取工具、变异、堆栈跟踪渲染）。所有基础部分的荣誉归于上游。
>
> **分支：** [`7c/bugsink-mcp`](https://github.com/7c/bugsink-mcp) — 添加了用于事件分析的法医层、光标分页、基于类的模块化结构和持续时间速记时间输入。参见下面的[本分支新增内容](#本分支新增内容)。
## 本分支新增内容
从上游的 v0.2.0 版本开始。以下所有内容均为本分支新增。
### v0.4.1 — 并行扫描 + 时间预算（超时修复）
- **并行详细信息获取。** `EventScanner` 现在会分发每个问题的事件详细 HTTP 调用，并具有有界的并发性（默认为 `8`，作为 `concurrency` 参数公开）。通常在 `search_events`、`aggregate_events`、`cross_tabulate`、`histogram`、`sample_events`、`get_project_stats` 上实现 5–10 倍的时钟速度提升。问题仍然按顺序遍历，以保留 `since` 短路。
- **每次调用的时钟时间预算。** 新增 `time_budget_ms` 参数（默认为 `200000` = 200s，大小低于典型的 MCP 客户端超时时间 ~240s）。当预算耗尽时，扫描返回其部分结果，并带有 `stop_reason: "time-budget-exhausted"` 和 `complete: false`，而不是让客户端取消整个调用。结果信封现在包含 `elapsed_ms`。
- **问题感知访问器。** `EventScanner.forEach` 现在传递 `(event, lightweight, issue)`，以便消费者可以直接从 `Issue` 读取问题级字段（`message`、`calculated_type`、`transaction`），而无需深入 `event.data`。新增 `DerivedPathResolver.getWithIssue(event, issue, path)` 助手。
- **stderr 心跳** 每 ~15s 在长时间扫描期间（`scanned=N fetched=M matched=K`）— 在 MCP 服务器日志中可见，以便用户可以查看长时间运行的调用仍在继续。
### v0.4.0 — 批量分析和交叉表格
- **`aggregate_summary`** — 快速聚合，根据 `group_by` 选择三种策略之一：
- *问题字段*（精确，**零事件获取**）：`message`、`calculated_type`、`transaction`、`is_resolved`、`is_muted`
- *轻量级派生*（精确，无详细获取）：`timestamp_hour`、`timestamp_day`、`timestamp_5min`
- *按问题采样*（近似，每个问题 × `digested_event_count` 获取一次）：`tags.*`、`level`、`request.host`、`request.ua_family`。响应声明 `strategy`，并在采样时包含警告。
- **`cross_tabulate`** — 二维分组。 对于每个前 N 个 `group_by` 值，返回前 M 个 `breakdown_by` 值和计数。 单次扫描，同时统计两个轴。
- **`sample_events`** — 将每个匹配的事件投影到一个扁平的字典中，仅包含请求的带点路径字段（比 `search_events` 小约 95% 的有效载荷）。
- **`histogram`** — 数值分桶。 既可以是显式断点 (`[0,100,500,1000,5000,15000]`)，也可以是自动 `bucket_size`。 报告 `null_or_missing`、`min_observed`、`max_observed`，以及开放式溢出。
- **持续时间速记**，用于 `since`/`until` everywhere：`"30s"`、`"30m"`、`"2h"`、`"1d"`、`"1w"` — 解释为 "<duration> ago from now"。ISO-8601 仍然有效。
- `search_events.summary_only` 现默认设置为 **`true`**（轻量级信封；如果为 `false`，则为完整 `data`）。**与 v0.3.0 相比的重大更改**。
### v0.3.0 — 法医 MVP
- **`get_event_full`** — 返回完整的事件 JSON。 接受公共 Sentry `event_id`（32-hex 或带短横线 UUID）或 Bugsink 内部 UUID； 在需要时回退到项目扫描。
- **`search_events`** — 跨问题扫描，带有时间范围、消息、标签、带点路径（`fields`）和自由文本（`query`）过滤器。 使用消息 ≈ `issue.calculated_value` 跳过整个问题。
- **`aggregate_events`** — 在 `event.data` 上精确分组 + 计数。 每个事件获取详细信息。
- **`get_project_stats`** — 窗口内的总数 + 分解，默认为 `group_by` 为 `message`。
- **`BugsinkClient`** 中的光标分页，使用 `iterateIssues` / `iterateEvents` 异步迭代器（上游客户端分页一次）。
- **基于类的模块化重构**：`index.ts` 从 554 行 → 70 行； 工具分为 `src/tools/*`，法医基元分为 `src/forensics/*`（`EventScanner`、`EventAggregator`、`SummaryAggregator`、`EventCrossTabulator`、`EventHistogrammer`、`EventProjector`），共享实用程序分为 `src/utils/*`（`PathResolver`、`EventIdNormalizer`、`TimeRange`、`DerivedPathResolver`、`TimestampBucket`、`UrlHostExtractor`、`UserAgentClassifier`）。
- **OpenAPI 参考** — 完整的 Bugsink API 文档位于 [`docs/BUGSINK-API.md`](docs/BUGSINK-API.md) 中，从实时 `/api/canonical/0/schema/` 规范生成。
### 关于 `aggregate_summary` 的诚实披露
Bugsink 的轻量级 `EventList` 信封 **不** 包含 `data.tags` / `data.message` / `data.level` — 仅包含 `id, event_id, issue, project, timestamp, ingested_at, digested_at, digest_order, grouping`。 因此，在没有服务器端帮助的情况下，真正的快速标签聚合是不可能的。 *按问题采样* 策略是一种可接受的近似值：对于在一个问题内恒定的字段（`level`，通常是 `request.host`）准确，对于高基数每个事件字段（`tags.juh`，`tags.cs`）偏差较大。 响应始终声明 `strategy`，以便调用者知道计数是精确的还是采样的 — 使用 `aggregate_events` 进行精确的标签计数。
## 功能（完整工具列表）
### 读取和总结（来自上游）
- **列出项目 / 团队 / 问题 / 事件 / 版本**
- **获取项目 / 问题 / 事件 / 版本** — 可读的摘要
- **获取堆栈跟踪** — 预渲染的 Markdown
- **测试连接** — 验证 API 连接性
### 变异（来自上游 v0.2）
- **创建 / 更新项目**，**创建 / 更新团队**，**创建版本**
### 法医（本分支新增）
- `get_event_full`、`search_events`、`sample_events`
- `aggregate_events`、`aggregate_summary`、`cross_tabulate`、`histogram`
- `get_project_stats`
参见 [本分支新增内容](#本分支新增内容)，获取每个法医工具的完整描述。
### 自省
- **`get_version`** — 返回运行服务器的 `name`、`version`、`description`、`homepage`、`bugsink_url` 和 `node_version`。 `version` 值在运行时从 `package.json` 读取，因此始终与发布的工件匹配。
> 需要在发出版本敏感的工具调用之前断言特定版本的代理可以检查 `serverInfo.version` 从 MCP `initialize` 响应中获取，或者在会话期间调用 `get_version`。 示例断言：
>
> ```jsonc
> // tools/call → get_version
> { "name": "bugsink-mcp", "version": "0.4.0", ... }
> ```
## 安装
### 通过 npx（推荐）
```bash
npx bugsink-mcp
```
### 全局安装
```bash
npm install -g bugsink-mcp
```
### 从源代码
```bash
git clone https://github.com/7c/bugsink-mcp.git
cd bugsink-mcp
npm install
npm run build
```
> 原始上游仓库：[`j-shelfwood/bugsink-mcp`](https://github.com/j-shelfwood/bugsink-mcp)
## 配置
### 环境变量
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `BUGSINK_URL` | 是 | 您的 Bugsink 实例 URL（例如 `https://error-tracking.example.com`） |
| `BUGSINK_TOKEN` | 是 | 用于身份验证的 API令牌 |
### 生成 API令牌
```bash
# 通过 Bugsink 管理命令
bugsink-manage create_auth_token
```
或通过 Bugsink Web UI 在设置 > API令牌下。
## MCP 客户端配置
### Claude 桌面版
将以下内容添加到您的 Claude 桌面配置（`~/.claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"bugsink": {
"command": "npx",
"args": ["bugsink-mcp"],
"env": {
"BUGSINK_URL": "https://your-bugsink-instance.com",
"BUGSINK_TOKEN": "your-api-token"
}
}
}
}
```
### Claude 代码 CLI
```bash
claude mcp add bugsink -- npx bugsink-mcp
```
然后在您的 shell 或 `.env` 文件中设置环境变量。
### Cursor
将以下内容添加到您的 Cursor MCP 设置：
```json
{
"mcpServers": {
"bugsink": {
"command": "npx",
"args": ["bugsink-mcp"],
"env": {
"BUGSINK_URL": "https://your-bugsink-instance.com",
"BUGSINK_TOKEN": "your-api-token"
}
}
}
}
```
## 可用工具
### `test_connection`
测试与您的 Bugsink 实例的连接。
### `list_projects`
列出 Bugsink 实例中的所有项目。
### `get_project`
获取特定项目的详细信息，包括 DSN。
**参数：**
- `project_id`（数字，必需）：项目 ID
### `list_teams`
列出 Bugsink 实例中的所有团队。
### `list_issues`
列出特定项目的 问题。
**参数：**
- `project_id`（数字，必需）：项目 ID
- `status`（字符串，可选）：按状态过滤（'unresolved', 'resolved', 'muted'）
- `limit`（数字，可选）：最大结果数（默认：25）
### `get_issue`
获取特定问题的详细信息。
**参数：**
- `issue_id`（数字，必需）：问题 ID
### `list_events`
列出特定问题的事件（个别错误发生）。
**参数：**
- `issue_id`（数字，必需）：问题 ID
- `limit`（数字，可选）：最大结果数（默认：10）
### `get_event`
人类可读的事件摘要，包括堆栈跟踪、标签、上下文。
**参数：**
- `event_id`（字符串，必需）：Bugsink 内部事件 UUID
### `get_event_full`
返回完整的事件 JSON（原始 `data` 负载 + Bugsink 信封）。 接受公共 Sentry `event_id`（32-hex 或带短横线）或 Bugsink 内部 UUID。
**参数：**
- `event_id`（字符串，必需）：公共 Sentry ID 或 Bugsink 内部 UUID
- `project_id`（数字，可选）：将备用扫描限制在单个项目内
- `max_scanned`（数字，可选，默认 5000）：备用扫描期间检查的事件上限
### `search_events`
跨问题事件扫描，带有过滤器。 每个匹配项返回完整的事件 JSON。
**参数：**
- `project_id`（数字，必需）
- `since` / `until`（ISO-8601 字符串，可选）：时间窗口
- `message`（对象，可选）：`{value, exact?, case_sensitive?}` — 也在 `data.message` ≈ `issue.calculated_value` 时短路问题迭代
- `tags`（对象，可选）：`data.tags` 上的相等过滤器，组合使用 AND
- `fields`（对象，可选）：`data` 上的带点路径相等过滤器（例如 `{"extra.diag.env.dnt":"true"}`)
- `query`（字符串，可选）：跨 JSON 序列化 `data` 的不区分大小写的子字符串搜索
- `summary_only`（布尔值，可选，默认 false）：跳过获取完整的 `data`，仅返回轻量级信封
- `limit`（数字，可选，默认 50，最大 500）：最大匹配事件数
- `max_fetched`（数字，可选，默认 500，最大 5000）：每次调用的最大完整事件获取数
- `max_scanned`（数字，可选，默认 5000，最大 50000）：每次调用检查的轻量级事件最大数量
### `aggregate_events`
在 `event.data` 上进行分组 + 计数。 按降序排列。
**参数：**
- `project_id`（数字，必需）
- `group_by`（字符串，必需）：带点路径（例如 `tags.page_host`、`extra.diag.timing.protocol`、`request.headers.User-Agent`、`level`）
- `since`、`until`、`message`、`tags`、`fields`、`query` — 与 `search_events` 相同
- `top_n`（数字，可选，默认 20，最大 500）
- `max_fetched`（数字，可选，默认 2000）
- `max_scanned`（数字，可选，默认 5000）
### `get_project_stats`
事件总数 + 按窗口分组计数。 适用于发送-vs-到达健全性检查。
**参数：**
- `project_id`（数字，必需）
- `since`、`until`、`message`、`tags`、`fields` — 与 `search_events` 相同
- `group_by`（字符串，可选，默认 `"message"`）：`event.data` 上的带点路径
- `max_fetched`（数字，可选，默认 5000），`max_scanned`（数字，可选，默认 20000）
## 示例用法
配置完成后，您可以询问您的 AI 助手：
- "列出 Bugsink 中的所有项目"
- "显示项目 1 的最新问题"
- "问题 #42 的堆栈跟踪是什么？"
- "获取最近的错误事件的详细信息"
- **法医：** "显示项目 2 中 `bad_xhr_status` 事件的前 20 个 `page_hosts`，过去 24 小时内"
- **法医：** "给我事件 ID `e1807dca09774e30b9c6c98b4eb96267` 项目 2 的完整有效载荷"
- **法医：** "项目 2 上 17:00 和 18:00 UTC 之间到达了多少事件，按消息分组？"
## 开发
```bash
# 安装依赖
npm install
# 以开发模式运行
npm run dev
# 构建生产版本
npm run build
# 运行测试
npm test
```
## API 兼容性
该服务器专为 [Bugsink](https://www.bugsink.com/) 设计，这是一个自托管的错误跟踪平台。 Bugsink 使用其自己的 REST API (`/api/canonical/0/`)，与 Sentry 的 API 不同。
**注意：** 该服务器 **不** 适用于 Sentry 或 Sentry 托管的服务。 对于 Sentry，请使用官方的 [sentry-mcp](https://github.com/getsentry/sentry-mcp) 服务器。
## 许可证
MIT — 与上游相同。
## 致谢
- **上游 / 原始作者：** [Joris Schelfhout](https://github.com/j-shelfwood) — [`j-shelfwood/bugsink-mcp`](https://github.com/j-shelfwood/bugsink-mcp)。 构建了原始的 MCP 服务器（v0.1） 和变异工具（v0.2）。 感谢基础部分。
- **分支维护者：** [`7c/bugsink-mcp`](https://github.com/7c/bugsink-mcp) — 法医层（v0.3 / v0.4）、光标分页、基于类的模块化结构。
## 贡献
对于此分支特有的功能（法医、聚合等），请在 [`7c/bugsink-mcp`](https://github.com/7c/bugsink-mcp) 上打开问题或 PR。
对于应流向上游的底层客户端 / 变异工具更改，请考虑在 [`j-shelfwood/bugsink-mcp`](https://github.com/j-shelfwood/bugsink-mcp) 上打开 PR。
