airbrake-mcp 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/CHANGELOG.md +199 -1
  2. package/README.md +150 -29
  3. package/dist/client/airbrake.d.ts +16 -0
  4. package/dist/client/airbrake.js +133 -76
  5. package/dist/client/airbrake.js.map +1 -1
  6. package/dist/client/errors.d.ts +2 -2
  7. package/dist/client/errors.js +9 -4
  8. package/dist/client/errors.js.map +1 -1
  9. package/dist/client/pagination.d.ts +20 -0
  10. package/dist/client/pagination.js +42 -4
  11. package/dist/client/pagination.js.map +1 -1
  12. package/dist/client/read-only-guard.d.ts +8 -0
  13. package/dist/client/read-only-guard.js +28 -0
  14. package/dist/client/read-only-guard.js.map +1 -0
  15. package/dist/client/retry-policy.d.ts +31 -0
  16. package/dist/client/retry-policy.js +76 -0
  17. package/dist/client/retry-policy.js.map +1 -0
  18. package/dist/config.d.ts +2 -0
  19. package/dist/config.js +15 -0
  20. package/dist/config.js.map +1 -1
  21. package/dist/server.d.ts +3 -2
  22. package/dist/server.js +105 -39
  23. package/dist/server.js.map +1 -1
  24. package/dist/tools/delete.d.ts +13 -0
  25. package/dist/tools/delete.js +41 -0
  26. package/dist/tools/delete.js.map +1 -0
  27. package/dist/tools/deploys-create.d.ts +8 -0
  28. package/dist/tools/deploys-create.js +30 -0
  29. package/dist/tools/deploys-create.js.map +1 -0
  30. package/dist/tools/deploys.d.ts +4 -34
  31. package/dist/tools/deploys.js +16 -25
  32. package/dist/tools/deploys.js.map +1 -1
  33. package/dist/tools/fields.d.ts +21 -0
  34. package/dist/tools/fields.js +48 -0
  35. package/dist/tools/fields.js.map +1 -0
  36. package/dist/tools/groups-update.d.ts +14 -0
  37. package/dist/tools/groups-update.js +37 -0
  38. package/dist/tools/groups-update.js.map +1 -0
  39. package/dist/tools/groups.d.ts +19 -126
  40. package/dist/tools/groups.js +113 -40
  41. package/dist/tools/groups.js.map +1 -1
  42. package/dist/tools/index.d.ts +1 -0
  43. package/dist/tools/index.js +19 -1
  44. package/dist/tools/index.js.map +1 -1
  45. package/dist/tools/moved-actions.d.ts +7 -0
  46. package/dist/tools/moved-actions.js +18 -0
  47. package/dist/tools/moved-actions.js.map +1 -0
  48. package/dist/tools/notices.d.ts +6 -38
  49. package/dist/tools/notices.js +19 -19
  50. package/dist/tools/notices.js.map +1 -1
  51. package/dist/tools/notify.d.ts +4 -24
  52. package/dist/tools/notify.js +12 -3
  53. package/dist/tools/notify.js.map +1 -1
  54. package/dist/tools/performance.d.ts +19 -66
  55. package/dist/tools/performance.js +11 -10
  56. package/dist/tools/performance.js.map +1 -1
  57. package/dist/tools/projects.d.ts +6 -30
  58. package/dist/tools/projects.js +13 -12
  59. package/dist/tools/projects.js.map +1 -1
  60. package/dist/tools/read-only.d.ts +9 -0
  61. package/dist/tools/read-only.js +14 -0
  62. package/dist/tools/read-only.js.map +1 -0
  63. package/dist/tools/request.d.ts +34 -20
  64. package/dist/tools/request.js +60 -15
  65. package/dist/tools/request.js.map +1 -1
  66. package/dist/tools/schemas.d.ts +34 -0
  67. package/dist/tools/schemas.js +41 -0
  68. package/dist/tools/schemas.js.map +1 -0
  69. package/dist/tools/sourcemap-file.d.ts +27 -0
  70. package/dist/tools/sourcemap-file.js +180 -0
  71. package/dist/tools/sourcemap-file.js.map +1 -0
  72. package/dist/tools/sourcemaps-upload.d.ts +25 -0
  73. package/dist/tools/sourcemaps-upload.js +68 -0
  74. package/dist/tools/sourcemaps-upload.js.map +1 -0
  75. package/dist/tools/sourcemaps.d.ts +4 -34
  76. package/dist/tools/sourcemaps.js +18 -21
  77. package/dist/tools/sourcemaps.js.map +1 -1
  78. package/dist/tools/types.d.ts +14 -1
  79. package/package.json +10 -6
