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 +21 -0
- package/README.md +149 -0
- package/dist/api.d.ts +38 -0
- package/dist/api.js +90 -0
- package/dist/config.d.ts +49 -0
- package/dist/config.js +86 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +40 -0
- package/dist/instructions.d.ts +1 -0
- package/dist/instructions.js +13 -0
- package/dist/openapi/v1.json +6006 -0
- package/dist/openapi.d.ts +45 -0
- package/dist/openapi.js +139 -0
- package/dist/result.d.ts +18 -0
- package/dist/result.js +70 -0
- package/dist/server.d.ts +8 -0
- package/dist/server.js +55 -0
- package/dist/tools.d.ts +14 -0
- package/dist/tools.js +67 -0
- package/dist/validate.d.ts +20 -0
- package/dist/validate.js +88 -0
- package/package.json +48 -0
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
|
+
}
|
package/dist/config.d.ts
ADDED
|
@@ -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
|
+
}
|
package/dist/index.d.ts
ADDED
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(" ");
|