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.
- package/CHANGELOG.md +199 -1
- package/README.md +150 -29
- package/dist/client/airbrake.d.ts +16 -0
- package/dist/client/airbrake.js +133 -76
- package/dist/client/airbrake.js.map +1 -1
- package/dist/client/errors.d.ts +2 -2
- package/dist/client/errors.js +9 -4
- package/dist/client/errors.js.map +1 -1
- package/dist/client/pagination.d.ts +20 -0
- package/dist/client/pagination.js +42 -4
- package/dist/client/pagination.js.map +1 -1
- package/dist/client/read-only-guard.d.ts +8 -0
- package/dist/client/read-only-guard.js +28 -0
- package/dist/client/read-only-guard.js.map +1 -0
- package/dist/client/retry-policy.d.ts +31 -0
- package/dist/client/retry-policy.js +76 -0
- package/dist/client/retry-policy.js.map +1 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +15 -0
- package/dist/config.js.map +1 -1
- package/dist/server.d.ts +3 -2
- package/dist/server.js +105 -39
- package/dist/server.js.map +1 -1
- package/dist/tools/delete.d.ts +13 -0
- package/dist/tools/delete.js +41 -0
- package/dist/tools/delete.js.map +1 -0
- package/dist/tools/deploys-create.d.ts +8 -0
- package/dist/tools/deploys-create.js +30 -0
- package/dist/tools/deploys-create.js.map +1 -0
- package/dist/tools/deploys.d.ts +4 -34
- package/dist/tools/deploys.js +16 -25
- package/dist/tools/deploys.js.map +1 -1
- package/dist/tools/fields.d.ts +21 -0
- package/dist/tools/fields.js +48 -0
- package/dist/tools/fields.js.map +1 -0
- package/dist/tools/groups-update.d.ts +14 -0
- package/dist/tools/groups-update.js +37 -0
- package/dist/tools/groups-update.js.map +1 -0
- package/dist/tools/groups.d.ts +19 -126
- package/dist/tools/groups.js +113 -40
- package/dist/tools/groups.js.map +1 -1
- package/dist/tools/index.d.ts +1 -0
- package/dist/tools/index.js +19 -1
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/moved-actions.d.ts +7 -0
- package/dist/tools/moved-actions.js +18 -0
- package/dist/tools/moved-actions.js.map +1 -0
- package/dist/tools/notices.d.ts +6 -38
- package/dist/tools/notices.js +19 -19
- package/dist/tools/notices.js.map +1 -1
- package/dist/tools/notify.d.ts +4 -24
- package/dist/tools/notify.js +12 -3
- package/dist/tools/notify.js.map +1 -1
- package/dist/tools/performance.d.ts +19 -66
- package/dist/tools/performance.js +11 -10
- package/dist/tools/performance.js.map +1 -1
- package/dist/tools/projects.d.ts +6 -30
- package/dist/tools/projects.js +13 -12
- package/dist/tools/projects.js.map +1 -1
- package/dist/tools/read-only.d.ts +9 -0
- package/dist/tools/read-only.js +14 -0
- package/dist/tools/read-only.js.map +1 -0
- package/dist/tools/request.d.ts +34 -20
- package/dist/tools/request.js +60 -15
- package/dist/tools/request.js.map +1 -1
- package/dist/tools/schemas.d.ts +34 -0
- package/dist/tools/schemas.js +41 -0
- package/dist/tools/schemas.js.map +1 -0
- package/dist/tools/sourcemap-file.d.ts +27 -0
- package/dist/tools/sourcemap-file.js +180 -0
- package/dist/tools/sourcemap-file.js.map +1 -0
- package/dist/tools/sourcemaps-upload.d.ts +25 -0
- package/dist/tools/sourcemaps-upload.js +68 -0
- package/dist/tools/sourcemaps-upload.js.map +1 -0
- package/dist/tools/sourcemaps.d.ts +4 -34
- package/dist/tools/sourcemaps.js +18 -21
- package/dist/tools/sourcemaps.js.map +1 -1
- package/dist/tools/types.d.ts +14 -1
- 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.
|
|
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
|
-
|
|
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
|
|
45
|
-
|
|
46
|
-
| `AIRBRAKE_USER_TOKEN`
|
|
47
|
-
| `AIRBRAKE_PROJECT_KEYS` | only for `airbrake_notify`
|
|
48
|
-
| `AIRBRAKE_HOST`
|
|
49
|
-
| `AIRBRAKE_TIMEOUT_MS`
|
|
50
|
-
| `AIRBRAKE_MAX_RETRIES`
|
|
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
|
|
75
|
-
|
|
76
|
-
| **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
77
|
-
| **Claude Code**
|
|
78
|
-
| **Cursor**
|
|
79
|
-
| **Cline (VS Code)**
|
|
80
|
-
| **Codex CLI**
|
|
81
|
-
| **Continue.dev**
|
|
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
|
|
103
|
-
|
|
104
|
-
| `airbrake_projects`
|
|
105
|
-
| `airbrake_groups`
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
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
|
|
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
|
|
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>;
|