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 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) => {
@@ -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 the two in
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 the two in
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.parameters) {
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
+ }
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- import type { OpenApiOperation } from "./openapi.js";
2
+ import { type OpenApiOperation } from "./openapi.js";
3
3
  /**
4
4
  * A validator for one operation's arguments.
5
5
  *
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
- for (const parameter of operation.parameters) {
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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "squally-mcp",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
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",