@smartruns/mcp 1.0.0 → 1.0.1

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.

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'),

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.0.1",
   "description": "MCP server for the SmartRuns REST API",
   "type": "module",
   "bin": {