@smartruns/mcp 1.0.0

package/dist/tools/specs.js

@@ -0,0 +1,146 @@
+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 }] };
+}
+// 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.
+//
+// Routes verified against config/routes.rb (`resources :specs` + member `get :history`)
+// and app/controllers/specs_controller.rb — the namespace integration tokens / PATs hit
+// (the web_app/ controller is the SPA's and is not reachable by token auth):
+//   GET    /specs              (index  → PLAIN ARRAY of list_payload, supports page/per_page)
+//   GET    /specs/:id          (show)
+//   POST   /specs              (create → spec_payload; title required, status enum)
+//   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].
+// 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.
+const acceptanceCriterionShape = z.object({
+    id: z.number().int().optional().describe('Existing acceptance criterion ID (omit to create a new one)'),
+    description: z.string().optional().describe('Acceptance criterion text'),
+    position: z.number().int().optional().describe('Ordering position (0-based)'),
+    _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.', {
+        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.'),
+    }, async ({ page, per_page, project_id }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = page;
+            if (per_page !== undefined)
+                params.per_page = per_page;
+            const result = await client.get('/specs', params, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            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.', {
+        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 }) => {
+        try {
+            const result = await client.get(`/specs/${id}`, undefined, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            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 }).', {
+        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'),
+        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 }) => {
+        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 result = await client.post('/specs', body, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            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 }.', {
+        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'),
+        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 }) => {
+        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;
+            const result = await client.put(`/specs/${id}`, body, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_spec_history', 'Get the activity/history feed for a spec (SR-370): the AuditLog entries (spec_create / spec_update / spec_delete events) for this spec, newest-first. Returns the raw history array.', {
+        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 }) => {
+        try {
+            const result = await client.get(`/specs/${id}/history`, undefined, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('delete_spec', 'Permanently delete a single spec by ID. This action is IRREVERSIBLE. Deletion is permitted wherever the authenticated user can access the spec (account/project tenant-scoped) — there is no dedicated RBAC permission gate on this route — but the server still surfaces a 403/404 if access is denied or the spec is not found.', {
+        id: z.number().int().describe('Spec 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(`/specs/${id}`, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, id }, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/statuses.js

@@ -0,0 +1,18 @@
+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 }] };
+}
+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 {
+            const result = await client.get('/status');
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/test-plans.js

@@ -0,0 +1,133 @@
+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 }] };
+}
+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'),
+        order: z.string().optional().describe('Sort order, e.g. "created_at desc"'),
+        status_id: z.number().int().optional().describe('Filter by status ID'),
+        assignee_id: z.number().int().optional().describe('Filter by assignee user ID'),
+        search: z.string().optional().describe('Search term to filter by name'),
+    }, async ({ page, order, status_id, assignee_id, search }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = page;
+            if (order !== undefined)
+                params.order = order;
+            if (status_id !== undefined)
+                params.status_id = status_id;
+            if (assignee_id !== undefined)
+                params.assignee_id = assignee_id;
+            if (search !== undefined)
+                params.search = search;
+            const result = await client.get('/test-plans', params);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_test_plan', 'Get a single test plan by ID.', {
+        id: z.number().int().describe('Test plan ID'),
+    }, async ({ id }) => {
+        try {
+            const result = await client.get(`/test-plans/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('create_test_plan', 'Create a new test plan in the current project.', {
+        name: z.string().describe('Test plan name'),
+        status: z.object({ id: z.number().int().describe('Status ID') }).describe('Status object with ID'),
+        reference: z.string().optional().describe('External reference or ticket key'),
+        preconditions: z.string().optional().describe('Preconditions for the test plan'),
+        assignee: z.object({ id: z.number().int().describe('Assignee user ID') }).optional().describe('Assignee object with user ID'),
+        labels: z.array(z.object({ id: z.number().int() })).optional().describe('Array of label objects with IDs'),
+        tests: z.array(z.object({ id: z.number().int() })).optional().describe('Array of test objects with IDs to include'),
+        stages: z.array(z.unknown()).optional().describe('Array of stage definitions'),
+        is_template: z.boolean().optional().describe('Whether this test plan is a template'),
+    }, async ({ name, status, reference, preconditions, assignee, labels, tests, stages, is_template }) => {
+        try {
+            const body = { name, status };
+            if (reference !== undefined)
+                body.reference = reference;
+            if (preconditions !== undefined)
+                body.preconditions = preconditions;
+            if (assignee !== undefined)
+                body.assignee = assignee;
+            if (labels !== undefined)
+                body.labels = labels;
+            if (tests !== undefined)
+                body.tests = tests;
+            if (stages !== undefined)
+                body.stages = stages;
+            if (is_template !== undefined)
+                body.is_template = is_template;
+            const result = await client.post('/test-plans', body);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('update_test_plan', 'Update an existing test plan. Requires the current lock_version to prevent overwriting concurrent edits.', {
+        id: z.number().int().describe('Test plan ID'),
+        lock_version: z.number().int().describe('Lock version from the last get_test_plan response — required to prevent overwriting concurrent edits'),
+        name: z.string().optional().describe('Test plan name'),
+        status: z.object({ id: z.number().int().describe('Status ID') }).optional().describe('Status object with ID'),
+        reference: z.string().optional().describe('External reference or ticket key'),
+        preconditions: z.string().optional().describe('Preconditions for the test plan'),
+        assignee: z.object({ id: z.number().int().describe('Assignee user ID') }).optional().describe('Assignee object with user ID'),
+        labels: z.array(z.object({ id: z.number().int() })).optional().describe('Array of label objects with IDs'),
+        tests: z.array(z.object({ id: z.number().int() })).optional().describe('Array of test objects with IDs to include'),
+        stages: z.array(z.unknown()).optional().describe('Array of stage definitions'),
+        is_template: z.boolean().optional().describe('Whether this test plan is a template'),
+    }, async ({ id, lock_version, name, status, reference, preconditions, assignee, labels, tests, stages, is_template }) => {
+        try {
+            const body = { lock_version };
+            if (name !== undefined)
+                body.name = name;
+            if (status !== undefined)
+                body.status = status;
+            if (reference !== undefined)
+                body.reference = reference;
+            if (preconditions !== undefined)
+                body.preconditions = preconditions;
+            if (assignee !== undefined)
+                body.assignee = assignee;
+            if (labels !== undefined)
+                body.labels = labels;
+            if (tests !== undefined)
+                body.tests = tests;
+            if (stages !== undefined)
+                body.stages = stages;
+            if (is_template !== undefined)
+                body.is_template = is_template;
+            const result = await client.put(`/test-plans/${id}`, body);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('delete_test_plan', 'Permanently delete a single test plan by ID (along with its plan-scoped tests and uploads). This action is IRREVERSIBLE. Deletion is RBAC-gated server-side (test_plans_delete_mine / test_plans_delete_all): if the authenticated user lacks permission, the API returns 403 and no record is removed.', {
+        id: z.number().int().describe('Test plan 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(`/test-plans/${id}`, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, id }, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/test-runs.js

@@ -0,0 +1,113 @@
+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 }] };
+}
+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'),
+        jira_ticket_key: z.string().optional().describe('Filter by associated Jira ticket key, e.g. "PROJ-123"'),
+    }, async ({ page, jira_ticket_key }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = page;
+            if (jira_ticket_key !== undefined)
+                params.jira_ticket_key = jira_ticket_key;
+            const result = await client.get('/test-runs', params);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_test_run', 'Get a single test run by ID.', {
+        id: z.number().int().describe('Test run ID'),
+    }, async ({ id }) => {
+        try {
+            const result = await client.get(`/test-runs/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('create_test_run', 'Create a new test run in the current project.', {
+        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'),
+        assignee: z.object({ id: z.number().int().describe('Assignee user ID') }).optional().describe('Assignee object with user ID'),
+        test_plan: z.object({ id: z.number().int().describe('Test plan ID') }).optional().describe('Associated test plan'),
+        // 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'),
+        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 }) => {
+        try {
+            const body = { status, stage };
+            if (details !== undefined)
+                body.details = details;
+            if (assignee !== undefined)
+                body.assignee = assignee;
+            if (test_plan !== undefined)
+                body.test_plan = test_plan;
+            if (testing_environment !== undefined)
+                body.testing_environment = testing_environment;
+            if (test_results !== undefined)
+                body.test_results = test_results;
+            if (custom_fields !== undefined)
+                body.custom_fields = custom_fields;
+            const result = await client.post('/test-runs', body, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('update_test_run', 'Update an existing test run. Requires the current lock_version to prevent overwriting concurrent edits.', {
+        id: z.number().int().describe('Test run ID'),
+        lock_version: z.number().int().describe('Lock version from the last get_test_run response — required to prevent overwriting concurrent edits'),
+        status: z.object({ id: z.number().int().describe('Status ID') }).optional().describe('Status object with ID'),
+        stage: z.object({ id: z.number().int().describe('Stage ID') }).optional().describe('Stage object with ID'),
+        details: z.string().optional().describe('Free-text details or description of the test run'),
+        assignee: z.object({ id: z.number().int().describe('Assignee user ID') }).optional().describe('Assignee object with user ID'),
+        test_plan: z.object({ id: z.number().int().describe('Test plan ID') }).optional().describe('Associated test plan'),
+        // Same object shape as create_test_run — bound to testing_environment_id by the API (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.object({
+            id: z.number().int().describe('Test result ID'),
+            lock_version: z.number().int().describe('Test result lock version'),
+        }).passthrough()).optional().describe('Array of test result objects with id and lock_version'),
+        custom_fields: z.record(z.string(), z.unknown()).optional().describe('Custom field key-value pairs'),
+    }, async ({ id, lock_version, status, stage, details, assignee, test_plan, testing_environment, test_results, custom_fields }) => {
+        try {
+            const body = { lock_version };
+            if (status !== undefined)
+                body.status = status;
+            if (stage !== undefined)
+                body.stage = stage;
+            if (details !== undefined)
+                body.details = details;
+            if (assignee !== undefined)
+                body.assignee = assignee;
+            if (test_plan !== undefined)
+                body.test_plan = test_plan;
+            if (testing_environment !== undefined)
+                body.testing_environment = testing_environment;
+            if (test_results !== undefined)
+                body.test_results = test_results;
+            if (custom_fields !== undefined)
+                body.custom_fields = custom_fields;
+            const result = await client.put(`/test-runs/${id}`, body);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/test-suites.js

@@ -0,0 +1,150 @@
+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 }] };
+}
+// 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 })
+//   GET    /test-suites/:id        (show)
+//   POST   /test-suites            (create)
+//   PUT    /test-suites/:id        (update — optimistic-locked via lock_version)
+//   POST   /test-suites/:id/clone  (clone member route)
+//   DELETE /test-suites/:id        (destroy — RBAC-gated, returns 200 { deleted: true })
+// The controller reads params directly (no strong-params block): name + status.id are
+// required (status_id/name presence-validated); assignee.id, jira_version_key,
+// custom_fields and test_plans are optional. There is NO web_app/ counterpart.
+export function registerTestSuiteTools(server, client) {
+    server.tool('list_test_suites', 'List test suites in the current project. Returns a paginated { entries, meta.pagination } payload.', {
+        page: z.number().int().optional().describe('Page number for pagination'),
+        order: z.string().optional().describe('Sort order as "<field>_<dir>", e.g. "created_desc", "updated_asc", "name_asc". Defaults to created_desc.'),
+        name: z.string().optional().describe('Filter by suite name (case-insensitive LIKE match)'),
+        status_id: z.number().int().optional().describe('Filter by status ID'),
+        assignee_id: z.number().int().optional().describe('Filter by assignee user ID'),
+        author_id: z.number().int().optional().describe('Filter by author user ID'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ page, order, name, status_id, assignee_id, author_id, project_id }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = page;
+            if (order !== undefined)
+                params.order = order;
+            if (name !== undefined)
+                params.name = name;
+            if (status_id !== undefined)
+                params.status_id = status_id;
+            if (assignee_id !== undefined)
+                params.assignee_id = assignee_id;
+            if (author_id !== undefined)
+                params.author_id = author_id;
+            const result = await client.get('/test-suites', params, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_test_suite', 'Get a single test suite by ID, including its test plans, watchers and lock_version.', {
+        id: z.number().int().describe('Test suite ID'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ id, project_id }) => {
+        try {
+            const result = await client.get(`/test-suites/${id}`, undefined, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('create_test_suite', 'Create a new test suite in the current project. name, status AND assignee are all required: although only name/status are model-validated, the backend rejects a missing assignee with a 409 "Assignee must exist", so assignee is de-facto required and is enforced client-side here to fail fast. Use list_statuses to find a valid status ID and list_users to find a valid assignee ID.', {
+        name: z.string().describe('Test suite name (required)'),
+        status: z.object({ id: z.number().int().describe('Status ID') }).describe('Status object with ID (required)'),
+        assignee: z.object({ id: z.number().int().describe('Assignee user ID') }).describe('Assignee object with user ID (required — the backend returns 409 "Assignee must exist" if omitted)'),
+        jira_version_key: z.string().optional().describe('Associated Jira version key'),
+        test_plans: z.array(z.object({ id: z.number().int() })).optional().describe('Array of test plan objects with IDs to attach to the suite'),
+        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 ({ name, status, assignee, jira_version_key, test_plans, custom_fields, project_id }) => {
+        try {
+            const body = { name, status, assignee };
+            if (jira_version_key !== undefined)
+                body.jira_version_key = jira_version_key;
+            if (test_plans !== undefined)
+                body.test_plans = test_plans;
+            if (custom_fields !== undefined)
+                body.custom_fields = custom_fields;
+            const result = await client.post('/test-suites', body, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('update_test_suite', 'Update an existing test suite. Requires the current lock_version to prevent overwriting concurrent edits (409 on stale). NOTE: the API overwrites name, status, assignee and jira_version_key from the payload — omitting name or status clears them and fails validation, so always include both. Use get_test_suite first to read current values.', {
+        id: z.number().int().describe('Test suite ID'),
+        lock_version: z.number().int().describe('Lock version from the last get_test_suite response — required to prevent overwriting concurrent edits'),
+        name: z.string().describe('Test suite name — must be included (the API clears it if omitted)'),
+        status: z.object({ id: z.number().int().describe('Status ID') }).describe('Status object with ID — must be included (the API clears it if omitted)'),
+        assignee: z.object({ id: z.number().int().describe('Assignee user ID') }).optional().describe('Assignee object with user ID'),
+        jira_version_key: z.string().optional().describe('Associated Jira version key'),
+        test_plans: z.array(z.object({ id: z.number().int() })).optional().describe('Array of test plan objects with IDs — replaces the current set of attached plans'),
+        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 ({ id, lock_version, name, status, assignee, jira_version_key, test_plans, custom_fields, project_id }) => {
+        try {
+            const body = { lock_version, name, status };
+            if (assignee !== undefined)
+                body.assignee = assignee;
+            if (jira_version_key !== undefined)
+                body.jira_version_key = jira_version_key;
+            if (test_plans !== undefined)
+                body.test_plans = test_plans;
+            if (custom_fields !== undefined)
+                body.custom_fields = custom_fields;
+            const result = await client.put(`/test-suites/${id}`, body, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('clone_test_suite', 'Clone an existing test suite, creating a duplicate named "Clone of \'<name>\'" with the same attached test plans and custom fields. Cloning is RBAC-gated (test_suites_create).', {
+        id: z.number().int().describe('Test suite ID to clone'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ id, project_id }) => {
+        try {
+            const result = await client.post(`/test-suites/${id}/clone`, {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('delete_test_suite', 'Permanently delete a single test suite by ID. This action is IRREVERSIBLE. Deletion is RBAC-gated server-side (test_suites_delete_mine / test_suites_delete_all): if the authenticated user lacks permission, the API returns 403 and no record is removed.', {
+        id: z.number().int().describe('Test suite 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(`/test-suites/${id}`, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, id }, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}