squally-mcp 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Squally
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,149 @@
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 CI runs happened, which
5
+ tests are flaky, 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**, their names and stable branches;
27
+ - your **CI runs** — commit SHA, branch, author, timing, pass/fail counts;
28
+ - **per-test results** for a run, including which shard ran what;
29
+ - for a failing attempt: the **error message and stack**, the **captured
30
+ browser console**, and the **Copy-for-AI prompt** — which contains
31
+ **verbatim source code from your test file** and an **ARIA snapshot of your
32
+ application at the moment of failure** (whatever was on screen, truncated to
33
+ 3000 characters);
34
+ - **flakiness verdicts** and how much time each flaky test has cost;
35
+ - **error signatures**: failures grouped across runs and branches.
36
+
37
+ It cannot see screenshots, videos or traces — artifacts are deliberately out of
38
+ scope — and it cannot see any key, secret or webhook URL.
39
+
40
+ The key reaches **every project in the organization**. Create one per machine so
41
+ a single revocation does not lock out everything, and revoke it in Settings →
42
+ API keys when the machine is retired.
43
+
44
+ ## Setup
45
+
46
+ You need an **organization read key** (`sqly_ro_…`): Squally → Settings → API
47
+ keys → *Create read key*. It is shown once. It is not the same thing as the
48
+ project ingest key your Playwright reporter uses — this server refuses that one
49
+ by name.
50
+
51
+ Requires **Node 22 or newer**. Read keys are available from the **Standard**
52
+ plan.
53
+
54
+ ### Claude Code
55
+
56
+ ```bash
57
+ claude mcp add squally --scope user \
58
+ --env SQUALLY_API_KEY=sqly_ro_your_key_here \
59
+ -- npx -y squally-mcp
60
+ ```
61
+
62
+ ### Codex
63
+
64
+ `~/.codex/config.toml`:
65
+
66
+ ```toml
67
+ [mcp_servers.squally]
68
+ command = "npx"
69
+ args = ["-y", "squally-mcp"]
70
+ env = { SQUALLY_API_KEY = "sqly_ro_your_key_here" }
71
+ ```
72
+
73
+ ### Cursor
74
+
75
+ `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
76
+
77
+ ```json
78
+ {
79
+ "mcpServers": {
80
+ "squally": {
81
+ "command": "npx",
82
+ "args": ["-y", "squally-mcp"],
83
+ "env": { "SQUALLY_API_KEY": "sqly_ro_your_key_here" }
84
+ }
85
+ }
86
+ }
87
+ ```
88
+
89
+ ### Claude Desktop
90
+
91
+ `claude_desktop_config.json` — macOS:
92
+ `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\` — then
93
+ restart the app:
94
+
95
+ ```json
96
+ {
97
+ "mcpServers": {
98
+ "squally": {
99
+ "command": "npx",
100
+ "args": ["-y", "squally-mcp"],
101
+ "env": { "SQUALLY_API_KEY": "sqly_ro_your_key_here" }
102
+ }
103
+ }
104
+ }
105
+ ```
106
+
107
+ ## Environment
108
+
109
+ | Variable | Required | Meaning |
110
+ |---|---|---|
111
+ | `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. |
112
+ | `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`. |
113
+
114
+ ## The tools
115
+
116
+ | Tool | What it answers | Cost |
117
+ |---|---|---|
118
+ | `squally-list-projects` | Which projects exist. **Start here** — every other tool needs a `projectId` from it. | cheap |
119
+ | `squally-find-run` | Which runs happened — latest, or by branch, commit SHA or status. Counters only. | cheap |
120
+ | `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, console, Copy-for-AI prompt. | cheap |
122
+ | `squally-get-test-status` | The stored flakiness status of **one** test. | cheap — one lookup |
123
+ | `squally-list-flaky-tests` | The ranked flaky/broken list with time lost. | **expensive — one engine pass** |
124
+ | `squally-list-errors` | Error signatures in a period: what keeps failing, grouped. | cheap |
125
+
126
+ For a single test use `squally-get-test-status`, not
127
+ `squally-list-flaky-tests` — the tool descriptions say so, and the server
128
+ repeats it in its instructions, because the difference is one database lookup
129
+ against a pass over the project's recent runs.
130
+
131
+ ## Development
132
+
133
+ ```bash
134
+ npm install
135
+ npm run build # tsc, then copy the vendored OpenAPI document into dist/
136
+ npm test # builds, then runs the suite
137
+ npm run vendor:openapi # re-fetch the API document; review the diff, then re-pin
138
+ ```
139
+
140
+ The tool schemas are **derived from Squally's published OpenAPI document**,
141
+ vendored at `src/openapi/v1.json` — an input schema is the operation's
142
+ parameters, an output schema is its 200 response. Nothing is transcribed by
143
+ hand, so the two cannot drift. `test/drift.test.js` compares the vendored copy
144
+ against the live document and fails when an operation or parameter has moved;
145
+ it skips loudly when offline.
146
+
147
+ ## License
148
+
149
+ MIT
package/dist/api.d.ts ADDED
@@ -0,0 +1,38 @@
1
+ import type { Config } from "./config.js";
2
+ import type { OpenApiOperation } from "./openapi.js";
3
+ /** Set by the API from 7 days before the key expires (OpenAPI components.headers). */
4
+ export declare const KEY_EXPIRY_HEADER = "Squally-Key-Expires-At";
5
+ export type ApiSuccess = {
6
+ kind: "success";
7
+ data: unknown;
8
+ /** The header's value when present, otherwise null. */
9
+ keyExpiresAt: string | null;
10
+ };
11
+ export type ApiFailure = {
12
+ kind: "failure";
13
+ status: number;
14
+ /** The API's own sentence, when it sent a body. */
15
+ message: string | null;
16
+ /** The API's stable slug, when it sent a body. */
17
+ code: string | null;
18
+ };
19
+ /** The request never reached the API, or the answer was not JSON. */
20
+ export type ApiUnreachable = {
21
+ kind: "unreachable";
22
+ detail: string;
23
+ url: string;
24
+ };
25
+ export type ApiResult = ApiSuccess | ApiFailure | ApiUnreachable;
26
+ /**
27
+ * Builds the request URL.
28
+ *
29
+ * PATH VALUES ARE ENCODED, and the one that matters is testName. A Playwright
30
+ * test name contains "/" whenever the spec file sits in a folder, and the API
31
+ * expects it as %2F - read-api-mcp-spec §4.2 measured exactly this: "%2F
32
+ * matches the [testName] route and arrives decoded; an unencoded a/b is a
33
+ * different path and 404s". encodeURIComponent does that, and leaves the rest
34
+ * of the name alone.
35
+ */
36
+ export declare function buildUrl(apiBase: string, operation: OpenApiOperation, args: Record<string, unknown>): string;
37
+ export type Fetcher = typeof fetch;
38
+ export declare function callOperation(config: Config, operation: OpenApiOperation, args: Record<string, unknown>, fetcher?: Fetcher): Promise<ApiResult>;
package/dist/api.js ADDED
@@ -0,0 +1,90 @@
1
+ /** Set by the API from 7 days before the key expires (OpenAPI components.headers). */
2
+ export const KEY_EXPIRY_HEADER = "Squally-Key-Expires-At";
3
+ /**
4
+ * Builds the request URL.
5
+ *
6
+ * PATH VALUES ARE ENCODED, and the one that matters is testName. A Playwright
7
+ * test name contains "/" whenever the spec file sits in a folder, and the API
8
+ * expects it as %2F - read-api-mcp-spec §4.2 measured exactly this: "%2F
9
+ * matches the [testName] route and arrives decoded; an unencoded a/b is a
10
+ * different path and 404s". encodeURIComponent does that, and leaves the rest
11
+ * of the name alone.
12
+ */
13
+ export function buildUrl(apiBase, operation, args) {
14
+ let path = operation.path;
15
+ for (const parameter of operation.parameters) {
16
+ if (parameter.in !== "path")
17
+ continue;
18
+ const value = args[parameter.name];
19
+ path = path.replace(`{${parameter.name}}`, encodeURIComponent(String(value)));
20
+ }
21
+ const query = new URLSearchParams();
22
+ for (const parameter of operation.parameters) {
23
+ if (parameter.in !== "query")
24
+ continue;
25
+ const value = args[parameter.name];
26
+ // Omitted rather than sent empty: the API is strict about query values and
27
+ // answers invalid_parameter rather than falling back to a default, so an
28
+ // empty string would turn "not specified" into a 400.
29
+ if (value === undefined || value === null || value === "")
30
+ continue;
31
+ query.set(parameter.name, String(value));
32
+ }
33
+ const suffix = query.size > 0 ? `?${query.toString()}` : "";
34
+ return `${apiBase}${path}${suffix}`;
35
+ }
36
+ export async function callOperation(config, operation, args, fetcher = fetch) {
37
+ const url = buildUrl(config.apiBase, operation, args);
38
+ let response;
39
+ try {
40
+ response = await fetcher(url, {
41
+ method: operation.method,
42
+ headers: {
43
+ authorization: `Bearer ${config.apiKey}`,
44
+ accept: "application/json",
45
+ "user-agent": config.userAgent,
46
+ },
47
+ });
48
+ }
49
+ catch (error) {
50
+ return {
51
+ kind: "unreachable",
52
+ detail: error instanceof Error ? error.message : String(error),
53
+ url,
54
+ };
55
+ }
56
+ if (response.ok) {
57
+ let data;
58
+ try {
59
+ data = await response.json();
60
+ }
61
+ catch (error) {
62
+ // A 200 that is not JSON is almost always a proxy or a login page
63
+ // wearing our status code - worth saying so rather than reporting a
64
+ // parse error the user cannot place.
65
+ return {
66
+ kind: "unreachable",
67
+ detail: `the response was not JSON (${error instanceof Error ? error.message : String(error)})`,
68
+ url,
69
+ };
70
+ }
71
+ return { kind: "success", data, keyExpiresAt: response.headers.get(KEY_EXPIRY_HEADER) };
72
+ }
73
+ // 429 carries no body - it comes from the edge firewall, not the
74
+ // application (§4.5, and x-error-codes marks it hasBody: false). Every other
75
+ // status is expected to carry {error, code}; a missing body is tolerated
76
+ // rather than treated as a second failure.
77
+ let message = null;
78
+ let code = null;
79
+ try {
80
+ const body = (await response.json());
81
+ if (typeof body?.error === "string")
82
+ message = body.error;
83
+ if (typeof body?.code === "string")
84
+ code = body.code;
85
+ }
86
+ catch {
87
+ // Left null; the caller has a sentence for every status either way.
88
+ }
89
+ return { kind: "failure", status: response.status, message, code };
90
+ }
@@ -0,0 +1,49 @@
1
+ /** The host the server talks to unless SQUALLY_API_URL says otherwise. */
2
+ export declare const DEFAULT_BASE_URL = "https://app.squally.dev";
3
+ /** Every route this server calls lives under this prefix. */
4
+ export declare const API_PREFIX = "/api/v1";
5
+ /**
6
+ * An organization READ key. The `_ro_` infix is a promise (read-api-mcp-spec
7
+ * §11 Q2): a key with this prefix can never gain a write scope.
8
+ */
9
+ export declare const READ_KEY_PREFIX = "sqly_ro_";
10
+ /**
11
+ * A project INGEST key - what the Playwright reporter uses. It is one
12
+ * character-class away from a read key, which is exactly why it is worth
13
+ * catching here (spec §2.4): sent to a read route it would earn a 401 that
14
+ * says "invalid key", and the user would go looking for a typo instead of
15
+ * reading the prefix.
16
+ */
17
+ export declare const INGEST_KEY_PREFIX = "sqly_";
18
+ export type Config = {
19
+ /** Fully-qualified, ending in /api/v1 and never in a slash. */
20
+ apiBase: string;
21
+ apiKey: string;
22
+ userAgent: string;
23
+ };
24
+ /**
25
+ * Turns whatever the user put in SQUALLY_API_URL into a base this server can
26
+ * append paths to.
27
+ *
28
+ * Accepts the three spellings people actually write - `https://host`,
29
+ * `https://host/`, `https://host/api/v1` - and produces one. Tolerating the
30
+ * third matters: the OpenAPI document's `servers` entry IS
31
+ * `https://app.squally.dev/api/v1`, so copying it out of the docs is the
32
+ * obvious mistake, and the result would otherwise be a silent
33
+ * `/api/v1/api/v1/...` that 404s while naming the right host.
34
+ */
35
+ export declare function normaliseBaseUrl(raw: string): string;
36
+ export type ConfigResult = {
37
+ ok: true;
38
+ config: Config;
39
+ } | {
40
+ ok: false;
41
+ message: string;
42
+ };
43
+ /**
44
+ * Resolves the configuration, or says in one sentence what to fix.
45
+ *
46
+ * Returns rather than throws, so index.ts owns the exit: a stack trace in a
47
+ * client's MCP log is noise, and the one line below is the whole diagnosis.
48
+ */
49
+ export declare function resolveConfig(env: NodeJS.ProcessEnv, version: string): ConfigResult;
package/dist/config.js ADDED
@@ -0,0 +1,86 @@
1
+ // Where the key and the base URL come from, and what is refused before a
2
+ // single request is made.
3
+ //
4
+ // NOTHING HERE EVER PRINTS A KEY. Every message names the variable, never its
5
+ // value - the same rule squally-reporter adopted after a key reached a results
6
+ // file in plain text. A server whose first line of output leaks a credential
7
+ // into a client's log has failed before it started.
8
+ /** The host the server talks to unless SQUALLY_API_URL says otherwise. */
9
+ export const DEFAULT_BASE_URL = "https://app.squally.dev";
10
+ /** Every route this server calls lives under this prefix. */
11
+ export const API_PREFIX = "/api/v1";
12
+ /**
13
+ * An organization READ key. The `_ro_` infix is a promise (read-api-mcp-spec
14
+ * §11 Q2): a key with this prefix can never gain a write scope.
15
+ */
16
+ export const READ_KEY_PREFIX = "sqly_ro_";
17
+ /**
18
+ * A project INGEST key - what the Playwright reporter uses. It is one
19
+ * character-class away from a read key, which is exactly why it is worth
20
+ * catching here (spec §2.4): sent to a read route it would earn a 401 that
21
+ * says "invalid key", and the user would go looking for a typo instead of
22
+ * reading the prefix.
23
+ */
24
+ export const INGEST_KEY_PREFIX = "sqly_";
25
+ /**
26
+ * Turns whatever the user put in SQUALLY_API_URL into a base this server can
27
+ * append paths to.
28
+ *
29
+ * Accepts the three spellings people actually write - `https://host`,
30
+ * `https://host/`, `https://host/api/v1` - and produces one. Tolerating the
31
+ * third matters: the OpenAPI document's `servers` entry IS
32
+ * `https://app.squally.dev/api/v1`, so copying it out of the docs is the
33
+ * obvious mistake, and the result would otherwise be a silent
34
+ * `/api/v1/api/v1/...` that 404s while naming the right host.
35
+ */
36
+ export function normaliseBaseUrl(raw) {
37
+ let base = raw.trim();
38
+ while (base.endsWith("/"))
39
+ base = base.slice(0, -1);
40
+ if (base.endsWith(API_PREFIX))
41
+ base = base.slice(0, -API_PREFIX.length);
42
+ while (base.endsWith("/"))
43
+ base = base.slice(0, -1);
44
+ return base + API_PREFIX;
45
+ }
46
+ /**
47
+ * Resolves the configuration, or says in one sentence what to fix.
48
+ *
49
+ * Returns rather than throws, so index.ts owns the exit: a stack trace in a
50
+ * client's MCP log is noise, and the one line below is the whole diagnosis.
51
+ */
52
+ export function resolveConfig(env, version) {
53
+ const apiKey = env.SQUALLY_API_KEY?.trim();
54
+ if (!apiKey) {
55
+ return {
56
+ ok: false,
57
+ message: "SQUALLY_API_KEY is not set. Create an organization read key in Squally under " +
58
+ "Settings -> API keys and set it in this server's environment.",
59
+ };
60
+ }
61
+ // The order matters: an ingest key DOES start with sqly_, so the read-key
62
+ // test has to come first or every read key would be reported as an ingest
63
+ // key.
64
+ if (!apiKey.startsWith(READ_KEY_PREFIX) && apiKey.startsWith(INGEST_KEY_PREFIX)) {
65
+ return {
66
+ ok: false,
67
+ message: "SQUALLY_API_KEY looks like a project ingest key; the MCP server needs an " +
68
+ "organization read key (Settings -> API keys). A read key starts with " +
69
+ `${READ_KEY_PREFIX} and is created separately from the ingest key your ` +
70
+ "Playwright reporter uses.",
71
+ };
72
+ }
73
+ // A key matching neither prefix is passed through on purpose: the server is
74
+ // the authority on what a valid key is, and it answers invalid_key with a
75
+ // sentence of its own. Guessing here would mean maintaining a second copy of
76
+ // that rule in a client we do not control the release of.
77
+ const rawBase = env.SQUALLY_API_URL?.trim();
78
+ return {
79
+ ok: true,
80
+ config: {
81
+ apiBase: rawBase ? normaliseBaseUrl(rawBase) : normaliseBaseUrl(DEFAULT_BASE_URL),
82
+ apiKey,
83
+ userAgent: `squally-mcp/${version}`,
84
+ },
85
+ };
86
+ }
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,40 @@
1
+ #!/usr/bin/env node
2
+ // squally-mcp - a local MCP server over stdio for Squally's read API.
3
+ //
4
+ // STDERR FOR EVERYTHING HUMAN. stdout is the MCP transport: one stray
5
+ // console.log there corrupts the JSON-RPC stream and the client reports a
6
+ // protocol error rather than the message that was written. Every diagnostic
7
+ // below therefore goes to stderr, which clients surface as the server's log.
8
+ import { readFileSync } from "node:fs";
9
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
10
+ import { resolveConfig } from "./config.js";
11
+ import { createServer } from "./server.js";
12
+ /** Read at runtime rather than imported: npm always ships package.json, and a
13
+ * JSON import would need an assertion that varies across Node versions. */
14
+ function version() {
15
+ try {
16
+ const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
17
+ return JSON.parse(raw).version ?? "0.0.0";
18
+ }
19
+ catch {
20
+ return "0.0.0";
21
+ }
22
+ }
23
+ async function main() {
24
+ const v = version();
25
+ const resolved = resolveConfig(process.env, v);
26
+ if (!resolved.ok) {
27
+ // One line, then stop. A server that starts without a key would answer
28
+ // every tool call with the same 401 and leave the user reading API errors
29
+ // for a configuration problem.
30
+ console.error(`squally-mcp: ${resolved.message}`);
31
+ process.exit(1);
32
+ }
33
+ const server = createServer(resolved.config, v);
34
+ await server.connect(new StdioServerTransport());
35
+ console.error(`squally-mcp ${v} ready - ${resolved.config.apiBase}`);
36
+ }
37
+ main().catch((error) => {
38
+ console.error(`squally-mcp: ${error instanceof Error ? error.message : String(error)}`);
39
+ process.exit(1);
40
+ });
@@ -0,0 +1 @@
1
+ export declare const INSTRUCTIONS: string;
@@ -0,0 +1,13 @@
1
+ // The server's `instructions` - what a client puts in front of the model once,
2
+ // before any tool is called (decided 24.09.).
3
+ //
4
+ // Four sentences, each preventing one concrete mistake: starting without a
5
+ // projectId (which every other tool needs), reaching for the expensive ranking
6
+ // to ask about one test, guessing at an ambiguous test name instead of passing
7
+ // filePath, and ignoring the action the API already put in the error.
8
+ export const INSTRUCTIONS = [
9
+ "Start with squally-list-projects; every other tool needs a projectId from it.",
10
+ "For one test, use squally-get-test-status (cheap), not squally-list-flaky-tests",
11
+ "(expensive, one engine pass). If a test name is ambiguous, repeat with filePath",
12
+ "from the error. Errors carry a code and an action; follow the action.",
13
+ ].join(" ");