squally-mcp 0.1.4 → 0.2.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/dist/openapi.d.ts CHANGED
@@ -32,28 +32,34 @@ export declare function parseDocument(text: string): OpenApiDocument;
32
32
  export declare function loadDocument(): OpenApiDocument;
33
33
  export declare function operationFor(operationId: string): OpenApiOperation;
34
34
  /**
35
- * Parameters of the operation that the tools do NOT offer - a deliberate
35
+ * Parameters of an operation that its tool does NOT offer - a deliberate
36
36
  * deviation from the OpenAPI document, like PARAMETER_DESCRIPTIONS above.
37
37
  *
38
38
  * QUIETER TOOLS (25.09., 0.1.3). Every property of an inputSchema sits in the
39
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:
40
+ * model spends a decision on. These answer no question an agent asks:
41
41
  *
42
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.
43
+ * squally-find-run and squally-list-errors. "More" stays one
44
+ * call away: `cursor` (runs) and `page` (errors) are kept.
46
45
  * direction paging back towards newer runs is a person's gesture; an agent
47
46
  * that wants the newest runs calls again without a cursor.
48
47
  *
48
+ * PER OPERATION SINCE 0.2.0, where it was one set for every tool: listTests
49
+ * KEEPS perPage (1-100, default 50) - asked for by name in the 0.2.0 brief,
50
+ * and the one list whose rows an agent may want many of at once, to rank the
51
+ * whole suite in one answer rather than ten rows at a time.
52
+ *
49
53
  * Left out of the input schema AND the validator (src/validate.ts), so an
50
54
  * 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
55
+ * forwarded. test/drift.test.js checks that each is still optional upstream
52
56
  * and that the default page size is still 10 - the moment either stops being
53
57
  * true, this deviation stops being harmless.
54
58
  */
55
- export declare const OMITTED_PARAMETERS: ReadonlySet<string>;
56
- /** The parameters a tool offers: the operation's, minus OMITTED_PARAMETERS. */
59
+ export declare const OMITTED_PARAMETERS: ReadonlyMap<string, ReadonlySet<string>>;
60
+ /** The parameters `operation`'s tool leaves out - empty for most. */
61
+ export declare function omittedParameters(operation: OpenApiOperation): ReadonlySet<string>;
62
+ /** The parameters a tool offers: the operation's, minus its OMITTED_PARAMETERS. */
57
63
  export declare function toolParameters(operation: OpenApiOperation): OpenApiParameter[];
58
64
  /**
59
65
  * The operation's parameters as one JSON Schema object.
package/dist/openapi.js CHANGED
@@ -112,30 +112,43 @@ const PARAMETER_DESCRIPTIONS = {
112
112
  "Without a cursor the newest runs come first.",
113
113
  };
114
114
  /**
115
- * Parameters of the operation that the tools do NOT offer - a deliberate
115
+ * Parameters of an operation that its tool does NOT offer - a deliberate
116
116
  * deviation from the OpenAPI document, like PARAMETER_DESCRIPTIONS above.
117
117
  *
118
118
  * QUIETER TOOLS (25.09., 0.1.3). Every property of an inputSchema sits in the
119
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:
120
+ * model spends a decision on. These answer no question an agent asks:
121
121
  *
122
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.
123
+ * squally-find-run and squally-list-errors. "More" stays one
124
+ * call away: `cursor` (runs) and `page` (errors) are kept.
126
125
  * direction paging back towards newer runs is a person's gesture; an agent
127
126
  * that wants the newest runs calls again without a cursor.
128
127
  *
128
+ * PER OPERATION SINCE 0.2.0, where it was one set for every tool: listTests
129
+ * KEEPS perPage (1-100, default 50) - asked for by name in the 0.2.0 brief,
130
+ * and the one list whose rows an agent may want many of at once, to rank the
131
+ * whole suite in one answer rather than ten rows at a time.
132
+ *
129
133
  * Left out of the input schema AND the validator (src/validate.ts), so an
130
134
  * 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
135
+ * forwarded. test/drift.test.js checks that each is still optional upstream
132
136
  * and that the default page size is still 10 - the moment either stops being
133
137
  * true, this deviation stops being harmless.
134
138
  */
