@smartruns/mcp 1.0.0

package/dist/tools/tests.js

@@ -0,0 +1,167 @@
+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 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'),
+        page: z.number().int().optional().describe('Page number for pagination'),
+        per_page: z.number().int().max(50).optional().describe('Number of results per page (max 50)'),
+        exclude_ids: z.string().optional().describe('Comma-separated list of test IDs to exclude from results'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, 
+    // project_id is destructured separately and passed as the trailing verb argument —
+    // never spread into params/body. This is the reference pattern for SR-378 slices 2–10.
+    async ({ search, page, per_page, exclude_ids, project_id }) => {
+        try {
+            const params = {};
+            if (search !== undefined)
+                params.search = search;
+            if (page !== undefined)
+                params.page = page;
+            if (per_page !== undefined)
+                params.per_page = per_page;
+            if (exclude_ids !== undefined)
+                params.exclude_ids = exclude_ids;
+            const result = await client.get('/tests/search', params, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_test', 'Get a single test case by ID.', {
+        id: z.number().int().describe('Test ID'),
+    }, async ({ id }) => {
+        try {
+            const result = await client.get(`/tests/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_test_history', 'Get the audit/activity history for a single test (read-only). Returns the AuditLog entries for the test, newest first — who changed what and when. Maps to GET /tests/:id/history.', {
+        id: z.number().int().describe('Test 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(`/tests/${id}/history`, {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('create_test', 'Create a new test case in the current project.', {
+        name: z.string().describe('Test case name'),
+        test_kind: z.object({ id: z.number().int().describe('Test kind ID') }).describe('Test kind — required by the API. Use get_test on an existing test to find a valid ID.'),
+        preconditions: z.string().optional().describe('Preconditions for the test'),
+        steps: z.string().optional().describe('Test steps as free text'),
+        expectation: z.string().optional().describe('Expected outcome'),
+        gherkin: z.string().optional().describe('Gherkin-format scenario (Given/When/Then)'),
+        automation_status: z.string().optional().describe('Automation status, e.g. "automated" or "manual"'),
+        product_area: z.object({ id: z.number().int().describe('Product area ID') }).optional().describe('Product area object with ID'),
+        test_preconditions: z.array(z.unknown()).optional().describe('Structured precondition objects'),
+        test_steps: z.array(z.unknown()).optional().describe('Structured test step objects'),
+        custom_fields: z.record(z.string(), z.unknown()).optional().describe('Custom field key-value pairs'),
+    }, async ({ name, test_kind, preconditions, steps, expectation, gherkin, automation_status, product_area, test_preconditions, test_steps, custom_fields }) => {
+        try {
+            const body = { name, test_kind };
+            if (preconditions !== undefined)
+                body.preconditions = preconditions;
+            if (steps !== undefined)
+                body.steps = steps;
+            if (expectation !== undefined)
+                body.expectation = expectation;
+            if (gherkin !== undefined)
+                body.gherkin = gherkin;
+            if (automation_status !== undefined)
+                body.automation_status = automation_status;
+            if (product_area !== undefined)
+                body.product_area = product_area;
+            if (test_preconditions !== undefined)
+                body.test_preconditions = test_preconditions;
+            if (test_steps !== undefined)
+                body.test_steps = test_steps;
+            if (custom_fields !== undefined)
+                body.custom_fields = custom_fields;
+            const result = await client.post('/tests', body);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('update_test', 'Update an existing test case. Requires the current lock_version to prevent overwriting concurrent edits. NOTE: test_kind must always be included — the API clears it if omitted. Use get_test first to read the current value.', {
+        id: z.number().int().describe('Test ID'),
+        lock_version: z.number().int().describe('Lock version from the last get_test response — required to prevent overwriting concurrent edits'),
+        test_kind: z.object({ id: z.number().int().describe('Test kind ID') }).describe('Test kind — must be included to avoid the API clearing it. Use get_test to read the current value.'),
+        name: z.string().optional().describe('Test case name'),
+        preconditions: z.string().optional().describe('Preconditions for the test'),
+        steps: z.string().optional().describe('Test steps as free text'),
+        expectation: z.string().optional().describe('Expected outcome'),
+        gherkin: z.string().optional().describe('Gherkin-format scenario (Given/When/Then)'),
+        automation_status: z.string().optional().describe('Automation status, e.g. "automated" or "manual"'),
+        product_area: z.object({ id: z.number().int().describe('Product area ID') }).optional().describe('Product area object with ID'),
+        test_preconditions: z.array(z.unknown()).optional().describe('Structured precondition objects'),
+        test_steps: z.array(z.unknown()).optional().describe('Structured test step objects'),
+        custom_fields: z.record(z.string(), z.unknown()).optional().describe('Custom field key-value pairs'),
+    }, async ({ id, lock_version, test_kind, name, preconditions, steps, expectation, gherkin, automation_status, product_area, test_preconditions, test_steps, custom_fields }) => {
+        try {
+            const body = { lock_version, test_kind };
+            if (name !== undefined)
+                body.name = name;
+            if (preconditions !== undefined)
+                body.preconditions = preconditions;
+            if (steps !== undefined)
+                body.steps = steps;
+            if (expectation !== undefined)
+                body.expectation = expectation;
+            if (gherkin !== undefined)
+                body.gherkin = gherkin;
+            if (automation_status !== undefined)
+                body.automation_status = automation_status;
+            if (product_area !== undefined)
+                body.product_area = product_area;
+            if (test_preconditions !== undefined)
+                body.test_preconditions = test_preconditions;
+            if (test_steps !== undefined)
+                body.test_steps = test_steps;
+            if (custom_fields !== undefined)
+                body.custom_fields = custom_fields;
+            const result = await client.put(`/tests/${id}`, body);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('clone_test', 'Clone an existing test case, creating a duplicate.', {
+        id: z.number().int().describe('Test ID to clone'),
+    }, async ({ id }) => {
+        try {
+            const result = await client.post(`/tests/${id}/clone`, {});
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('delete_test', 'Permanently delete a single test case by ID. This action is IRREVERSIBLE. Deletion is permitted wherever the authenticated user can access the test (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 test is not found. The destroy route responds 204 No Content, so success is reported as { deleted: true, id }.', {
+        id: z.number().int().describe('Test 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(`/tests/${id}`, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, id }, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/users.js

@@ -0,0 +1,27 @@
+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 registerUserTools(server, client) {
+    server.tool('list_users', 'List all users in the current account.', {}, async () => {
+        try {
+            const result = await client.get('/users');
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_current_user', 'Get the currently authenticated user profile.', {}, async () => {
+        try {
+            const result = await client.get('/users/me');
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/watchers.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+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 }] };
+}
+// Watching in SmartRuns is polymorphic and driven by two flat params,
+// `source_type` + `source_id`, on a pair of singular routes:
+//   POST   /watch  -> WatchersController#create  (add current user as watcher)
+//   DELETE /watch  -> WatchersController#destroy (remove current user as watcher)
+// The supported types are WatchersController::SUPPORTED_WATCHABLES. The watcher is
+// always the authenticated user (set server-side); the entity itself is resolved
+// with for_current_account.for_current_project, so these calls are project-scoped.
+// Keep this enum in sync with WatchersController::SUPPORTED_WATCHABLES.
+const SOURCE_TYPES = ['test', 'test_plan', 'test_run', 'test_suite', 'defect'];
+const sourceTypeSchema = z
+    .enum(SOURCE_TYPES)
+    .describe('Type of entity to watch (WatchersController::SUPPORTED_WATCHABLES).');
+export function registerWatcherTools(server, client) {
+    server.tool('watch_entity', 'Subscribe the authenticated user to notifications for an entity (test, test_plan, test_run, test_suite, or defect). Identify the entity with source_type + source_id. The watcher is always the current user (set server-side). Returns the entity\'s updated watcher list as { watchers: [...] }.', {
+        source_type: sourceTypeSchema,
+        source_id: z.number().int().describe('ID of the entity to watch'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ source_type, source_id, project_id }) => {
+        try {
+            const result = await client.post('/watch', { source_type, source_id }, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('unwatch_entity', 'Unsubscribe the authenticated user from notifications for an entity (test, test_plan, test_run, test_suite, or defect). Identify the entity with source_type + source_id. Returns the entity\'s updated watcher list as { watchers: [...] }.', {
+        source_type: sourceTypeSchema,
+        source_id: z.number().int().describe('ID of the entity to stop watching'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ source_type, source_id, project_id }) => {
+        try {
+            // DELETE /watch identifies the target via a JSON body, not the path.
+            const result = await client.delete('/watch', project_id, { source_type, source_id });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@smartruns/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the SmartRuns REST API",
+  "type": "module",
+  "bin": {
+    "smartruns-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/add-shebang.mjs",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.4"
+  }
+}