package/CHANGELOG.md CHANGED
@@ -7,6 +7,202 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.2.0] — 2026-11-18
11
+
12
+ **Breaking:** write and destructive actions moved to dedicated tools (12
13
+ tools, was 8) so each tool carries accurate MCP annotations; the HTTP
14
+ requests are unchanged. See **Changed** below and the README section
15
+ "Migrating from 0.1.x". Also new: `AIRBRAKE_READ_ONLY` mode, source-map
16
+ upload, `has_more`/`next_page` pagination, `fields` projection, zod 4, and
17
+ safer retries (non-idempotent requests are never re-sent after an ambiguous
18
+ failure).
19
+
20
+ ### Added
21
+
22
+ - `airbrake_groups` `get_stats` accepts an optional `limit` (1–1000;
23
+ Airbrake defaults to 100), sent only when given.
24
+ - `_pagination` on list results now reports `has_more` and, when true,
25
+ `next_page`, so the model no longer has to do arithmetic to decide whether
26
+ to fetch another page. When Airbrake returns `count`, `has_more` compares
27
+ the items actually served so far against it (so a page capped below
28
+ `per_page` still reports more) and `total_pages` is added. When `count` is
29
+ absent (or not a finite, non-negative number), `has_more` is inferred from
30
+ the length of the primary list and flagged with
31
+ `has_more_is_estimate: true`; if there is no list either, the fields are
32
+ omitted. Existing `page`/`per_page`/`count` fields are unchanged.
33
+ - Optional `fields` (1–50 non-empty key names) on every list-type action —
34
+ `airbrake_projects` `list`/`list_activities`, `airbrake_groups` `list`,
35
+ `airbrake_notices` `list`, `airbrake_deploys` `list`,
36
+ `airbrake_sourcemaps` `list`. Each item of every top-level array in the
37
+ payload is reduced to those top-level keys; `count`, `_pagination` and
38
+ other non-array properties are untouched. Omitting `fields` keeps the raw
39
+ payload.
40
+ - **`airbrake_sourcemaps_upload` tool.** Uploads a local source map
41
+ (`file_path`, `name`, optional `pattern`) as multipart/form-data — no more
42
+ hand-building a multipart string for `airbrake_request`. Before any HTTP
43
+ request, `file_path` must be absolute (no Windows UNC/device paths) and
44
+ end in `.map`, and must resolve (symlinks followed) to a regular `*.map`
45
+ file of at most 50 MiB whose content is a source map v3; `name`/`pattern`
46
+ are trimmed and must be non-empty, ≤ 2048 chars and free of CR/LF. This
47
+ stops a prompt-injected model from exfiltrating arbitrary local files.
48
+ Upload attempts get a timeout of at least 55 s. Like every `POST`, an
49
+ upload is never re-sent after a network error, timeout or 5xx (only 429
50
+ and connection failures before sending are retried), so a lost response
51
+ cannot create a duplicate map; such errors say the request may have been
52
+ applied, and the tool description says to check `list` first.
53
+ - HTTP client request options: a `FormData` body is passed to `fetch` as-is
54
+ (fetch sets the multipart boundary, any caller content-type is dropped)
55
+ and re-sent in full on retries; `minTimeoutMs` raises the per-attempt
56
+ timeout for one request.
57
+ - **MCP tool annotations.** Every tool now advertises a `title` and
58
+ `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
59
+ `openWorldHint`) in `tools/list`, so clients can auto-approve reads and
60
+ flag destructive calls. See the annotation table in the README.
61
+ - **`AIRBRAKE_READ_ONLY` read-only mode.** `1`/`true`/`yes` (case-insensitive)
62
+ hides `airbrake_groups_update`, `airbrake_deploys_create`,
63
+ `airbrake_sourcemaps_upload`, `airbrake_notify` and `airbrake_delete` from `tools/list` and refuses calls to them in the
64
+ call handler without any HTTP request. `airbrake_request` stays available
65
+ but GET-only (advertised `method` enum `["GET"]`, no `body`; write
66
+ methods and bodies are rejected before any HTTP; annotations become
67
+ read-only). As a backstop below every tool, the HTTP client refuses
68
+ anything but a plain GET in read-only mode, including method-override
69
+ headers and a `_method` query parameter (in `query` or embedded in `path`).
70
+ Calling a moved action on a read tool says its replacement is disabled.
71
+ A one-line notice is written to stderr at startup. Values other than `1/true/yes/0/false/no/""`
72
+ fail startup.
73
+ - New tools `airbrake_groups_update`, `airbrake_deploys_create` and
74
+ `airbrake_delete` (see **Changed**), and `airbrake_sourcemaps_upload`
75
+ (see the source-map upload entry).
76
+
77
+ ### Changed
78
+
79
+ - CI's dependency audit is now `scripts/audit.mjs` (`npm run audit:ci`) instead
80
+ of `npm audit --audit-level=high`. It still fails on every high/critical
81
+ advisory, except those with a reviewed entry in `audit-allowlist.json`. Each
82
+ entry is scoped (`dev` entries can never cover a runtime finding), must name
83
+ the reported package, carries a reason, and must expire within 180 days for
84
+ `dev` or 90 for `runtime`. Expired and stale entries also fail. It audits
85
+ the lockfile only, in its own CI job before any install; `release.yml` runs
86
+ it before `npm ci`. Dev, optional and peer dependencies are always included.
87
+ The only entry is `picomatch` GHSA-fc5q-39xc-vjpf (dev-only, no upstream
88
+ fix; expires 2027-02-17); the `zod` advisory is fixed by the zod 4
89
+ migration (see the zod 4 entry).
90
+ - CI now runs `npm run test:coverage` (new script, `vitest run --coverage`)
91
+ instead of `npm test`, so the coverage thresholds declared in
92
+ `vitest.config.ts` (lines/functions/statements 85%, branches 80%) are
93
+ actually enforced. Added `@vitest/coverage-v8` as a dev dependency, on the
94
+ same `^4.1.12` range as `vitest` (it requires an exact-match `vitest` peer,
95
+ so the two must be bumped together). `src/bin.ts` is excluded from unit
96
+ coverage — it is exercised by the e2e suite. The lcov report is uploaded as
97
+ a CI artifact from the Node 22 leg.
98
+ - Internal: shared schema module (`src/tools/schemas.ts`) replaces per-tool
99
+ copies of the ID, pagination and time-range schemas; no behaviour change.
100
+ - Migrated from `zod` 3 to `zod` 4 (`^4.6.7`) and dropped the
101
+ `zod-to-json-schema` dependency: tool input schemas are now generated with
102
+ zod 4's native `z.toJSONSchema` (draft-07, input types, everything
103
+ inlined). The `tools/list` output is semantically unchanged — same tools,
104
+ descriptions, properties, `action` enums and `required` sets.
105
+ - Tool argument validation errors are now short, readable text instead of a
106
+ JSON dump of zod issues, e.g.
107
+ `Invalid arguments for airbrake_groups:\n✖ Invalid input: expected string, received number\n → at group_id`.
108
+ Clients that parsed the old JSON error array should match on the text
109
+ instead.
110
+ - Tool results are now serialised as compact JSON (no indentation), cutting
111
+ ~38% of the bytes of every response. Error texts are unchanged.
112
+ - `airbrake_notices` `list` now defaults to `per_page: 10` (was 50; max is
113
+ still 200) since every notice carries a full backtrace/context/params.
114
+ Pass `per_page` explicitly to get the old page size.
115
+ - **BREAKING:** write and destructive actions moved out of the resource
116
+ tools into dedicated tools so that each tool's annotations are accurate.
117
+ The HTTP requests sent are unchanged.
118
+ - `airbrake_groups` `mute` / `unmute` / `resolve` / `unresolve` →
119
+ `airbrake_groups_update` (same arguments).
120
+ - `airbrake_groups` `delete` → `airbrake_delete` with `resource: "group"`.
121
+ - `airbrake_sourcemaps` `delete` → `airbrake_delete` with
122
+ `resource: "sourcemap"`.
123
+ - `airbrake_deploys` `create` → `airbrake_deploys_create` (`project_id` +
124
+ `deploy`, no `action`).
125
+ - `airbrake_groups`, `airbrake_deploys` and `airbrake_sourcemaps` are now
126
+ read-only; calling a removed action returns an error naming its
127
+ replacement.
128
+ - The server now exposes 12 tools (was 8).
129
+
130
+ ### Fixed
131
+
132
+ - **`AIRBRAKE_TIMEOUT_MS` now covers the response body.** The timeout was
133
+ cleared as soon as response headers arrived, so a server that sent headers
134
+ and then stalled mid-body hung the tool call forever. The deadline now
135
+ spans the whole attempt (connect, headers and full body read) and the timer
136
+ is cleared on every path. A timeout or connection failure while reading the
137
+ body is reported as an `AirbrakeNetworkError` (previously an
138
+ `AirbrakeApiError` carrying the HTTP status) that still names the status,
139
+ and follows the same retry policy as any other network error (see the
140
+ next entry). Timeout messages now state the
141
+ duration, e.g. `request timed out after 15000ms` or
142
+ `request timed out after 15000ms while reading the HTTP 200 response body`.
143
+ The unread body of a 429/5xx response that is about to be retried is now
144
+ cancelled, which releases its connection. The 25 MB body cap is unchanged
145
+ and still surfaces as an `AirbrakeApiError`.
146
+ - **Duplicate side effects from retried non-idempotent requests.** The client
147
+ retried every method on 5xx responses and network errors/timeouts, so a
148
+ `POST` that the server had already processed (e.g. `airbrake_notify`,
149
+ `airbrake_deploys` `create` (now `airbrake_deploys_create`), or a `POST` via
150
+ `airbrake_request`) could be
151
+ sent again, creating duplicate notices or deploy markers. A retried `DELETE`
152
+ whose first response was lost would get a 404 and report failure for an
153
+ operation that had succeeded. 5xx responses, dropped connections and
154
+ timeouts (including `AIRBRAKE_TIMEOUT_MS`, and failures while reading the
155
+ response body) are now retried only for `GET`,
156
+ `HEAD` and `PUT`; `POST`, `PATCH` and `DELETE` fail immediately, with an
157
+ error message noting that the request may have been applied. Requests the
158
+ server never processed are still retried for every method:
159
+ `429 Too Many Requests` (honouring `Retry-After`) and connection failures
160
+ before anything was sent (`ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`, undici's
161
+ connect timeout, and `ENETUNREACH`/`EHOSTUNREACH`/`ETIMEDOUT` raised by
162
+ `connect`). If the connection retries run out, the error says the request
163
+ was not sent.
164
+ - `airbrake_groups` `get_stats` now matches Airbrake's documented contract:
165
+ `time__lt` is optional (omitted from the request so Airbrake defaults it
166
+ to now), and `time__gte` / `time__lt` accept Unix seconds (non-negative
167
+ integer, as in the docs, or a digit-only string) as well as ISO 8601
168
+ strings. Values are
169
+ forwarded verbatim. Malformed timestamps (e.g. `"yesterday"`,
170
+ `2026-02-30`), negative/fractional/millisecond numbers, and ranges where
171
+ `time__gte >= time__lt` are rejected before any HTTP request (offset-less
172
+ times are read as UTC for that check). Note: strings were previously
173
+ forwarded unvalidated; anything that is not an ISO 8601 / RFC 3339 date
174
+ or date-time is now rejected.
175
+ - List actions no longer throw when Airbrake answers with an empty body or
176
+ 204: the `null` payload is returned as-is.
177
+
178
+ ### Security
179
+
180
+ - Raised the `@modelcontextprotocol/sdk` floor from `^1.0.0` to `^1.32.0`
181
+ (lockfile: 1.29.0 → 1.32.2) and refreshed the lockfile via `npm audit fix`
182
+ to remediate: `@modelcontextprotocol/sdk` (GHSA-6qxp-vccf-f47h,
183
+ GHSA-22jm-h49p-29qw, GHSA-46jr-4wx8-v453, GHSA-rvq5-wwqv-78pq,
184
+ GHSA-f897-62hf-6gxq, GHSA-6prh-2h8m-c8cw — HTTP/OAuth transports, not
185
+ used by this stdio-only server) and its transitive `@hono/node-server`,
186
+ `hono`, `body-parser`, `proxy-addr`, `qs`, `fast-uri` and `ip-address`
187
+ advisories; plus dev-toolchain advisories in `vitest`/`@vitest/mocker`
188
+ (GHSA-82fw-gwwq-j7x9, GHSA-qxg6-89mg-rqv8), `vite`, `postcss`,
189
+ `source-map-js`, `nanoid`, `js-yaml`, `minimatch` and `brace-expansion`.
190
+ The `vitest` floor is raised to `^4.1.12` (patched release). Still open:
191
+ `picomatch` GHSA-fc5q-39xc-vjpf (dev-only, no upstream patch yet).
192
+ - Upgrading to `zod` 4.6.7 also remediates GHSA-mrhx-c7xc-m3w5 (memory
193
+ exhaustion while validating oversized constrained collections, zod
194
+ `<4.6.6`, high); its `audit-allowlist.json` entry is removed.
195
+
196
+ ## [0.1.3] — 2026-06-04
197
+
198
+ ### Security
199
+
200
+ - Bumped `vitest` from 2.1.9 to 4.1.0 (dev dependency) to remediate a
201
+ critical advisory in the Vitest UI server (GHSA-5xrq-8626-4rwp) and the
202
+ related moderate `esbuild`/`vite` advisories (GHSA-67mh-4wv8-2f99). This
203
+ is a dev/CI toolchain change only — the published package has no runtime
204
+ changes from 0.1.2.
205
+
10
206
  ## [0.1.2] — 2026-05-26
11
207
 
12
208
  ### Security
@@ -95,7 +291,9 @@ API tokens (and therefore not modeled), and for endpoints we expose that
95
291
  aren't in Airbrake's public docs (live-verified working on hosted
96
292
  Airbrake but not part of the public contract).
97
293
 
98
- [Unreleased]: https://github.com/francktrouillez/airbrake-mcp/compare/v0.1.2...HEAD
294
+ [Unreleased]: https://github.com/francktrouillez/airbrake-mcp/compare/v0.2.0...HEAD
295
+ [0.2.0]: https://github.com/francktrouillez/airbrake-mcp/releases/tag/v0.2.0
296
+ [0.1.3]: https://github.com/francktrouillez/airbrake-mcp/releases/tag/v0.1.3
99
297
  [0.1.2]: https://github.com/francktrouillez/airbrake-mcp/releases/tag/v0.1.2
100
298
  [0.1.1]: https://github.com/francktrouillez/airbrake-mcp/releases/tag/v0.1.1
101
299
  [0.1.0]: https://github.com/francktrouillez/airbrake-mcp/releases/tag/v0.1.0
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  An MCP (Model Context Protocol) server that exposes the Airbrake public API to LLM clients. Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Cline, Codex CLI, Continue.dev, etc.).
9
9
 
10
- Eight resource-grouped tools cover what hosted Airbrake actually exposes (projects, error groups, notices, deploys, v5 APM, source maps, the v3 Notifier), plus a generic `airbrake_request` escape hatch for endpoints not directly modeled — including project-key endpoints and multipart uploads.
10
+ Twelve tools cover what hosted Airbrake actually exposes (projects, error groups, notices, deploys, v5 APM, source maps, the v3 Notifier), plus a generic `airbrake_request` escape hatch for endpoints not directly modeled — including project-key endpoints and multipart uploads. Tools are split by side effect and carry MCP [tool annotations](#tool-annotations), so clients can auto-approve reads and flag deletes; an optional [read-only mode](#read-only-mode) hides every write.
11
11
 
12
12
  **Unofficial. Not affiliated with or endorsed by Airbrake.**
13
13
 
@@ -41,13 +41,14 @@ It will wait for JSON-RPC messages on stdin. Useful for debugging the install on
41
41
 
42
42
  All configuration is via environment variables.
43
43
 
44
- | Var | Required | Default | Purpose |
45
- |---|---|---|---|
46
- | `AIRBRAKE_USER_TOKEN` | yes (except for notify-only setups) | — | Bearer token for the management API |
47
- | `AIRBRAKE_PROJECT_KEYS` | only for `airbrake_notify` | — | JSON map `{"123":"notifier_key"}` |
48
- | `AIRBRAKE_HOST` | no | `https://api.airbrake.io` | Override for self-hosted Airbrake or Errbit |
49
- | `AIRBRAKE_TIMEOUT_MS` | no | `15000` | Per-request timeout |
50
- | `AIRBRAKE_MAX_RETRIES` | no | `2` | Retries on 429 and 5xx |
44
+ | Var | Required | Default | Purpose |
45
+ | ----------------------- | ----------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
46
+ | `AIRBRAKE_USER_TOKEN` | yes (except for notify-only setups) | — | Bearer token for the management API |
47
+ | `AIRBRAKE_PROJECT_KEYS` | only for `airbrake_notify` | — | JSON map `{"123":"notifier_key"}` |
48
+ | `AIRBRAKE_HOST` | no | `https://api.airbrake.io` | Override for self-hosted Airbrake or Errbit |
49
+ | `AIRBRAKE_TIMEOUT_MS` | no | `15000` | Per-request timeout in ms (including the response body read); applies to each retry attempt |
50
+ | `AIRBRAKE_MAX_RETRIES` | no | `2` | Retries on 429 and failed connections (all methods), and on 5xx/network errors/timeouts for GET/HEAD/PUT only |
51
+ | `AIRBRAKE_READ_ONLY` | no | off | `1`/`true`/`yes` enables [read-only mode](#read-only-mode); `0`/`false`/`no`/empty disables it (case-insensitive). Any other value is a startup error. |
51
52
 
52
53
  Get a User API token from Airbrake → User Settings → Personal API tokens.
53
54
 
@@ -71,14 +72,14 @@ The MCP entry below is the same for every MCP client — only the config file lo
71
72
 
72
73
  Where to put it, by client:
73
74
 
74
- | Client | Location |
75
- |---|---|
76
- | **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
77
- | **Claude Code** | `~/.claude.json` — or use `claude mcp add airbrake --scope user --env AIRBRAKE_USER_TOKEN=… -- npx -y airbrake-mcp` |
78
- | **Cursor** | `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (user-wide) |
79
- | **Cline (VS Code)** | VS Code Settings → Cline → MCP servers (UI), or `cline_mcp_settings.json` |
80
- | **Codex CLI** | `~/.codex/config.json` under `mcpServers` |
81
- | **Continue.dev** | `.continue/config.json` under `experimental.modelContextProtocolServers` |
75
+ | Client | Location |
76
+ | -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
77
+ | **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
78
+ | **Claude Code** | `~/.claude.json` — or use `claude mcp add airbrake --scope user --env AIRBRAKE_USER_TOKEN=… -- npx -y airbrake-mcp` |
79
+ | **Cursor** | `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (user-wide) |
80
+ | **Cline (VS Code)** | VS Code Settings → Cline → MCP servers (UI), or `cline_mcp_settings.json` |
81
+ | **Codex CLI** | `~/.codex/config.json` under `mcpServers` |
82
+ | **Continue.dev** | `.continue/config.json` under `experimental.modelContextProtocolServers` |
82
83
 
83
84
  To enable the notifier (sending errors TO Airbrake), add the project keys map:
84
85
 
@@ -99,18 +100,79 @@ To enable the notifier (sending errors TO Airbrake), add the project keys map:
99
100
 
100
101
  ## Tools
101
102
 
102
- | Tool | Actions | Notes |
103
- |---|---|---|
104
- | `airbrake_projects` | `list`, `get`, `list_activities` | Project updates are not modeled — see the caveat below. |
105
- | `airbrake_groups` | `list`, `get`, `get_stats`, `mute`, `unmute`, `resolve`, `unresolve`, `delete` | `list` supports `environment`, `resolved`, `muted`, `archived`, `deploy_id`, `start_time`, `end_time`, `order`, `query`. `get_stats` (v5) requires `time__gte`/`time__lt`/`period`. `resolve`/`unresolve` follow the documented mute PUT convention; fall back to `airbrake_request` if your instance disagrees. |
106
- | `airbrake_notices` | `list`, `get`, `get_status` | `list` and `get_status` are documented; `get` calls an undocumented endpoint that currently works on hosted Airbrake. |
107
- | `airbrake_deploys` | `list`, `get`, `create` | All documented. |
108
- | `airbrake_performance` | `routes_stats`, `queries_stats`, `queues_stats` | v5 APM. All actions require `time__gte`/`time__lt`/`period` (`minute`\|`hour`\|`day`). **`queries_stats` additionally requires a `route` filter** and **`queues_stats` additionally requires a `queue` filter** — the server returns 400 without them. The GET (read) side of these endpoints is not in Airbrake's public docs (which only show the PUT ingest side) but is live-verified working on hosted Airbrake. `routes-breakdowns` is intentionally not modeled (PUT-only SDK endpoint). |
109
- | `airbrake_notify` | `notify` | Sends errors TO Airbrake (v3 Notifier API). |
110
- | `airbrake_sourcemaps` | `list`, `get`, `delete` | Upload is multipart/form-data — use `airbrake_request` with a pre-formed multipart body. |
111
- | `airbrake_request` | `request` | Escape hatch for any endpoint. Supports `auth: 'none'` (project-key endpoints), raw string bodies (multipart), arbitrary headers and query. |
103
+ | Tool | Actions | Notes |
104
+ | ---------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
105
+ | `airbrake_projects` | `list`, `get`, `list_activities` | Read-only. Project updates are not modeled — see the caveat below. |
106
+ | `airbrake_groups` | `list`, `get`, `get_stats` | Read-only. `list` supports `environment`, `resolved`, `muted`, `archived`, `deploy_id`, `start_time`, `end_time`, `order`, `query`. `get_stats` (v5) requires `time__gte` and `period` (`minute`/`hour`; `day` is also accepted by the tool for backward compatibility but is not in Airbrake's public docs); `time__lt` is optional (Airbrake defaults it to now) and `limit` (1–1000, default 100) is optional. Times are Unix seconds (integer or digit string) or ISO 8601 strings, forwarded as given. |
107
+ | `airbrake_groups_update` | `mute`, `unmute`, `resolve`, `unresolve` | PUT to `.../groups/:id/{muted,unmuted,resolved,unresolved}`. `resolve`/`unresolve` follow the documented mute PUT convention; fall back to `airbrake_request` if your instance disagrees. |
108
+ | `airbrake_notices` | `list`, `get`, `get_status` | Read-only. `list` and `get_status` are documented; `get` calls an undocumented endpoint that currently works on hosted Airbrake. |
109
+ | `airbrake_deploys` | `list`, `get` | Read-only. |
110
+ | `airbrake_deploys_create` | — | Creates a deploy marker. Pass the deploy fields as `deploy: {…}`; they are sent at the top level of the POST body. |
111
+ | `airbrake_performance` | `routes_stats`, `queries_stats`, `queues_stats` | Read-only. v5 APM. All actions require `time__gte`/`time__lt`/`period` (`minute`\|`hour`\|`day`). **`queries_stats` additionally requires a `route` filter** and **`queues_stats` additionally requires a `queue` filter** — the server returns 400 without them. The GET (read) side of these endpoints is not in Airbrake's public docs (which only show the PUT ingest side) but is live-verified working on hosted Airbrake. `routes-breakdowns` is intentionally not modeled (PUT-only SDK endpoint). |
112
+ | `airbrake_notify` | `notify` | Sends errors TO Airbrake (v3 Notifier API). |
113
+ | `airbrake_sourcemaps` | `list`, `get` | Read-only. |
114
+ | `airbrake_sourcemaps_upload` | — | Reads a local source map file and POSTs it as multipart/form-data — see [Source-map upload](#source-map-upload). |
115
+ | `airbrake_delete` | `resource: group \| sourcemap` | Permanent delete. `resource: "group"` requires `group_id`; `resource: "sourcemap"` requires `sourcemap_id`. Passing the other resource's ID is rejected. |
116
+ | `airbrake_request` | — | Escape hatch for any endpoint. Supports `auth: 'none'` (project-key endpoints), raw string bodies (multipart), arbitrary headers and query. GET-only in read-only mode. |
112
117
 
113
- Tools return raw Airbrake JSON payloads with no field-stripping. List actions add a `_pagination` metadata object so the model can iterate pages.
118
+ Tools return raw Airbrake JSON payloads with no field-stripping by default. List actions add a `_pagination` metadata object so the model can iterate pages.
119
+
120
+ ### Keeping responses small
121
+
122
+ Every tool result is serialised as **compact JSON** (no indentation or newlines) — whitespace costs tokens and carries no information for the model.
123
+
124
+ **`airbrake_notices` `list` defaults to `per_page: 10`** (max 200) because each notice carries a full backtrace, context, environment, session and params. All other list actions default to 50.
125
+
126
+ Every list-type action (`airbrake_projects` `list` / `list_activities`, `airbrake_groups` `list`, `airbrake_notices` `list`, `airbrake_deploys` `list`, `airbrake_sourcemaps` `list`) accepts an optional **`fields`** array (1–50 non-empty key names). When given, each object in every top-level array of the payload (`groups`, `notices`, `deploys`, …) is reduced to just those top-level keys; missing keys are omitted. Non-array properties such as `count` and `_pagination` are kept as-is. Without `fields`, the payload is returned unchanged.
127
+
128
+ ```json
129
+ { "action": "list", "project_id": 123, "fields": ["id", "errors", "noticeCount", "lastNoticeAt"] }
130
+ ```
131
+
132
+ For a realistic page of notices (~30-frame backtraces plus context/params), the result text drops from ~768 KB (pretty-printed, 50 per page — the previous behaviour) to ~95 KB (compact, 10 per page) and ~7 KB with `fields: ["id", "createdAt", "context"]`.
133
+
134
+ ### Tool annotations
135
+
136
+ Every tool advertises a `title` and MCP [`annotations`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) in `tools/list`. All hints are set explicitly; `openWorldHint` is `true` everywhere because every tool talks to Airbrake.
137
+
138
+ | Tool | `readOnlyHint` | `destructiveHint` | `idempotentHint` |
139
+ | ----------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------- | ---------------- |
140
+ | `airbrake_projects`, `airbrake_groups`, `airbrake_notices`, `airbrake_deploys`, `airbrake_performance`, `airbrake_sourcemaps` | `true` | `false` | `true` |
141
+ | `airbrake_groups_update` | `false` | `false` | `true` |
142
+ | `airbrake_deploys_create` | `false` | `false` | `false` |
143
+ | `airbrake_sourcemaps_upload` | `false` | `false` | `false` |
144
+ | `airbrake_notify` | `false` | `false` | `false` |
145
+ | `airbrake_delete` | `false` | `true` | `true` |
146
+ | `airbrake_request` | `false` | `true` | `false` |
147
+ | `airbrake_request` (read-only mode) | `true` | `false` | `true` |
148
+
149
+ Annotations are hints for the client's approval UX, not a security boundary — use read-only mode if writes must be impossible.
150
+
151
+ ### Read-only mode
152
+
153
+ Set `AIRBRAKE_READ_ONLY=1` to run the server without any ability to change Airbrake state:
154
+
155
+ - `airbrake_groups_update`, `airbrake_deploys_create`, `airbrake_sourcemaps_upload`, `airbrake_notify`, and `airbrake_delete` are not listed in `tools/list`, and calling them anyway returns an error (`<tool> is disabled: AIRBRAKE_READ_ONLY is set`) without any HTTP request.
156
+ - `airbrake_request` stays available but GET-only: its advertised `method` enum is `["GET"]` and it has no `body` field. Write methods and a `body` are rejected before any HTTP request, and its annotations become read-only.
157
+ - As a backstop below every tool, the HTTP client refuses anything but a plain GET while read-only mode is on: any other method, method-override headers (`X-HTTP-Method-Override`, `X-HTTP-Method`, `X-Method-Override`), and a `_method` query parameter (whether passed in `query` or embedded in `path`).
158
+ - The server writes a one-line notice to stderr at startup.
159
+
160
+ ```bash
161
+ claude mcp add airbrake --scope user \
162
+ --env AIRBRAKE_USER_TOKEN=YOUR_TOKEN --env AIRBRAKE_READ_ONLY=1 \
163
+ -- npx -y airbrake-mcp
164
+ ```
165
+
166
+ ### Migrating from 0.1.x
167
+
168
+ Write and destructive actions moved out of the resource tools into dedicated tools (so each tool's annotations are accurate). The HTTP requests are unchanged.
169
+
170
+ | Before | After |
171
+ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
172
+ | `airbrake_groups` `{action: "mute" \| "unmute" \| "resolve" \| "unresolve", project_id, group_id}` | `airbrake_groups_update` with the same arguments |
173
+ | `airbrake_groups` `{action: "delete", project_id, group_id}` | `airbrake_delete` `{resource: "group", project_id, group_id}` |
174
+ | `airbrake_sourcemaps` `{action: "delete", project_id, sourcemap_id}` | `airbrake_delete` `{resource: "sourcemap", project_id, sourcemap_id}` |
175
+ | `airbrake_deploys` `{action: "create", project_id, deploy}` | `airbrake_deploys_create` `{project_id, deploy}` (no `action`) |
114
176
 
115
177
  ### ID precision — strings only for snowflakes
116
178
 
@@ -118,15 +180,55 @@ Airbrake's group/notice/deploy/sourcemap IDs are **19-digit snowflakes** that ex
118
180
 
119
181
  The schemas reject numeric IDs explicitly; you'll see a clear zod error if you try. Project IDs are small integers and can be passed as numbers as usual.
120
182
 
183
+ ### Source-map upload
184
+
185
+ `airbrake_sourcemaps_upload`:
186
+
187
+ ```json
188
+ {
189
+ "project_id": 123,
190
+ "file_path": "/abs/path/to/dist/app.min.js.map",
191
+ "name": "https://cdn.example.com/app.min.js",
192
+ "pattern": "%/app.min.js"
193
+ }
194
+ ```
195
+
196
+ `name` is the minified file URL (or name) the map applies to; `pattern` is an optional SQL `LIKE` pattern matching minified file URLs. The server reads the file itself and builds the multipart request (`file`, `name`, `pattern` parts) — no hand-built multipart body is needed.
197
+
198
+ Because this tool reads a file from the machine running the MCP server and sends it to the Airbrake host, it is locked down so a prompt-injected model cannot use it to exfiltrate arbitrary files. All of the following are enforced **before any HTTP request is made**:
199
+
200
+ - `file_path` must be absolute and its own file name must end in `.map` (case-insensitive). This is checked before the filesystem is touched, so the tool cannot be used to probe whether arbitrary files exist; missing and unreadable paths get the same error. On Windows, network (UNC, `\\host\share`) and device (`\\?\`, `\\.\`) paths are rejected outright, since merely resolving a UNC path sends the user's NTLM credentials to that host.
201
+ - It must resolve (via `realpath`, following every symlink) to a **regular file** — directories, devices, FIFOs and sockets are rejected — whose **resolved** name also ends in `.map`. A symlink `bundle.js.map → ~/.ssh/id_rsa` is rejected.
202
+ - The file must be at most **50 MiB**, checked via `lstat` before it is read. The open handle is re-checked (same inode, still within the cap) so a file swapped after the check is not read.
203
+ - The content must parse as JSON and look like a **source map v3**: `version === 3`, `mappings` is a string, and `sources` (if present) is an array of strings or `null`s. Index maps (`sections`) are not accepted. This content check is also what stops a hard link named `*.map` that points at a secret.
204
+ - `name` and `pattern` are trimmed, then must be non-empty, at most 2048 characters, and contain no CR/LF.
205
+
206
+ Rejection messages never include the resolved target path or any file content.
207
+
208
+ Each upload attempt gets at least 55 s (or `AIRBRAKE_TIMEOUT_MS`, if larger) — long enough for large maps, while a single attempt stays under the 60 s default request timeout of MCP SDK clients. Because POST is not idempotent, an upload is **not** retried after a network error, a timeout, or any 5xx (Airbrake may already have stored it); only 429 and connection failures before anything was sent are retried, per `AIRBRAKE_MAX_RETRIES`. After an ambiguous failure the error says so — check with `list` before uploading again.
209
+
121
210
  ### Pagination params
122
211
 
123
212
  Airbrake accepts both `limit` and `per_page` on list endpoints. This MCP standardizes on `page` + `per_page` for consistency across all list actions.
124
213
 
214
+ List actions add a `_pagination` object so the model knows whether to fetch another page without doing arithmetic:
215
+
216
+ | Field | When present | Meaning |
217
+ | ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
218
+ | `page`, `per_page` | always | The page that was requested. |
219
+ | `count` | Airbrake returned a numeric `count` | Total reported by Airbrake (passed through unchanged). |
220
+ | `has_more` | `count` present, or the payload has a list | `true` if another page exists. With `count`, it compares the items actually served so far, `(page - 1) * per_page + list.length`, against `count`, so a page Airbrake capped below `per_page` still reports more. |
221
+ | `next_page` | only when `has_more` is `true` | `page + 1` — pass it as `page` on the next call. |
222
+ | `total_pages` | `count` present | `ceil(count / per_page)` (`0` when `count` is `0`). Assumes Airbrake honoured the requested `per_page`. |
223
+ | `has_more_is_estimate` | `count` absent and the payload has a list | `true`: `has_more` was inferred from the first list in the payload (`length >= per_page`), so a full last page may yield one empty follow-up page. |
224
+
225
+ If Airbrake returns neither `count` nor a list, `has_more`/`next_page` are omitted rather than guessed. `has_more` errs towards one extra (possibly empty) fetch rather than skipping pages; stop when it is `false`.
226
+
125
227
  ### Coverage caveats
126
228
 
127
229
  - **Project updates are not exposed.** The `PUT /api/v4/projects/:id` endpoint requires dashboard-session credentials (cookies + CSRF), not Personal API tokens, and returns 401 from every token shape we tested. Use the Airbrake dashboard to change project settings.
128
230
  - **`airbrake_notices.get`** calls an undocumented endpoint. It works on hosted Airbrake today but is not part of the public contract — may break or differ on self-hosted instances and Errbit.
129
- - **Source-map upload (`POST /api/v4/projects/:pid/sourcemaps`)** requires multipart/form-data. The escape hatch supports it via raw string body + a `Content-Type: multipart/form-data; boundary=…` header; constructing the multipart body is the caller's responsibility.
231
+ - **Source-map upload auth.** Airbrake's docs list project-key or user-key auth for `POST /api/v4/projects/:pid/sourcemaps`; `airbrake_sourcemaps_upload` sends the same `Authorization: Bearer <AIRBRAKE_USER_TOKEN>` as every other management call.
130
232
  - **`POST /api/v3/projects/:pid/ios-reports`** (iOS crash reports) requires `?key=PROJECT_KEY` and no `Authorization` header. Call via `airbrake_request` with `auth: 'none'` and pass the project key in `query`.
131
233
  - **APM write endpoints** (`PUT /api/v5/.../routes-stats` etc.) are SDK-internal; not modeled, but reachable via the escape hatch.
132
234
  - **What this MCP intentionally doesn't model:** the Airbrake dashboard exposes endpoints for comments, bookmarks, iframes, personal tokens, project stats, and a cross-project `/api/v4/groups` listing — these all returned 404/401 against hosted Airbrake from a User API token. They were modeled in earlier versions and removed. If your instance does support them, reach for `airbrake_request`.
@@ -136,13 +238,32 @@ Airbrake accepts both `limit` and `per_page` on list endpoints. This MCP standar
136
238
  ```bash
137
239
  npm install
138
240
  npm test # vitest, 80 tests
241
+ npm run test:coverage # vitest with v8 coverage; fails below the thresholds in vitest.config.ts
139
242
  npm run typecheck
140
243
  npm run lint
141
244
  npm run build # emits dist/
142
- npm run validate # spawns the built server, checks tool schemas (expects 8 tools)
245
+ npm run validate # spawns the built server, checks tool schemas (expects 12 tools)
246
+ npm run test:e2e # builds, then drives dist/bin.js over stdio against a local mock Airbrake
143
247
  npm run dev # tsx src/bin.ts (for local stdio testing)
248
+ npm run audit:ci # dependency audit gate (what CI runs)
144
249
  ```
145
250
 
251
+ ### Dependency audit
252
+
253
+ CI runs `node scripts/audit.mjs` (also available as `npm run audit:ci`) instead of a bare `npm audit`. It audits `package-lock.json` only (`--package-lock-only`), so it runs in its own job **before** any install, and no dependency's install script can tamper with it. Dev, optional and peer dependencies are always included, whatever `NODE_ENV` or `.npmrc` says.
254
+
255
+ It fails on any **high or critical** advisory unless [`audit-allowlist.json`](audit-allowlist.json) has a matching entry, and each entry has to justify itself:
256
+
257
+ - **`scope`** is `dev` or `runtime`. A `dev` entry only covers an advisory that is absent from the shipped tree (`npm audit --omit=dev`), so a dev-tooling exception can never hide a vulnerability users install. `runtime` entries should be rare and short-lived.
258
+ - **`package`** must name the package npm reports the advisory against, and only covers it if that's the _only_ package hit. The GHSA id alone isn't enough, so a mislabeled entry can't get waved through in review.
259
+ - **`reason`** says why it's acceptable for now, and what removes it.
260
+ - **`expires`** (`YYYY-MM-DD`): the gate fails after that date, and also when the date is more than **180 days** out for `dev` or **90 days** for `runtime`. Nothing can be waved through indefinitely.
261
+ - **Stale entries fail too.** Once an entry covers nothing, because the advisory was fixed upstream or the dependency was bumped, the gate asks for it to be removed. The list can only shrink back to empty.
262
+
263
+ If npm's report format ever changes such that a high/critical package can't be matched to an advisory, the gate errors (exit 2) instead of reading it as a clean tree.
264
+
265
+ Moderate and low advisories don't block CI. Check `npm audit` locally from time to time.
266
+
146
267
  ## Contributing
147
268
 
148
269
  Issues and pull requests welcome at <https://github.com/francktrouillez/airbrake-mcp/issues>.
@@ -2,10 +2,25 @@ import type { Config } from '../config.js';
2
2
  export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
3
3
  export declare const MAX_RETRY_DELAY_MS = 60000;
4
4
  export declare const MAX_RESPONSE_BYTES: number;
5
+ /** The response body exceeded the size cap (see MAX_RESPONSE_BYTES). */
6
+ export declare class ResponseTooLargeError extends Error {
7
+ constructor(message: string);
8
+ }
5
9
  export interface RequestOptions {
6
10
  query?: Record<string, string | number | boolean | undefined>;
11
+ /**
12
+ * - `FormData`: sent as multipart/form-data; fetch generates the boundary,
13
+ * so any caller-supplied content-type is dropped.
14
+ * - `string`: sent verbatim; caller controls content-type via `headers`.
15
+ * - anything else: JSON-serialized with `content-type: application/json`.
16
+ */
7
17
  body?: unknown;
8
18
  headers?: Record<string, string>;
19
+ /**
20
+ * Raise the per-attempt timeout to at least this many ms for this request
21
+ * (the effective timeout is max(config.timeoutMs, minTimeoutMs)).
22
+ */
23
+ minTimeoutMs?: number;
9
24
  /** 'bearer' (default) uses AIRBRAKE_USER_TOKEN; 'none' omits Authorization (notifier path) */
10
25
  auth?: 'bearer' | 'none';
11
26
  }
@@ -15,5 +30,6 @@ export declare class AirbrakeClient {
15
30
  private readonly config;
16
31
  constructor(config: Config);
17
32
  request(method: HttpMethod, path: string, options?: RequestOptions): Promise<unknown>;
33
+ private attempt;
18
34
  }
19
35
  export declare function readBodyWithLimit(response: Response, max: number): Promise<string>;