@smartruns/mcp 1.0.0

package/README.md

@@ -0,0 +1,302 @@
+# SmartRuns MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that wraps the SmartRuns
+REST API, giving AI assistants (Claude Code, Claude Desktop, etc.) direct, user-scoped access
+to your test management data — projects, tests, test plans/runs/suites, defects, specs,
+comments, labels, watchers, notifications and AI generation.
+
+## Prerequisites
+
+- Node.js 18 or later.
+- A SmartRuns **Personal Access Token** (PAT), your **tenant** (subdomain), and a default project ID.
+
+### Creating a Personal Access Token (PAT)
+
+1. Sign in to SmartRuns.
+2. Go to **Profile → Access Tokens**.
+3. Create a token. It looks like `srpat_…`.
+4. Copy it immediately — it is shown only once.
+
+The PAT authenticates **as your user**, so every tool call runs with **your own RBAC
+permissions** and is scoped to your account. Treat the token like a password; never commit it.
+
+> **Integration tokens are deprecated for MCP use.** Account-level integration tokens still
+> authenticate (so existing setups keep working during the migration window), but the server
+> logs a warning on startup if the token does not start with `srpat_`. New setups should use a
+> PAT.
+
+## Setup
+
+```bash
+cd mcp
+npm install
+npm run build
+```
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SMARTRUNS_API_TOKEN` | Yes | Personal Access Token (`srpat_…`, created in SmartRuns → Profile → Access Tokens). Sent raw in the `Authorization` header, no "Bearer" prefix. Integration tokens still work but are deprecated for MCP use. |
+| `SMARTRUNS_TENANT` | Yes | Your SmartRuns tenant (subdomain), e.g. `acme`. Sent as the `X-WT-Tenant` header on every request. Must match the account that owns your PAT — a mismatch is rejected by the API with `403`. |
+| `SMARTRUNS_PROJECT_ID` | Yes | **Default** project ID, sent as the `WTProject` header. Project-scoped tools can override it per call via the optional `project_id` argument. |
+| `SMARTRUNS_API_URL` | No | **Local development override only.** Base API URL; defaults to `https://api.smartruns.io` with zero config. Leave unset in normal use. |
+
+### Per-call project override
+
+`SMARTRUNS_PROJECT_ID` is only the default. Project-scoped tools accept an optional
+`project_id` argument that overrides the `WTProject` header for that single call, leaving the
+default unchanged for every other call. Pass the numeric project id **as a string**, e.g.
+`list_tests({ search: "login", project_id: "77" })`. Omit it to use the default project.
+
+## Usage with Claude Code
+
+```bash
+claude mcp add smartruns \
+  -e SMARTRUNS_API_TOKEN=srpat_your_personal_access_token \
+  -e SMARTRUNS_TENANT=acme \
+  -e SMARTRUNS_PROJECT_ID=your_project_id \
+  -- npx -y @smartruns/mcp
+```
+
+## Usage with Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "smartruns": {
+      "command": "npx",
+      "args": ["-y", "@smartruns/mcp"],
+      "env": {
+        "SMARTRUNS_API_TOKEN": "srpat_your_personal_access_token",
+        "SMARTRUNS_TENANT": "acme",
+        "SMARTRUNS_PROJECT_ID": "your_project_id"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+Run directly from source (no build step required):
+
+```bash
+SMARTRUNS_API_TOKEN=... SMARTRUNS_TENANT=... SMARTRUNS_PROJECT_ID=... npm run dev
+# Optionally target a local backend with SMARTRUNS_API_URL=http://localhost:3000
+```
+
+Run the test suite (unit + full registration smoke; no live API needed):
+
+```bash
+npm test          # vitest run
+npm run build     # tsc + shebang postbuild — must be clean
+```
+
+The `build` script compiles with `tsc` and then runs `scripts/add-shebang.mjs`, which
+prepends `#!/usr/bin/env node` to `dist/index.js` and marks it executable so the published
+`bin` works under `npx`. `dist/` is gitignored and built fresh in CI — never commit it.
+
+## Publishing
+
+This package is published to npm as the public scoped package `@smartruns/mcp` by a
+tag-driven CI workflow (`.github/workflows/mcp-publish.yml`).
+
+To cut a release:
+
+1. Bump `version` in `mcp/package.json` (e.g. `1.0.0`).
+2. Push a matching tag of the form `mcp-v<version>` (e.g. `mcp-v1.0.0`).
+
+The workflow then builds `dist/`, runs the tests, **asserts the tag version equals
+`mcp/package.json` version** (and fails the publish on any mismatch), and runs
+`npm publish --access public`.
+
+**Prerequisites (human/ops):**
+
+- An `NPM_TOKEN` automation secret must exist in GitHub Actions (npm org `@smartruns`,
+  owned by Kalinka). CI uses it as `NODE_AUTH_TOKEN`; publishing fails without it.
+- The tag name and the manifest version must agree — the workflow refuses to publish a
+  mismatched tag.
+
+## Available Tools (61)
+
+> 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
+> recent `get_*` response.
+
+### Projects (2)
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all projects in the account; optional `archived` filter |
+| `get_project` | Get a single project by ID |
+
+### Test Plans (5)
+| Tool | Description |
+|------|-------------|
+| `list_test_plans` | List test plans in the current project (optional page/status/assignee/search filters) |
+| `get_test_plan` | Get a single test plan by ID |
+| `create_test_plan` | Create a new test plan |
+| `update_test_plan` | Update a test plan — requires `lock_version` |
+| `delete_test_plan` | Permanently delete a test plan and its plan-scoped tests/uploads — RBAC-gated (`test_plans_delete_mine` / `_all`) |
+
+### Test Runs (4)
+| Tool | Description |
+|------|-------------|
+| `list_test_runs` | List test runs in the current project (optional filters) |
+| `get_test_run` | Get a single test run by ID |
+| `create_test_run` | Create a new test run (status + stage) |
+| `update_test_run` | Update a test run — requires `lock_version` |
+
+### Tests (7)
+| Tool | Description |
+|------|-------------|
+| `list_tests` | Search/list tests via the `/tests/search` endpoint |
+| `get_test` | Get a single test case by ID |
+| `get_test_history` | Read-only audit/activity history for a test (AuditLog entries, newest first) |
+| `create_test` | Create a new test case (`test_kind` required) |
+| `update_test` | Update a test case — requires `lock_version`; always include `test_kind` (cleared if omitted) |
+| `clone_test` | Clone an existing test case into a duplicate |
+| `delete_test` | Permanently delete a test case — tenant-scoped; surfaces 403/404 from the server |
+
+### Test Suites (6)
+| Tool | Description |
+|------|-------------|
+| `list_test_suites` | List test suites in the current project (paginated `{ entries, meta }`) |
+| `get_test_suite` | Get a single test suite by ID (includes `lock_version`, watchers, plans) |
+| `create_test_suite` | Create a test suite — `name`, `status` **and** `assignee` all required |
+| `update_test_suite` | Update a test suite — requires `lock_version`; always include `name` + `status` |
+| `clone_test_suite` | Clone a test suite — RBAC-gated (`test_suites_create`) |
+| `delete_test_suite` | Permanently delete a test suite — RBAC-gated (`test_suites_delete_mine` / `_all`) |
+
+### Defects (5)
+| Tool | Description |
+|------|-------------|
+| `list_defects` | List defects; at most ONE filter (`ticket_id`, `pull_request_id`, or `test_run_id`) at a time |
+| `get_defect` | Get a single defect by ID |
+| `create_defect` | Create a defect (`summary`/`steps`/`current`/`expected`/`status` required) |
+| `update_defect` | Update an existing defect |
+| `delete_defect` | Permanently delete a defect — tenant-scoped; surfaces 403/404 from the server |
+
+### Specs (6)
+| Tool | Description |
+|------|-------------|
+| `list_specs` | List specs (spec-driven development); feature-gated — may return 403/404 if the flag is off |
+| `get_spec` | Get a single spec with acceptance criteria, linked tickets, attachments and coverage roll-up |
+| `create_spec` | Create a spec (`title` required; status defaults to `draft`) |
+| `update_spec` | Partial update of a spec — **no** `lock_version` (specs are not optimistically locked) |
+| `get_spec_history` | Read-only activity/history feed for a spec (AuditLog entries, newest first) |
+| `delete_spec` | Permanently delete a spec — tenant-scoped; surfaces 403/404 from the server |
+
+### Comments (4)
+| Tool | Description |
+|------|-------------|
+| `list_comments` | List comments on a parent entity (`test`/`test_plan`/`test_run`/`test_suite`/`spec`) |
+| `create_comment` | Create a comment on a parent entity (body in the `text` field) |
+| `update_comment` | Update a comment — RBAC-gated (`comments_edit_mine` / `_all`) |
+| `delete_comment` | Delete a comment — RBAC-gated (`comments_delete_mine` / `_all`) |
+
+### Statuses (1)
+| Tool | Description |
+|------|-------------|
+| `list_statuses` | List all statuses grouped by scope (returns an object keyed by scope, not an array) |
+
+### Labels (3)
+| 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 |
+
+### Watchers (2)
+| Tool | Description |
+|------|-------------|
+| `watch_entity` | Subscribe the current user to an entity; returns `{ watchers: [...] }` |
+| `unwatch_entity` | Unsubscribe the current user from an entity; returns `{ watchers: [...] }` |
+
+### Notifications (3)
+| Tool | Description |
+|------|-------------|
+| `list_notifications` | List the authenticated user's notifications (user-scoped, not project-scoped) |
+| `mark_notification_read` | Mark a single notification read (or unread via `read=false`) |
+| `mark_all_notifications_read` | Mark ALL of the user's unread notifications as read |
+
+### Users (2)
+| Tool | Description |
+|------|-------------|
+| `list_users` | List all users in the current account |
+| `get_current_user` | Get the currently authenticated user's profile |
+
+### Reference data (5, read-only)
+These lookups exist so an LLM can discover valid IDs before constructing a write payload.
+They are **read-only** — there are intentionally no create/update/delete tools for reference
+data (that is admin/project configuration, out of scope).
+
+| Tool | Description |
+|------|-------------|
+| `list_product_areas` | List product areas (to get a valid `product_area { id }`) |
+| `list_test_kinds` | List test kinds (to get a valid `test_kind { id }`) |
+| `list_stages` | List stages (to get a valid stage for test runs) |
+| `list_testing_environments` | List testing environments (for test runs) |
+| `list_custom_fields` | List custom field definitions (to learn accepted `custom_fields` keys/types) |
+
+### AI generation (6) — ⚠ consumes AI credits / billing
+Every tool below invokes the SmartRuns AI backend and **consumes the account's AI credits**
+(and may incur billing). Each tool's description starts with that warning so an LLM treats it
+cautiously.
+
+| Tool | Sync/Async | Description |
+|------|------------|-------------|
+| `generate_tests_with_ai` | Sync | Generate proposed tests from a Jira ticket; results returned inline |
+| `request_ai_suggestions` | Async (fire-and-forget) | Enqueue AI suggestions for an existing test; re-read the test for results |
+| `create_agent_task` | Async (create → poll) | Create a test-generation / requirements-review task; returns `202` with a task id. Returns `403 plan_limit` when AI credits are exhausted |
+| `get_agent_task` | Poll | Poll a task's status, logs and result payload until terminal |
+| `list_agent_tasks` | Read | List/filter agent tasks by `status` / `type` |
+| `confirm_agent_task` | Write | Persist generated tests once a task is `awaiting_confirmation` |
+
+The agent-task flow is **asynchronous**: `create_agent_task` returns immediately with a task
+id; poll `get_agent_task` until `status.value` is terminal (`succeeded` / `failed` /
+`awaiting_confirmation`), then `confirm_agent_task` for test-case generation. No tool
+blocks/long-polls inside a single call.
+
+## Intentionally excluded / out of scope
+
+The MCP deliberately exposes a **safe, read-and-write-where-it-makes-sense** surface for
+day-to-day test management. The following are **not** exposed — by design — so both users and
+LLMs know the boundaries. If you need one of these, use the SmartRuns web app:
+
+- **Admin / project configuration writes** — creating or editing product areas, test kinds,
+  stages, testing environments, custom field *definitions*, statuses, roles or permissions.
+  Reference data is read-only here.
+- **User management** — inviting, editing, deactivating or deleting users (`list_users` and
+  `get_current_user` are read-only).
+- **PAT / token management** — creating, listing, rotating or revoking Personal Access Tokens
+  or integration tokens.
+- **Password / credential changes** — no auth or account-credential mutation.
+- **Bulk test deletion** — only single-record `delete_test` is exposed; the bulk-delete
+  endpoint is intentionally omitted.
+- **Label merge** — `update_label` renames a single label; merging labels is not exposed.
+- **File / attachment uploads** — uploading or deleting attachments on any entity.
+
+## Notes
+
+- Write operations on optimistically-locked entities (`update_test`, `update_test_run`,
+  `update_test_plan`, `update_test_suite`) require a `lock_version` taken from the most recent
+  `get_*` response. On a 409 lock conflict, re-fetch the record and retry with the new
+  `lock_version`. (Specs are **not** locked — `update_spec` takes no `lock_version`.)
+- Defect list filters (`ticket_id`, `pull_request_id`, `test_run_id`) are mutually exclusive —
+  supply at most one per call.
+- `list_tests` uses `/tests/search` under the hood (not the base `/tests` index, which
+  requires explicit IDs).
+- Label names are **not** unique — `create_label`/`update_label` accept duplicate names.
+- Specs are feature-gated; if the flag is off for the account, the specs tools surface the
+  server's 403/404 verbatim.
+- The full tool catalogue above is asserted by `src/smoke.test.ts` (registration smoke test):
+  if a tool is added, removed or renamed, update both that test and this README.

package/dist/api-client.js

@@ -0,0 +1,142 @@
+const REQUEST_TIMEOUT_MS = 30_000;
+export class ApiClient {
+    baseUrl;
+    token;
+    projectId;
+    tenant;
+    // SR-393: `tenant` is the customer's SMARTRUNS_TENANT and is threaded through
+    // like `projectId`. It is sent as the X-WT-Tenant header on EVERY request so
+    // the backend can enforce the token/tenant guardrail on the PAT auth path.
+    constructor(baseUrl, token, projectId, tenant) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.token = token;
+        this.projectId = projectId;
+        this.tenant = tenant;
+    }
+    // An optional projectIdOverride lets a single call target a different project
+    // (WTProject header) without changing the client default (SMARTRUNS_PROJECT_ID).
+    // X-WT-Tenant is constant for the lifetime of the client (one tenant per token).
+    commonHeaders(projectIdOverride) {
+        return {
+            Authorization: this.token,
+            'WTProject': projectIdOverride ?? this.projectId,
+            'X-WT-Tenant': this.tenant,
+        };
+    }
+    async get(path, params, projectId) {
+        let url = `${this.baseUrl}${path}`;
+        if (params) {
+            const searchParams = new URLSearchParams();
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== null) {
+                    searchParams.append(key, String(value));
+                }
+            }
+            const queryString = searchParams.toString();
+            if (queryString) {
+                url += `?${queryString}`;
+            }
+        }
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: this.commonHeaders(projectId),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return this.handleResponse(response, 'GET', path);
+        }
+        catch (err) {
+            ApiClient.wrapTimeoutError(err, 'GET', path);
+        }
+    }
+    async post(path, body, projectId) {
+        const url = `${this.baseUrl}${path}`;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    ...this.commonHeaders(projectId),
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return this.handleResponse(response, 'POST', path);
+        }
+        catch (err) {
+            ApiClient.wrapTimeoutError(err, 'POST', path);
+        }
+    }
+    async put(path, body, projectId) {
+        const url = `${this.baseUrl}${path}`;
+        try {
+            const response = await fetch(url, {
+                method: 'PUT',
+                headers: {
+                    ...this.commonHeaders(projectId),
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return this.handleResponse(response, 'PUT', path);
+        }
+        catch (err) {
+            ApiClient.wrapTimeoutError(err, 'PUT', path);
+        }
+    }
+    // DELETE mirrors put()/post() minus the body and Content-Type. Many SmartRuns
+    // DELETE endpoints return 204 No Content; handleResponse short-circuits that to null.
+    // A few DELETE routes (e.g. DELETE /watch) identify the target via a JSON body
+    // rather than the path; pass `body` for those. When omitted, no body or
+    // Content-Type header is sent (the common case).
+    async delete(path, projectId, body) {
+        const url = `${this.baseUrl}${path}`;
+        const hasBody = body !== undefined;
+        try {
+            const response = await fetch(url, {
+                method: 'DELETE',
+                headers: hasBody
+                    ? { ...this.commonHeaders(projectId), 'Content-Type': 'application/json' }
+                    : this.commonHeaders(projectId),
+                ...(hasBody ? { body: JSON.stringify(body) } : {}),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return this.handleResponse(response, 'DELETE', path);
+        }
+        catch (err) {
+            ApiClient.wrapTimeoutError(err, 'DELETE', path);
+        }
+    }
+    // Called by callers to wrap fetch so AbortError surfaces as a readable message.
+    static wrapTimeoutError(err, method, path) {
+        if (err instanceof Error && err.name === 'TimeoutError') {
+            throw { status: 408, method, path, body: `Request timed out after ${REQUEST_TIMEOUT_MS}ms` };
+        }
+        throw err;
+    }
+    async handleResponse(response, method, path) {
+        // 204 No Content has an empty body; calling response.json() would throw.
+        // Short-circuit so delete() (and any empty-bodied success) resolves to null.
+        if (response.status === 204) {
+            return null;
+        }
+        let responseBody;
+        try {
+            responseBody = await response.json();
+        }
+        catch {
+            responseBody = await response.text().catch(() => null);
+        }
+        if (!response.ok) {
+            const error = {
+                status: response.status,
+                method,
+                path,
+                body: responseBody,
+            };
+            throw error;
+        }
+        return responseBody;
+    }
+}

package/dist/config.js

@@ -0,0 +1,33 @@
+// SR-393: Public env contract for the npx-distributed MCP.
+//
+// The MCP is published to npm and installed by external customers via
+//   claude mcp add smartruns -e SMARTRUNS_API_TOKEN=… -e SMARTRUNS_TENANT=acme \
+//     -e SMARTRUNS_PROJECT_ID=… -- npx -y @smartruns/mcp
+// so the API base URL is NOT something a customer should ever supply. It is
+// hardcoded to the production host. SMARTRUNS_API_URL is retained ONLY as an
+// optional override for local development against a non-prod backend — it is
+// never required and must default to the production host with zero config.
+export const DEFAULT_API_URL = 'https://api.smartruns.io';
+// Required, customer-supplied env vars. SMARTRUNS_API_URL is intentionally NOT
+// here — it is optional (see DEFAULT_API_URL above).
+export const REQUIRED_ENV = [
+    'SMARTRUNS_API_TOKEN',
+    'SMARTRUNS_TENANT',
+    'SMARTRUNS_PROJECT_ID',
+];
+// Resolve and validate the MCP configuration from the environment. Throws an
+// Error naming the first missing required variable so a misconfigured install
+// fails fast with an actionable message (no token bytes are ever included).
+export function resolveConfig(env = process.env) {
+    for (const key of REQUIRED_ENV) {
+        if (!env[key]) {
+            throw new Error(`Missing required env var: ${key}`);
+        }
+    }
+    return {
+        apiUrl: env['SMARTRUNS_API_URL'] || DEFAULT_API_URL,
+        apiToken: env['SMARTRUNS_API_TOKEN'],
+        tenant: env['SMARTRUNS_TENANT'],
+        projectId: env['SMARTRUNS_PROJECT_ID'],
+    };
+}

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { resolveConfig } from './config.js';
+// SR-393: validate + resolve the public env contract (throws, naming the first
+// missing required var). The API base URL defaults to https://api.smartruns.io
+// with zero config; the customer supplies SMARTRUNS_TENANT (sent as X-WT-Tenant).
+const config = resolveConfig();
+// Warn-and-continue PAT sanity-check. The MCP now expects a user Personal Access Token
+// (srpat_…); integration tokens still authenticate but are deprecated for MCP use, so we
+// must NOT hard-fail during the migration window. Log to stderr (stdout is the MCP
+// transport) and never echo any token bytes.
+if (!config.apiToken.startsWith('srpat_')) {
+    console.error('SmartRuns MCP: SMARTRUNS_API_TOKEN does not start with "srpat_" — it does not look like a Personal Access Token. This MCP now expects a user PAT (create one in SmartRuns → Profile → Tokens). Continuing for backward compatibility; integration tokens still authenticate but are deprecated for MCP use.');
+}
+const server = createServer(config.apiUrl, config.apiToken, config.projectId, config.tenant);
+const transport = new StdioServerTransport();
+console.error(`SmartRuns MCP starting — API: ${config.apiUrl}, tenant: ${config.tenant}, project: ${config.projectId}`);
+await server.connect(transport);

package/dist/server.js

@@ -0,0 +1,42 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ApiClient } from './api-client.js';
+import { registerProjectTools } from './tools/projects.js';
+import { registerTestPlanTools } from './tools/test-plans.js';
+import { registerTestRunTools } from './tools/test-runs.js';
+import { registerTestTools } from './tools/tests.js';
+import { registerTestSuiteTools } from './tools/test-suites.js';
+import { registerDefectTools } from './tools/defects.js';
+import { registerSpecTools } from './tools/specs.js';
+import { registerCommentTools } from './tools/comments.js';
+import { registerStatusTools } from './tools/statuses.js';
+import { registerLabelTools } from './tools/labels.js';
+import { registerWatcherTools } from './tools/watchers.js';
+import { registerNotificationTools } from './tools/notifications.js';
+import { registerUserTools } from './tools/users.js';
+import { registerReferenceDataTools } from './tools/reference-data.js';
+import { registerAiTools } from './tools/ai.js';
+export function createServer(apiUrl, apiToken, projectId, tenant) {
+    const server = new McpServer({
+        name: 'smartruns-mcp',
+        version: '1.0.0',
+    });
+    const client = new ApiClient(apiUrl, apiToken, projectId, tenant);
+    registerProjectTools(server, client);
+    registerTestPlanTools(server, client);
+    registerTestRunTools(server, client);
+    registerTestTools(server, client);
+    registerTestSuiteTools(server, client);
+    registerDefectTools(server, client);
+    registerSpecTools(server, client);
+    registerCommentTools(server, client);
+    registerStatusTools(server, client);
+    registerLabelTools(server, client);
+    registerWatcherTools(server, client);
+    registerNotificationTools(server, client);
+    registerUserTools(server, client);
+    registerReferenceDataTools(server, client);
+    // SR-387 (slice 9, BILLING-flagged): AI-generation tools — ship last; every tool
+    // description warns that invoking it consumes the account's AI credits.
+    registerAiTools(server, client);
+    return server;
+}