squally-mcp 0.1.2 → 0.1.4
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 +20 -0
- package/dist/api.d.ts +3 -0
- package/dist/api.js +22 -10
- package/dist/diagnostics.d.ts +26 -0
- package/dist/diagnostics.js +78 -0
- package/dist/index.js +10 -0
- package/dist/openapi/v1.json +9 -1
- package/dist/openapi.d.ts +27 -2
- package/dist/openapi.js +35 -3
- package/dist/result.d.ts +5 -0
- package/dist/result.js +7 -1
- package/dist/server.js +8 -0
- package/dist/system-ca.d.ts +28 -0
- package/dist/system-ca.js +96 -0
- package/dist/validate.d.ts +1 -1
- package/dist/validate.js +4 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -111,6 +111,26 @@ restart the app:
|
|
|
111
111
|
|---|---|---|
|
|
112
112
|
| `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. |
|
|
113
113
|
| `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`. |
|
|
114
|
+
| `SQUALLY_USE_SYSTEM_CA` | no | `0` keeps Node's bundled certificates only. |
|
|
115
|
+
|
|
116
|
+
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.
|
|
117
|
+
|
|
118
|
+
## Troubleshooting
|
|
119
|
+
|
|
120
|
+
### Claude Desktop
|
|
121
|
+
|
|
122
|
+
- **The server does not start in time.** The first start through `npx`
|
|
123
|
+
downloads the package, which can take longer than Claude Desktop's 60-second
|
|
124
|
+
start-up limit. Install it once beforehand with `npm install -g squally-mcp`;
|
|
125
|
+
`npx -y squally-mcp` then runs that copy without a download. Update it with
|
|
126
|
+
the same command.
|
|
127
|
+
- **Where the log is.** The Microsoft Store build of Claude Desktop writes it to
|
|
128
|
+
`%LOCALAPPDATA%\Claude\logs\mcp-server-squally.log`. Its first lines say which
|
|
129
|
+
Node runs the server and whether it trusts the system's certificate store;
|
|
130
|
+
a request that never arrives is logged there with its cause.
|
|
131
|
+
- **Edit the config only while the app is closed.** Quit Claude Desktop
|
|
132
|
+
completely, including from the system tray, before changing
|
|
133
|
+
`claude_desktop_config.json`.
|
|
114
134
|
|
|
115
135
|
## The tools
|
|
116
136
|
|
package/dist/api.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Config } from "./config.js";
|
|
2
|
+
import { type ErrorCause } from "./diagnostics.js";
|
|
2
3
|
import type { OpenApiOperation } from "./openapi.js";
|
|
3
4
|
/** Set by the API from 7 days before the key expires (OpenAPI components.headers). */
|
|
4
5
|
export declare const KEY_EXPIRY_HEADER = "Squally-Key-Expires-At";
|
|
@@ -20,6 +21,8 @@ export type ApiFailure = {
|
|
|
20
21
|
export type ApiUnreachable = {
|
|
21
22
|
kind: "unreachable";
|
|
22
23
|
detail: string;
|
|
24
|
+
/** error.cause and below - where "fetch failed" keeps its reason. */
|
|
25
|
+
causes: ErrorCause[];
|
|
23
26
|
url: string;
|
|
24
27
|
};
|
|
25
28
|
export type ApiResult = ApiSuccess | ApiFailure | ApiUnreachable;
|
package/dist/api.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { errorCauses } from "./diagnostics.js";
|
|
1
2
|
/** Set by the API from 7 days before the key expires (OpenAPI components.headers). */
|
|
2
3
|
export const KEY_EXPIRY_HEADER = "Squally-Key-Expires-At";
|
|
3
4
|
/**
|
|
@@ -33,6 +34,25 @@ export function buildUrl(apiBase, operation, args) {
|
|
|
33
34
|
const suffix = query.size > 0 ? `?${query.toString()}` : "";
|
|
34
35
|
return `${apiBase}${path}${suffix}`;
|
|
35
36
|
}
|
|
37
|
+
/**
|
|
38
|
+
* Removes the key from text a network stack produced. No stack is known to
|
|
39
|
+
* echo a request header into an error, but these strings go to the model and
|
|
40
|
+
* to the client's log, and "never the key" should not rest on that.
|
|
41
|
+
*/
|
|
42
|
+
function withoutKey(text, apiKey) {
|
|
43
|
+
return apiKey ? text.split(apiKey).join("[redacted]") : text;
|
|
44
|
+
}
|
|
45
|
+
function unreachable(error, detail, url, apiKey) {
|
|
46
|
+
return {
|
|
47
|
+
kind: "unreachable",
|
|
48
|
+
detail: withoutKey(detail, apiKey),
|
|
49
|
+
causes: errorCauses(error).map((cause) => ({
|
|
50
|
+
code: cause.code === null ? null : withoutKey(cause.code, apiKey),
|
|
51
|
+
message: withoutKey(cause.message, apiKey),
|
|
52
|
+
})),
|
|
53
|
+
url,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
36
56
|
export async function callOperation(config, operation, args, fetcher = fetch) {
|
|
37
57
|
const url = buildUrl(config.apiBase, operation, args);
|
|
38
58
|
let response;
|
|
@@ -47,11 +67,7 @@ export async function callOperation(config, operation, args, fetcher = fetch) {
|
|
|
47
67
|
});
|
|
48
68
|
}
|
|
49
69
|
catch (error) {
|
|
50
|
-
return
|
|
51
|
-
kind: "unreachable",
|
|
52
|
-
detail: error instanceof Error ? error.message : String(error),
|
|
53
|
-
url,
|
|
54
|
-
};
|
|
70
|
+
return unreachable(error, error instanceof Error ? error.message : String(error), url, config.apiKey);
|
|
55
71
|
}
|
|
56
72
|
if (response.ok) {
|
|
57
73
|
let data;
|
|
@@ -62,11 +78,7 @@ export async function callOperation(config, operation, args, fetcher = fetch) {
|
|
|
62
78
|
// A 200 that is not JSON is almost always a proxy or a login page
|
|
63
79
|
// wearing our status code - worth saying so rather than reporting a
|
|
64
80
|
// 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
|
-
};
|
|
81
|
+
return unreachable(error, `the response was not JSON (${error instanceof Error ? error.message : String(error)})`, url, config.apiKey);
|
|
70
82
|
}
|
|
71
83
|
return { kind: "success", data, keyExpiresAt: response.headers.get(KEY_EXPIRY_HEADER) };
|
|
72
84
|
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** One link of an error's cause chain. */
|
|
2
|
+
export type ErrorCause = {
|
|
3
|
+
/** The system or library code (ENOTFOUND, UND_ERR_CONNECT_TIMEOUT, ...), if any. */
|
|
4
|
+
code: string | null;
|
|
5
|
+
message: string;
|
|
6
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* The causes below an error, outermost first: each `cause`, and for an
|
|
9
|
+
* AggregateError each of its `errors` before its own cause. The error itself
|
|
10
|
+
* is not included - its message is the one the caller already has. Cycles and
|
|
11
|
+
* runaway chains stop at MAX_CAUSES.
|
|
12
|
+
*/
|
|
13
|
+
export declare function errorCauses(error: unknown): ErrorCause[];
|
|
14
|
+
/** "fetch failed; cause [ENOTFOUND]: getaddrinfo ENOTFOUND app.squally.dev" */
|
|
15
|
+
export declare function describeFailure(detail: string, causes: ErrorCause[]): string;
|
|
16
|
+
/**
|
|
17
|
+
* The variables that change how Node reaches the network, matched in any
|
|
18
|
+
* case (Windows keeps whatever case they were set in; undici-style tools read
|
|
19
|
+
* both spellings of the proxy ones).
|
|
20
|
+
*/
|
|
21
|
+
export declare const NETWORK_VARIABLES: readonly ["HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY", "NO_PROXY", "NODE_EXTRA_CA_CERTS", "NODE_OPTIONS"];
|
|
22
|
+
/**
|
|
23
|
+
* One line for stderr at startup: the Node that runs this server, and which of
|
|
24
|
+
* NETWORK_VARIABLES are set - by NAME ONLY, an empty one marked as such.
|
|
25
|
+
*/
|
|
26
|
+
export declare function environmentLine(env: NodeJS.ProcessEnv, nodeVersion: string, execPath: string): string;
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// Diagnostics for the failure a user cannot see from inside a client: a
|
|
2
|
+
// request that never reached the API.
|
|
3
|
+
//
|
|
4
|
+
// WHY (25.09.): a Claude Desktop session on Windows (Microsoft Store build)
|
|
5
|
+
// answered every tool call with "fetch failed", while plain node in a terminal
|
|
6
|
+
// on the same machine reached the same URL. "fetch failed" is undici's wrapper
|
|
7
|
+
// for everything from DNS to TLS; the reason is in error.cause - and, when a
|
|
8
|
+
// connect tried several addresses, in an AggregateError's `errors`. Without
|
|
9
|
+
// them the log says nothing about which of those it was.
|
|
10
|
+
//
|
|
11
|
+
// NEVER A SECRET. The startup line names variables and never prints a value:
|
|
12
|
+
// a proxy URL can carry credentials, and NODE_OPTIONS can carry anything. The
|
|
13
|
+
// causes carry only what the network stack wrote; api.ts still scrubs the key
|
|
14
|
+
// out of them, in case a stack ever echoes a header.
|
|
15
|
+
/** Enough for any real chain (fetch -> connect -> AggregateError -> 2 addresses). */
|
|
16
|
+
const MAX_CAUSES = 8;
|
|
17
|
+
/**
|
|
18
|
+
* The causes below an error, outermost first: each `cause`, and for an
|
|
19
|
+
* AggregateError each of its `errors` before its own cause. The error itself
|
|
20
|
+
* is not included - its message is the one the caller already has. Cycles and
|
|
21
|
+
* runaway chains stop at MAX_CAUSES.
|
|
22
|
+
*/
|
|
23
|
+
export function errorCauses(error) {
|
|
24
|
+
const causes = [];
|
|
25
|
+
const seen = new Set();
|
|
26
|
+
const visit = (value) => {
|
|
27
|
+
if (value === undefined || value === null || causes.length >= MAX_CAUSES || seen.has(value))
|
|
28
|
+
return;
|
|
29
|
+
seen.add(value);
|
|
30
|
+
if (typeof value !== "object") {
|
|
31
|
+
causes.push({ code: null, message: String(value) });
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
const link = value;
|
|
35
|
+
const code = typeof link.code === "string" || typeof link.code === "number" ? String(link.code) : null;
|
|
36
|
+
// An AggregateError from a failed multi-address connect has an empty
|
|
37
|
+
// message; its name is the next best thing.
|
|
38
|
+
const message = typeof link.message === "string" && link.message !== "" ? link.message : String(link.name ?? "Error");
|
|
39
|
+
causes.push({ code, message });
|
|
40
|
+
if (Array.isArray(link.errors))
|
|
41
|
+
for (const inner of link.errors)
|
|
42
|
+
visit(inner);
|
|
43
|
+
visit(link.cause);
|
|
44
|
+
};
|
|
45
|
+
if (typeof error === "object" && error !== null)
|
|
46
|
+
visit(error.cause);
|
|
47
|
+
return causes;
|
|
48
|
+
}
|
|
49
|
+
/** "fetch failed; cause [ENOTFOUND]: getaddrinfo ENOTFOUND app.squally.dev" */
|
|
50
|
+
export function describeFailure(detail, causes) {
|
|
51
|
+
return [detail, ...causes.map((c) => (c.code ? `cause [${c.code}]: ${c.message}` : `cause: ${c.message}`))].join("; ");
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The variables that change how Node reaches the network, matched in any
|
|
55
|
+
* case (Windows keeps whatever case they were set in; undici-style tools read
|
|
56
|
+
* both spellings of the proxy ones).
|
|
57
|
+
*/
|
|
58
|
+
export const NETWORK_VARIABLES = [
|
|
59
|
+
"HTTPS_PROXY",
|
|
60
|
+
"HTTP_PROXY",
|
|
61
|
+
"ALL_PROXY",
|
|
62
|
+
"NO_PROXY",
|
|
63
|
+
"NODE_EXTRA_CA_CERTS",
|
|
64
|
+
"NODE_OPTIONS",
|
|
65
|
+
];
|
|
66
|
+
/**
|
|
67
|
+
* One line for stderr at startup: the Node that runs this server, and which of
|
|
68
|
+
* NETWORK_VARIABLES are set - by NAME ONLY, an empty one marked as such.
|
|
69
|
+
*/
|
|
70
|
+
export function environmentLine(env, nodeVersion, execPath) {
|
|
71
|
+
const rank = (name) => NETWORK_VARIABLES.indexOf(name.toUpperCase());
|
|
72
|
+
const set = Object.keys(env)
|
|
73
|
+
.filter((name) => rank(name) >= 0 && env[name] !== undefined)
|
|
74
|
+
.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
|
|
75
|
+
.map((name) => (env[name] === "" ? `${name} (empty)` : name));
|
|
76
|
+
return (`squally-mcp environment: node ${nodeVersion} at ${execPath}; ` +
|
|
77
|
+
`network variables set: ${set.length > 0 ? set.join(", ") : "none"}`);
|
|
78
|
+
}
|
package/dist/index.js
CHANGED
|
@@ -8,7 +8,9 @@
|
|
|
8
8
|
import { readFileSync } from "node:fs";
|
|
9
9
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
10
10
|
import { resolveConfig } from "./config.js";
|
|
11
|
+
import { environmentLine } from "./diagnostics.js";
|
|
11
12
|
import { createServer } from "./server.js";
|
|
13
|
+
import { systemCaLine, trustSystemCertificates } from "./system-ca.js";
|
|
12
14
|
/** Read at runtime rather than imported: npm always ships package.json, and a
|
|
13
15
|
* JSON import would need an assertion that varies across Node versions. */
|
|
14
16
|
function version() {
|
|
@@ -30,8 +32,16 @@ async function main() {
|
|
|
30
32
|
console.error(`squally-mcp: ${resolved.message}`);
|
|
31
33
|
process.exit(1);
|
|
32
34
|
}
|
|
35
|
+
// Before anything can make a request: a TLS session cached earlier would
|
|
36
|
+
// not see the added roots (src/system-ca.ts).
|
|
37
|
+
const systemCa = trustSystemCertificates(process.env);
|
|
33
38
|
const server = createServer(resolved.config, v);
|
|
34
39
|
await server.connect(new StdioServerTransport());
|
|
40
|
+
// Once, before "ready": which Node runs this, and which network variables
|
|
41
|
+
// it was given - names only (src/diagnostics.ts). A client's environment is
|
|
42
|
+
// not the user's terminal, and this is the line that shows the difference.
|
|
43
|
+
console.error(environmentLine(process.env, process.version, process.execPath));
|
|
44
|
+
console.error(systemCaLine(systemCa));
|
|
35
45
|
console.error(`squally-mcp ${v} ready - ${resolved.config.apiBase}`);
|
|
36
46
|
}
|
|
37
47
|
main().catch((error) => {
|
package/dist/openapi/v1.json
CHANGED
|
@@ -1758,6 +1758,7 @@
|
|
|
1758
1758
|
"flipRate": 0.31,
|
|
1759
1759
|
"failureRate": 0.18,
|
|
1760
1760
|
"runsConsidered": 38,
|
|
1761
|
+
"runsInWindow": 44,
|
|
1761
1762
|
"failureStreak": 0,
|
|
1762
1763
|
"lastSeenAt": "2026-09-24T07:34:05.000Z",
|
|
1763
1764
|
"lastRun": {
|
|
@@ -1780,6 +1781,7 @@
|
|
|
1780
1781
|
"flipRate": 0.05,
|
|
1781
1782
|
"failureRate": 1,
|
|
1782
1783
|
"runsConsidered": 12,
|
|
1784
|
+
"runsInWindow": 12,
|
|
1783
1785
|
"failureStreak": 12,
|
|
1784
1786
|
"lastSeenAt": "2026-09-23T16:09:31.000Z",
|
|
1785
1787
|
"lastRun": {
|
|
@@ -4964,7 +4966,12 @@
|
|
|
4964
4966
|
]
|
|
4965
4967
|
},
|
|
4966
4968
|
"runsConsidered": {
|
|
4967
|
-
"type": "integer"
|
|
4969
|
+
"type": "integer",
|
|
4970
|
+
"description": "How many runs flipRate and flakeScore are computed over (the flip_rate signal uses exactly these) - NOT how many runs the test appeared in, which is runsInWindow. Counted over the response's window, completed runs only (runs excluded as mass failures never count), one per run in which the test has a final result that is not skipped, and only runs that pass the revision filter: every run on the project's stableBranch (main when none is set) counts; a run on any other branch counts only if its testedRevision is set and equals the testedRevision of the test's previous run. Runs on other branches without a testedRevision do not count - squally-reporter sets one only with SAME_REPO_AS_APP=true or TESTED_REVISION - so a test that runs every day, but only on feature branches, can show 0. 0 therefore does not mean the test did not run, and it does not weaken the verdict: status can come from a signal that counts differently - retry_rate counts every run on every branch; consecutive_failures, failure_rate_flaky and failure_rate_broken count stableBranch runs only."
|
|
4971
|
+
},
|
|
4972
|
+
"runsInWindow": {
|
|
4973
|
+
"type": "integer",
|
|
4974
|
+
"description": "Runs in the response's window that contain this test, on all branches - the plain count, with no branch or revision filter. Completed runs only (runs excluded as mass failures never count), one per run in which the test has a final result that is not skipped. Never smaller than runsConsidered, which counts only the runs flipRate is computed over."
|
|
4968
4975
|
},
|
|
4969
4976
|
"failureStreak": {
|
|
4970
4977
|
"type": "integer"
|
|
@@ -5009,6 +5016,7 @@
|
|
|
5009
5016
|
"flipRate",
|
|
5010
5017
|
"failureRate",
|
|
5011
5018
|
"runsConsidered",
|
|
5019
|
+
"runsInWindow",
|
|
5012
5020
|
"failureStreak",
|
|
5013
5021
|
"lastSeenAt",
|
|
5014
5022
|
"lastRun"
|
package/dist/openapi.d.ts
CHANGED
|
@@ -31,6 +31,30 @@ export type OpenApiDocument = {
|
|
|
31
31
|
export declare function parseDocument(text: string): OpenApiDocument;
|
|
32
32
|
export declare function loadDocument(): OpenApiDocument;
|
|
33
33
|
export declare function operationFor(operationId: string): OpenApiOperation;
|
|
34
|
+
/**
|
|
35
|
+
* Parameters of the operation that the tools do NOT offer - a deliberate
|
|
36
|
+
* deviation from the OpenAPI document, like PARAMETER_DESCRIPTIONS above.
|
|
37
|
+
*
|
|
38
|
+
* QUIETER TOOLS (25.09., 0.1.3). Every property of an inputSchema sits in the
|
|
39
|
+
* model's context on every turn, and a parameter on offer is a parameter the
|
|
40
|
+
* model spends a decision on. These two answer no question an agent asks:
|
|
41
|
+
*
|
|
42
|
+
* perPage the page size is FIXED at the API's default, 10 rows, for
|
|
43
|
+
* squally-find-run, squally-list-flaky-tests and
|
|
44
|
+
* squally-list-errors alike. "More" stays one call away:
|
|
45
|
+
* `cursor` (runs) and `page` (flaky tests, errors) are kept.
|
|
46
|
+
* direction paging back towards newer runs is a person's gesture; an agent
|
|
47
|
+
* that wants the newest runs calls again without a cursor.
|
|
48
|
+
*
|
|
49
|
+
* Left out of the input schema AND the validator (src/validate.ts), so an
|
|
50
|
+
* agent that sends one is told it made the argument up, and none is ever
|
|
51
|
+
* forwarded. test/drift.test.js checks that both are still optional upstream
|
|
52
|
+
* and that the default page size is still 10 - the moment either stops being
|
|
53
|
+
* true, this deviation stops being harmless.
|
|
54
|
+
*/
|
|
55
|
+
export declare const OMITTED_PARAMETERS: ReadonlySet<string>;
|
|
56
|
+
/** The parameters a tool offers: the operation's, minus OMITTED_PARAMETERS. */
|
|
57
|
+
export declare function toolParameters(operation: OpenApiOperation): OpenApiParameter[];
|
|
34
58
|
/**
|
|
35
59
|
* The operation's parameters as one JSON Schema object.
|
|
36
60
|
*
|
|
@@ -38,8 +62,9 @@ export declare function operationFor(operationId: string): OpenApiOperation;
|
|
|
38
62
|
* should be told, not silently ignored - an ignored `?branch=` reads to the
|
|
39
63
|
* agent as "there are no runs on that branch".
|
|
40
64
|
*
|
|
41
|
-
* Descriptions come from the document except for
|
|
42
|
-
* PARAMETER_DESCRIPTIONS - see there for why those cannot
|
|
65
|
+
* Descriptions come from the document except for those in
|
|
66
|
+
* PARAMETER_DESCRIPTIONS - see there for why those cannot - and the parameters
|
|
67
|
+
* in OMITTED_PARAMETERS are not offered at all.
|
|
43
68
|
*/
|
|
44
69
|
export declare function inputSchemaFor(operation: OpenApiOperation): JsonSchema;
|
|
45
70
|
export declare function outputSchemaFor(operation: OpenApiOperation): JsonSchema;
|
package/dist/openapi.js
CHANGED
|
@@ -105,7 +105,38 @@ const PARAMETER_DESCRIPTIONS = {
|
|
|
105
105
|
"means a test with no file. Pass it exactly as shown in Squally; do not URL-encode, " +
|
|
106
106
|
"the server does. Needed only when the name exists in several files - the " +
|
|
107
107
|
"ambiguous_test error lists them.",
|
|
108
|
+
// The document's cursor text sends the caller to direction=prev, which the
|
|
109
|
+
// tool does not offer (OMITTED_PARAMETERS). An agent told to use a parameter
|
|
110
|
+
// it cannot send gets an "invented argument" error for following orders.
|
|
111
|
+
cursor: "Opaque. Pass nextCursor from the previous answer for the next page of older runs. " +
|
|
112
|
+
"Without a cursor the newest runs come first.",
|
|
108
113
|
};
|
|
114
|
+
/**
|
|
115
|
+
* Parameters of the operation that the tools do NOT offer - a deliberate
|
|
116
|
+
* deviation from the OpenAPI document, like PARAMETER_DESCRIPTIONS above.
|
|
117
|
+
*
|
|
118
|
+
* QUIETER TOOLS (25.09., 0.1.3). Every property of an inputSchema sits in the
|
|
119
|
+
* model's context on every turn, and a parameter on offer is a parameter the
|
|
120
|
+
* model spends a decision on. These two answer no question an agent asks:
|
|
121
|
+
*
|
|
122
|
+
* perPage the page size is FIXED at the API's default, 10 rows, for
|
|
123
|
+
* squally-find-run, squally-list-flaky-tests and
|
|
124
|
+
* squally-list-errors alike. "More" stays one call away:
|
|
125
|
+
* `cursor` (runs) and `page` (flaky tests, errors) are kept.
|
|
126
|
+
* direction paging back towards newer runs is a person's gesture; an agent
|
|
127
|
+
* that wants the newest runs calls again without a cursor.
|
|
128
|
+
*
|
|
129
|
+
* Left out of the input schema AND the validator (src/validate.ts), so an
|
|
130
|
+
* agent that sends one is told it made the argument up, and none is ever
|
|
131
|
+
* forwarded. test/drift.test.js checks that both are still optional upstream
|
|
132
|
+
* and that the default page size is still 10 - the moment either stops being
|
|
133
|
+
* true, this deviation stops being harmless.
|
|
134
|
+
*/
|
|
135
|
+
export const OMITTED_PARAMETERS = new Set(["perPage", "direction"]);
|
|
136
|
+
/** The parameters a tool offers: the operation's, minus OMITTED_PARAMETERS. */
|
|
137
|
+
export function toolParameters(operation) {
|
|
138
|
+
return operation.parameters.filter((parameter) => !OMITTED_PARAMETERS.has(parameter.name));
|
|
139
|
+
}
|
|
109
140
|
/**
|
|
110
141
|
* The operation's parameters as one JSON Schema object.
|
|
111
142
|
*
|
|
@@ -113,13 +144,14 @@ const PARAMETER_DESCRIPTIONS = {
|
|
|
113
144
|
* should be told, not silently ignored - an ignored `?branch=` reads to the
|
|
114
145
|
* agent as "there are no runs on that branch".
|
|
115
146
|
*
|
|
116
|
-
* Descriptions come from the document except for
|
|
117
|
-
* PARAMETER_DESCRIPTIONS - see there for why those cannot
|
|
147
|
+
* Descriptions come from the document except for those in
|
|
148
|
+
* PARAMETER_DESCRIPTIONS - see there for why those cannot - and the parameters
|
|
149
|
+
* in OMITTED_PARAMETERS are not offered at all.
|
|
118
150
|
*/
|
|
119
151
|
export function inputSchemaFor(operation) {
|
|
120
152
|
const properties = {};
|
|
121
153
|
const required = [];
|
|
122
|
-
for (const parameter of operation
|
|
154
|
+
for (const parameter of toolParameters(operation)) {
|
|
123
155
|
const { description, ...rest } = parameter.schema;
|
|
124
156
|
const override = PARAMETER_DESCRIPTIONS[parameter.name];
|
|
125
157
|
const text = override ?? parameter.description ?? description;
|
package/dist/result.d.ts
CHANGED
|
@@ -14,5 +14,10 @@ export declare const RATE_LIMITED_TEXT = "Rate limited - wait 60 seconds, then r
|
|
|
14
14
|
export declare function expiryLine(isoDate: string): string;
|
|
15
15
|
export declare function successResult(data: unknown, keyExpiresAt: string | null): CallToolResult;
|
|
16
16
|
export declare function failureResult(failure: ApiFailure, errorCodes: Map<string, ErrorCode>): CallToolResult;
|
|
17
|
+
/**
|
|
18
|
+
* WITH THE CAUSES: "fetch failed" alone names no reason; error.cause says
|
|
19
|
+
* whether it was DNS, a refused connect, a timeout or a certificate
|
|
20
|
+
* (src/diagnostics.ts).
|
|
21
|
+
*/
|
|
17
22
|
export declare function unreachableResult(failure: ApiUnreachable, apiBase: string): CallToolResult;
|
|
18
23
|
export declare function toolResult(result: ApiResult, errorCodes: Map<string, ErrorCode>, apiBase: string): CallToolResult;
|
package/dist/result.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { describeFailure } from "./diagnostics.js";
|
|
1
2
|
/** The one message for a rate limit, which arrives without a body. */
|
|
2
3
|
export const RATE_LIMITED_TEXT = "Rate limited - wait 60 seconds, then retry.";
|
|
3
4
|
function text(value) {
|
|
@@ -48,10 +49,15 @@ export function failureResult(failure, errorCodes) {
|
|
|
48
49
|
}
|
|
49
50
|
return { content: [text(lines.join("\n"))], isError: true };
|
|
50
51
|
}
|
|
52
|
+
/**
|
|
53
|
+
* WITH THE CAUSES: "fetch failed" alone names no reason; error.cause says
|
|
54
|
+
* whether it was DNS, a refused connect, a timeout or a certificate
|
|
55
|
+
* (src/diagnostics.ts).
|
|
56
|
+
*/
|
|
51
57
|
export function unreachableResult(failure, apiBase) {
|
|
52
58
|
return {
|
|
53
59
|
content: [
|
|
54
|
-
text(`Could not reach the Squally API at ${apiBase} (${failure.detail}). ` +
|
|
60
|
+
text(`Could not reach the Squally API at ${apiBase} (${describeFailure(failure.detail, failure.causes)}). ` +
|
|
55
61
|
"Check that the host is correct and reachable; if SQUALLY_API_URL is set, it should be " +
|
|
56
62
|
"a base URL such as https://app.squally.dev."),
|
|
57
63
|
],
|
package/dist/server.js
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
|
|
11
11
|
import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
|
|
12
12
|
import { callOperation } from "./api.js";
|
|
13
|
+
import { describeFailure } from "./diagnostics.js";
|
|
13
14
|
import { INSTRUCTIONS } from "./instructions.js";
|
|
14
15
|
import { inputSchemaFor, loadDocument, operationFor, outputSchemaFor } from "./openapi.js";
|
|
15
16
|
import { toolResult } from "./result.js";
|
|
@@ -49,6 +50,13 @@ export function createServer(config, version, fetcher = fetch) {
|
|
|
49
50
|
return { content: [{ type: "text", text: validated.message }], isError: true };
|
|
50
51
|
}
|
|
51
52
|
const result = await callOperation(config, operation, validated.args, fetcher);
|
|
53
|
+
// Also to stderr, which every client keeps as the server's log: whether a
|
|
54
|
+
// client logs tool results is up to the client; the reason a request never
|
|
55
|
+
// arrived should be readable there either way. Key-free (api.ts).
|
|
56
|
+
if (result.kind === "unreachable") {
|
|
57
|
+
console.error(`squally-mcp: ${tool.name} could not reach ${config.apiBase}: ` +
|
|
58
|
+
describeFailure(result.detail, result.causes));
|
|
59
|
+
}
|
|
52
60
|
return toolResult(result, document.errorCodes, config.apiBase);
|
|
53
61
|
});
|
|
54
62
|
return server;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/** The two tls functions this needs; absent on a Node that predates them. */
|
|
2
|
+
export type CaApi = {
|
|
3
|
+
getCACertificates?: (type?: "default" | "system" | "bundled" | "extra") => string[];
|
|
4
|
+
setDefaultCACertificates?: (certs: string[]) => void;
|
|
5
|
+
};
|
|
6
|
+
export type SystemCaOutcome = {
|
|
7
|
+
kind: "disabled";
|
|
8
|
+
} | {
|
|
9
|
+
kind: "unsupported";
|
|
10
|
+
nodeVersion: string;
|
|
11
|
+
} | {
|
|
12
|
+
kind: "failed";
|
|
13
|
+
reason: string;
|
|
14
|
+
} | {
|
|
15
|
+
kind: "loaded";
|
|
16
|
+
added: number;
|
|
17
|
+
unparseable: number;
|
|
18
|
+
};
|
|
19
|
+
/** SQUALLY_USE_SYSTEM_CA=0 (or false/no/off) opts out; anything else, or unset, opts in. */
|
|
20
|
+
export declare function systemCaDisabled(env: NodeJS.ProcessEnv): boolean;
|
|
21
|
+
/**
|
|
22
|
+
* Adds the system store's certificates to Node's default CA list for this
|
|
23
|
+
* process, and reports what it did. Never throws: a store that cannot be read
|
|
24
|
+
* leaves Node's defaults exactly as they were.
|
|
25
|
+
*/
|
|
26
|
+
export declare function trustSystemCertificates(env: NodeJS.ProcessEnv, api?: CaApi, nodeVersion?: string): SystemCaOutcome;
|
|
27
|
+
/** The one stderr line at startup. Counts only - no certificate subject. */
|
|
28
|
+
export declare function systemCaLine(outcome: SystemCaOutcome): string;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
// Trust the operating system's certificate store, IN ADDITION to Node's own.
|
|
2
|
+
//
|
|
3
|
+
// WHY (25.09., 0.1.3): behind antivirus HTTPS scanning (measured: Norton
|
|
4
|
+
// Web/Mail Shield on Windows) or a TLS-inspecting corporate proxy, every
|
|
5
|
+
// certificate the API presents is re-signed by a root that lives in the
|
|
6
|
+
// operating system's store - where browsers find it - and not in Node's
|
|
7
|
+
// bundled Mozilla list. fetch then fails with UNABLE_TO_VERIFY_LEAF_SIGNATURE
|
|
8
|
+
// and the user sees "fetch failed", while their browser opens the same URL.
|
|
9
|
+
//
|
|
10
|
+
// THE RULES, each one a decision:
|
|
11
|
+
// - ADD, never replace. The new default list is Node's current default
|
|
12
|
+
// (bundled Mozilla roots, plus NODE_EXTRA_CA_CERTS if set, plus the system
|
|
13
|
+
// store if Node already runs with --use-system-ca) and only then the system
|
|
14
|
+
// certificates it does not already contain, matched by fingerprint - the
|
|
15
|
+
// same root often comes in a different PEM encoding. Everything that
|
|
16
|
+
// connected before still connects.
|
|
17
|
+
// - Verification stays on. This changes which roots are trusted, never
|
|
18
|
+
// whether certificates are checked.
|
|
19
|
+
// - SQUALLY_USE_SYSTEM_CA=0 opts out, leaving Node's defaults untouched.
|
|
20
|
+
// - Visible: startupLine() says what happened, with a count and never a
|
|
21
|
+
// certificate subject.
|
|
22
|
+
//
|
|
23
|
+
// MECHANISM, from Node's documentation: tls.getCACertificates('system') since
|
|
24
|
+
// v22.15.0 / v23.10.0, tls.setDefaultCACertificates since v22.19.0 / v24.5.0.
|
|
25
|
+
// Both are needed; on an older Node the store is left alone and the line says
|
|
26
|
+
// so, with the flag that works there (--use-system-ca, v22.15.0 / v23.8.0).
|
|
27
|
+
// Called before the first request: sessions an agent has already cached are not
|
|
28
|
+
// affected by a later change (Node's note on setDefaultCACertificates).
|
|
29
|
+
import tls from "node:tls";
|
|
30
|
+
import { X509Certificate } from "node:crypto";
|
|
31
|
+
/** SQUALLY_USE_SYSTEM_CA=0 (or false/no/off) opts out; anything else, or unset, opts in. */
|
|
32
|
+
export function systemCaDisabled(env) {
|
|
33
|
+
const value = env.SQUALLY_USE_SYSTEM_CA?.trim().toLowerCase();
|
|
34
|
+
return value === "0" || value === "false" || value === "no" || value === "off";
|
|
35
|
+
}
|
|
36
|
+
function fingerprint(pem) {
|
|
37
|
+
return new X509Certificate(pem).fingerprint256;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Adds the system store's certificates to Node's default CA list for this
|
|
41
|
+
* process, and reports what it did. Never throws: a store that cannot be read
|
|
42
|
+
* leaves Node's defaults exactly as they were.
|
|
43
|
+
*/
|
|
44
|
+
export function trustSystemCertificates(env, api = tls, nodeVersion = process.version) {
|
|
45
|
+
if (systemCaDisabled(env))
|
|
46
|
+
return { kind: "disabled" };
|
|
47
|
+
if (typeof api.getCACertificates !== "function" || typeof api.setDefaultCACertificates !== "function") {
|
|
48
|
+
return { kind: "unsupported", nodeVersion };
|
|
49
|
+
}
|
|
50
|
+
try {
|
|
51
|
+
const current = api.getCACertificates("default");
|
|
52
|
+
const trusted = new Set(current.map(fingerprint));
|
|
53
|
+
const additions = new Map();
|
|
54
|
+
let unparseable = 0;
|
|
55
|
+
for (const pem of api.getCACertificates("system")) {
|
|
56
|
+
let id;
|
|
57
|
+
try {
|
|
58
|
+
id = fingerprint(pem);
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
// One odd entry in a system store must not cost the other hundred:
|
|
62
|
+
// setDefaultCACertificates refuses the whole list if one fails to parse.
|
|
63
|
+
unparseable += 1;
|
|
64
|
+
continue;
|
|
65
|
+
}
|
|
66
|
+
if (!trusted.has(id) && !additions.has(id))
|
|
67
|
+
additions.set(id, pem);
|
|
68
|
+
}
|
|
69
|
+
// Node's current list first and unchanged; only new certificates appended.
|
|
70
|
+
if (additions.size > 0)
|
|
71
|
+
api.setDefaultCACertificates([...current, ...additions.values()]);
|
|
72
|
+
return { kind: "loaded", added: additions.size, unparseable };
|
|
73
|
+
}
|
|
74
|
+
catch (error) {
|
|
75
|
+
return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
/** The one stderr line at startup. Counts only - no certificate subject. */
|
|
79
|
+
export function systemCaLine(outcome) {
|
|
80
|
+
switch (outcome.kind) {
|
|
81
|
+
case "loaded":
|
|
82
|
+
return (`squally-mcp TLS: trusting the operating system's certificate store in addition to ` +
|
|
83
|
+
`Node's (${outcome.added} certificate${outcome.added === 1 ? "" : "s"} added` +
|
|
84
|
+
(outcome.unparseable > 0 ? `, ${outcome.unparseable} unreadable skipped` : "") +
|
|
85
|
+
`)`);
|
|
86
|
+
case "disabled":
|
|
87
|
+
return "squally-mcp TLS: operating system's certificate store disabled by SQUALLY_USE_SYSTEM_CA - Node's bundled certificates only";
|
|
88
|
+
case "unsupported":
|
|
89
|
+
return (`squally-mcp TLS: could not load the operating system's certificate store - Node ` +
|
|
90
|
+
`${outcome.nodeVersion} cannot add it at runtime (needs 22.19+ or 24.5+); ` +
|
|
91
|
+
`NODE_OPTIONS=--use-system-ca does the same from 22.15. Using Node's bundled certificates only`);
|
|
92
|
+
case "failed":
|
|
93
|
+
return (`squally-mcp TLS: could not load the operating system's certificate store ` +
|
|
94
|
+
`(${outcome.reason}) - using Node's bundled certificates only`);
|
|
95
|
+
}
|
|
96
|
+
}
|
package/dist/validate.d.ts
CHANGED
package/dist/validate.js
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
// Built FROM the OpenAPI parameter schema rather than written beside it, for
|
|
11
11
|
// the reason src/openapi.ts gives: two descriptions of one contract drift.
|
|
12
12
|
import { z } from "zod";
|
|
13
|
+
import { toolParameters } from "./openapi.js";
|
|
13
14
|
function stringSchema(schema) {
|
|
14
15
|
const values = schema["enum"];
|
|
15
16
|
if (Array.isArray(values)) {
|
|
@@ -66,7 +67,9 @@ function forParameter(schema) {
|
|
|
66
67
|
*/
|
|
67
68
|
export function validatorFor(operation) {
|
|
68
69
|
const shape = {};
|
|
69
|
-
|
|
70
|
+
// The parameters the tool offers, not all the operation has: one the tool
|
|
71
|
+
// leaves out (OMITTED_PARAMETERS) is refused like any invented one.
|
|
72
|
+
for (const parameter of toolParameters(operation)) {
|
|
70
73
|
const base = forParameter(parameter.schema);
|
|
71
74
|
shape[parameter.name] = parameter.required ? base : base.optional();
|
|
72
75
|
}
|