@smartruns/mcp 1.0.0 → 1.1.0

package/README.md

@@ -126,7 +126,7 @@ The workflow then builds `dist/`, runs the tests, **asserts the tag version equa
 - The tag name and the manifest version must agree — the workflow refuses to publish a
   mismatched tag.
 
-## Available Tools (61)
+## Available Tools (62)
 
 > Tip: tools marked **project-scoped** accept the optional per-call `project_id` argument.
 > Write tools on optimistically-locked entities require a `lock_version` taken from the most
@@ -208,12 +208,13 @@ The workflow then builds `dist/`, runs the tests, **asserts the tag version equa
 |------|-------------|
 | `list_statuses` | List all statuses grouped by scope (returns an object keyed by scope, not an array) |
 
-### Labels (3)
+### Labels (4)
 | Tool | Description |
 |------|-------------|
 | `list_labels` | List labels in the current project (optional `terms` search) |
 | `create_label` | Create a label (`name` only; duplicate names are allowed — no uniqueness validation) |
 | `update_label` | Rename a label by ID — this is a rename only, NOT a merge |
+| `delete_label` | Permanently delete a label by ID (IRREVERSIBLE; removes the label and its associations, not the tagged entities) |
 
 ### Watchers (2)
 | Tool | Description |

package/dist/tools/ai.js

@@ -1,11 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 // SR-387 (slice 9, BILLING-flagged). Every tool description in this file MUST begin
 // with this warning so an external LLM treats the tool cautiously and a user knows the
 // cost: invoking any of these tools generates content via the SmartRuns AI backend and

package/dist/tools/comments.js

@@ -1,10 +1,9 @@
 import { z } from 'zod';
