@robotyxx/robotyx-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1274 @@
+#!/usr/bin/env node
+/**
+ * Robotyx MCP server — a thin, stdio MCP wrapper around Robotyx's REST API.
+ *
+ * Lets Claude Code / Claude Desktop browse a recorded workflow, refine the
+ * functional TestSteps (group "1-7" → "Log in as admin"), and push the result
+ * back — without leaving the chat. No new business logic lives here; every
+ * tool is a wrapper around an existing endpoint the web UI also uses.
+ *
+ * Env:
+ *   ROBOTYX_URL      — gateway base URL (default http://localhost:3001)
+ *   ROBOTYX_API_KEY  — long-lived `rx_…` Bearer token (required)
+ *
+ * Wire-up (Claude Code):
+ *   In the project's `.mcp.json`:
+ *   {
+ *     "mcpServers": {
+ *       "robotyx": {
+ *         "command": "npx",
+ *         "args": ["-y", "tsx", "<path-to-this-file>"],
+ *         "env": { "ROBOTYX_URL": "http://localhost:3001", "ROBOTYX_API_KEY": "rx_…" }
+ *       }
+ *     }
+ *   }
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// Load robotyx-mcp/.env (next to package.json) without adding a dependency.
+// Existing process env wins, so `.mcp.json` / real env vars still override.
+try {
+    const envPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", ".env");
+    for (const line of readFileSync(envPath, "utf8").split("\n")) {
+        const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/);
+        if (!m)
+            continue;
+        if (process.env[m[1]] === undefined) {
+            process.env[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
+        }
+    }
+}
+catch {
+    /* no .env file — fall back to process env */
+}
+// ── Config ──────────────────────────────────────────────────────────────── //
+const ROBOTYX_URL = (process.env.ROBOTYX_URL || "http://localhost:3001").replace(/\/+$/, "");
+const ROBOTYX_API_KEY = process.env.ROBOTYX_API_KEY || "";
+// Tenant scope — tenant-scoped routes (testsuites, projects, …) resolve the
+// customer from X-Customer-Id, falling back to the catch-all when absent. Set
+// this so the MCP sees a specific customer's data (e.g. live recordings) rather
+// than only catch-all rows.
+const ROBOTYX_CUSTOMER_ID = process.env.ROBOTYX_CUSTOMER_ID || "";
+if (!ROBOTYX_API_KEY) {
+    // Fail loudly on stderr — stdout is reserved for MCP protocol frames.
+    process.stderr.write("[robotyx-mcp] ROBOTYX_API_KEY is not set. Mint a key in the Robotyx UI " +
+        "(Settings → API Keys) and add it to the MCP env block.\n");
+}
+// ── HTTP helper ─────────────────────────────────────────────────────────── //
+async function robotyx(method, path, body) {
+    const url = `${ROBOTYX_URL}${path}`;
+    const res = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${ROBOTYX_API_KEY}`,
+            "Content-Type": "application/json",
+            ...(ROBOTYX_CUSTOMER_ID ? { "X-Customer-Id": ROBOTYX_CUSTOMER_ID } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Robotyx ${method} ${path} → ${res.status} ${res.statusText}${text ? `: ${text}` : ""}`);
+    }
+    // 204 No Content paths still need a value the caller can JSON-serialize.
+    if (res.status === 204)
+        return {};
+    return (await res.json());
+}
+/** Fetch a blob URL ref (relative like "/api/blobs/sha.png") or absolute URL,
+ * returning base64-encoded bytes + mime type. Used to surface screenshots as
+ * MCP image content blocks — vision tokens (~1.5k each) instead of base64
+ * text inside JSON (which would be ~120k tokens for a 400KB PNG). */
+async function fetchBlobBase64(refOrUrl) {
+    try {
+        const url = refOrUrl.startsWith("http") ? refOrUrl : `${ROBOTYX_URL}${refOrUrl}`;
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${ROBOTYX_API_KEY}` } });
+        if (!res.ok)
+            return null;
+        const mimeType = res.headers.get("content-type") || "image/png";
+        const ab = await res.arrayBuffer();
+        return { base64: Buffer.from(ab).toString("base64"), mimeType };
+    }
+    catch {
+        return null;
+    }
+}
+/** Upload a local image file to /api/blobs and return the screenshot ref to
+ * store on a TestStep (e.g. "/api/blobs/<id>.png"). Shared by add_test_step
+ * and update_test_step. */
+async function uploadScreenshotRef(imagePath, mimeType) {
+    const mime = mimeType || "image/png";
+    const buf = readFileSync(imagePath);
+    const res = await fetch(`${ROBOTYX_URL}/api/blobs`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${ROBOTYX_API_KEY}`, "Content-Type": mime },
+        body: new Uint8Array(buf),
+    });
+    if (!res.ok) {
+        const t = await res.text().catch(() => "");
+        throw new Error(`Robotyx POST /api/blobs → ${res.status} ${res.statusText}${t ? `: ${t}` : ""}`);
+    }
+    const blob = (await res.json());
+    const ext = mime === "image/jpeg" ? "jpg" : mime.split("/")[1] || "png";
+    const ref = blob.ref ?? blob.url ?? (blob.id ? `/api/blobs/${blob.id}.${ext}` : undefined);
+    if (!ref)
+        throw new Error(`Robotyx /api/blobs returned no id/url/ref: ${JSON.stringify(blob)}`);
+    return ref;
+}
+/** Legacy fallback: some old workflow_steps.parameters may still hold a
+ * data:image/png;base64,… URL. Decode in-place rather than refusing. */
+function dataUrlToBase64(dataUrl) {
+    const m = /^data:([^;,]+)(;base64)?,(.+)$/i.exec(dataUrl);
+    if (!m)
+        return null;
+    const mimeType = m[1] || "image/png";
+    return m[2] ? { base64: m[3], mimeType } : null;
+}
+function trimStep(step, includeScreenshot) {
+    const params = { ...(step.parameters || {}) };
+    if (!includeScreenshot)
+        delete params.screenshot;
+    // Always drop the per-step footprint bookkeeping fields — they're useless
+    // for refinement (raw a11y dumps, console logs) and bulk up token count.
+    for (const k of Object.keys(params)) {
+        if (k.startsWith("footprint_"))
+            delete params[k];
+    }
+    return { ...step, parameters: params };
+}
+// ── ISTQB classification helpers ────────────────────────────────────────── //
+// Robotyx has no dedicated ISTQB columns: the react-ui Requirement editor
+// stores classification on the requirement's free-form `attributes` JSON bag
+// (see Projects.tsx → RequirementEditor). The MCP writes the *same* keys so a
+// requirement classified here is editable in the app — and lands on the
+// Product-Risk (PRA) matrix — and vice-versa. Enum values are mirrored in the
+// create/update_requirement input schemas below.
+/** MCP arg name → attributes key the UI reads/writes. */
+const ISTQB_ARG_TO_ATTR = {
+    istqb_test_level: "istqbTestLevel",
+    istqb_quality_characteristic: "istqbQualityCharacteristic",
+    istqb_risk_class: "istqbRiskClass",
+    istqb_probability: "istqbProbability",
+};
+function hasIstqbArgs(args) {
+    return Object.keys(ISTQB_ARG_TO_ATTR).some((k) => args[k] !== undefined);
+}
+/** Merge ISTQB picks into an existing attributes bag. A provided null or empty
+ * string deletes the key (matches the UI's setOrDrop) so unclassified
+ * requirements stay clean; all other keys in the bag are preserved untouched. */
+function mergeIstqbAttributes(base, args) {
+    const out = { ...(base ?? {}) };
+    for (const [arg, attr] of Object.entries(ISTQB_ARG_TO_ATTR)) {
+        if (args[arg] === undefined)
+            continue;
+        const v = args[arg];
+        if (v === null || v === "")
+            delete out[attr];
+        else
+            out[attr] = v;
+    }
+    return out;
+}
+// ── Tool definitions ────────────────────────────────────────────────────── //
+const TOOLS = [
+    {
+        name: "list_workflows",
+        description: "List all Workflows on the Robotyx gateway. Returns id + name + tags + step count for each — pick one to inspect with get_workflow.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_workflow",
+        description: "Fetch a Workflow with its full ordered step list. Screenshot URLs are always stripped from the JSON payload; when include_screenshots is 'all' or 'indices', the matching screenshots are attached as real image content blocks (vision-tokenized, ~1.5k tokens each) interleaved with text captions identifying the step. Use 'indices' + screenshot_step_indices:[…] (1-based) to fetch only specific steps' screenshots when grouping ambiguous interactions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workflow_id: { type: "string", description: "Workflow UUID" },
+                include_screenshots: {
+                    type: "string",
+                    enum: ["none", "all", "indices"],
+                    default: "none",
+                    description: "none = drop all screenshots; all = include every step's; indices = include only the steps named in screenshot_step_indices.",
+                },
+                screenshot_step_indices: {
+                    type: "array",
+                    items: { type: "integer", minimum: 1 },
+                    description: "1-based step indices to include screenshots for (only used when include_screenshots is 'indices').",
+                },
+            },
+            required: ["workflow_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_testsuites",
+        description: "List all TestSuites on the gateway.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_testsuite",
+        description: "Fetch a TestSuite with its cases and each case's TestSteps. Use this to see the current grouping before refining.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+            },
+            required: ["testsuite_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_testsuite",
+        description: "Create a new TestSuite (cases-collection for a release/sprint/run). project_id is required for tenancy — the suite and every case added to it inherit it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string", description: "Owning Project id — required (tenancy). Cases added to this suite inherit it." },
+                name: { type: "string" },
+                category: { type: "string", description: "Optional grouping label, e.g. '2026-06 regression', 'Smoke'." },
+                description: { type: "string" },
+                owner: { type: "string" },
+                status: { type: "string", enum: ["draft", "ready", "in_review", "archived"], default: "draft" },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["project_id", "name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "add_test_case",
+        description: "Add a TestCase to a TestSuite, optionally linking it to a Workflow id (so the case's TestSteps can reference WorkflowSteps).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                name: { type: "string" },
+                workflow_id: { type: "string", description: "Optional Workflow this case wires up." },
+                priority: { type: "string", enum: ["P1", "P2", "P3", "P4"], default: "P3" },
+                description: { type: "string" },
+                expected_result: { type: "string" },
+                coverage: { type: "string", enum: ["covered", "built_no_story", "transcript_no_story", "not_built", "unknown"], description: "Build/story kenmerk (default unknown)." },
+            },
+            required: ["testsuite_id", "name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "add_test_step",
+        description: "Append a single functional TestStep to a TestCase — manual authoring, NOT workflow-derived (unlike set_test_steps which needs a Workflow). order auto-increments when omitted. Call once per step to build up a step-by-step case.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                description: { type: "string", description: "The action/step, e.g. 'Open /klant and pick a destination'." },
+                expected_result: { type: ["string", "null"], description: "Per-step expected result (optional)." },
+                order: { type: "integer", minimum: 0, description: "Optional 0-based position; appended to the end when omitted." },
+                screenshot: { type: "string", description: "Optional blob ref for a screenshot of this step, e.g. '/api/blobs/<id>.png' (as returned by upload_screenshot). Takes precedence over image_path if both given." },
+                image_path: { type: "string", description: "Optional local image file to upload as this step's screenshot; uploaded to /api/blobs and the resulting ref is attached automatically." },
+                mime_type: { type: "string", description: "MIME type for image_path upload (default image/png)." },
+            },
+            required: ["testsuite_id", "testcase_id", "description"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "update_test_step",
+        description: "Update an existing TestStep in place (PATCH). Use to fix a step's description/expected_result/order or to attach a screenshot to a step that was created without one. Only provided fields change. Pass image_path to upload a local screenshot to /api/blobs and attach it; or screenshot for an existing blob ref.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                step_id: { type: "string", description: "The TestStep id to update (from get_testsuite)." },
+                description: { type: "string", description: "New step text (optional)." },
+                expected_result: { type: ["string", "null"], description: "New per-step expected result (optional)." },
+                order: { type: "integer", minimum: 0, description: "New 0-based position (optional)." },
+                screenshot: { type: ["string", "null"], description: "Blob ref to attach, e.g. '/api/blobs/<id>.png'; null clears it. Takes precedence over image_path." },
+                image_path: { type: "string", description: "Local image file to upload to /api/blobs and attach as this step's screenshot." },
+                mime_type: { type: "string", description: "MIME type for image_path upload (default image/png)." },
+            },
+            required: ["testsuite_id", "testcase_id", "step_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "delete_test_step",
+        description: "Delete a TestStep from a TestCase. Use to remove a generic/incorrect step so it can be re-authored screen-grounded.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                step_id: { type: "string" },
+            },
+            required: ["testsuite_id", "testcase_id", "step_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_test_run",
+        description: "Create a TestRun — the test-perspective execution record (expected ⇄ actual), the test analogue of a workflow/flow run. Most runs come from CI/CD; this also covers manual triggers. Pass seed_from_test_case_id (or seed_from_test_suite_id) to snapshot the case's functional steps (action + expected result + reference screenshot) + test data as the EXPECTED context (actuals start 'not_run'), so you can later fill actual results and compare. Or pass steps[] explicitly for external ingest. id is optional for idempotent re-POSTs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string", description: "Tenancy anchor (required)." },
+                id: { type: "string", description: "Optional caller-supplied id for idempotent CI re-POSTs." },
+                test_suite_id: { type: "string", description: "Suite this run exercised (optional)." },
+                test_case_id: { type: "string", description: "Single case this run exercised (optional)." },
+                seed_from_test_case_id: { type: "string", description: "Snapshot expected steps from this TestCase at create time." },
+                seed_from_test_suite_id: { type: "string", description: "Snapshot expected steps from every case in this TestSuite." },
+                name: { type: "string", description: "Label, e.g. 'CI #123' or 'Manual 2026-06-16'." },
+                status: { type: "string", enum: ["running", "passed", "failed", "blocked", "skipped", "aborted"] },
+                trigger: { type: "string", description: "'cicd' | 'manual' | 'external' | …" },
+                environment: { type: "string", description: "Where it ran, e.g. 'sme-test.koppel.ai'." },
+                external_ref: { type: "string", description: "Pointer to the external system (CI build url/id)." },
+                started_at: { type: "string", description: "ISO timestamp; defaults to now." },
+                completed_at: { type: "string" },
+                duration_ms: { type: "integer", minimum: 0 },
+                steps: {
+                    type: "array",
+                    description: "Explicit steps for external ingest (snake_case keys: description, expected_result, expected_screenshot, test_data, status, actual_screenshot, error, duration_ms, test_case_id, test_step_id, order).",
+                    items: { type: "object", additionalProperties: true },
+                },
+            },
+            required: ["project_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_test_runs",
+        description: "List TestRuns for reporting (steps omitted). Filter by project_id (recommended) and optionally test_case_id / test_suite_id. Newest first.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                test_case_id: { type: "string" },
+                test_suite_id: { type: "string" },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_test_run",
+        description: "Fetch a TestRun with its steps (expected ⇄ actual) — the expected-vs-actual report for one execution.",
+        inputSchema: {
+            type: "object",
+            properties: { testrun_id: { type: "string" } },
+            required: ["testrun_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "update_test_run",
+        description: "Update run-level fields of a TestRun (status, name, trigger, environment, external_ref, timings). Only provided fields change. Does not touch steps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testrun_id: { type: "string" },
+                status: { type: "string", enum: ["running", "passed", "failed", "blocked", "skipped", "aborted"] },
+                name: { type: "string" },
+                trigger: { type: "string" },
+                environment: { type: "string" },
+                external_ref: { type: "string" },
+                started_at: { type: "string" },
+                completed_at: { type: "string" },
+                duration_ms: { type: "integer", minimum: 0 },
+            },
+            required: ["testrun_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "add_case_to_test_run",
+        description: "Add a TestCase to an existing TestRun — snapshots that case's expected steps (appended). Use to assemble a multi-case run/cycle.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testrun_id: { type: "string" },
+                test_case_id: { type: "string" },
+            },
+            required: ["testrun_id", "test_case_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "set_test_run_step_result",
+        description: "Record the ACTUAL outcome of one TestRun step (validate expected vs actual). Pass image_path to upload the actual screenshot to /api/blobs and attach it; or actual_screenshot for an existing blob ref.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testrun_id: { type: "string" },
+                step_id: { type: "string", description: "TestRunStep id (from get_test_run)." },
+                status: { type: "string", enum: ["not_run", "passed", "failed", "blocked", "skipped"] },
+                error: { type: ["string", "null"], description: "Failure / deviation detail." },
+                duration_ms: { type: "integer", minimum: 0 },
+                actual_screenshot: { type: ["string", "null"], description: "Blob ref for the actual screenshot." },
+                image_path: { type: "string", description: "Local image to upload as the actual screenshot." },
+                mime_type: { type: "string", description: "MIME for image_path (default image/png)." },
+            },
+            required: ["testrun_id", "step_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "delete_test_run",
+        description: "Delete a TestRun (and its steps).",
+        inputSchema: {
+            type: "object",
+            properties: { testrun_id: { type: "string" } },
+            required: ["testrun_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "set_test_steps",
+        description: "Replace (or append) a TestCase's functional TestSteps from a mapping. Each mapping row groups 1-N WorkflowSteps by 1-based indices. Same shape as the Robotyx UI's Excel import path. Use this after get_workflow to apply your AI-proposed grouping. The workflow_step_ids array MUST be the workflow's full ordered step-id list (in order); the server resolves indices → ids.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                workflow_step_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Full ordered list of the linked workflow's step ids — same order as get_workflow returns them.",
+                },
+                mappings: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            description: { type: "string", description: "Functional step description, e.g. 'Log in as admin'." },
+                            expected_result: { type: "string" },
+                            workflow_step_indices: {
+                                type: "array",
+                                items: { type: "integer", minimum: 1 },
+                                description: "1-based indices into workflow_step_ids that this functional step covers.",
+                            },
+                        },
+                        required: ["description", "workflow_step_indices"],
+                        additionalProperties: false,
+                    },
+                },
+                mode: { type: "string", enum: ["replace", "append"], default: "replace" },
+            },
+            required: ["testsuite_id", "testcase_id", "workflow_step_ids", "mappings"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "merge_step",
+        description: "Collapse a TestStep into its predecessor (workflowStepIds are concatenated, descriptions joined). The trailing step's screenshot wins.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                teststep_id: { type: "string" },
+            },
+            required: ["testsuite_id", "testcase_id", "teststep_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "split_step",
+        description: "Re-explode a multi-step TestStep into N consecutive single-step rows. Reverse of merge_step / set_test_steps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                teststep_id: { type: "string" },
+            },
+            required: ["testsuite_id", "testcase_id", "teststep_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_projects",
+        description: "List Projects — long-lived containers above TestSuite. Each owns its own Requirements and is the bucket TestSuites get organised under.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "create_project",
+        description: "Create a new Project. Optional 'key' is a short code (e.g. 'DELA') for human-friendly prefixes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                key: { type: "string" },
+                description: { type: "string" },
+                owner: { type: "string" },
+                status: { type: "string", enum: ["active", "archived"], default: "active" },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_processes",
+        description: "List business Processes under a Project. A Process (e.g. \"Intake\", \"Manifest\") sits between Project and Requirement; each Requirement is assigned to at most one. Returns id + prefixId (PRC-N) + name — use the id as process_id on create_requirement/update_requirement to plot requirements onto a process.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+            },
+            required: ["project_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_process",
+        description: "Create a business Process under a Project. prefix_id (PRC-N) is auto-allocated. Use the returned id as process_id on requirements to map them to this process.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                name: { type: "string" },
+                description: { type: "string" },
+                status: { type: "string", enum: ["active", "archived"], default: "active" },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["project_id", "name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "update_process",
+        description: "Update fields on a Process — name, description, status, tags. All fields optional; only the ones you pass are changed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                process_id: { type: "string" },
+                name: { type: "string" },
+                description: { type: ["string", "null"] },
+                status: { type: "string", enum: ["active", "archived"] },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["project_id", "process_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "delete_process",
+        description: "Delete a Process. Requirements assigned to it are NOT deleted — their process_id is set back to null (unassigned).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                process_id: { type: "string" },
+            },
+            required: ["project_id", "process_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_products",
+        description: "List Products under a Project. A Product is the documentation container; it links M:N to Processes and can hold product documentation (markdown, incl. embedded screenshots) on attributes.documentation.",
+        inputSchema: {
+            type: "object",
+            properties: { project_id: { type: "string" } },
+            required: ["project_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_product",
+        description: "Create a Product under a Project. Use `documentation` (markdown) for the product/werkproces documentation — embed screenshots with ![caption](/api/blobs/<id>) (upload via upload_screenshot). Works for not-yet-built functionality (text-first).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                name: { type: "string" },
+                description: { type: "string", description: "Short one-line summary." },
+                documentation: { type: "string", description: "Full product documentation in markdown (stored on attributes.documentation). May embed /api/blobs screenshots." },
+                status: { type: "string", enum: ["active", "archived"], default: "active" },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["project_id", "name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "update_product",
+        description: "Update a Product — name, short description, documentation (markdown), status, tags. All optional. Passing `documentation` replaces attributes.documentation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                product_id: { type: "string" },
+                name: { type: "string" },
+                description: { type: ["string", "null"] },
+                documentation: { type: "string", description: "Full product documentation markdown (stored on attributes.documentation)." },
+                status: { type: "string", enum: ["active", "archived"] },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["project_id", "product_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "link_product_to_process",
+        description: "Link a Product to a Process (M:N). Idempotent. Use this to attach the product documentation to the werkprocessen (PRC-N) it describes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                product_id: { type: "string" },
+                process_id: { type: "string" },
+            },
+            required: ["project_id", "product_id", "process_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "upload_screenshot",
+        description: "Upload an image to the Robotyx blob store and get back a ref. Pass image_path (a local file, e.g. a screenshot saved by selenium-mcp take_screenshot — read by the MCP host) OR image_base64. Use the ref to embed in product documentation or on test steps: ![caption](/api/blobs/<id>).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                image_path: { type: "string", description: "Local file path to an image (read by the MCP host). Use this OR image_base64." },
+                image_base64: { type: "string", description: "Base64-encoded image bytes. Use this OR image_path." },
+                mime_type: { type: "string", default: "image/png", description: "MIME type of the image." },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "list_requirements",
+        description: "List Requirements under a Project. Server orders parents first so the tree is easy to reconstruct via parentId. Each row carries prefixId (REQ-N) for human reference.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+            },
+            required: ["project_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_requirement",
+        description: "Fetch a Requirement with its immediate child requirements and linked test case ids.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                requirement_id: { type: "string" },
+            },
+            required: ["project_id", "requirement_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_requirement",
+        description: "Create a Requirement under a Project. prefix_id (REQ-N) is auto-allocated. Pass parent_id for hierarchical children, process_id to plot it onto a business Process, and the istqb_* fields to classify it (they round-trip through the app's Requirement editor).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                short_description: { type: "string" },
+                long_description: { type: "string" },
+                parent_id: { type: "string", description: "Optional parent requirement id for hierarchy." },
+                process_id: { type: ["string", "null"], description: "Optional business Process id (PRC-N's uuid) to assign this requirement to. null = unassigned. See list_processes / create_process." },
+                status: { type: "string", enum: ["draft", "reviewed", "approved", "implemented", "deprecated"], default: "draft" },
+                importance: { type: "string", enum: ["critical", "high", "medium", "low"], default: "medium" },
+                confluence_link: { type: "string" },
+                jira_story_link: { type: "string" },
+                spec_reference: { type: "string", description: "Free-form reference to a spec / doc / .md file — URL, repo path, or any identifier." },
+                istqb_test_level: { type: ["string", "null"], enum: ["component", "integration", "system", "acceptance", null], description: "ISTQB test level. Stored on attributes.istqbTestLevel — the same field the app's Requirement editor uses." },
+                istqb_quality_characteristic: { type: ["string", "null"], enum: ["functional suitability", "performance efficiency", "compatibility", "usability", "reliability", "security", "maintainability", "portability", null], description: "ISO/IEC 25010 quality characteristic (for non-functional reqs). Stored on attributes.istqbQualityCharacteristic." },
+                istqb_risk_class: { type: ["string", "null"], enum: ["low", "medium", "high", "critical", null], description: "Risk class = impact axis of the Product-Risk (PRA) matrix. Stored on attributes.istqbRiskClass." },
+                istqb_probability: { type: ["string", "null"], enum: ["low", "medium", "high", "critical", null], description: "Likelihood axis of the PRA matrix. Stored on attributes.istqbProbability." },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["project_id", "short_description"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "update_requirement",
+        description: "Update fields on an existing Requirement — short/long description, status, importance, parentId, process assignment, ISTQB classification, links. All fields optional; only the ones you pass are changed. ISTQB fields merge into the existing attributes bag (pass null/empty to clear one). Use this to apply AI-proposed refinements without recreating.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                requirement_id: { type: "string" },
+                short_description: { type: "string" },
+                long_description: { type: "string" },
+                parent_id: { type: ["string", "null"] },
+                process_id: { type: ["string", "null"], description: "Business Process id to assign (PRC-N's uuid), or null to unassign. See list_processes." },
+                status: { type: "string", enum: ["draft", "reviewed", "approved", "implemented", "deprecated"] },
+                importance: { type: "string", enum: ["critical", "high", "medium", "low"] },
+                confluence_link: { type: ["string", "null"] },
+                jira_story_link: { type: ["string", "null"] },
+                spec_reference: { type: ["string", "null"] },
+                istqb_test_level: { type: ["string", "null"], enum: ["component", "integration", "system", "acceptance", null], description: "ISTQB test level (attributes.istqbTestLevel). null/'' clears it." },
+                istqb_quality_characteristic: { type: ["string", "null"], enum: ["functional suitability", "performance efficiency", "compatibility", "usability", "reliability", "security", "maintainability", "portability", null], description: "ISO/IEC 25010 quality characteristic (attributes.istqbQualityCharacteristic)." },
+                istqb_risk_class: { type: ["string", "null"], enum: ["low", "medium", "high", "critical", null], description: "Risk class / impact axis of the PRA matrix (attributes.istqbRiskClass)." },
+                istqb_probability: { type: ["string", "null"], enum: ["low", "medium", "high", "critical", null], description: "Likelihood axis of the PRA matrix (attributes.istqbProbability)." },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["project_id", "requirement_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "update_test_case",
+        description: "Update fields on a TestCase — name, priority, status, workflow link, description, test data, expected result, screenshot URL, coverage. All fields optional. Pass workflow_id: null to unlink the workflow. Refinement loop: get_testsuite → propose changes → update_test_case.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                name: { type: "string" },
+                workflow_id: { type: ["string", "null"] },
+                priority: { type: "string", enum: ["P1", "P2", "P3", "P4"] },
+                status: { type: "string", enum: ["draft", "ready", "deprecated"] },
+                description: { type: ["string", "null"] },
+                test_data: { type: ["string", "null"] },
+                expected_result: { type: ["string", "null"] },
+                screenshot: { type: ["string", "null"], description: "Blob ref URL like /api/blobs/<sha>.png — upload bytes via /api/blobs first." },
+                tags: { type: "array", items: { type: "string" } },
+                coverage: { type: "string", enum: ["covered", "built_no_story", "transcript_no_story", "not_built", "unknown"], description: "Build/story kenmerk: covered=built+story; built_no_story=built, no story; transcript_no_story=in transcript, not built; not_built=gap/defect; unknown." },
+                automation: { type: ["string", "null"], enum: ["record", "refined", "automated", null], description: "Automation lifecycle kenmerk: record=footprint captured; refined=functional steps (expected results) authored; automated=runnable/replayable. Promote to 'refined' after filling expected results." },
+                recording_source: { type: ["string", "null"], enum: ["selenium", "windows", "manual", null], description: "Origin of the footprint (selenium | windows | manual)." },
+            },
+            required: ["testsuite_id", "testcase_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "link_requirement_to_testcase",
+        description: "Many-to-many link between a TestCase and a Requirement (traceability). Idempotent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                requirement_id: { type: "string" },
+                testcase_id: { type: "string" },
+            },
+            required: ["project_id", "requirement_id", "testcase_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_defect",
+        description: "File a defect against a TestSuite/TestCase (or standalone).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string" },
+                description: { type: "string" },
+                severity: { type: "string", enum: ["low", "medium", "high", "critical"], default: "medium" },
+                priority: { type: "string", enum: ["P0", "P1", "P2", "P3", "P4"], default: "P3" },
+                testsuite_id: { type: "string" },
+                testcase_id: { type: "string" },
+                source_label: { type: "string", default: "mcp-client" },
+            },
+            required: ["title"],
+            additionalProperties: false,
+        },
+    },
+];
+function isRawContent(v) {
+    return typeof v === "object" && v !== null && Array.isArray(v.__raw_content);
+}
+async function callTool(name, args) {
+    switch (name) {
+        case "list_workflows": {
+            const data = await robotyx("GET", "/api/workflows");
+            // The list endpoint returns summary rows only — no .steps. Call
+            // get_workflow on a specific id to inspect the step list.
+            const workflows = (data.workflows ?? []).map((w) => ({
+                id: w.id,
+                name: w.name,
+                tags: w.tags ?? [],
+                updatedAt: w.updatedAt,
+            }));
+            return { workflows };
+        }
+        case "get_workflow": {
+            const wf = await robotyx("GET", `/api/workflows/${args.workflow_id}`);
+            const mode = args.include_screenshots ?? "none";
+            const onlySet = new Set(Array.isArray(args.screenshot_step_indices) ? args.screenshot_step_indices : []);
+            // Always strip screenshots from the JSON payload — the URLs are short
+            // refs anyway and the image bytes are returned as image blocks.
+            const trimmed = [];
+            const screenshotsToFetch = [];
+            for (let i = 0; i < (wf.steps ?? []).length; i++) {
+                const s = wf.steps[i];
+                trimmed.push(trimStep(s, false)); // never inline; we attach image blocks instead.
+                const include = mode === "all" || (mode === "indices" && onlySet.has(i + 1));
+                // Live recordings store the ref on screenshotPath; footprint imports on
+                // parameters.screenshot. Accept either.
+                const ref = s.screenshotPath
+                    || s.parameters?.screenshot;
+                if (include && typeof ref === "string" && ref.length > 0) {
+                    screenshotsToFetch.push({
+                        stepIndex: i + 1,
+                        ref,
+                        action: String(s.action ?? ""),
+                        domain: String(s.domain ?? ""),
+                    });
+                }
+            }
+            const jsonPayload = { ...wf, steps: trimmed };
+            const content = [
+                { type: "text", text: JSON.stringify(jsonPayload, null, 2) },
+            ];
+            // Walk screenshots sequentially so steps stay in order. Failed fetches
+            // become text breadcrumbs instead of crashing the whole call.
+            for (const shot of screenshotsToFetch) {
+                let img;
+                if (shot.ref.startsWith("data:")) {
+                    img = dataUrlToBase64(shot.ref);
+                }
+                else {
+                    img = await fetchBlobBase64(shot.ref);
+                }
+                if (!img) {
+                    content.push({
+                        type: "text",
+                        text: `Screenshot for step ${shot.stepIndex} (${shot.domain}/${shot.action}): could not load ${shot.ref}`,
+                    });
+                    continue;
+                }
+                content.push({
+                    type: "text",
+                    text: `Screenshot for step ${shot.stepIndex} (${shot.domain}/${shot.action}):`,
+                });
+                content.push({
+                    type: "image",
+                    data: img.base64,
+                    mimeType: img.mimeType,
+                });
+            }
+            return { __raw_content: content };
+        }
+        case "list_testsuites": {
+            const data = await robotyx("GET", "/api/testsuites");
+            return { suites: data.suites ?? [] };
+        }
+        case "get_testsuite": {
+            return await robotyx("GET", `/api/testsuites/${args.testsuite_id}`);
+        }
+        case "create_testsuite": {
+            const body = { name: args.name, projectId: args.project_id };
+            if (args.category)
+                body.category = args.category;
+            if (args.description)
+                body.description = args.description;
+            if (args.owner)
+                body.owner = args.owner;
+            if (args.status)
+                body.status = args.status;
+            if (args.tags)
+                body.tags = args.tags;
+            return await robotyx("POST", "/api/testsuites", body);
+        }
+        case "add_test_case": {
+            const body = {
+                name: args.name,
+                workflowId: args.workflow_id ?? null,
+                priority: args.priority ?? "P3",
+                description: args.description ?? null,
+                expectedResult: args.expected_result ?? null,
+            };
+            if (args.coverage !== undefined)
+                body.coverage = args.coverage;
+            return await robotyx("POST", `/api/testsuites/${args.testsuite_id}/cases`, body);
+        }
+        case "add_test_step": {
+            const body = { description: args.description };
+            if (args.expected_result !== undefined)
+                body.expectedResult = args.expected_result;
+            if (args.order !== undefined)
+                body.order = args.order;
+            // Per-step screenshot: explicit ref wins; otherwise upload image_path to /api/blobs.
+            if (args.screenshot) {
+                body.screenshot = args.screenshot;
+            }
+            else if (args.image_path) {
+                body.screenshot = await uploadScreenshotRef(args.image_path, args.mime_type);
+            }
+            return await robotyx("POST", `/api/testsuites/${args.testsuite_id}/cases/${args.testcase_id}/steps`, body);
+        }
+        case "update_test_step": {
+            const body = {};
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.expected_result !== undefined)
+                body.expectedResult = args.expected_result;
+            if (args.order !== undefined)
+                body.order = args.order;
+            if (args.screenshot !== undefined)
+                body.screenshot = args.screenshot;
+            else if (args.image_path)
+                body.screenshot = await uploadScreenshotRef(args.image_path, args.mime_type);
+            return await robotyx("PATCH", `/api/testsuites/${args.testsuite_id}/cases/${args.testcase_id}/steps/${args.step_id}`, body);
+        }
+        case "delete_test_step": {
+            await robotyx("DELETE", `/api/testsuites/${args.testsuite_id}/cases/${args.testcase_id}/steps/${args.step_id}`);
+            return { deleted: true, step_id: args.step_id };
+        }
+        case "create_test_run": {
+            const body = { projectId: args.project_id };
+            if (args.id !== undefined)
+                body.id = args.id;
+            if (args.test_suite_id !== undefined)
+                body.testSuiteId = args.test_suite_id;
+            if (args.test_case_id !== undefined)
+                body.testCaseId = args.test_case_id;
+            if (args.seed_from_test_case_id !== undefined)
+                body.seedFromTestCaseId = args.seed_from_test_case_id;
+            if (args.seed_from_test_suite_id !== undefined)
+                body.seedFromTestSuiteId = args.seed_from_test_suite_id;
+            if (args.name !== undefined)
+                body.name = args.name;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.trigger !== undefined)
+                body.trigger = args.trigger;
+            if (args.environment !== undefined)
+                body.environment = args.environment;
+            if (args.external_ref !== undefined)
+                body.externalRef = args.external_ref;
+            if (args.started_at !== undefined)
+                body.startedAt = args.started_at;
+            if (args.completed_at !== undefined)
+                body.completedAt = args.completed_at;
+            if (args.duration_ms !== undefined)
+                body.durationMs = args.duration_ms;
+            if (Array.isArray(args.steps)) {
+                body.steps = args.steps.map((s) => ({
+                    testCaseId: s.test_case_id, testStepId: s.test_step_id, order: s.order,
+                    description: s.description, expectedResult: s.expected_result,
+                    expectedScreenshot: s.expected_screenshot, testData: s.test_data,
+                    status: s.status, actualScreenshot: s.actual_screenshot,
+                    error: s.error, durationMs: s.duration_ms,
+                }));
+            }
+            return await robotyx("POST", `/api/testruns`, body);
+        }
+        case "list_test_runs": {
+            const qs = new URLSearchParams();
+            if (args.project_id)
+                qs.set("projectId", args.project_id);
+            if (args.test_case_id)
+                qs.set("testCaseId", args.test_case_id);
+            if (args.test_suite_id)
+                qs.set("testSuiteId", args.test_suite_id);
+            const q = qs.toString();
+            const data = await robotyx("GET", `/api/testruns${q ? `?${q}` : ""}`);
+            return { runs: data.runs ?? [] };
+        }
+        case "get_test_run": {
+            return await robotyx("GET", `/api/testruns/${args.testrun_id}`);
+        }
+        case "update_test_run": {
+            const body = {};
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.name !== undefined)
+                body.name = args.name;
+            if (args.trigger !== undefined)
+                body.trigger = args.trigger;
+            if (args.environment !== undefined)
+                body.environment = args.environment;
+            if (args.external_ref !== undefined)
+                body.externalRef = args.external_ref;
+            if (args.started_at !== undefined)
+                body.startedAt = args.started_at;
+            if (args.completed_at !== undefined)
+                body.completedAt = args.completed_at;
+            if (args.duration_ms !== undefined)
+                body.durationMs = args.duration_ms;
+            return await robotyx("PATCH", `/api/testruns/${args.testrun_id}`, body);
+        }
+        case "add_case_to_test_run": {
+            return await robotyx("POST", `/api/testruns/${args.testrun_id}/cases`, {
+                testCaseId: args.test_case_id,
+            });
+        }
+        case "set_test_run_step_result": {
+            const body = {};
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.error !== undefined)
+                body.error = args.error;
+            if (args.duration_ms !== undefined)
+                body.durationMs = args.duration_ms;
+            if (args.actual_screenshot !== undefined)
+                body.actualScreenshot = args.actual_screenshot;
+            else if (args.image_path)
+                body.actualScreenshot = await uploadScreenshotRef(args.image_path, args.mime_type);
+            return await robotyx("PATCH", `/api/testruns/${args.testrun_id}/steps/${args.step_id}`, body);
+        }
+        case "delete_test_run": {
+            await robotyx("DELETE", `/api/testruns/${args.testrun_id}`);
+            return { deleted: true, testrun_id: args.testrun_id };
+        }
+        case "set_test_steps": {
+            const body = {
+                workflowStepIds: args.workflow_step_ids,
+                mappings: args.mappings.map((m) => ({
+                    description: m.description,
+                    expectedResult: m.expected_result ?? null,
+                    workflowStepIndices: m.workflow_step_indices,
+                })),
+                mode: args.mode ?? "replace",
+            };
+            return await robotyx("POST", `/api/testsuites/${args.testsuite_id}/cases/${args.testcase_id}/import-mapping`, body);
+        }
+        case "merge_step": {
+            return await robotyx("POST", `/api/testsuites/${args.testsuite_id}/cases/${args.testcase_id}/steps/${args.teststep_id}/merge`, {});
+        }
+        case "split_step": {
+            return await robotyx("POST", `/api/testsuites/${args.testsuite_id}/cases/${args.testcase_id}/steps/${args.teststep_id}/split`, {});
+        }
+        case "list_projects": {
+            const data = await robotyx("GET", "/api/projects");
+            return { projects: data.projects ?? [] };
+        }
+        case "create_project": {
+            const body = { name: args.name };
+            if (args.key)
+                body.key = args.key;
+            if (args.description)
+                body.description = args.description;
+            if (args.owner)
+                body.owner = args.owner;
+            if (args.status)
+                body.status = args.status;
+            if (args.tags)
+                body.tags = args.tags;
+            return await robotyx("POST", "/api/projects", body);
+        }
+        case "list_processes": {
+            const data = await robotyx("GET", `/api/projects/${args.project_id}/processes`);
+            return { processes: data.processes ?? [] };
+        }
+        case "create_process": {
+            const body = { name: args.name };
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.tags !== undefined)
+                body.tags = args.tags;
+            return await robotyx("POST", `/api/projects/${args.project_id}/processes`, body);
+        }
+        case "update_process": {
+            const body = {};
+            if (args.name !== undefined)
+                body.name = args.name;
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.tags !== undefined)
+                body.tags = args.tags;
+            return await robotyx("PATCH", `/api/projects/${args.project_id}/processes/${args.process_id}`, body);
+        }
+        case "delete_process": {
+            await robotyx("DELETE", `/api/projects/${args.project_id}/processes/${args.process_id}`);
+            return { deleted: true, process_id: args.process_id };
+        }
+        case "list_products": {
+            const data = await robotyx("GET", `/api/projects/${args.project_id}/products`);
+            return { products: data.products ?? [] };
+        }
+        case "create_product": {
+            const body = { name: args.name };
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.tags !== undefined)
+                body.tags = args.tags;
+            if (args.documentation !== undefined)
+                body.attributes = { documentation: args.documentation };
+            return await robotyx("POST", `/api/projects/${args.project_id}/products`, body);
+        }
+        case "update_product": {
+            const body = {};
+            if (args.name !== undefined)
+                body.name = args.name;
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.tags !== undefined)
+                body.tags = args.tags;
+            if (args.documentation !== undefined)
+                body.attributes = { documentation: args.documentation };
+            return await robotyx("PATCH", `/api/projects/${args.project_id}/products/${args.product_id}`, body);
+        }
+        case "link_product_to_process": {
+            await robotyx("POST", `/api/projects/${args.project_id}/products/${args.product_id}/processes/${args.process_id}`, {});
+            return { linked: true, product_id: args.product_id, process_id: args.process_id };
+        }
+        case "upload_screenshot": {
+            const mime = args.mime_type || "image/png";
+            let buf;
+            if (args.image_path)
+                buf = readFileSync(args.image_path);
+            else if (args.image_base64)
+                buf = Buffer.from(args.image_base64, "base64");
+            else
+                throw new Error("upload_screenshot requires image_path or image_base64");
+            const res = await fetch(`${ROBOTYX_URL}/api/blobs`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${ROBOTYX_API_KEY}`, "Content-Type": mime },
+                body: new Uint8Array(buf),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "");
+                throw new Error(`Robotyx POST /api/blobs → ${res.status} ${res.statusText}${t ? `: ${t}` : ""}`);
+            }
+            return await res.json();
+        }
+        case "list_requirements": {
+            const data = await robotyx("GET", `/api/projects/${args.project_id}/requirements`);
+            return { requirements: data.requirements ?? [] };
+        }
+        case "get_requirement": {
+            return await robotyx("GET", `/api/projects/${args.project_id}/requirements/${args.requirement_id}`);
+        }
+        case "create_requirement": {
+            const body = {
+                shortDescription: args.short_description,
+                longDescription: args.long_description ?? null,
+                processId: args.process_id ?? null,
+                parentId: args.parent_id ?? null,
+                status: args.status ?? "draft",
+                importance: args.importance ?? "medium",
+                confluenceLink: args.confluence_link ?? null,
+                jiraStoryLink: args.jira_story_link ?? null,
+                specReference: args.spec_reference ?? null,
+                tags: args.tags ?? [],
+            };
+            // ISTQB classification rides on the `attributes` bag using the exact keys
+            // the react-ui Requirement editor reads — only attach it when supplied.
+            if (hasIstqbArgs(args)) {
+                body.attributes = mergeIstqbAttributes({}, args);
+            }
+            return await robotyx("POST", `/api/projects/${args.project_id}/requirements`, body);
+        }
+        case "update_requirement": {
+            const body = {};
+            if (args.short_description !== undefined)
+                body.shortDescription = args.short_description;
+            if (args.long_description !== undefined)
+                body.longDescription = args.long_description;
+            if (args.process_id !== undefined)
+                body.processId = args.process_id;
+            if (args.parent_id !== undefined)
+                body.parentId = args.parent_id;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.importance !== undefined)
+                body.importance = args.importance;
+            if (args.confluence_link !== undefined)
+                body.confluenceLink = args.confluence_link;
+            if (args.jira_story_link !== undefined)
+                body.jiraStoryLink = args.jira_story_link;
+            if (args.spec_reference !== undefined)
+                body.specReference = args.spec_reference;
+            if (args.tags !== undefined)
+                body.tags = args.tags;
+            // ISTQB picks merge into the *existing* attributes so we never clobber
+            // other keys the bag holds — needs a read-before-write because the PATCH
+            // replaces attributes wholesale server-side.
+            if (hasIstqbArgs(args)) {
+                const current = await robotyx("GET", `/api/projects/${args.project_id}/requirements/${args.requirement_id}`);
+                body.attributes = mergeIstqbAttributes(current?.attributes ?? {}, args);
+            }
+            return await robotyx("PATCH", `/api/projects/${args.project_id}/requirements/${args.requirement_id}`, body);
+        }
+        case "update_test_case": {
+            const body = {};
+            if (args.name !== undefined)
+                body.name = args.name;
+            if (args.workflow_id !== undefined)
+                body.workflowId = args.workflow_id;
+            if (args.priority !== undefined)
+                body.priority = args.priority;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.test_data !== undefined)
+                body.testData = args.test_data;
+            if (args.expected_result !== undefined)
+                body.expectedResult = args.expected_result;
+            if (args.screenshot !== undefined)
+                body.screenshot = args.screenshot;
+            if (args.tags !== undefined)
+                body.tags = args.tags;
+            if (args.coverage !== undefined)
+                body.coverage = args.coverage;
+            if (args.automation !== undefined)
+                body.automation = args.automation;
+            if (args.recording_source !== undefined)
+                body.recordingSource = args.recording_source;
+            return await robotyx("PATCH", `/api/testsuites/${args.testsuite_id}/cases/${args.testcase_id}`, body);
+        }
+        case "link_requirement_to_testcase": {
+            return await robotyx("POST", `/api/projects/${args.project_id}/requirements/${args.requirement_id}/testcases/${args.testcase_id}`, {});
+        }
+        case "create_defect": {
+            const body = {
+                title: args.title,
+                description: args.description ?? null,
+                severity: args.severity ?? "medium",
+                priority: args.priority ?? "P3",
+                testSuiteId: args.testsuite_id ?? null,
+                testCaseId: args.testcase_id ?? null,
+                sourceLabel: args.source_label ?? "mcp-client",
+            };
+            return await robotyx("POST", "/api/defects", body);
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+// ── Server boot ─────────────────────────────────────────────────────────── //
+const server = new Server({ name: "robotyx-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+        const result = await callTool(name, (args ?? {}));
+        if (isRawContent(result)) {
+            return { content: result.__raw_content };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: err.message ?? String(err) }],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[robotyx-mcp] connected, target ${ROBOTYX_URL}\n`);