squally-mcp 0.1.0 → 0.1.2
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/README.md +58 -5
- package/dist/instructions.js +3 -0
- package/dist/openapi/v1.json +3 -3
- package/dist/tools.d.ts +13 -0
- package/dist/tools.js +14 -0
- package/package.json +17 -2
package/README.md
CHANGED
|
@@ -24,11 +24,12 @@ Worth knowing before you hand a key to an assistant. Through this server an
|
|
|
24
24
|
agent can read:
|
|
25
25
|
|
|
26
26
|
- your **projects**, their names and stable branches;
|
|
27
|
-
- your **CI runs** — commit SHA, branch, author,
|
|
27
|
+
- your **CI runs** — commit SHA and message, branch, author, pull request,
|
|
28
|
+
timing, pass/fail counts;
|
|
28
29
|
- **per-test results** for a run, including which shard ran what;
|
|
29
|
-
- for a failing attempt: the **error message and stack**, the **
|
|
30
|
-
|
|
31
|
-
|
|
30
|
+
- for a failing attempt: the **error message and stack**, the **code snippet**
|
|
31
|
+
— **verbatim source code from your test file** — and the **Copy-for-AI
|
|
32
|
+
prompt**, which carries the same snippet plus an **ARIA snapshot of your
|
|
32
33
|
application at the moment of failure** (whatever was on screen, truncated to
|
|
33
34
|
3000 characters);
|
|
34
35
|
- **flakiness verdicts** and how much time each flaky test has cost;
|
|
@@ -118,7 +119,7 @@ restart the app:
|
|
|
118
119
|
| `squally-list-projects` | Which projects exist. **Start here** — every other tool needs a `projectId` from it. | cheap |
|
|
119
120
|
| `squally-find-run` | Which runs happened — latest, or by branch, commit SHA or status. Counters only. | cheap |
|
|
120
121
|
| `squally-get-run` | One run with its per-test rows, across all shards. Which test is red. | cheap |
|
|
121
|
-
| `squally-debug-failure` | Every attempt of one test in one run: error, stack,
|
|
122
|
+
| `squally-debug-failure` | Every attempt of one test in one run: error, stack, Copy-for-AI prompt. | cheap |
|
|
122
123
|
| `squally-get-test-status` | The stored flakiness status of **one** test. | cheap — one lookup |
|
|
123
124
|
| `squally-list-flaky-tests` | The ranked flaky/broken list with time lost. | **expensive — one engine pass** |
|
|
124
125
|
| `squally-list-errors` | Error signatures in a period: what keeps failing, grouped. | cheap |
|
|
@@ -144,6 +145,58 @@ hand, so the two cannot drift. `test/drift.test.js` compares the vendored copy
|
|
|
144
145
|
against the live document and fails when an operation or parameter has moved;
|
|
145
146
|
it skips loudly when offline.
|
|
146
147
|
|
|
148
|
+
## Releasing
|
|
149
|
+
|
|
150
|
+
Publishing is **staged**: CI uploads the tarball, a maintainer approves it, and
|
|
151
|
+
only then is the version installable. `npm stage publish` never asks for 2FA,
|
|
152
|
+
which is what makes it usable from a workflow; the 2FA prompt moves to the
|
|
153
|
+
approval step, so a compromised workflow can stage a version but cannot put one
|
|
154
|
+
in front of users. Direct `npm publish` is not permitted for this package's
|
|
155
|
+
trusted publisher, so this is the only route.
|
|
156
|
+
|
|
157
|
+
> **0.1.0 is the exception.** It was published by hand with `npm publish`
|
|
158
|
+
> before the trusted publisher existed, so it carries no provenance
|
|
159
|
+
> attestation. Every version from 0.1.1 on goes through the steps below.
|
|
160
|
+
|
|
161
|
+
1. **Bump and tag.** The lockfile belongs to the release commit, so let `npm
|
|
162
|
+
version` write both and commit them together:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
npm install # only if package.json changed by hand
|
|
166
|
+
npm version patch # or minor / major - writes package.json + lockfile, makes the tag
|
|
167
|
+
git push --follow-tags
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
2. **The tag starts the workflow.** `.github/workflows/publish.yml` runs on
|
|
171
|
+
`v*`: it tests, checks that the tag and `package.json` agree, and runs
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
npm stage publish --provenance --access public
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
through npm's trusted publishing (OIDC) — no npm token in GitHub secrets.
|
|
178
|
+
`--provenance` attaches a signed statement linking the tarball to that
|
|
179
|
+
workflow run and commit.
|
|
180
|
+
|
|
181
|
+
3. **Approve the staged version.** On
|
|
182
|
+
[npmjs.com/package/squally-mcp](https://www.npmjs.com/package/squally-mcp) →
|
|
183
|
+
**Staged Packages** → **Approve**, which asks for 2FA. Or from a terminal:
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
npm stage list squally-mcp
|
|
187
|
+
npm stage view <stage-id> # what is in the tarball
|
|
188
|
+
npm stage approve <stage-id> # also asks for 2FA
|
|
189
|
+
npm stage reject <stage-id> # if something is wrong
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Until this step the version exists in the registry but installs nothing.
|
|
193
|
+
|
|
194
|
+
**Requirements for step 3 on your machine:** npm **11.15.0 or later** and Node
|
|
195
|
+
**22.14.0 or higher** ([npm docs](https://docs.npmjs.com/staged-publishing/)).
|
|
196
|
+
Node 22 still bundles npm 10.9.9, so check `npm --version` rather than assuming
|
|
197
|
+
your Node version brought a new enough npm. The workflow uses Node 24 for the
|
|
198
|
+
same reason and fails with that requirement if a runner ever ships an older npm.
|
|
199
|
+
|
|
147
200
|
## License
|
|
148
201
|
|
|
149
202
|
MIT
|
package/dist/instructions.js
CHANGED
|
@@ -5,6 +5,9 @@
|
|
|
5
5
|
// projectId (which every other tool needs), reaching for the expensive ranking
|
|
6
6
|
// to ask about one test, guessing at an ambiguous test name instead of passing
|
|
7
7
|
// filePath, and ignoring the action the API already put in the error.
|
|
8
|
+
//
|
|
9
|
+
// Exported as `squally-mcp/instructions` (package.json), so it stays a plain
|
|
10
|
+
// constant - test/exports.test.js imports it through the package name.
|
|
8
11
|
export const INSTRUCTIONS = [
|
|
9
12
|
"Start with squally-list-projects; every other tool needs a projectId from it.",
|
|
10
13
|
"For one test, use squally-get-test-status (cheap), not squally-list-flaky-tests",
|
package/dist/openapi/v1.json
CHANGED
|
@@ -131,7 +131,7 @@
|
|
|
131
131
|
"code": "test_not_found",
|
|
132
132
|
"status": 404,
|
|
133
133
|
"when": "No test with this name in this project.",
|
|
134
|
-
"action": "Check the test name
|
|
134
|
+
"action": "Check the test name and filePath exactly as Squally shows them; do not retry.",
|
|
135
135
|
"hasBody": true
|
|
136
136
|
},
|
|
137
137
|
{
|
|
@@ -1775,7 +1775,7 @@
|
|
|
1775
1775
|
"alsoActive": [
|
|
1776
1776
|
"failure_rate_broken"
|
|
1777
1777
|
],
|
|
1778
|
-
"timeLostMs":
|
|
1778
|
+
"timeLostMs": 540000,
|
|
1779
1779
|
"flakeScore": 0.9,
|
|
1780
1780
|
"flipRate": 0.05,
|
|
1781
1781
|
"failureRate": 1,
|
|
@@ -4945,7 +4945,7 @@
|
|
|
4945
4945
|
"type": "null"
|
|
4946
4946
|
}
|
|
4947
4947
|
],
|
|
4948
|
-
"description": "Time lost to failed and retried attempts in the window, ms (approximation: final attempt duration
|
|
4948
|
+
"description": "Time lost to failed and retried attempts in the window, ms (approximation: wasted attempts x the final attempt duration). A failed run wastes every attempt it made, a run rescued by a retry wastes the attempts before it, and a run that passed first time wastes none - so 0 is a real measurement. Computed for every listed test; null is a guard for a test with no occurrence in the window and should not occur here."
|
|
4949
4949
|
},
|
|
4950
4950
|
"flakeScore": {
|
|
4951
4951
|
"type": "number"
|
package/dist/tools.d.ts
CHANGED
|
@@ -10,5 +10,18 @@ export type ToolDefinition = {
|
|
|
10
10
|
title: string;
|
|
11
11
|
operationId: string;
|
|
12
12
|
description: string;
|
|
13
|
+
/**
|
|
14
|
+
* FOR PEOPLE, NOT THE MODEL: what the tool answers, in one line - the
|
|
15
|
+
* README's tool table and the docs' tool list. Never sent to a client:
|
|
16
|
+
* toolList() (server.ts) copies the wire fields one by one, and the digest
|
|
17
|
+
* pinned in test/tools.test.js would catch a leak.
|
|
18
|
+
*/
|
|
19
|
+
answers: string;
|
|
20
|
+
/**
|
|
21
|
+
* FOR PEOPLE: "expensive" is the one engine pass (§4.2.2), everything else
|
|
22
|
+
* is "cheap". The model learns the same from `description` and the server
|
|
23
|
+
* instructions, not from this.
|
|
24
|
+
*/
|
|
25
|
+
cost: "cheap" | "expensive";
|
|
13
26
|
};
|
|
14
27
|
export declare const TOOLS: ToolDefinition[];
|
package/dist/tools.js
CHANGED
|
@@ -16,6 +16,8 @@ export const TOOLS = [
|
|
|
16
16
|
operationId: "listProjects",
|
|
17
17
|
description: "Lists the projects in your Squally organization. Start here: every other tool needs a " +
|
|
18
18
|
"projectId, and this is the only tool that produces one.",
|
|
19
|
+
answers: "Which projects exist. Start here — every other tool needs a projectId from it.",
|
|
20
|
+
cost: "cheap",
|
|
19
21
|
},
|
|
20
22
|
{
|
|
21
23
|
name: "squally-find-run",
|
|
@@ -24,6 +26,8 @@ export const TOOLS = [
|
|
|
24
26
|
description: "Finds CI runs of a project - the latest, or filtered by branch, commit SHA or status. " +
|
|
25
27
|
"One row per logical run: a sharded run is collapsed into a single entry. Returns summary " +
|
|
26
28
|
"counters only; use squally-get-run for the per-test rows.",
|
|
29
|
+
answers: "Which runs happened — latest, or by branch, commit SHA or status. Counters only.",
|
|
30
|
+
cost: "cheap",
|
|
27
31
|
},
|
|
28
32
|
{
|
|
29
33
|
name: "squally-get-run",
|
|
@@ -31,6 +35,8 @@ export const TOOLS = [
|
|
|
31
35
|
operationId: "getRun",
|
|
32
36
|
description: "One run with its per-test result rows, across every shard. Use this to find out which " +
|
|
33
37
|
"test is red in a run; the run list carries only the counters.",
|
|
38
|
+
answers: "One run with its per-test rows, across all shards. Which test is red.",
|
|
39
|
+
cost: "cheap",
|
|
34
40
|
},
|
|
35
41
|
{
|
|
36
42
|
name: "squally-debug-failure",
|
|
@@ -39,6 +45,8 @@ export const TOOLS = [
|
|
|
39
45
|
description: "Every attempt of one test in one run, oldest first, each with the error, the stack and " +
|
|
40
46
|
"the Copy-for-AI prompt (the same text the Squally UI puts on the clipboard). This is the " +
|
|
41
47
|
"tool for 'why did this test fail'. If the test name is ambiguous, pass filePath.",
|
|
48
|
+
answers: "Every attempt of one test in one run: error, stack, Copy-for-AI prompt.",
|
|
49
|
+
cost: "cheap",
|
|
42
50
|
},
|
|
43
51
|
{
|
|
44
52
|
name: "squally-get-test-status",
|
|
@@ -47,6 +55,8 @@ export const TOOLS = [
|
|
|
47
55
|
description: "The stored flakiness status and active signals for ONE test. Cheap - one findUnique. " +
|
|
48
56
|
"Use this when you are asking about a single test; do not reach for " +
|
|
49
57
|
"squally-list-flaky-tests, which is expensive.",
|
|
58
|
+
answers: "The stored flakiness status of one test.",
|
|
59
|
+
cost: "cheap",
|
|
50
60
|
},
|
|
51
61
|
{
|
|
52
62
|
name: "squally-list-flaky-tests",
|
|
@@ -55,6 +65,8 @@ export const TOOLS = [
|
|
|
55
65
|
description: "The project's flaky and broken tests, ranked, with the time each has cost (timeLostMs). " +
|
|
56
66
|
"Expensive - one engine pass over the project's recent runs. For a single test use " +
|
|
57
67
|
"squally-get-test-status instead.",
|
|
68
|
+
answers: "The ranked flaky/broken list with time lost.",
|
|
69
|
+
cost: "expensive",
|
|
58
70
|
},
|
|
59
71
|
{
|
|
60
72
|
name: "squally-list-errors",
|
|
@@ -63,5 +75,7 @@ export const TOOLS = [
|
|
|
63
75
|
description: "The project's error signatures in a period: failures grouped by fingerprint, with how " +
|
|
64
76
|
"often and how recently each occurred. Answers 'is this failure one instance of something " +
|
|
65
77
|
"that keeps happening' - a grouping no agent can compute from the repository alone.",
|
|
78
|
+
answers: "Error signatures in a period: what keeps failing, grouped.",
|
|
79
|
+
cost: "cheap",
|
|
66
80
|
},
|
|
67
81
|
];
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "squally-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Local MCP server for Squally — read-only access to your Playwright test runs, flaky tests and failures.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Squally",
|
|
7
|
-
"homepage": "https://
|
|
7
|
+
"homepage": "https://docs.squally.dev/agents/mcp-server/",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
10
10
|
"url": "git+https://github.com/squallydev-admin/squally-mcp.git"
|
|
@@ -25,6 +25,21 @@
|
|
|
25
25
|
},
|
|
26
26
|
"main": "dist/index.js",
|
|
27
27
|
"types": "dist/index.d.ts",
|
|
28
|
+
"exports": {
|
|
29
|
+
".": {
|
|
30
|
+
"types": "./dist/index.d.ts",
|
|
31
|
+
"default": "./dist/index.js"
|
|
32
|
+
},
|
|
33
|
+
"./tools": {
|
|
34
|
+
"types": "./dist/tools.d.ts",
|
|
35
|
+
"default": "./dist/tools.js"
|
|
36
|
+
},
|
|
37
|
+
"./instructions": {
|
|
38
|
+
"types": "./dist/instructions.d.ts",
|
|
39
|
+
"default": "./dist/instructions.js"
|
|
40
|
+
},
|
|
41
|
+
"./package.json": "./package.json"
|
|
42
|
+
},
|
|
28
43
|
"files": [
|
|
29
44
|
"dist"
|
|
30
45
|
],
|