+import { handleError as sharedHandleError } from './handle-error.js';
 function handleError(err) {
-    const e = err;
-    const msg = e.status === 403
-        ? `Forbidden (403) on ${e.method} ${e.path}: editing or deleting a comment may be restricted to its author, or your token lacks the required permission. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
+    return sharedHandleError(err, {
+        403: (e) => `Forbidden (403) on ${e.method} ${e.path}: editing or deleting a comment may be restricted to its author, or your token lacks the required permission. API response: ${JSON.stringify(e.body)}`,
+    });
 }
 // Comments in SmartRuns are polymorphic but NOT via Rails-standard commentable_type /
 // commentable_id, and NOT nested under a parent route. The CommentsController

package/dist/tools/defects.js

@@ -1,11 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 export function registerDefectTools(server, client) {
     server.tool('list_defects', 'List defects in the current project. At most ONE filter (ticket_id, pull_request_id, or test_run_id) may be specified at a time.', {
         page: z.number().int().optional().describe('Page number for pagination'),

package/dist/tools/handle-error.js

@@ -0,0 +1,44 @@
+// Shared error formatter for all MCP tools.
+//
+// SR-399: previously every tool file carried its own `handleError` that mapped
+// *every* HTTP 409 to a canned "Conflict (lock_version stale). Re-fetch and retry"
+// message. That is wrong for the many non-lock 409s the API returns (e.g.
+// "Couldn't find TestKind without an ID", "Assignee must exist", and other
+// validation conflicts): it told the LLM/user to re-fetch and retry forever on
+// errors that retrying can never resolve. SR-388 softened only test-suites.ts;
+// this centralises the correct behaviour so it is consistent everywhere.
+//
+// Rule: the stale-lock wording appears ONLY when the response body actually
+// indicates a stale optimistic-lock conflict (it carries a `lock_version` field,
+// or its message text references `lock_version`). Any other 409 surfaces the
+// server's real error body plainly, with no retry advice. Tools that need
+// status-specific guidance (e.g. comments' 403, watchers' 422) pass `overrides`.
+// True when the 409 body genuinely reflects a stale optimistic-lock conflict:
+// either a structured `lock_version` field, or a message that references it.
+export function indicatesStaleLock(body) {
+    if (typeof body === 'object' && body !== null && 'lock_version' in body) {
+        return true;
+    }
+    try {
+        return JSON.stringify(body).toLowerCase().includes('lock_version');
+    }
+    catch {
+        return false;
+    }
+}
+export function handleError(err, overrides = {}) {
+    const e = err;
+    let msg;
+    if (e.status !== undefined && overrides[e.status]) {
+        msg = overrides[e.status](e);
+    }
+    else if (e.status === 409) {
+        msg = indicatesStaleLock(e.body)
+            ? `Conflict (409, stale lock_version) on ${e.method} ${e.path}. Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
+            : `Conflict (409) on ${e.method} ${e.path}: the request conflicts with the current state (e.g. a validation conflict such as a missing/invalid reference), not a stale lock — do NOT blindly retry. API response: ${JSON.stringify(e.body)}`;
+    }
+    else {
+        msg = `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
+    }
+    return { isError: true, content: [{ type: 'text', text: msg }] };
+}

package/dist/tools/labels.js

@@ -1,12 +1,8 @@
 import { z } from 'zod';
+import { handleError } from './handle-error.js';
 // NOTE: the Label model has NO uniqueness validation, so a duplicate name is NOT rejected
 // (create/rename to an existing name succeeds with 200). Do not special-case 409 as a
 // "name already taken" conflict — surface any error uniformly.
-function handleError(err) {
-    const e = err;
-    const msg = `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
 export function registerLabelTools(server, client) {
     server.tool('list_labels', 'List labels in the current project, optionally filtered by search terms.', {
         terms: z.string().optional().describe('Search terms to filter labels by name'),
@@ -51,4 +47,19 @@ export function registerLabelTools(server, client) {
             return handleError(err);
         }
     });
+    // SR-399: DELETE /labels/:id is exposed by the backend (LabelsController#destroy,
+    // routes: `resources :labels, except: [:new, :edit, :show]`). Mirrors the other
+    // delete_* tools (client.delete forwards project_id to the WTProject header only).
+    server.tool('delete_label', 'Permanently delete a label by ID. This action is IRREVERSIBLE. The label is resolved tenant-scoped (account + project), so the server returns 404 if it does not exist in the current project. Deleting a label only removes the label itself and its associations to entities — it does not delete the tagged tests/plans. Returns { deleted: true, id } on success.', {
+        id: z.number().int().describe('Label ID to delete'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ id, project_id }) => {
+        try {
+            await client.delete(`/labels/${id}`, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, id }, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
 }

package/dist/tools/notifications.js

@@ -1,9 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 // Notifications are USER-scoped, not project-scoped: NotificationsController#base_scope
 // is Notification.for_current_account.where(user: Current.user) with no project filter.
 // Therefore these tools intentionally do NOT expose a per-call project_id arg.

package/dist/tools/projects.js

@@ -1,11 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 export function registerProjectTools(server, client) {
     server.tool('list_projects', 'List all projects in the account. Optionally filter by archived status.', {
         archived: z.boolean().optional().describe('Filter by archived status. Omit to return all projects.'),

package/dist/tools/reference-data.js

@@ -1,11 +1,7 @@
 import { z } from 'zod';
+import { handleError } from './handle-error.js';
 // These are all GET-only reference lookups, so there is no optimistic-lock conflict to
 // handle — a 409 lock_version branch would be dead code. Surface every error uniformly.
-function handleError(err) {
-    const e = err;
-    const msg = `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
 // Shared per-call project override. Every reference list below is project-scoped on the
 // backend (`for_current_account.for_current_project`), so each accepts an optional project_id
 // that overrides the WTProject header for the call (SR-378 per-call override decision).

package/dist/tools/specs.js

@@ -1,11 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 // SR-382 (slice 3) introduces this file with ONLY delete_spec. SR-384 (slice 6) adds
 // the rest of the specs toolset (list / get / create / update / history) to this same
 // file — keep additions additive and do not duplicate the file.
@@ -19,13 +13,19 @@ function handleError(err) {
 //   PUT    /specs/:id          (update → spec_payload; PARTIAL via strong-params permit)
 //   GET    /specs/:id/history  (member → PLAIN ARRAY of AuditLog entries, newest-first)
 //   DELETE /specs/:id          (destroy → { deleted: true })
-// Strong params (spec_params): title, description, status, acceptance_criteria:
-// [id, description, position, _destroy]. The controller also reads params[:tickets].
+// Strong params (spec_params): title, description, due_date, problem_statement,
+// out_of_scope, constraints, open_questions, decision_log, acceptance_criteria:
+// [id, description, position, _destroy]. The controller also resolves, via tenant-scoped
+// finders (not mass-assignment): status_id, assignee_id, product_area_id, and the
+// set-semantics arrays reviewer_ids[], label_ids[], test_plan_ids[], test_run_ids[],
+// defect_ids[]. It also reads params[:tickets]. `author` is server-set and never accepted.
+// SR-413: status migrated from the draft/active/archived enum to a configurable Status
+// record — send status_id (integer); the returned spec exposes `status` as a nested
+// object { id, name, color, category } plus the scalar status_id.
 // IMPORTANT: Spec is NOT optimistically locked — there is no lock_version column, so
 // update_spec must NOT require or send one (unlike test-suites/test-runs). Because the
 // controller uses params.permit + assign_attributes, omitted fields are left untouched,
 // so update_spec is a true partial update.
-const SPEC_STATUSES = ['draft', 'active', 'archived'];
 // Acceptance criteria are nested records. On create supply { description, position };
 // on update include { id } to edit an existing criterion or { id, _destroy: true } to
 // remove one. Shape mirrors the controller's permitted acceptance_criteria keys.
@@ -36,7 +36,7 @@ const acceptanceCriterionShape = z.object({
     _destroy: z.boolean().optional().describe('Set true to delete this existing criterion (requires id)'),
 });
 export function registerSpecTools(server, client) {
-    server.tool('list_specs', 'List specs (spec-driven-development entities) in the current project, newest first. Returns a plain array of specs, each with an acceptance_criteria_count. NOTE: Specs are feature-gated (SR-371); if the flag is off for the account the API may return 403/404, surfaced verbatim.', {
+    server.tool('list_specs', 'List specs (spec-driven-development entities) in the current project, newest first. Returns a plain array of specs, each with status (nested object), author, assignee (safe user fields), due_date, product_area, labels and acceptance_criteria_count. NOTE: Specs are feature-gated (SR-371); if the flag is off for the account the API may return 403/404, surfaced verbatim.', {
         page: z.number().int().optional().describe('Page number for pagination (default 1)'),
         per_page: z.number().int().optional().describe('Results per page (default 10)'),
         project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
@@ -54,7 +54,7 @@ export function registerSpecTools(server, client) {
             return handleError(err);
         }
     });
-    server.tool('get_spec', 'Get a single spec by ID, including its acceptance_criteria, linked Jira tickets, attachments, linked_tests and coverage roll-up.', {
+    server.tool('get_spec', 'Get a single spec by ID, including its acceptance_criteria, status (nested object), author/assignee/reviewers (safe user fields), due_date, product_area, labels, narrative fields (problem_statement, out_of_scope, constraints, open_questions, decision_log), linked Jira tickets, linked_test_plans, linked_test_runs, linked_defects, attachments, linked_tests and coverage roll-up.', {
         id: z.number().int().describe('Spec ID'),
         project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
     }, async ({ id, project_id }) => {
@@ -66,24 +66,33 @@ export function registerSpecTools(server, client) {
             return handleError(err);
         }
     });
-    server.tool('create_spec', 'Create a new spec in the current project. Only title is required; status defaults to "draft". Optionally seed acceptance_criteria (use { description, position }).', {
+    server.tool('create_spec', 'Create a new spec in the current project. Only title is required; status defaults to the project default spec status when status_id is omitted. The author is set automatically to the calling user. Optionally seed acceptance_criteria, narrative fields, ownership/scheduling, product area, labels, reviewers and links to test plans / test runs / defects.', {
         title: z.string().describe('Spec title (required — the model validates its presence)'),
-        description: z.string().optional().describe('Spec description / body'),
-        status: z.enum(SPEC_STATUSES).optional().describe('Spec status: draft (default), active or archived'),
+        description: z.string().optional().describe('Spec description / body (markdown)'),
+        status_id: z.number().int().optional().describe('Configurable Status id (scope: spec). Omit to use the project default. Cross-tenant ids are ignored.'),
+        assignee_id: z.number().int().optional().describe('User id responsible for the spec (must belong to the current account)'),
+        due_date: z.string().optional().describe('Due date, ISO yyyy-mm-dd (date only, no time)'),
+        product_area_id: z.number().int().optional().describe('Product area id to classify the spec (current account/project)'),
+        problem_statement: z.string().optional().describe('Problem statement (markdown)'),
+        out_of_scope: z.string().optional().describe('Out of scope (markdown)'),
+        constraints: z.string().optional().describe('Constraints (markdown)'),
+        open_questions: z.string().optional().describe('Open questions (markdown)'),
+        decision_log: z.string().optional().describe('Decision log (markdown)'),
+        reviewer_ids: z.array(z.number().int()).optional().describe('User ids of reviewers (set semantics — replaces the full set; [] clears)'),
+        label_ids: z.array(z.number().int()).optional().describe('Label ids to tag the spec (set semantics; [] clears)'),
+        test_plan_ids: z.array(z.number().int()).optional().describe('Test plan ids to link (set semantics; [] clears)'),
+        test_run_ids: z.array(z.number().int()).optional().describe('Test run ids to link (set semantics; [] clears)'),
+        defect_ids: z.array(z.number().int()).optional().describe('Defect ids to link (set semantics; [] clears)'),
         acceptance_criteria: z.array(acceptanceCriterionShape).optional().describe('Acceptance criteria to create with the spec, each { description, position }'),
         tickets: z.array(z.record(z.string(), z.unknown())).optional().describe('Linked Jira tickets to associate (each e.g. { id, key, name, kind, source, status })'),
         project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
-    }, async ({ title, description, status, acceptance_criteria, tickets, project_id }) => {
+    }, async ({ project_id, ...rest }) => {
         try {
-            const body = { title };
-            if (description !== undefined)
-                body.description = description;
-            if (status !== undefined)
-                body.status = status;
-            if (acceptance_criteria !== undefined)
-                body.acceptance_criteria = acceptance_criteria;
-            if (tickets !== undefined)
-                body.tickets = tickets;
+            const body = {};
+            for (const [key, value] of Object.entries(rest)) {
+                if (value !== undefined)
+                    body[key] = value;
+            }
             const result = await client.post('/specs', body, project_id);
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
@@ -91,27 +100,34 @@ export function registerSpecTools(server, client) {
             return handleError(err);
         }
     });
-    server.tool('update_spec', 'Update an existing spec. This is a PARTIAL update — only the fields you pass are changed; omitted fields are left untouched. Specs are NOT optimistically locked, so no lock_version is needed. To edit acceptance criteria include their { id }; to remove one pass { id, _destroy: true }.', {
+    server.tool('update_spec', 'Update an existing spec. This is a PARTIAL update — only the fields you pass are changed; omitted fields are left untouched. Specs are NOT optimistically locked, so no lock_version is needed. The *_ids arrays use set semantics (replace the full set; pass [] to clear). To edit acceptance criteria include their { id }; to remove one pass { id, _destroy: true }. The author cannot be changed.', {
         id: z.number().int().describe('Spec ID'),
         title: z.string().optional().describe('New spec title (omit to leave unchanged)'),
-        description: z.string().optional().describe('New spec description / body'),
-        status: z.enum(SPEC_STATUSES).optional().describe('New spec status: draft, active or archived'),
+        description: z.string().optional().describe('New spec description / body (markdown)'),
+        status_id: z.number().int().optional().describe('New configurable Status id (scope: spec). Cross-tenant ids are ignored.'),
+        assignee_id: z.number().int().optional().describe('New assignee user id (current account). Pass null to clear via the API directly.'),
+        due_date: z.string().optional().describe('Due date, ISO yyyy-mm-dd (date only)'),
+        product_area_id: z.number().int().optional().describe('Product area id (current account/project)'),
+        problem_statement: z.string().optional().describe('Problem statement (markdown)'),
+        out_of_scope: z.string().optional().describe('Out of scope (markdown)'),
+        constraints: z.string().optional().describe('Constraints (markdown)'),
+        open_questions: z.string().optional().describe('Open questions (markdown)'),
+        decision_log: z.string().optional().describe('Decision log (markdown)'),
+        reviewer_ids: z.array(z.number().int()).optional().describe('Replacement set of reviewer user ids ([] clears)'),
+        label_ids: z.array(z.number().int()).optional().describe('Replacement set of label ids ([] clears)'),
+        test_plan_ids: z.array(z.number().int()).optional().describe('Replacement set of linked test plan ids ([] clears)'),
+        test_run_ids: z.array(z.number().int()).optional().describe('Replacement set of linked test run ids ([] clears)'),
+        defect_ids: z.array(z.number().int()).optional().describe('Replacement set of linked defect ids ([] clears)'),
         acceptance_criteria: z.array(acceptanceCriterionShape).optional().describe('Acceptance criteria changes: new ones, edits (with id), or removals (id + _destroy)'),
         tickets: z.array(z.record(z.string(), z.unknown())).optional().describe('Replacement set of linked Jira tickets'),
         project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
-    }, async ({ id, title, description, status, acceptance_criteria, tickets, project_id }) => {
+    }, async ({ id, project_id, ...rest }) => {
         try {
             const body = {};
-            if (title !== undefined)
-                body.title = title;
-            if (description !== undefined)
-                body.description = description;
-            if (status !== undefined)
-                body.status = status;
-            if (acceptance_criteria !== undefined)
-                body.acceptance_criteria = acceptance_criteria;
-            if (tickets !== undefined)
-                body.tickets = tickets;
+            for (const [key, value] of Object.entries(rest)) {
+                if (value !== undefined)
+                    body[key] = value;
+            }
             const result = await client.put(`/specs/${id}`, body, project_id);
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }

package/dist/tools/statuses.js

@@ -1,10 +1,4 @@
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 export function registerStatusTools(server, client) {
     server.tool('list_statuses', 'List all available statuses grouped by scope (test plan, test run, defect, etc.). Returns an object keyed by scope name.', {}, async () => {
         try {

package/dist/tools/test-plans.js

@@ -1,11 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 export function registerTestPlanTools(server, client) {
     server.tool('list_test_plans', 'List test plans in the current project with optional filters.', {
         page: z.number().int().optional().describe('Page number for pagination'),

package/dist/tools/test-runs.js

@@ -1,11 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 export function registerTestRunTools(server, client) {
     server.tool('list_test_runs', 'List test runs in the current project with optional filters.', {
         page: z.number().int().optional().describe('Page number for pagination'),
@@ -35,7 +29,16 @@ export function registerTestRunTools(server, client) {
             return handleError(err);
         }
     });
-    server.tool('create_test_run', 'Create a new test run in the current project.', {
+    server.tool('create_test_run', [
+        'Create a new test run in the current project.',
+        '',
+        'WORKFLOW (test plans): when `test_plan` is provided, the run is AUTOMATICALLY POPULATED',
+        'server-side with one UNTESTED test result per plan test — you do NOT need to enumerate the',
+        'plan tests yourself. To record pass/fail outcomes, SET the `test_results` statuses (either',
+        'here at creation, or later via `update_test_run`). NEVER record test outcomes in a comment —',
+        'comments are for genuine commentary only; outcomes must be real `test_results` so reporting',
+        'works. Use `list_statuses` (scope `test_result`) to find valid status IDs.',
+    ].join('\n'), {
         status: z.object({ id: z.number().int().describe('Status ID') }).describe('Status object with ID'),
         stage: z.object({ id: z.number().int().describe('Stage ID') }).describe('Stage object with ID'),
         details: z.string().optional().describe('Free-text details or description of the test run'),
@@ -44,7 +47,16 @@ export function registerTestRunTools(server, client) {
         // The API binds this to testing_environment_id via params.dig(:testing_environment, :id),
         // so it must be an object { id } — a bare string is silently ignored (SR-380).
         testing_environment: z.object({ id: z.number().int().describe('Testing environment ID') }).optional().describe('Testing environment object with ID — use list_testing_environments to find a valid ID.'),
-        test_results: z.array(z.unknown()).optional().describe('Array of test result objects to include in the run'),
+        // SR-425: typed shape mirroring what the backend consumes. When `test_plan` is set the
+        // backend auto-creates UNTESTED results for any plan test not listed here, so you only need
+        // to send entries for tests you want to give a specific status/details — the rest are filled in.
+        test_results: z.array(z.object({
+            test: z.object({ id: z.number().int().describe('Test ID') }).describe('The test this result is for'),
+            status: z.object({ id: z.number().int().describe('test_result-scoped Status ID (use list_statuses)') }).describe('The outcome status for this test'),
+            details: z.string().optional().describe('Free-text notes about this result'),
+            assignee: z.object({ id: z.number().int().describe('Assignee user ID') }).optional().describe('Who this result is assigned to'),
+            run_time: z.number().optional().describe('Execution time in seconds'),
+        })).optional().describe('Explicit per-test outcomes. Optional: for a plan-backed run, omitted tests are auto-populated as UNTESTED server-side.'),
         custom_fields: z.record(z.string(), z.unknown()).optional().describe('Custom field key-value pairs'),
         project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
     }, async ({ status, stage, details, assignee, test_plan, testing_environment, test_results, custom_fields, project_id }) => {

package/dist/tools/test-suites.js

@@ -1,22 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    let msg;
-    if (e.status === 409) {
-        // Not every 409 here is a stale optimistic-lock conflict. update_test_suite can hit a
-        // lock conflict (body carries a lock_version), but create_test_suite can also return 409
-        // for a plain validation conflict (e.g. "Assignee must exist"). Only call it a lock
-        // conflict when the body actually carries lock_version, so we don't mislabel the rest.
-        const isLockConflict = typeof e.body === 'object' && e.body !== null && 'lock_version' in e.body;
-        msg = isLockConflict
-            ? `Conflict (409, stale lock_version) on ${e.method} ${e.path}. Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-            : `Conflict (409) on ${e.method} ${e.path}: the request conflicts with the current state (e.g. a validation conflict such as a missing/invalid assignee), not necessarily a stale lock. API response: ${JSON.stringify(e.body)}`;
-    }
-    else {
-        msg = `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    }
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 // SR-383 (slice 5) — full test-suites tool surface.
 // Routes verified against config/routes.rb + app/controllers/test_suites_controller.rb:
 //   GET    /test-suites            (index → { entries, meta.pagination })

package/dist/tools/tests.js

@@ -1,11 +1,5 @@
 import { z } from 'zod';
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 export function registerTestTools(server, client) {
     server.tool('list_tests', 'Search/list tests in the current project. Uses the /tests/search endpoint.', {
         search: z.string().optional().describe('Search term to filter tests by name or content'),

package/dist/tools/users.js

@@ -1,10 +1,4 @@
-function handleError(err) {
-    const e = err;
-    const msg = e.status === 409
-        ? `Conflict (lock_version stale). Re-fetch the record and retry with the updated lock_version. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
-}
+import { handleError } from './handle-error.js';
 export function registerUserTools(server, client) {
     server.tool('list_users', 'List all users in the current account.', {}, async () => {
         try {

package/dist/tools/watchers.js

@@ -1,10 +1,9 @@
 import { z } from 'zod';
+import { handleError as sharedHandleError } from './handle-error.js';
 function handleError(err) {
-    const e = err;
-    const msg = e.status === 422
-        ? `Unsupported source_type (422) on ${e.method} ${e.path}: the entity type cannot be watched. API response: ${JSON.stringify(e.body)}`
-        : `API error ${e.status} on ${e.method} ${e.path}: ${JSON.stringify(e.body)}`;
-    return { isError: true, content: [{ type: 'text', text: msg }] };
+    return sharedHandleError(err, {
+        422: (e) => `Unsupported source_type (422) on ${e.method} ${e.path}: the entity type cannot be watched. API response: ${JSON.stringify(e.body)}`,
+    });
 }
 // Watching in SmartRuns is polymorphic and driven by two flat params,
 // `source_type` + `source_id`, on a pair of singular routes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartruns/mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for the SmartRuns REST API",
   "type": "module",
   "bin": {
@@ -28,9 +28,9 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.9"
   }
 }