135
- export const OMITTED_PARAMETERS = new Set(["perPage", "direction"]);
136
- /** The parameters a tool offers: the operation's, minus OMITTED_PARAMETERS. */
139
+ export const OMITTED_PARAMETERS = new Map([
140
+ ["listRuns", new Set(["perPage", "direction"])],
141
+ ["listErrors", new Set(["perPage"])],
142
+ ]);
143
+ const NOTHING_OMITTED = new Set();
144
+ /** The parameters `operation`'s tool leaves out - empty for most. */
145
+ export function omittedParameters(operation) {
146
+ return OMITTED_PARAMETERS.get(operation.operationId) ?? NOTHING_OMITTED;
147
+ }
148
+ /** The parameters a tool offers: the operation's, minus its OMITTED_PARAMETERS. */
137
149
  export function toolParameters(operation) {
138
- return operation.parameters.filter((parameter) => !OMITTED_PARAMETERS.has(parameter.name));
150
+ const omitted = omittedParameters(operation);
151
+ return operation.parameters.filter((parameter) => !omitted.has(parameter.name));
139
152
  }
140
153
  /**
141
154
  * The operation's parameters as one JSON Schema object.
package/dist/result.d.ts CHANGED
@@ -13,6 +13,18 @@ export declare const RATE_LIMITED_TEXT = "Rate limited - wait 60 seconds, then r
13
13
  */
14
14
  export declare function expiryLine(isoDate: string): string;
15
15
  export declare function successResult(data: unknown, keyExpiresAt: string | null): CallToolResult;
16
+ /**
17
+ * The files an ambiguous_test answer names, as the filePath values to retry
18
+ * with - or null when the sentence does not have the expected shape.
19
+ *
20
+ * WHY PARSE A SENTENCE the document says "may be reworded": the files exist
21
+ * nowhere else in the answer, and the sentence names them in HTTP terms
22
+ * ("Pass ?filePath= with one of: tests/a.spec.ts, (no file).") - where
23
+ * "(no file)" is a placeholder the model must NOT copy: the argument for a
24
+ * test with no file is the empty string. A reworded sentence only costs this
25
+ * extra line; the sentence itself is always shown verbatim above it.
26
+ */
27
+ export declare function ambiguousFilePaths(message: string): string[] | null;
16
28
  export declare function failureResult(failure: ApiFailure, errorCodes: Map<string, ErrorCode>): CallToolResult;
