squally-mcp 0.8.0 → 0.8.1

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 (3) hide show
  1. package/README.md +321 -321
  2. package/dist/openapi/v1.json +384 -549
  3. package/package.json +63 -63
package/README.md CHANGED
@@ -1,321 +1,321 @@
1
- # squally-mcp
2
-
3
- A local [MCP](https://modelcontextprotocol.io) server that lets a coding agent
4
- read your [Squally](https://app.squally.dev) data: which runs happened, how
5
- stable each test is, and why a particular test failed.
6
-
7
- It runs on your machine over stdio and talks to Squally's read API over HTTPS.
8
- Point Claude Code, Codex, Cursor or Claude Desktop at it and ask "why is
9
- `checkout.spec.ts` failing on main?".
10
-
11
- ## Read-only, and structurally so
12
-
13
- The server issues **HTTP GETs and nothing else**. There is no code path that
14
- writes, and every tool is annotated `readOnlyHint: true`, so a client can run
15
- them without asking you to confirm each one.
16
-
17
- It also cannot reach past your own organization: the key is scoped to one
18
- organization, and scoping, plan checks and secret exclusion are all enforced
19
- by the API, not by this client.
20
-
21
- ## What an agent can see
22
-
23
- Worth knowing before you hand a key to an assistant. Through this server an
24
- agent can read:
25
-
26
- - your **projects** and their names;
27
- - your **runs**, CI and local — commit SHA and message, branch, author, pull
28
- request, job key, a link to the CI run, timing, pass/fail counts;
29
- - **per-test results** for a run, including which shard ran what;
30
- - for a failing attempt: the **error message and stack**, the **code snippet**
31
- — **verbatim source code from your test file** — and the **full-context
32
- prompt** (the text behind Copy the full context in Squally), which carries the same snippet plus an **ARIA snapshot of your
33
- application at the moment of failure** (whatever was on screen, truncated to
34
- 3000 characters);
35
- - **per-test metrics**: how often each test passed on the first try, passed
36
- only after a retry, or failed, and how much time retries and failures cost;
37
- - **error signatures**: failures grouped across runs and branches.
38
-
39
- It cannot see screenshots, videos or traces — artifacts are deliberately out of
40
- scope — and it cannot see any key, secret or webhook URL.
41
-
42
- The key reaches **every project in the organization**. Create one per machine so
43
- a single revocation does not lock out everything, and revoke it under
44
- Organization › Read keys when the machine is retired.
45
-
46
- ## Setup
47
-
48
- You need an **organization read key** (`sqly_ro_…`): Squally → Organization ›
49
- Read keys → *Create read key*. It is shown once. It is not the same thing as the
50
- project ingest key your Playwright reporter uses — this server refuses that one
51
- by name.
52
-
53
- Requires **Node 22 or newer**. Read keys are available from the **Standard**
54
- plan.
55
-
56
- ### Claude Code
57
-
58
- ```bash
59
- claude mcp add squally --scope user \
60
- --env SQUALLY_API_KEY=sqly_ro_your_key_here \
61
- -- npx -y squally-mcp
62
- ```
63
-
64
- ### Codex
65
-
66
- `~/.codex/config.toml`:
67
-
68
- ```toml
69
- [mcp_servers.squally]
70
- command = "npx"
71
- args = ["-y", "squally-mcp"]
72
- env = { SQUALLY_API_KEY = "sqly_ro_your_key_here" }
73
- ```
74
-
75
- ### Cursor
76
-
77
- `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
78
-
79
- ```json
80
- {
81
- "mcpServers": {
82
- "squally": {
83
- "command": "npx",
84
- "args": ["-y", "squally-mcp"],
85
- "env": { "SQUALLY_API_KEY": "sqly_ro_your_key_here" }
86
- }
87
- }
88
- }
89
- ```
90
-
91
- ### Claude Desktop
92
-
93
- `claude_desktop_config.json` — macOS:
94
- `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\` — then
95
- restart the app:
96
-
97
- ```json
98
- {
99
- "mcpServers": {
100
- "squally": {
101
- "command": "npx",
102
- "args": ["-y", "squally-mcp"],
103
- "env": { "SQUALLY_API_KEY": "sqly_ro_your_key_here" }
104
- }
105
- }
106
- }
107
- ```
108
-
109
- ## Environment
110
-
111
- | Variable | Required | Meaning |
112
- |---|---|---|
113
- | `SQUALLY_API_KEY` | yes | Organization read key, `sqly_ro_…`. Missing or an ingest key by mistake, and the server exits with one line saying so. |
114
- | `SQUALLY_API_URL` | no | Base URL, default `https://app.squally.dev`. A trailing `/` or `/api/v1` is tolerated. Useful against a local Squally: `http://localhost:3000`. |
115
- | `SQUALLY_USE_SYSTEM_CA` | no | `0` keeps Node's bundled certificates only. |
116
-
117
- squally-mcp trusts your operating system's certificate store, like your browser does; set SQUALLY_USE_SYSTEM_CA=0 to use Node's bundled certificates only.
118
-
119
- ## Troubleshooting
120
-
121
- ### Claude Desktop
122
-
123
- - **The server does not start in time.** The first start through `npx`
124
- downloads the package, which can take longer than Claude Desktop's 60-second
125
- start-up limit. Install it once beforehand with `npm install -g squally-mcp`;
126
- `npx -y squally-mcp` then runs that copy without a download. Update it with
127
- the same command.
128
- - **Where the log is.** The Microsoft Store build of Claude Desktop writes it to
129
- `%LOCALAPPDATA%\Claude\logs\mcp-server-squally.log`. Its first lines say which
130
- Node runs the server and whether it trusts the system's certificate store;
131
- a request that never arrives is logged there with its cause.
132
- - **Edit the config only while the app is closed.** Quit Claude Desktop
133
- completely, including from the system tray, before changing
134
- `claude_desktop_config.json`.
135
-
136
- ## The tools
137
-
138
- | Tool | What it answers | Cost |
139
- |---|---|---|
140
- | `squally-list-projects` | Which projects exist. **Start here** — every other tool needs a `projectId` from it. | cheap |
141
- | `squally-find-run` | Which runs happened — latest, or by branch, commit SHA, status or source. Counters only. | cheap |
142
- | `squally-get-run` | One run with its per-test rows, across all shards. Which test is red. | cheap |
143
- | `squally-debug-failure` | Every attempt of one test in one run: error, stack, full-context prompt. | cheap |
144
- | `squally-get-test-metrics` | One test's stability, flaky rate and failure rate over a period. | cheap — one test |
145
- | `squally-list-tests` | Every test with a run in the period, ranked by stability, flaky rate or failures. | cheap — two queries, paged |
146
- | `squally-list-errors` | Error signatures in a period: what keeps failing, grouped, and how its runs ended. | cheap |
147
-
148
- For a single test use `squally-get-test-metrics`, not `squally-list-tests` —
149
- the tool descriptions say so, and the server repeats it in its instructions.
150
-
151
- ### Runs
152
-
153
- `squally-find-run` lists every run, CI and local alike; `source` (`all` by
154
- default, `ci` or `local`) narrows it, and each run says whether it was
155
- `local`. A run's `status` is the dashboard's word: `passed`, `failed`,
156
- `cancelled`, `incomplete` (a shard timed out, was stopped by the monthly
157
- result limit or never reported) or `running` - and `?status=` filters by
158
- any of them. A cancelled run is `cancelled`; `cancellation` says how, when
159
- and by whom. A sharded run is one row, its counters over all its shards with
160
- every test once, and the tests a cancel cut off count nowhere.
161
-
162
- Each run also says whether it is `settled` - final and counted; an
163
- `incomplete` run that is not settled still waits for a shard within the run
164
- timeout - and, from squally-reporter 0.11.0, which job of its CI run it is
165
- (`jobKey`, from `SQUALLY_CI_JOB_KEY`; each job is its own run), which
166
- `attempt`, which run it re-ran (`rerunOf`) and where the CI run is
167
- (`ciRunUrl`; for GitHub Actions also for older reporters when the project
168
- has one linked repository).
169
-
170
- ### What the numbers mean
171
-
172
- The two test tools count **finished runs, CI and local,** in the period (7, 14, 30 or 90
173
- days; 30 by default), on every branch unless you name one. A run finishes when
174
- all its shards have - or, once the run timeout has passed, with the results its
175
- shards reported, like a cancelled run; a shard stopped by the monthly result
176
- limit counts like one that timed out. A sharded run counts once, placed in the period
177
- by its first shard's start; a run that was a mass failure as a whole is left
178
- out. `source` is `all` (the default since read API 1.0.0-beta.18; `ci`
179
- before), `ci` or `local` - send `source=ci` for CI runs only - and the
180
- response's `population` names which runs it counted. Per test:
181
-
182
- - **stability** — runs that passed on the first try ÷ runs;
183
- - **flakyRate** — runs that passed only after a retry ÷ runs;
184
- - **failureRate** — failed runs ÷ runs.
185
-
186
- Each is a fraction from 0 to 1, and `null` when the test has no run in the
187
- period. **There is no verdict**: nothing calls a test flaky, broken or
188
- healthy. The tools return the numbers; the agent — or you — judges them.
189
-
190
- ### Example: `squally-list-tests`
191
-
192
- ```json
193
- { "projectId": "3f7c2a91-5b8e-4d0a-9c61-2e4b7f0d8a15", "perPage": 3 }
194
- ```
195
-
196
- The three least stable tests of the last 30 days (abridged):
197
-
198
- ```json
199
- {
200
- "population": "ci_groups_finished_not_mass_failure",
201
- "days": 30,
202
- "sort": "stability",
203
- "total": 409,
204
- "items": [
205
- {
206
- "testName": "chromium > checkout.spec.ts > Checkout > applies a coupon code",
207
- "filePath": "tests/checkout.spec.ts",
208
- "runs": 8,
209
- "stability": 0.5,
210
- "flakyRate": 0.5,
211
- "failureRate": 0,
212
- "timeLostMs": 7361,
213
- "topBranch": { "branch": "main", "kind": "retries", "count": 3 }
214
- }
215
- ]
216
- }
217
- ```
218
-
219
- ### Example: `squally-get-test-metrics`
220
-
221
- ```json
222
- {
223
- "projectId": "3f7c2a91-5b8e-4d0a-9c61-2e4b7f0d8a15",
224
- "testName": "chromium > checkout.spec.ts > Checkout > applies a coupon code"
225
- }
226
- ```
227
-
228
- The same numbers as that test's row, for one test (abridged):
229
-
230
- ```json
231
- {
232
- "days": 30,
233
- "branch": null,
234
- "runs": 8,
235
- "stableRuns": 4,
236
- "flakyRuns": 4,
237
- "failedRuns": 0,
238
- "stability": 0.5,
239
- "flakyRate": 0.5,
240
- "failureRate": 0,
241
- "branches": ["feature/saved-carts", "main"]
242
- }
243
- ```
244
-
245
- Pass the name exactly as Squally shows it. When it exists in several spec
246
- files, the tool answers with the `filePath` values to retry with; a test with
247
- results but no counted run in the period answers `runs: 0` and `null`
248
- rates — an answer, not an error.
249
-
250
- ## Development
251
-
252
- ```bash
253
- npm install
254
- npm run build # tsc, then copy the vendored OpenAPI document into dist/
255
- npm test # builds, then runs the suite
256
- npm run vendor:openapi # re-fetch the API document; review the diff, then re-pin
257
- ```
258
-
259
- The tool schemas are **derived from Squally's published OpenAPI document**,
260
- vendored at `src/openapi/v1.json` — an input schema is the operation's
261
- parameters, an output schema is its 200 response. Nothing is transcribed by
262
- hand, so the two cannot drift. `test/drift.test.js` compares the vendored copy
263
- against the live document and fails when an operation or parameter has moved;
264
- it skips loudly when offline, and while the live API is still an older version
265
- than the vendored one — a release that has not been deployed yet.
266
-
267
- ## Releasing
268
-
269
- Publishing is **staged**: CI uploads the tarball, a maintainer approves it, and
270
- only then is the version installable. `npm stage publish` never asks for 2FA,
271
- which is what makes it usable from a workflow; the 2FA prompt moves to the
272
- approval step, so a compromised workflow can stage a version but cannot put one
273
- in front of users. Direct `npm publish` is not permitted for this package's
274
- trusted publisher, so this is the only route.
275
-
276
- > **0.1.0 is the exception.** It was published by hand with `npm publish`
277
- > before the trusted publisher existed, so it carries no provenance
278
- > attestation. Every version from 0.1.1 on goes through the steps below.
279
-
280
- 1. **Bump and tag.** The lockfile belongs to the release commit, so let `npm
281
- version` write both and commit them together:
282
-
283
- ```bash
284
- npm install # only if package.json changed by hand
285
- npm version patch # or minor / major - writes package.json + lockfile, makes the tag
286
- git push --follow-tags
287
- ```
288
-
289
- 2. **The tag starts the workflow.** `.github/workflows/publish.yml` runs on
290
- `v*`: it tests, checks that the tag and `package.json` agree, and runs
291
-
292
- ```bash
293
- npm stage publish --provenance --access public
294
- ```
295
-
296
- through npm's trusted publishing (OIDC) — no npm token in GitHub secrets.
297
- `--provenance` attaches a signed statement linking the tarball to that
298
- workflow run and commit.
299
-
300
- 3. **Approve the staged version.** On
301
- [npmjs.com/package/squally-mcp](https://www.npmjs.com/package/squally-mcp) →
302
- **Staged Packages** → **Approve**, which asks for 2FA. Or from a terminal:
303
-
304
- ```bash
305
- npm stage list squally-mcp
306
- npm stage view <stage-id> # what is in the tarball
307
- npm stage approve <stage-id> # also asks for 2FA
308
- npm stage reject <stage-id> # if something is wrong
309
- ```
310
-
311
- Until this step the version exists in the registry but installs nothing.
312
-
313
- **Requirements for step 3 on your machine:** npm **11.15.0 or later** and Node
314
- **22.14.0 or higher** ([npm docs](https://docs.npmjs.com/staged-publishing/)).
315
- Node 22 still bundles npm 10.9.9, so check `npm --version` rather than assuming
316
- your Node version brought a new enough npm. The workflow uses Node 24 for the
317
- same reason and fails with that requirement if a runner ever ships an older npm.
318
-
319
- ## License
320
-
321
- MIT
1
+ # squally-mcp
2
+
3
+ A local [MCP](https://modelcontextprotocol.io) server that lets a coding agent
4
+ read your [Squally](https://app.squally.dev) data: which runs happened, how
5
+ stable each test is, and why a particular test failed.
6
+
7
+ It runs on your machine over stdio and talks to Squally's read API over HTTPS.
8
+ Point Claude Code, Codex, Cursor or Claude Desktop at it and ask "why is
9
+ `checkout.spec.ts` failing on main?".
10
+
11
+ ## Read-only, and structurally so
12
+
13
+ The server issues **HTTP GETs and nothing else**. There is no code path that
14
+ writes, and every tool is annotated `readOnlyHint: true`, so a client can run
15
+ them without asking you to confirm each one.
16
+
17
+ It also cannot reach past your own organization: the key is scoped to one
18
+ organization, and scoping, plan checks and secret exclusion are all enforced
19
+ by the API, not by this client.
20
+
21
+ ## What an agent can see
22
+
23
+ Worth knowing before you hand a key to an assistant. Through this server an
24
+ agent can read:
25
+
26
+ - your **projects** and their names;
27
+ - your **runs**, CI and local — commit SHA and message, branch, author, pull
28
+ request, job key, a link to the CI run, timing, pass/fail counts;
29
+ - **per-test results** for a run, including which shard ran what;
30
+ - for a failing attempt: the **error message and stack**, the **code snippet**
31
+ — **verbatim source code from your test file** — and the **full-context
32
+ prompt** (the text behind Copy the full context in Squally), which carries the same snippet plus an **ARIA snapshot of your
33
+ application at the moment of failure** (whatever was on screen, truncated to
34
+ 3000 characters);
35
+ - **per-test metrics**: how often each test passed on the first try, passed
36
+ only after a retry, or failed, and how much time retries and failures cost;
37
+ - **error signatures**: failures grouped across runs and branches.
38
+
39
+ It cannot see screenshots, videos or traces — artifacts are deliberately out of
40
+ scope — and it cannot see any key, secret or webhook URL.
41
+
42
+ The key reaches **every project in the organization**. Create one per machine so
43
+ a single revocation does not lock out everything, and revoke it under
44
+ Organization › Read keys when the machine is retired.
45
+
46
+ ## Setup
47
+
48
+ You need an **organization read key** (`sqly_ro_…`): Squally → Organization ›
49
+ Read keys → *Create read key*. It is shown once. It is not the same thing as the
50
+ project ingest key your Playwright reporter uses — this server refuses that one
51
+ by name.
52
+
53
+ Requires **Node 22 or newer**. Read keys are available from the **Standard**
54
+ plan.
55
+
56
+ ### Claude Code
57
+
58
+ ```bash
59
+ claude mcp add squally --scope user \
60
+ --env SQUALLY_API_KEY=sqly_ro_your_key_here \
61
+ -- npx -y squally-mcp
62
+ ```
63
+
64
+ ### Codex
65
+
66
+ `~/.codex/config.toml`:
67
+
68
+ ```toml
69
+ [mcp_servers.squally]
70
+ command = "npx"
71
+ args = ["-y", "squally-mcp"]
72
+ env = { SQUALLY_API_KEY = "sqly_ro_your_key_here" }
73
+ ```
74
+
75
+ ### Cursor
76
+
77
+ `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
78
+
79
+ ```json
80
+ {
81
+ "mcpServers": {
82
+ "squally": {
83
+ "command": "npx",
84
+ "args": ["-y", "squally-mcp"],
85
+ "env": { "SQUALLY_API_KEY": "sqly_ro_your_key_here" }
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ ### Claude Desktop
92
+
93
+ `claude_desktop_config.json` — macOS:
94
+ `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\` — then
95
+ restart the app:
96
+
97
+ ```json
98
+ {
99
+ "mcpServers": {
100
+ "squally": {
101
+ "command": "npx",
102
+ "args": ["-y", "squally-mcp"],
103
+ "env": { "SQUALLY_API_KEY": "sqly_ro_your_key_here" }
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ ## Environment
110
+
111
+ | Variable | Required | Meaning |
112
+ |---|---|---|
113
+ | `SQUALLY_API_KEY` | yes | Organization read key, `sqly_ro_…`. Missing or an ingest key by mistake, and the server exits with one line saying so. |
114
+ | `SQUALLY_API_URL` | no | Base URL, default `https://app.squally.dev`. A trailing `/` or `/api/v1` is tolerated. Useful against a local Squally: `http://localhost:3000`. |
115
+ | `SQUALLY_USE_SYSTEM_CA` | no | `0` keeps Node's bundled certificates only. |
116
+
117
+ squally-mcp trusts your operating system's certificate store, like your browser does; set SQUALLY_USE_SYSTEM_CA=0 to use Node's bundled certificates only.
118
+
119
+ ## Troubleshooting
120
+
121
+ ### Claude Desktop
122
+
123
+ - **The server does not start in time.** The first start through `npx`
124
+ downloads the package, which can take longer than Claude Desktop's 60-second
125
+ start-up limit. Install it once beforehand with `npm install -g squally-mcp`;
126
+ `npx -y squally-mcp` then runs that copy without a download. Update it with
127
+ the same command.
128
+ - **Where the log is.** The Microsoft Store build of Claude Desktop writes it to
129
+ `%LOCALAPPDATA%\Claude\logs\mcp-server-squally.log`. Its first lines say which
130
+ Node runs the server and whether it trusts the system's certificate store;
131
+ a request that never arrives is logged there with its cause.
132
+ - **Edit the config only while the app is closed.** Quit Claude Desktop
133
+ completely, including from the system tray, before changing
134
+ `claude_desktop_config.json`.
135
+
136
+ ## The tools
137
+
138
+ | Tool | What it answers | Cost |
139
+ |---|---|---|
140
+ | `squally-list-projects` | Which projects exist. **Start here** — every other tool needs a `projectId` from it. | cheap |
141
+ | `squally-find-run` | Which runs happened — latest, or by branch, commit SHA, status or source. Counters only. | cheap |
142
+ | `squally-get-run` | One run with its per-test rows, across all shards. Which test is red. | cheap |
143
+ | `squally-debug-failure` | Every attempt of one test in one run: error, stack, full-context prompt. | cheap |
144
+ | `squally-get-test-metrics` | One test's stability, flaky rate and failure rate over a period. | cheap — one test |
145
+ | `squally-list-tests` | Every test with a run in the period, ranked by stability, flaky rate or failures. | cheap — two queries, paged |
146
+ | `squally-list-errors` | Error signatures in a period: what keeps failing, grouped, and how its runs ended. | cheap |
147
+
148
+ For a single test use `squally-get-test-metrics`, not `squally-list-tests` —
149
+ the tool descriptions say so, and the server repeats it in its instructions.
150
+
151
+ ### Runs
152
+
153
+ `squally-find-run` lists every run, CI and local alike; `source` (`all` by
154
+ default, `ci` or `local`) narrows it, and each run says whether it was
155
+ `local`. A run's `status` is the dashboard's word: `passed`, `failed`,
156
+ `cancelled`, `incomplete` (a shard timed out, was stopped by the monthly
157
+ result limit or never reported) or `running` - and `?status=` filters by
158
+ any of them. A cancelled run is `cancelled`; `cancellation` says how, when
159
+ and by whom. A sharded run is one row, its counters over all its shards with
160
+ every test once, and the tests a cancel cut off count nowhere.
161
+
162
+ Each run also says whether it is `settled` - final and counted; an
163
+ `incomplete` run that is not settled still waits for a shard within the run
164
+ timeout - and, from squally-reporter 0.11.0, which job of its CI run it is
165
+ (`jobKey`, from `SQUALLY_CI_JOB_KEY`; each job is its own run), which
166
+ `attempt`, which run it re-ran (`rerunOf`) and where the CI run is
167
+ (`ciRunUrl`; for GitHub Actions also for older reporters when the project
168
+ has one linked repository).
169
+
170
+ ### What the numbers mean
171
+
172
+ The two test tools count **finished runs, CI and local,** in the period (7, 14, 30 or 90
173
+ days; 30 by default), on every branch unless you name one. A run finishes when
174
+ all its shards have - or, once the run timeout has passed, with the results its
175
+ shards reported, like a cancelled run; a shard stopped by the monthly result
176
+ limit counts like one that timed out. A sharded run counts once, placed in the period
177
+ by its first shard's start; a run that was a mass failure as a whole is left
178
+ out. `source` is `all` (the default since read API 1.0.0-beta.18; `ci`
179
+ before), `ci` or `local` - send `source=ci` for CI runs only - and the
180
+ response's `population` names which runs it counted. Per test:
181
+
182
+ - **stability** — runs that passed on the first try ÷ runs;
183
+ - **flakyRate** — runs that passed only after a retry ÷ runs;
184
+ - **failureRate** — failed runs ÷ runs.
185
+
186
+ Each is a fraction from 0 to 1, and `null` when the test has no run in the
187
+ period. **There is no verdict**: nothing calls a test flaky, broken or
188
+ healthy. The tools return the numbers; the agent — or you — judges them.
189
+
190
+ ### Example: `squally-list-tests`
191
+
192
+ ```json
193
+ { "projectId": "3f7c2a91-5b8e-4d0a-9c61-2e4b7f0d8a15", "perPage": 3 }
194
+ ```
195
+
196
+ The three least stable tests of the last 30 days (abridged):
197
+
198
+ ```json
199
+ {
200
+ "population": "ci_groups_finished_not_mass_failure",
201
+ "days": 30,
202
+ "sort": "stability",
203
+ "total": 409,
204
+ "items": [
205
+ {
206
+ "testName": "chromium > checkout.spec.ts > Checkout > applies a coupon code",
207
+ "filePath": "tests/checkout.spec.ts",
208
+ "runs": 8,
209
+ "stability": 0.5,
210
+ "flakyRate": 0.5,
211
+ "failureRate": 0,
212
+ "timeLostMs": 7361,
213
+ "topBranch": { "branch": "main", "kind": "retries", "count": 3 }
214
+ }
215
+ ]
216
+ }
217
+ ```
218
+
219
+ ### Example: `squally-get-test-metrics`
220
+
221
+ ```json
222
+ {
223
+ "projectId": "3f7c2a91-5b8e-4d0a-9c61-2e4b7f0d8a15",
224
+ "testName": "chromium > checkout.spec.ts > Checkout > applies a coupon code"
225
+ }
226
+ ```
227
+
228
+ The same numbers as that test's row, for one test (abridged):
229
+
230
+ ```json
231
+ {
232
+ "days": 30,
233
+ "branch": null,
234
+ "runs": 8,
235
+ "stableRuns": 4,
236
+ "flakyRuns": 4,
237
+ "failedRuns": 0,
238
+ "stability": 0.5,
239
+ "flakyRate": 0.5,
240
+ "failureRate": 0,
241
+ "branches": ["feature/saved-carts", "main"]
242
+ }
243
+ ```
244
+
245
+ Pass the name exactly as Squally shows it. When it exists in several spec
246
+ files, the tool answers with the `filePath` values to retry with; a test with
247
+ results but no counted run in the period answers `runs: 0` and `null`
248
+ rates — an answer, not an error.
249
+
250
+ ## Development
251
+
252
+ ```bash
253
+ npm install
254
+ npm run build # tsc, then copy the vendored OpenAPI document into dist/
255
+ npm test # builds, then runs the suite
256
+ npm run vendor:openapi # re-fetch the API document; review the diff, then re-pin
257
+ ```
258
+
259
+ The tool schemas are **derived from Squally's published OpenAPI document**,
260
+ vendored at `src/openapi/v1.json` — an input schema is the operation's
261
+ parameters, an output schema is its 200 response. Nothing is transcribed by
262
+ hand, so the two cannot drift. `test/drift.test.js` compares the vendored copy
263
+ against the live document and fails when an operation or parameter has moved;
264
+ it skips loudly when offline, and while the live API is still an older version
265
+ than the vendored one — a release that has not been deployed yet.
266
+
267
+ ## Releasing
268
+
269
+ Publishing is **staged**: CI uploads the tarball, a maintainer approves it, and
270
+ only then is the version installable. `npm stage publish` never asks for 2FA,
271
+ which is what makes it usable from a workflow; the 2FA prompt moves to the
272
+ approval step, so a compromised workflow can stage a version but cannot put one
273
+ in front of users. Direct `npm publish` is not permitted for this package's
274
+ trusted publisher, so this is the only route.
275
+
276
+ > **0.1.0 is the exception.** It was published by hand with `npm publish`
277
+ > before the trusted publisher existed, so it carries no provenance
278
+ > attestation. Every version from 0.1.1 on goes through the steps below.
279
+
280
+ 1. **Bump and tag.** The lockfile belongs to the release commit, so let `npm
281
+ version` write both and commit them together:
282
+
283
+ ```bash
284
+ npm install # only if package.json changed by hand
285
+ npm version patch # or minor / major - writes package.json + lockfile, makes the tag
286
+ git push --follow-tags
287
+ ```
288
+
289
+ 2. **The tag starts the workflow.** `.github/workflows/publish.yml` runs on
290
+ `v*`: it tests, checks that the tag and `package.json` agree, and runs
291
+
292
+ ```bash
293
+ npm stage publish --provenance --access public
294
+ ```
295
+
296
+ through npm's trusted publishing (OIDC) — no npm token in GitHub secrets.
297
+ `--provenance` attaches a signed statement linking the tarball to that
298
+ workflow run and commit.
299
+
300
+ 3. **Approve the staged version.** On
301
+ [npmjs.com/package/squally-mcp](https://www.npmjs.com/package/squally-mcp) →
302
+ **Staged Packages** → **Approve**, which asks for 2FA. Or from a terminal:
303
+
304
+ ```bash
305
+ npm stage list squally-mcp
306
+ npm stage view <stage-id> # what is in the tarball
307
+ npm stage approve <stage-id> # also asks for 2FA
308
+ npm stage reject <stage-id> # if something is wrong
309
+ ```
310
+
311
+ Until this step the version exists in the registry but installs nothing.
312
+
313
+ **Requirements for step 3 on your machine:** npm **11.15.0 or later** and Node
314
+ **22.14.0 or higher** ([npm docs](https://docs.npmjs.com/staged-publishing/)).
315
+ Node 22 still bundles npm 10.9.9, so check `npm --version` rather than assuming
316
+ your Node version brought a new enough npm. The workflow uses Node 24 for the
317
+ same reason and fails with that requirement if a runner ever ships an older npm.
318
+
319
+ ## License
320
+
321
+ MIT