@smartruns/mcp 1.0.0

package/dist/tools/ai.js

@@ -0,0 +1,134 @@
+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-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
+// consumes the account's AI credits (and may incur billing). This is a hard AC (AC3).
+const CREDIT_WARNING = '⚠ Consumes AI credits and may incur billing — invoking this generates content via the SmartRuns AI backend.';
+export function registerAiTools(server, client) {
+    // SYNCHRONOUS. POST /tests/generate-tests-with-ai (collection action `generate` in
+    // TestsController). Body: { jira_ticket_key }. Returns the generated proposal JSON in
+    // the same response (TestCaseGenerator.call). Consumes AI credits server-side.
+    server.tool('generate_tests_with_ai', `${CREDIT_WARNING} Synchronously generates proposed test cases for a Jira ticket and returns them in the response. This is a SYNCHRONOUS call (no polling needed). For the richer async agent-task flow with progress logs and confirmation, use create_agent_task instead.`, {
+        jira_ticket_key: z.string().describe('Jira ticket key to generate tests from, e.g. "SR-123" (required)'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ jira_ticket_key, project_id }) => {
+        try {
+            const result = await client.post('/tests/generate-tests-with-ai', { jira_ticket_key }, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    // ASYNC fire-and-forget. POST /tests/:id/request-ai-suggestions (member action) enqueues
+    // TestAiWorker and returns { status: 'job scheduled' } immediately. There is NO dedicated
+    // poll endpoint for this worker — re-read the test (get_test) afterwards to see suggestions.
+    server.tool('request_ai_suggestions', `${CREDIT_WARNING} Asynchronously requests AI suggestions/improvements for an EXISTING test case. Enqueues a background job and returns immediately with { status: "job scheduled" } — it does NOT return the suggestions inline and has no dedicated poll endpoint; re-read the test with get_test after a short delay to see the applied suggestions.`, {
+        id: z.number().int().describe('ID of the existing test to request AI suggestions for (required)'),
+        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(`/tests/${id}/request-ai-suggestions`, {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    // ASYNC create→poll→confirm. POST /agent_tasks creates an AgentTask, returns 202 with
+    // { task: { id, status: { value } } } where status starts at "pending"/"running". The
+    // create is CREDIT-GATED server-side (enforce_ai_credits!): when the account has
+    // exhausted its monthly AI credits the API returns 403 { error: { code: 'plan_limit' } }.
+    // Do NOT block inside this tool — poll get_agent_task until the status is terminal.
+    server.tool('create_agent_task', `${CREDIT_WARNING} Creates an ASYNCHRONOUS AI agent task (test-case generation or requirements review) and returns its task id immediately (HTTP 202) — it does NOT wait for completion. Poll get_agent_task with the returned id until status is terminal (succeeded / failed / awaiting_confirmation). If AI credits are exhausted the API returns 403 plan_limit and no task is created. For a TestCaseGenerationTask that reaches "awaiting_confirmation", call confirm_agent_task to persist the generated tests.`, {
+        type: z.string().optional().describe('Task type: "test_case_generation" (default, or "TestCaseGenerationTask") or "requirements_review" (or "RequirementsReviewTask"). Omit for test-case generation.'),
+        jira_ticket_key: z.string().optional().describe('Jira ticket key to drive the task, e.g. "SR-123". Provide this or jira_ticket_keys.'),
+        jira_ticket_keys: z.array(z.string()).optional().describe('Multiple Jira ticket keys (alternative to jira_ticket_key).'),
+        custom_instructions: z.string().optional().describe('Extra guidance appended to the AI prompt.'),
+        selected_bot_id: z.number().int().optional().describe('Associate the run with a specific bot profile.'),
+        create_test_plan: z.boolean().optional().describe('TestCaseGenerationTask only: also create a test plan from the generated tests.'),
+        spec_id: z.number().int().optional().describe('TestCaseGenerationTask only: generate from a Spec instead of a Jira ticket.'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ type, jira_ticket_key, jira_ticket_keys, custom_instructions, selected_bot_id, create_test_plan, spec_id, project_id }) => {
+        try {
+            const body = {};
+            if (type !== undefined)
+                body.type = type;
+            if (jira_ticket_key !== undefined)
+                body.jira_ticket_key = jira_ticket_key;
+            if (jira_ticket_keys !== undefined)
+                body.jira_ticket_keys = jira_ticket_keys;
+            if (custom_instructions !== undefined)
+                body.custom_instructions = custom_instructions;
+            if (selected_bot_id !== undefined)
+                body.selected_bot_id = selected_bot_id;
+            if (create_test_plan !== undefined)
+                body.create_test_plan = create_test_plan;
+            if (spec_id !== undefined)
+                body.spec_id = spec_id;
+            const result = await client.post('/agent_tasks', body, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    // GET /agent_tasks/:id — the STATUS/RESULT route. Returns { task, logs, result, result_objects }.
+    // This is the poll endpoint for create_agent_task. Reading does not consume credits, but
+    // the warning is retained so the tool stays grouped and clearly part of the AI flow.
+    server.tool('get_agent_task', `${CREDIT_WARNING} (This read-only poll itself does not consume credits, but it belongs to the credit-consuming agent-task flow.) Polls a single AI agent task by id and returns its status, progress logs, and result payload. Call repeatedly after create_agent_task until status.value is terminal (succeeded / failed / awaiting_confirmation). Returns 404 if the task is not in the current account/project scope.`, {
+        id: z.number().int().describe('Agent task id returned by create_agent_task (required)'),
+        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(`/agent_tasks/${id}`, undefined, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    // GET /agent_tasks — list/filter tasks for the current account/project. Optional status
+    // and type filters (Rails Array.wrap accepts the scalar form). Read-only.
+    server.tool('list_agent_tasks', `${CREDIT_WARNING} (This read-only listing itself does not consume credits, but it belongs to the credit-consuming agent-task flow.) Lists AI agent tasks for the current project, optionally filtered by status and type. Use it to discover in-progress or completed tasks to poll with get_agent_task.`, {
+        status: z.string().optional().describe('Filter by status, e.g. "pending", "running", "awaiting_confirmation", "succeeded", "failed".'),
+        type: z.string().optional().describe('Filter by type, e.g. "test_case_generation" or "requirements_review".'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ status, type, project_id }) => {
+        try {
+            const params = {};
+            if (status !== undefined)
+                params.status = status;
+            if (type !== undefined)
+                params.type = type;
+            const result = await client.get('/agent_tasks', params, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    // POST /agent_tasks/:id/confirm — confirms a TestCaseGenerationTask that is in the
+    // "awaiting_confirmation" state, persisting the generated tests. Returns { task,
+    // created_tests, test_plan, spec_id, spec_tests }. 404 if missing; 422 if the task is
+    // not awaiting confirmation or is a different task type.
+    server.tool('confirm_agent_task', `${CREDIT_WARNING} (This confirmation persists already-generated content; the credits were spent during create_agent_task.) Confirms a test-case-generation agent task that is in the "awaiting_confirmation" state, persisting the generated tests into the project. Call this only after get_agent_task reports status.value = "awaiting_confirmation". Returns 422 if the task is not awaiting confirmation.`, {
+        id: z.number().int().describe('Agent task id to confirm (must be awaiting_confirmation) (required)'),
+        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(`/agent_tasks/${id}/confirm`, {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/comments.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+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 }] };
+}
+// Comments in SmartRuns are polymorphic but NOT via Rails-standard commentable_type /
+// commentable_id, and NOT nested under a parent route. The CommentsController
+// (app/controllers/comments_controller.rb) drives everything off two flat params,
+// `source_type` + `source_id`, validated against Comment::SUPPORTED_SCOPES
+// (app/models/comment.rb). The comment body lives on the `text` attribute. Keep this
+// enum in sync with Comment::SUPPORTED_SCOPES.
+const SOURCE_TYPES = ['test', 'test_plan', 'test_run', 'test_suite', 'spec'];
+const sourceTypeSchema = z
+    .enum(SOURCE_TYPES)
+    .describe('Parent entity type the comment belongs to (Comment::SUPPORTED_SCOPES).');
+export function registerCommentTools(server, client) {
+    server.tool('list_comments', 'List comments on a parent entity (test, test_plan, test_run, test_suite, or spec). Comments are polymorphic: identify the parent with source_type + source_id. Scoped to the current account and project server-side.', {
+        source_type: sourceTypeSchema,
+        source_id: z.number().int().describe('ID of the parent entity the comments belong to'),
+        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.get('/comments', { source_type, source_id }, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('create_comment', 'Create a comment on a parent entity (test, test_plan, test_run, test_suite, or spec). The comment body goes in the "text" field. The parent is identified by source_type + source_id. The author is set server-side from the authenticated token.', {
+        source_type: sourceTypeSchema,
+        source_id: z.number().int().describe('ID of the parent entity to comment on'),
+        text: z.string().describe('The comment body (required)'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ source_type, source_id, text, project_id }) => {
+        try {
+            const result = await client.post('/comments', { source_type, source_id, text }, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('update_comment', 'Update an existing comment by ID. The new body goes in the "text" field. NOTE: the server may restrict editing to the comment\'s own author (RBAC: comments_edit_mine / comments_edit_all); if not permitted the API returns 403.', {
+        id: z.number().int().describe('Comment ID to update'),
+        text: z.string().describe('The new comment body (required)'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ id, text, project_id }) => {
+        try {
+            const result = await client.put(`/comments/${id}`, { text }, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('delete_comment', 'Permanently delete a comment by ID. This action is IRREVERSIBLE. NOTE: the server may restrict deletion to the comment\'s own author (RBAC: comments_delete_mine / comments_delete_all); if not permitted the API returns 403 and no record is removed.', {
+        id: z.number().int().describe('Comment 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(`/comments/${id}`, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, id }, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/defects.js

@@ -0,0 +1,150 @@
+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 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'),
+        per_page: z.number().int().optional().describe('Number of results per page'),
+        ticket_id: z.number().int().optional().describe('Filter by Jira ticket ID (mutually exclusive with pull_request_id and test_run_id)'),
+        pull_request_id: z.number().int().optional().describe('Filter by pull request ID (mutually exclusive with ticket_id and test_run_id)'),
+        test_run_id: z.number().int().optional().describe('Filter by test run ID (mutually exclusive with ticket_id and pull_request_id)'),
+    }, async ({ page, per_page, ticket_id, pull_request_id, test_run_id }) => {
+        const filterCount = [ticket_id, pull_request_id, test_run_id].filter(v => v !== undefined).length;
+        if (filterCount > 1) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'At most one filter (ticket_id, pull_request_id, or test_run_id) may be specified at a time.' }],
+            };
+        }
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = page;
+            if (per_page !== undefined)
+                params.per_page = per_page;
+            if (ticket_id !== undefined)
+                params.ticket_id = ticket_id;
+            if (pull_request_id !== undefined)
+                params.pull_request_id = pull_request_id;
+            if (test_run_id !== undefined)
+                params.test_run_id = test_run_id;
+            const result = await client.get('/defects', params);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_defect', 'Get a single defect by ID.', {
+        id: z.number().int().describe('Defect ID'),
+    }, async ({ id }) => {
+        try {
+            const result = await client.get(`/defects/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('create_defect', 'Create a new defect in the current project. summary, steps, current, expected and status are all required by the Defect model — use list_statuses (scope: defect) to find a valid status ID.', {
+        // Required set mirrors Defect model validations (app/models/defect.rb:14-15):
+        // summary, steps, current, expected and status_id all validate presence: true.
+        // `creator` is server-set; `state` is auto-derived from status (before_validation
+        // :sync_state_from_status), so both stay off / optional here (SR-380).
+        summary: z.string().describe('Short summary describing the defect (required)'),
+        steps: z.string().describe('Steps to reproduce the defect (required)'),
+        current: z.string().describe('Current (actual) behavior (required)'),
+        expected: z.string().describe('Expected behavior (required)'),
+        status: z.object({ id: z.number().int().describe('Status ID') }).describe('Status object with ID (required) — drives the defect state'),
+        extra: z.string().optional().describe('Additional context or notes'),
+        state: z.string().optional().describe('Defect state — usually omitted; the API derives it from the status'),
+        ticket_id: z.number().int().optional().describe('Associated Jira ticket ID'),
+        pull_request_id: z.number().int().optional().describe('Associated pull request ID'),
+        test_run_id: z.number().int().optional().describe('Associated test run ID'),
+        test_plan_id: z.number().int().optional().describe('Associated test plan ID'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ summary, steps, current, expected, extra, state, status, ticket_id, pull_request_id, test_run_id, test_plan_id, project_id }) => {
+        try {
+            const body = { summary, steps, current, expected, status };
+            if (extra !== undefined)
+                body.extra = extra;
+            if (state !== undefined)
+                body.state = state;
+            if (ticket_id !== undefined)
+                body.ticket_id = ticket_id;
+            if (pull_request_id !== undefined)
+                body.pull_request_id = pull_request_id;
+            if (test_run_id !== undefined)
+                body.test_run_id = test_run_id;
+            if (test_plan_id !== undefined)
+                body.test_plan_id = test_plan_id;
+            const result = await client.post('/defects', body, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('update_defect', 'Update an existing defect.', {
+        id: z.number().int().describe('Defect ID'),
+        summary: z.string().optional().describe('Short summary describing the defect'),
+        steps: z.string().optional().describe('Steps to reproduce the defect'),
+        current: z.string().optional().describe('Current (actual) behavior'),
+        expected: z.string().optional().describe('Expected behavior'),
+        extra: z.string().optional().describe('Additional context or notes'),
+        state: z.string().optional().describe('Defect state, e.g. "open" or "closed"'),
+        status: z.object({ id: z.number().int().describe('Status ID') }).optional().describe('Status object with ID'),
+        ticket_id: z.number().int().optional().describe('Associated Jira ticket ID'),
+        pull_request_id: z.number().int().optional().describe('Associated pull request ID'),
+        test_run_id: z.number().int().optional().describe('Associated test run ID'),
+        test_plan_id: z.number().int().optional().describe('Associated test plan ID'),
+    }, async ({ id, summary, steps, current, expected, extra, state, status, ticket_id, pull_request_id, test_run_id, test_plan_id }) => {
+        try {
+            const body = {};
+            if (summary !== undefined)
+                body.summary = summary;
+            if (steps !== undefined)
+                body.steps = steps;
+            if (current !== undefined)
+                body.current = current;
+            if (expected !== undefined)
+                body.expected = expected;
+            if (extra !== undefined)
+                body.extra = extra;
+            if (state !== undefined)
+                body.state = state;
+            if (status !== undefined)
+                body.status = status;
+            if (ticket_id !== undefined)
+                body.ticket_id = ticket_id;
+            if (pull_request_id !== undefined)
+                body.pull_request_id = pull_request_id;
+            if (test_run_id !== undefined)
+                body.test_run_id = test_run_id;
+            if (test_plan_id !== undefined)
+                body.test_plan_id = test_plan_id;
+            const result = await client.put(`/defects/${id}`, body);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('delete_defect', 'Permanently delete a single defect by ID. This action is IRREVERSIBLE. Deletion is permitted wherever the authenticated user can access the defect (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 defect is not found.', {
+        id: z.number().int().describe('Defect 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(`/defects/${id}`, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, id }, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/labels.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+// 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'),
+    }, async ({ terms }) => {
+        try {
+            const params = {};
+            if (terms !== undefined)
+                params.terms = terms;
+            const result = await client.get('/labels', params);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    // Labels are scoped to the current account AND project server-side
+    // (LabelsController uses for_current_account.for_current_project), so both
+    // create and update honour the per-call project_id (WTProject header).
+    // NOTE: merge and delete are intentionally NOT exposed (out of scope for SR-386).
+    server.tool('create_label', 'Create a label in the current project. The only writable field is "name"; the account and project are set server-side from the authenticated token / WTProject header. Returns the created label. NOTE: label names are NOT required to be unique — creating a label whose name already exists succeeds (200) and yields a second label; duplicates are not rejected.', {
+        name: z.string().describe('The label name (required). Duplicate names are allowed — the Label model does not enforce uniqueness.'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ name, project_id }) => {
+        try {
+            const result = await client.post('/labels', { name }, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('update_label', 'Rename an existing label by ID. The only writable field is "name". Returns the updated label, or 404 if the label does not exist in the current project. NOTE: label names are NOT required to be unique, so renaming to a name that already exists is allowed and succeeds (it does NOT return a conflict). This is a rename only — it is NOT a merge.', {
+        id: z.number().int().describe('Label ID to update'),
+        name: z.string().describe('The new label name (required)'),
+        project_id: z.string().optional().describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+    }, async ({ id, name, project_id }) => {
+        try {
+            const result = await client.put(`/labels/${id}`, { name }, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/notifications.js

@@ -0,0 +1,55 @@
+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 }] };
+}
+// 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.
+//   GET  /notifications                 -> index     (list, paginated, ?unread filter)
+//   PUT  /notifications/:id             -> update    (mark a single id read/unread)
+//   POST /notifications/mark_all_read   -> mark_all_read
+export function registerNotificationTools(server, client) {
+    server.tool('list_notifications', 'List the authenticated user\'s notifications (paginated, newest first). Notifications are user-scoped, not project-scoped. Returns { entries, meta: { pagination, counts: { unread } } }.', {
+        page: z.number().int().positive().optional().describe('Page number (1-based, default 1)'),
+        per_page: z.number().int().positive().optional().describe('Items per page (default 25)'),
+        unread: z.boolean().optional().describe('When true, return only unread notifications'),
+    }, async ({ page, per_page, unread }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = page;
+            if (per_page !== undefined)
+                params.per_page = per_page;
+            if (unread !== undefined)
+                params.unread = unread;
+            const result = await client.get('/notifications', params);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('mark_notification_read', 'Mark a single notification as read (or unread) by ID. Pass read=false to mark it unread; defaults to read=true. This is a single-id operation only — use mark_all_notifications_read to clear everything. Returns the updated notification and the remaining unread count.', {
+        id: z.number().int().describe('Notification ID to update'),
+        read: z.boolean().optional().describe('Read state to set (default true). Pass false to mark unread.'),
+    }, async ({ id, read }) => {
+        try {
+            const result = await client.put(`/notifications/${id}`, { read: read ?? true });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('mark_all_notifications_read', 'Mark ALL of the authenticated user\'s unread notifications as read in one call. Returns the remaining unread count (0 on success).', {}, async () => {
+        try {
+            const result = await client.post('/notifications/mark_all_read', {});
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/projects.js

@@ -0,0 +1,35 @@
+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 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.'),
+    }, async ({ archived }) => {
+        try {
+            const params = {};
+            if (archived !== undefined)
+                params.archived = archived;
+            const result = await client.get('/projects', params);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('get_project', 'Get a single project by ID.', {
+        id: z.number().int().describe('Project ID'),
+    }, async ({ id }) => {
+        try {
+            const result = await client.get(`/projects/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}

package/dist/tools/reference-data.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+// 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).
+const projectIdArg = {
+    project_id: z
+        .string()
+        .optional()
+        .describe('Override the project for this call (WTProject header). Defaults to SMARTRUNS_PROJECT_ID.'),
+};
+// These are READ-ONLY reference/lookup tools. An LLM calls them to discover valid IDs before
+// constructing a write payload (create_test_run, create_test, create_defect, etc.). There are
+// deliberately NO create/update/delete tools here — reference data is admin/project configuration
+// and is explicitly out of scope for the MCP epic (SR-378 / SR-385).
+export function registerReferenceDataTools(server, client) {
+    server.tool('list_product_areas', 'List the product areas configured in the current project (read-only). Call this to get a valid product_area { id } before setting create_test/update_test\'s product_area. Returns a tree of areas; supports an optional name search.', {
+        search: z.string().optional().describe('Filter product areas by name (substring match)'),
+        ...projectIdArg,
+    }, async ({ search, project_id }) => {
+        try {
+            const params = {};
+            if (search !== undefined)
+                params.search = search;
+            const result = await client.get('/product_areas', params, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('list_test_kinds', 'List the test kinds configured in the current project (read-only). Call this to get a valid test_kind { id } before create_test/update_test, which require one (the API clears the kind if it is omitted on update).', {
+        ...projectIdArg,
+    }, async ({ project_id }) => {
+        try {
+            const result = await client.get('/test-kinds', {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('list_stages', 'List the stages configured in the current project (read-only). Call this to get a valid stage { id } before create_test_run/update_test_run, which require a stage.', {
+        ...projectIdArg,
+    }, async ({ project_id }) => {
+        try {
+            const result = await client.get('/stages', {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('list_testing_environments', 'List the testing environments configured in the current project (read-only). Call this to get a valid testing_environment { id } for create_test_run/update_test_run, which bind testing_environment to its id.', {
+        ...projectIdArg,
+    }, async ({ project_id }) => {
+        try {
+            const result = await client.get('/testing-environments', {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+    server.tool('list_custom_fields', 'List the custom field definitions configured in the current project (read-only). Call this to learn which custom_fields keys/types a write accepts before populating the custom_fields map on create_test/create_test_run/create_defect. This is read-only — it does NOT create or edit field definitions (that is admin configuration, out of scope).', {
+        ...projectIdArg,
+    }, async ({ project_id }) => {
+        try {
+            const result = await client.get('/custom-fields', {}, project_id);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return handleError(err);
+        }
+    });
+}