17
29
  /**
18
30
  * WITH THE CAUSES: "fetch failed" alone names no reason; error.cause says
package/dist/result.js CHANGED
@@ -30,6 +30,27 @@ export function successResult(data, keyExpiresAt) {
30
30
  structuredContent: data,
31
31
  };
32
32
  }
33
+ /**
34
+ * The files an ambiguous_test answer names, as the filePath values to retry
35
+ * with - or null when the sentence does not have the expected shape.
36
+ *
37
+ * WHY PARSE A SENTENCE the document says "may be reworded": the files exist
38
+ * nowhere else in the answer, and the sentence names them in HTTP terms
39
+ * ("Pass ?filePath= with one of: tests/a.spec.ts, (no file).") - where
40
+ * "(no file)" is a placeholder the model must NOT copy: the argument for a
41
+ * test with no file is the empty string. A reworded sentence only costs this
42
+ * extra line; the sentence itself is always shown verbatim above it.
43
+ */
44
+ export function ambiguousFilePaths(message) {
45
+ const listed = /one of: (.+)\.$/.exec(message.trim())?.[1];
46
+ if (!listed)
47
+ return null;
48
+ return listed.split(", ").map((file) => (file === "(no file)" ? "" : file));
49
+ }
50
+ function filePathLine(paths) {
51
+ const quoted = paths.map((path) => path === "" ? `"" (the test with no file)` : JSON.stringify(path));
52
+ return `Retry with filePath set to exactly one of: ${quoted.join(", ")}`;
53
+ }
33
54
  export function failureResult(failure, errorCodes) {
34
55
  if (failure.status === 429) {
35
56
  return { content: [text(RATE_LIMITED_TEXT)], isError: true };
@@ -39,6 +60,11 @@ export function failureResult(failure, errorCodes) {
39
60
  lines.push(failure.message ?? `The Squally API answered HTTP ${failure.status}.`);
40
61
  if (failure.code)
41
62
  lines.push(`Error code: ${failure.code}`);
63
+ if (failure.code === "ambiguous_test" && failure.message) {
64
+ const paths = ambiguousFilePaths(failure.message);
65
+ if (paths && paths.length > 0)
66
+ lines.push(filePathLine(paths));
67
+ }
42
68
  if (known) {
43
69
  lines.push(`What to do: ${known.action}`);
44
70
  }
package/dist/tools.d.ts CHANGED
@@ -18,9 +18,12 @@ export type ToolDefinition = {
18
18
  */
19
19
  answers: string;
20
20
  /**
21
- * FOR PEOPLE: "expensive" is the one engine pass (§4.2.2), everything else
22
- * is "cheap". The model learns the same from `description` and the server
23
- * instructions, not from this.
21
+ * FOR PEOPLE: "expensive" was the one engine pass (§4.2.2), everything else
22
+ * is "cheap". Since 0.2.0 no tool is expensive - the engine is gone, and the
23
+ * tests list is paged in the database. The value stays in the type for the
24
+ * consumers of `squally-mcp/tools` (the docs), which render both. The model
25
+ * learns the cost from `description` and the server instructions, not from
26
+ * this.
24
27
  */
25
28
  cost: "cheap" | "expensive";
26
29
  };
package/dist/tools.js CHANGED
@@ -49,24 +49,30 @@ export const TOOLS = [
49
49
  cost: "cheap",
50
50
  },
51
51
  {
52
- name: "squally-get-test-status",
53
- title: "Get a test's status",
54
- operationId: "getTestStatus",
55
- description: "The stored flakiness status and active signals for ONE test. Cheap - one findUnique. " +
56
- "Use this when you are asking about a single test; do not reach for " +
57
- "squally-list-flaky-tests, which is expensive.",
58
- answers: "The stored flakiness status of one test.",
52
+ name: "squally-get-test-metrics",
53
+ title: "Get one test's metrics",
54
+ operationId: "getTestMetrics",
55
+ description: "One test's numbers over a period: runs, stability (runs that passed on the first try " +
56
+ "/ runs), flakyRate (runs that passed only after a retry / runs), failureRate (failed " +
57
+ "runs / runs), time lost to retries and failures, its last 20 runs and the branches it " +
58
+ "ran on. Counts completed CI runs of the period, without runs where most of the suite " +
59
+ "failed at once; local runs never count. There is no verdict - the tool returns the " +
60
+ "numbers and you judge them. runs = 0 with null rates is a valid answer: no completed " +
61
+ "CI run of this test in the period. Cheap; for one test use this, not squally-list-tests.",
62
+ answers: "One test's stability, flaky rate and failure rate over a period.",
59
63
  cost: "cheap",
60
64
  },
61
65
  {
62
- name: "squally-list-flaky-tests",
63
- title: "List flaky tests",
64
- operationId: "listFlakyTests",
65
- description: "The project's flaky and broken tests, ranked, with the time each has cost (timeLostMs). " +
66
- "Expensive - one engine pass over the project's recent runs. For a single test use " +
67
- "squally-get-test-status instead.",
68
- answers: "The ranked flaky/broken list with time lost.",
69
- cost: "expensive",
66
+ name: "squally-list-tests",
67
+ title: "List tests",
68
+ operationId: "listTests",
69
+ description: "Every test with a completed CI run in the period, with the same numbers per test as " +
70
+ "squally-get-test-metrics - runs, stability, flakyRate, failureRate, time lost - ranked " +
71
+ "worst first by the chosen sort (default: lowest stability). There is no verdict and no " +
72
+ "status - the tool labels no test; you judge the numbers. Moderate - two queries over " +
73
+ "the period, paged; for a single test use squally-get-test-metrics.",
74
+ answers: "Every test with a CI run in the period, ranked by stability, flaky rate or failures.",
75
+ cost: "cheap",
70
76
  },
71
77
  {
72
78
  name: "squally-list-errors",
package/dist/validate.js CHANGED
@@ -41,8 +41,14 @@ function integerSchema(schema) {
41
41
  }
42
42
  let out = z.number().int();
43
43
  const minimum = schema["minimum"];
44
+ const maximum = schema["maximum"];
44
45
  if (typeof minimum === "number")
45
46
  out = out.min(minimum);
47
+ // Read since 0.2.0: squally-list-tests' perPage is the first parameter with
48
+ // an upper bound (1-100). Unread, perPage=500 would pass here and come back
49
+ // from the API as a 400 about a value the model never saw refused.
50
+ if (typeof maximum === "number")
51
+ out = out.max(maximum);
46
52
  return out;
47
53
  }
48
54
  function forParameter(schema) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "squally-mcp",
3
- "version": "0.1.4",
3
+ "version": "0.2.0",
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",