common-qa-mcp 0.3.0 → 0.4.0

package/dist/tools/discovery.tools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { ok, err } from '../mcpResult.js';
-import { zJournalOp } from './schemas.js';
+import { zJournalOp, zRawFilter } from './schemas.js';
 import { stepsMarkdown } from './markdown.js';
 const NOT_CONNECTED = 'Not connected to a product. Use qa_connect({ url, token, projectId }) first — listing and ' +
     'reading existing test cases needs a live backend connection (the offline path only authors drafts).';
@@ -11,6 +11,50 @@ function describeError(e) {
 function escCell(v) {
     return String(v ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
 }
+/** SQA adapter attaches `totalCount` as a side-band prop on the returned array (via
+ *  mapper.withTotal). The provider interface declares plain `T[]`, so read it via a widening cast. */
+function totalOf(rows) {
+    const t = rows.totalCount;
+    return typeof t === 'number' ? t : undefined;
+}
+/** Header line for a list tool: "Showing 100 of 350 test cases" when the backend returned a
+ *  totalCount larger than the page, else "N test cases". Pluralises via `plural` (defaults to `s`
+ *  suffix — pass explicit forms for "stor y/ies", etc). */
+function countHeader(rows, singular, plural = singular + 's') {
+    const shown = rows.length;
+    const total = totalOf(rows) ?? shown;
+    const word = total === 1 ? singular : plural;
+    return total > shown ? `Showing ${shown} of ${total} ${word}` : `${total} ${word}`;
+}
+/** One-line human summary of a single version's dependency row from `delete_version`'s dry-run.
+ *  Shape branches on `parentType`: TC has 7 ref maps (defects, suites, execplans, scenarios,
+ *  schedulers, pipelines, workflows), FN has 3 (tcs, fns, workflows). Each map is {projectId → ids}. */
+function renderVersionDepRow(dep) {
+    const totalIn = (m) => Object.values(m).reduce((n, arr) => n + arr.length, 0);
+    const parts = [];
+    if ('defectArr' in dep) {
+        const d = dep;
+        const bits = [
+            ['defect', totalIn(d.defectArr)], ['suite', totalIn(d.suiteArr)],
+            ['exec-plan', totalIn(d.epArr)], ['scenario', totalIn(d.scenarioArr)],
+            ['schedule', totalIn(d.schedulerArr)], ['pipeline', totalIn(d.pipelineArr)],
+            ['workflow', totalIn(d.workflowArr)],
+        ];
+        for (const [label, n] of bits)
+            if (n)
+                parts.push(`${n} ${label}${n === 1 ? '' : 's'}`);
+    }
+    else {
+        const d = dep;
+        const bits = [
+            ['test case', totalIn(d.tcArr)], ['function', totalIn(d.fnArr)], ['workflow', totalIn(d.wfArr)],
+        ];
+        for (const [label, n] of bits)
+            if (n)
+                parts.push(`${n} ${label}${n === 1 ? '' : 's'}`);
+    }
+    return parts.length ? `- ${parts.join(', ')}` : '- (no references)';
+}
 export function registerDiscoveryTools(server, deps) {
     server.registerTool('list_projects', {
         title: 'List projects (resolve a project name to its id)',
@@ -26,30 +70,39 @@ export function registerDiscoveryTools(server, deps) {
         try {
             const rows = await adapter.listProjects();
             if (!rows.length)
-                return ok('No projects found.', { projects: [] });
-            const text = `${rows.length} project${rows.length === 1 ? '' : 's'}:\n\n` +
-                '| id | name | test cases |\n|---|---|---|\n' +
-                rows.map((p) => `| ${escCell(p.id)} | ${escCell(p.name)} | ${p.counts?.['testCases'] ?? '-'} |`).join('\n');
-            return ok(text, { projects: rows });
+                return ok('No projects found.', { projects: [], totalCount: totalOf(rows) ?? 0 });
+            const view = rows.map(({ id: _id, ...rest }) => rest);
+            const text = `${countHeader(rows, 'project')}:\n\n` +
+                '| key | name | test cases |\n|---|---|---|\n' +
+                rows.map((p) => `| ${escCell(p.code)} | ${escCell(p.name)} | ${p.counts?.['testCases'] ?? '-'} |`).join('\n');
+            return ok(text, { projects: view, totalCount: totalOf(rows) ?? rows.length });
         }
         catch (e) {
             return err(describeError(e));
         }
     });
     server.registerTool('tc_list', {
-        title: 'List / search existing test cases',
-        description: 'List or search EXISTING test cases in the connected product. Requires a live connection ' +
-            '(qa_connect). Returns a summary list — id, title, priority, status, step count. Use tc_get ' +
-            'to read one in full. This is a read-only, product-neutral tool: it works identically ' +
-            'whichever product the session is connected to.',
+        title: 'List / search existing test cases (NOT reusable functions)',
+        description: 'List or search EXISTING TEST CASES (TC_* ids) in the connected product. NOT for reusable ' +
+            'functions: if the user asks for functions, FN_*, the function library, or reusable steps, ' +
+            'use `list_functions` instead. Trigger words for THIS tool: "test case", "TC", "TC_", ' +
+            '"scenario", "script". Requires a live connection (qa_connect). Returns a summary list — id, ' +
+            'title, technology, execution type, status, step count. Use `tc_get` to read one in full. ' +
+            'Read-only, product-neutral.',
         inputSchema: {
             search: z.string().optional().describe('Free-text search over title / id.'),
             status: z.string().optional().describe('Filter by status.'),
             limit: z.number().int().positive().optional().describe('Max results (paging).'),
             offset: z.number().int().nonnegative().optional().describe('Result offset (paging).'),
+            createdBy: z.string().optional().describe('Numeric userId of the creator. Pass "me" to filter by the current caller (needs QA_MCP_USER_ID for API-key auth). Resolve names to ids via list_users first.'),
+            updatedBy: z.string().optional().describe('Numeric userId of the last updater. Pass "me" for the current caller. Resolve names via list_users first.'),
+            storyId: z.string().optional().describe('Only test cases tagged to this user story (id or business key, e.g. US_123).'),
+            moduleId: z.string().optional().describe('Only test cases filed under this module (id or business key, e.g. MO_12). SimplifyQA only — ignored elsewhere.'),
+            obsolete: z.boolean().optional().describe('True → only obsolete TCs; false → only non-obsolete. Omit to include both. The response summary always reports how many of the returned rows are obsolete.'),
+            filters: z.array(zRawFilter).optional().describe('Extra raw column filters for project-configured columns with no dedicated parameter above (Release/Priority/custom fields) — use the field\'s backend key as `column`.'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ search, status, limit, offset }) => {
+    }, async ({ search, status, limit, offset, createdBy, updatedBy, storyId, moduleId, obsolete, filters }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
@@ -59,16 +112,25 @@ export function registerDiscoveryTools(server, deps) {
                 ...(status !== undefined ? { status } : {}),
                 ...(limit !== undefined ? { limit } : {}),
                 ...(offset !== undefined ? { offset } : {}),
+                ...(createdBy !== undefined ? { createdBy } : {}),
+                ...(updatedBy !== undefined ? { updatedBy } : {}),
+                ...(storyId !== undefined ? { storyId } : {}),
+                ...(moduleId !== undefined ? { moduleId } : {}),
+                ...(obsolete !== undefined ? { obsolete } : {}),
+                ...(filters?.length ? { filters } : {}),
             };
             const rows = await adapter.listTestCases(q);
             if (!rows.length)
-                return ok('No test cases found.', { testCases: [] });
-            const text = `${rows.length} test case${rows.length === 1 ? '' : 's'}:\n\n` +
-                '| id | title | priority | status | steps |\n|---|---|---|---|---|\n' +
+                return ok('No test cases found.', { testCases: [], totalCount: totalOf(rows) ?? 0 });
+            const view = rows.map(({ id: _id, priority: _p, ...rest }) => rest);
+            const obsoleteCount = rows.filter((r) => r.obsolete === true).length;
+            const obsoleteNote = obsoleteCount ? ` · ${obsoleteCount} obsolete` : '';
+            const text = `${countHeader(rows, 'test case')}${obsoleteNote}:\n\n` +
+                '| key | title | technology | execution | status | steps | obsolete |\n|---|---|---|---|---|---|---|\n' +
                 rows
-                    .map((r) => `| ${escCell(r.id)} | ${escCell(r.title)} | ${r.priority} | ${r.status ?? '-'} | ${r.stepCount ?? '-'} |`)
+                    .map((r) => `| ${escCell(r.code)} | ${escCell(r.title)} | ${r.technologyType ?? '-'} | ${r.executionType ?? '-'} | ${r.status ?? '-'} | ${r.stepCount ?? '-'} | ${r.obsolete === true ? 'yes' : ''} |`)
                     .join('\n');
-            return ok(text, { testCases: rows });
+            return ok(text, { testCases: view, totalCount: totalOf(rows) ?? rows.length, obsoleteOnPage: obsoleteCount });
         }
         catch (e) {
             return err(describeError(e));
@@ -78,21 +140,53 @@ export function registerDiscoveryTools(server, deps) {
         title: 'Read one test case (with steps)',
         description: 'Read a single EXISTING test case in full — metadata plus its steps as a readable table — ' +
             'from the connected product. Requires a live connection (qa_connect). `id` accepts the ' +
-            "product's id or business key. Product-neutral: same shape on any connected product.",
+            "product's id or business key. Product-neutral: same shape on any connected product.\n\n" +
+            'VERSIONS: SimplifyQA TCs can have multiple versions, each with its own steps. When the TC ' +
+            "has more than one version and `versionId` is omitted, this tool REFUSES and lists the " +
+            "available versions — ASK the user which one to read, then call again with `versionId`. " +
+            "Pass `versionId: ''` (empty string) to accept the TC's currently-selected version. Single- " +
+            'version TCs are read directly. Providers without versioning (Walnut) ignore `versionId`.',
         inputSchema: {
             id: z.string().describe('The test case id (or business key) to read.'),
+            versionId: z.string().optional().describe("Version to read (an id from the TC's `versions[]`). Omit to trigger the ASK-user " +
+                "prompt when the TC has multiple versions. Pass '' (empty string) to accept the TC's " +
+                'currently-selected version without prompting.'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ id }) => {
+    }, async ({ id, versionId }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
         try {
-            const tc = await adapter.getTestCase(id);
-            const steps = tc.steps.length;
+            // Cheap pre-flight: read the TC without steps so we can inspect versions before deciding
+            // whether to prompt. Adapter's getTestCase(id) with no versionId is the natural way, and
+            // for SQA the version list is on the TC doc itself so this is one HTTP round-trip that
+            // we're going to do anyway.
+            const preview = await adapter.getTestCase(id);
+            const versions = preview.versions ?? [];
+            if (versions.length > 1 && versionId === undefined) {
+                const listing = versions
+                    .map((v) => `  • \`${v.id}\` — **${v.name}**${v.isCurrent ? ' (current)' : ''}${v.reviewApproveStatus ? ` · ${v.reviewApproveStatus}` : ''}`)
+                    .join('\n');
+                return err(`Test case ${preview.id ?? id} has ${versions.length} versions — ASK the user which ` +
+                    `one to read, then call \`tc_get\` again with { id, versionId }. ` +
+                    `Pass \`versionId: ''\` to accept the current version.\n\n${listing}`);
+            }
+            // versionId === '' means "explicit current" — pass undefined to the adapter (its default).
+            // Otherwise pass through.
+            const chosen = versionId === undefined || versionId === '' ? undefined : versionId;
+            const tc = chosen ? await adapter.getTestCase(id, chosen) : preview;
+            const stepCount = tc.steps.length;
+            const versionLine = tc.versions?.length
+                ? (() => {
+                    const current = tc.versions.find((v) => v.isCurrent) ?? tc.versions[tc.versions.length - 1];
+                    return ` · version: ${current.name}${tc.versions.length > 1 ? ` (${tc.versions.length} total)` : ''}`;
+                })()
+                : '';
             const header = `**${tc.title}**${tc.id ? ` · ${tc.id}` : ''}\n` +
                 `priority: ${tc.priority} · category: ${tc.category}` +
-                `${tc.status ? ` · status: ${tc.status}` : ''} · ${steps} step${steps === 1 ? '' : 's'}`;
+                `${tc.status ? ` · status: ${tc.status}` : ''} · ${stepCount} step${stepCount === 1 ? '' : 's'}` +
+                versionLine;
             return ok(`${header}\n\n${stepsMarkdown(tc)}`, { tc });
         }
         catch (e) {
@@ -100,19 +194,233 @@ export function registerDiscoveryTools(server, deps) {
         }
     });
     server.registerTool('tc_delete', {
-        title: 'Delete a test case',
-        description: 'Delete an existing test case in the connected product. It is RECOVERABLE from the product ' +
-            'recycle bin, not a hard delete. Requires a live connection (qa_connect). `tcId` accepts the ' +
-            "product's id or business key. Product-neutral.",
-        inputSchema: { tcId: z.string().describe('The test case id (or business key) to delete.') },
-        annotations: { readOnlyHint: false },
-    }, async ({ tcId }) => {
+        title: 'Delete a test case (two-step confirm)',
+        description: 'Soft-delete an existing test case in the connected product. TWO-STEP CONFIRM: call once ' +
+            'with just `tcId` to preview the target (title + step count) and get a warning; then call ' +
+            'again with `{ tcId, confirm: true }` to actually delete. Refuses to delete without ' +
+            "`confirm:true`. `tcId` accepts the product's id or business key. Requires a live " +
+            'connection (qa_connect). Product-neutral.',
+        inputSchema: {
+            tcId: z.string().describe('The test case id (or business key) to delete.'),
+            confirm: z.boolean().optional().describe('Set to true on the SECOND call to actually delete.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ tcId, confirm }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
+        if (!confirm) {
+            try {
+                // Delete preview: read the current version — no step-collapse hint anymore since
+                // the adapter's getTestCase signature dropped that arg in favor of a versionId param.
+                const tc = await adapter.getTestCase(tcId);
+                const steps = tc.steps.length;
+                return ok(`⚠️ About to delete test case **${tc.title}**` +
+                    `${tc.id ? ` (${tc.id})` : ''} — ${steps} step${steps === 1 ? '' : 's'}. ` +
+                    `To proceed, call again with { tcId: "${tcId}", confirm: true }.`, { preview: true, tc });
+            }
+            catch (e) {
+                return err(describeError(e));
+            }
+        }
         try {
             await adapter.deleteTestCase(tcId);
-            return ok(`Deleted ${tcId} — recoverable from the product's recycle bin.`);
+            return ok(`Deleted ${tcId}.`);
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('tc_clone', {
+        title: 'Clone a test case (copy in place with steps, versions, testdata)',
+        description: 'FOR TEST CASES ONLY. NOT for reusable functions: if the user names an `FN_*` key or asks to ' +
+            'clone a function, use `fn_clone` instead. Trigger words for THIS tool: "test case", "TC", ' +
+            '"TC_", "scenario", "script".\n\n' +
+            'Save an existing test case as a NEW copy in the SAME project + module — all steps, ' +
+            'versions, test data (all environments), parameters, object refs, and nested function ' +
+            "calls are carried over. Uses SimplifyQA's native TC/FN copy endpoint. `tcId` accepts the " +
+            "product's id or business key (`TC_*`).\n\n" +
+            'Naming: pass `newName` for a custom title; otherwise the backend auto-names the copy as ' +
+            '`{sourceName}_copy1`, `_copy2`, etc.\n\n' +
+            'VERSIONS — TWO-STEP: call once WITHOUT `versions` to get a preview of the source\'s ' +
+            'versions and confirm with the user which to clone; then call again with `versions` set. ' +
+            '`versions:["*"]` clones every version; `versions:["v1.0","v2.0",...]` clones only those. ' +
+            'The tool REFUSES to clone until `versions` is passed — the preview step is not skippable.\n\n' +
+            'PERMISSION: requires the `copy_testcase_across_project` privilege on the project (admins ' +
+            "have it by default; other roles need it granted). If you get a permission error, ask your " +
+            'project admin. Requires a live connection.',
+        inputSchema: {
+            tcId: z.string().describe('The source test case id or business key (e.g. TC_123).'),
+            newName: z.string().optional().describe('Custom title for the copy. Omit to let the backend auto-name it (`{sourceName}_copy1`).'),
+            versions: z.array(z.string()).optional().describe('REQUIRED to actually clone. Version NAMES to clone (e.g. ["v1.0"]), or ["*"] to clone every version. Omit on the first call to get a preview + version list; ask the user which they want; then call again with the chosen value.'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ tcId, newName, versions }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.cloneTestCase)
+            return err('This product does not support test-case clone.');
+        if (!adapter.getTestCase)
+            return err('This product does not support test-case read.');
+        // Preview step: no `versions` → fetch the source's version list and hand it back so the
+        // caller can confirm with the user which to clone. Adapter is not touched for the write.
+        if (versions === undefined) {
+            try {
+                const tc = await adapter.getTestCase(tcId);
+                const names = (tc.versions ?? []).map((v) => v.name);
+                if (names.length === 0) {
+                    return err(`Cannot clone ${tcId}: source has no versions to copy.`);
+                }
+                return ok(`**${tcId}** has ${names.length} version${names.length === 1 ? '' : 's'}: ` +
+                    `${names.map((n) => `\`${n}\``).join(', ')}.\n\n` +
+                    `**Ask the user which version(s) to clone**, then call \`tc_clone\` again:\n` +
+                    `- \`versions: ["*"]\` → clone ALL versions\n` +
+                    `- \`versions: ${JSON.stringify([names[0]])}\` → clone only that version\n` +
+                    `- \`versions: [name1, name2]\` → clone a specific subset`, { preview: true, versions: names, totalCount: names.length });
+            }
+            catch (e) {
+                return err(describeError(e));
+            }
+        }
+        // Explicit sentinel ["*"] = "all versions" — pass through as undefined to the adapter.
+        const isAll = versions.length === 1 && versions[0] === '*';
+        const effectiveVersions = isAll ? undefined : versions;
+        try {
+            const ref = await adapter.cloneTestCase(tcId, newName, effectiveVersions);
+            const nameNote = newName ? ` renamed to **${newName}**` : ' (auto-named by the backend)';
+            const versionNote = isAll
+                ? ' All versions were carried over.'
+                : ` Only version(s) ${versions.map((v) => `**${v}**`).join(', ')} were carried over.`;
+            return ok(`Cloned ${tcId} →${nameNote}. New id: **${ref.id}**` +
+                (ref.productUrl ? ` · ${ref.productUrl}` : '') +
+                `.${versionNote}`, { savedRef: ref });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('tc_save_as_new_version', {
+        title: 'Snapshot a test case as a new version',
+        description: 'FOR TEST CASES ONLY. NOT for reusable functions: if the user names an `FN_*` key or asks to ' +
+            'snapshot / create a new version of a function, use `fn_save_as_new_version` instead. ' +
+            'Trigger words for THIS tool: "test case", "TC", "TC_", "scenario", "script".\n\n' +
+            'Freeze the CURRENT server state of a test case under a NEW version name — same TC id, a ' +
+            'new version row with cloned steps. Mirrors the SimplifyQA UI "Save as new version" dialog ' +
+            '(operation: SAVENEWVERSION). `tcId` accepts the numeric id or business key (`TC_*`).\n\n' +
+            '`versionName` must be unique for this TC — the backend rejects duplicates.\n\n' +
+            '`tdCopy` (default TRUE) clones the source version\'s testdata iterations across every ' +
+            'environment. Pass `false` to copy only the iteration STRUCTURE — values are empty, and ' +
+            'parameters without a project-level defaultValue get suffixed column names. That matches ' +
+            'the FE\'s "Cancel" button on the testdata-copy prompt.\n\n' +
+            '`sourceVersionId` picks which version to snapshot; omit to snapshot the TC\'s currently ' +
+            'selected version. Requires a live connection.',
+        inputSchema: {
+            tcId: z.string().describe('The test case id or business key (e.g. TC_123).'),
+            versionName: z.string().min(1).describe('Name for the new version (must be unique for this TC).'),
+            tdCopy: z.boolean().optional().describe('Clone testdata iterations from the source version. Default: true.'),
+            sourceVersionId: z.string().optional().describe('Version to snapshot; defaults to the TC\'s current version.'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ tcId, versionName, tdCopy, sourceVersionId }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.saveAsNewVersion)
+            return err('This product does not support save-as-new-version.');
+        const effectiveTdCopy = tdCopy ?? true;
+        try {
+            const ref = await adapter.saveAsNewVersion(tcId, {
+                versionName,
+                tdCopy: effectiveTdCopy,
+                ...(sourceVersionId !== undefined ? { sourceVersionId } : {}),
+            });
+            const tdNote = effectiveTdCopy
+                ? ' Testdata iterations were copied across environments.'
+                : ' Testdata structure was carried over but values are empty (tdCopy:false).';
+            return ok(`Snapshotted ${tcId} as new version **${versionName}**` +
+                (ref.productUrl ? ` · ${ref.productUrl}` : '') +
+                `.${tdNote}`, { savedRef: ref });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('tc_steps_to_function', {
+        title: 'Extract selected steps of a test case into a new reusable function',
+        description: 'Take a subset of the steps on an EXISTING test case and save them as a new reusable ' +
+            'function (SimplifyQA STEPSTOFN operation). Mirrors the FE "Save as function" modal. ' +
+            'Steps are picked by their current `seq`, resequenced 1..N in the new function, and filed ' +
+            'under `moduleId`. `tcId` accepts the numeric id or business key (TC_123). Requires a live ' +
+            'connection (qa_connect).\n\n' +
+            'CALL THIS when the user says things like "save these steps as a function", "convert the ' +
+            'first N steps to a function", "extract these steps into a function". Show the steps of the ' +
+            'TC first (via tc_get) so the user can confirm which `seq`s to extract, and ASK the user ' +
+            'which module to file the new function under — call `list_modules` if the module id is not ' +
+            'known.\n\n' +
+            '`executionType` forces every picked step into the AUTOMATION or MANUAL bucket; omit to ' +
+            'split by each step\'s own executionType (function will be DUO if both are present).\n\n' +
+            'TESTDATA: iterations from the source TC version are copied to the new function by default. ' +
+            'The backend prunes them to only the parameters the extracted steps reference (via key-based ' +
+            'matching in tcfn.service.js `compareDatas` `isStepsToFn` mode), across every environment ' +
+            'the source version has. Pass `copyTestData: false` if you explicitly want a bare function.\n\n' +
+            'REPLACE-IN-SOURCE: pass `replaceInSource: true` to also splice a FUNCTION + FUNCTION_END ' +
+            'pair back into the source TC in place of the extracted steps (mirrors the FE "Save & Replace" ' +
+            'button). The extracted rows are soft-deleted; the backend automatically drops any testdata ' +
+            'columns those steps owned and injects an FN cell (with the FN\'s per-env default iteration) ' +
+            'into every TC iteration row. Requires a contiguous `stepSeqs` range and refuses picks that ' +
+            'cross control-flow (IF/WHILE/FOR/DO) or nested FUNCTION brackets, and DUO/SYNCON TCs — those ' +
+            'are v2 cases.\n\n' +
+            'FAILURE MODE with replaceInSource: if the FN is created but the follow-up PUT fails, the ' +
+            'error surfaces the new fn id + version id so you can retry or delete the phantom function.',
+        inputSchema: {
+            tcId: z.string().describe('The source test case id or business key (e.g. TC_123).'),
+            stepSeqs: z.array(z.number().int().positive()).min(1)
+                .describe('Current `seq` numbers of the steps to extract (e.g. [1,2,3,4] for the first four). Must be contiguous when replaceInSource is true.'),
+            name: z.string().min(1).describe('Name for the new function.'),
+            moduleId: z.number().int().positive()
+                .describe('Module id to file the new function under. Resolve via list_modules if unknown.'),
+            executionType: z.enum(['AUTOMATION', 'MANUAL']).optional()
+                .describe('Force all picked steps into this bucket; omit to split by each step\'s own executionType.'),
+            copyTestData: z.boolean().optional()
+                .describe('Copy the source version\'s testdata iterations to the new function (backend prunes to only the params the extracted steps use). Default: true.'),
+            replaceInSource: z.boolean().optional()
+                .describe('Replace the extracted steps on the source TC with a FUNCTION + FUNCTION_END call to the new function. Default: false (create-only). Requires contiguous stepSeqs and refuses DUO/SYNCON/control-flow spans.'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ tcId, stepSeqs, name, moduleId, executionType, copyTestData, replaceInSource }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.saveStepsAsFunction) {
+            return err('This product does not support extracting steps to a function.');
+        }
+        const tdCopy = copyTestData ?? true;
+        const tdNote = tdCopy
+            ? ' Testdata iterations were copied (pruned to the extracted steps\' parameters).'
+            : ' No testdata was copied.';
+        if (replaceInSource) {
+            if (!adapter.extractStepsAsFunctionAndReplace) {
+                return err('This product does not support replace-in-source for step-to-function extraction.');
+            }
+            try {
+                const ref = await adapter.extractStepsAsFunctionAndReplace(tcId, {
+                    stepSeqs, name, moduleId, copyTestData: tdCopy,
+                    ...(executionType !== undefined ? { executionType } : {}),
+                });
+                return ok(`Created function **${name}** (id: ${ref.fnId}, version: ${ref.fnVersionId}) and replaced ` +
+                    `steps [${stepSeqs.join(', ')}] on ${tcId} with a FUNCTION call.${tdNote}`, { savedRef: ref });
+            }
+            catch (e) {
+                return err(describeError(e));
+            }
+        }
+        try {
+            const ref = await adapter.saveStepsAsFunction(tcId, {
+                stepSeqs, name, moduleId, copyTestData: tdCopy,
+                ...(executionType !== undefined ? { executionType } : {}),
+            });
+            return ok(`Created function **${name}** (id: ${ref.id}) from ${tcId} steps [${stepSeqs.join(', ')}].${tdNote}`, { savedRef: ref });
         }
         catch (e) {
             return err(describeError(e));
@@ -131,9 +439,13 @@ export function registerDiscoveryTools(server, deps) {
             offset: z.number().int().nonnegative().optional(),
             sprintId: z.string().optional().describe('Only stories that belong to this sprint (from list_sprints).'),
             releaseId: z.string().optional().describe('Only stories that belong to this release (from list_releases).'),
+            createdBy: z.string().optional().describe('Numeric userId of the creator. Pass "me" to filter by the current caller (needs QA_MCP_USER_ID for API-key auth). Resolve names to ids via list_users first.'),
+            updatedBy: z.string().optional().describe('Numeric userId of the last updater. Pass "me" for the current caller. Resolve names via list_users first.'),
+            ownerId: z.string().optional().describe('Numeric userId of the story OWNER (assignee). Pass "me" for the current caller. Resolve names via list_users first.'),
+            filters: z.array(zRawFilter).optional().describe('Extra raw column filters for project-configured columns with no dedicated parameter above (Feature/Epic/Priority/custom fields) — use the field\'s backend key as `column`.'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ search, status, limit, offset, sprintId, releaseId }) => {
+    }, async ({ search, status, limit, offset, sprintId, releaseId, createdBy, updatedBy, ownerId, filters }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
@@ -147,13 +459,18 @@ export function registerDiscoveryTools(server, deps) {
                 ...(offset != null ? { offset } : {}),
                 ...(sprintId ? { sprintId } : {}),
                 ...(releaseId ? { releaseId } : {}),
+                ...(createdBy ? { createdBy } : {}),
+                ...(updatedBy ? { updatedBy } : {}),
+                ...(ownerId ? { ownerId } : {}),
+                ...(filters?.length ? { filters } : {}),
             });
             if (!rows.length)
-                return ok('No user stories found.', { stories: [] });
-            const text = `${rows.length} stor${rows.length === 1 ? 'y' : 'ies'}:\n\n` +
+                return ok('No user stories found.', { stories: [], totalCount: totalOf(rows) ?? 0 });
+            const view = rows.map(({ id: _id, ...rest }) => rest);
+            const text = `${countHeader(rows, 'story', 'stories')}:\n\n` +
                 '| key | title | status |\n|---|---|---|\n' +
                 rows.map((s) => `| ${escCell(s.key ?? s.id)} | ${escCell(s.title)} | ${escCell(s.status ?? '-')} |`).join('\n');
-            return ok(text, { stories: rows });
+            return ok(text, { stories: view, totalCount: totalOf(rows) ?? rows.length });
         }
         catch (e) {
             return err(describeError(e));
@@ -205,13 +522,13 @@ export function registerDiscoveryTools(server, deps) {
         try {
             const rows = await adapter.listReleases({ scope });
             if (!rows.length)
-                return ok(`No releases found (scope: ${scope}).`, { releases: [] });
-            const text = `${rows.length} release${rows.length === 1 ? '' : 's'} (scope: ${scope}):\n\n` +
+                return ok(`No releases found (scope: ${scope}).`, { releases: [], totalCount: totalOf(rows) ?? 0 });
+            const text = `${countHeader(rows, 'release')} (scope: ${scope}):\n\n` +
                 '| id | name | state | planned start | planned end |\n|---|---|---|---|---|\n' +
                 rows
                     .map((r) => `| ${escCell(r.id)} | ${escCell(r.name)} | ${escCell(r.state ?? '-')} | ${escCell(r.plannedStartDate ?? '-')} | ${escCell(r.plannedEndDate ?? '-')} |`)
                     .join('\n');
-            return ok(text, { releases: rows });
+            return ok(text, { releases: rows, totalCount: totalOf(rows) ?? rows.length });
         }
         catch (e) {
             return err(describeError(e));
@@ -236,13 +553,266 @@ export function registerDiscoveryTools(server, deps) {
         try {
             const rows = await adapter.listSprints(releaseId !== undefined ? { releaseId } : {});
             if (!rows.length)
-                return ok('No sprints found.', { sprints: [] });
-            const text = `${rows.length} sprint${rows.length === 1 ? '' : 's'}${releaseId ? ` (release ${releaseId})` : ''}:\n\n` +
+                return ok('No sprints found.', { sprints: [], totalCount: totalOf(rows) ?? 0 });
+            const text = `${countHeader(rows, 'sprint')}${releaseId ? ` (release ${releaseId})` : ''}:\n\n` +
                 '| id | name | release | state | planned start | planned end |\n|---|---|---|---|---|---|\n' +
                 rows
                     .map((s) => `| ${escCell(s.id)} | ${escCell(s.name)} | ${escCell(s.releaseId ?? '-')} | ${escCell(s.state ?? '-')} | ${escCell(s.plannedStartDate ?? '-')} | ${escCell(s.plannedEndDate ?? '-')} |`)
                     .join('\n');
-            return ok(text, { sprints: rows });
+            return ok(text, { sprints: rows, totalCount: totalOf(rows) ?? rows.length });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('list_functions', {
+        title: 'List / search reusable functions (NOT test cases)',
+        description: 'List reusable FUNCTIONS in the connected project — the FN_* library of building blocks that ' +
+            'test cases call as nested steps. NOT test cases: if the user asks for test cases, TCs, ' +
+            'scenarios, or scripts, use `tc_list` instead. Trigger words for THIS tool: "functions", ' +
+            '"reusable functions", "function library", "FN_", "shared steps", "building blocks". Returns ' +
+            'id, key (FN_*), name, description, technology (WEB/API/ANDROID/IOS), execution type ' +
+            '(MANUAL/AUTOMATION), review status, step count. Use `get_function` to read one in full ' +
+            '(with its steps) and `delete_function` to soft-delete. SimplifyQA-only. Requires a live ' +
+            'connection (qa_connect). Read-only.',
+        inputSchema: {
+            search: z.string().optional().describe('Free-text search over the function name.'),
+            fnType: z.string().optional().describe('Filter by technology (WEB / API / ANDROID / IOS).'),
+            executionType: z.string().optional().describe('Filter by execution type (MANUAL / AUTOMATION).'),
+            moduleId: z.string().optional().describe('Only functions filed under this module (id or business key, e.g. MO_12).'),
+            createdBy: z.string().optional().describe('Numeric userId of the creator. Pass "me" to filter by the current caller (needs QA_MCP_USER_ID for API-key auth). Resolve names to ids via list_users first.'),
+            updatedBy: z.string().optional().describe('Numeric userId of the last updater. Pass "me" for the current caller. Resolve names via list_users first.'),
+            limit: z.number().int().positive().optional().describe('Max results (paging).'),
+            offset: z.number().int().nonnegative().optional().describe('Result offset (paging).'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ search, fnType, executionType, moduleId, createdBy, updatedBy, limit, offset }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.listFunctions)
+            return err('This product has no reusable-function library.');
+        try {
+            const rows = await adapter.listFunctions({
+                ...(search !== undefined ? { search } : {}),
+                ...(fnType !== undefined ? { fnType } : {}),
+                ...(executionType !== undefined ? { executionType } : {}),
+                ...(moduleId !== undefined ? { moduleId } : {}),
+                ...(createdBy !== undefined ? { createdBy } : {}),
+                ...(updatedBy !== undefined ? { updatedBy } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+                ...(offset !== undefined ? { offset } : {}),
+            });
+            if (!rows.length)
+                return ok('No functions found.', { functions: [], totalCount: totalOf(rows) ?? 0 });
+            const view = rows.map(({ id: _id, ...rest }) => rest);
+            const text = `${countHeader(rows, 'function')}:\n\n` +
+                '| key | name | technology | execution | status | steps |\n|---|---|---|---|---|---|\n' +
+                rows
+                    .map((f) => `| ${escCell(f.code)} | ${escCell(f.name)} | ${f.fnType ?? '-'} | ${f.executionType ?? '-'} | ${f.status ?? '-'} | ${f.stepCount ?? '-'} |`)
+                    .join('\n');
+            return ok(text, { functions: view, totalCount: totalOf(rows) ?? rows.length });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('get_function', {
+        title: 'Read / explain one reusable function (NOT a test case)',
+        description: 'Read a single reusable FUNCTION in full — metadata, description, and steps as a readable ' +
+            "table — from the connected product. `id` accepts the function's numeric id or its business key " +
+            '(e.g. FN_123). NOT for test cases: if the user asks to read / explain a TC or TC_* id, use ' +
+            '`tc_get` instead. Trigger words for THIS tool: "function", "FN_", "reusable function", ' +
+            '"explain this function". Use this to explain what a function does before calling it from a ' +
+            'test case or before deleting it. Requires a live connection (qa_connect).',
+        inputSchema: {
+            id: z.string().describe('The function id (or business key like FN_123) to read.'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.getFunction)
+            return err('This product has no reusable-function library.');
+        try {
+            const fn = await adapter.getFunction(id);
+            const steps = fn.steps.length;
+            const versionCount = fn.versions?.length ?? 0;
+            const header = `**${fn.name}**${fn.code ? ` · ${fn.code}` : fn.id ? ` · ${fn.id}` : ''}\n` +
+                `technology: ${fn.fnType ?? '-'} · execution: ${fn.executionType ?? '-'}` +
+                `${fn.status ? ` · status: ${fn.status}` : ''} · ${steps} step${steps === 1 ? '' : 's'}` +
+                `${versionCount ? ` · ${versionCount} version${versionCount === 1 ? '' : 's'}: ${fn.versions.map((v) => v.name).join(', ')}` : ''}` +
+                `${fn.description ? `\n\n${fn.description}` : ''}`;
+            const body = steps
+                ? '\n\n| # | type | description |\n|---|---|---|\n' +
+                    fn.steps
+                        .map((s) => `| ${s.n} | ${escCell(s.stepType)}${s.controlFlow ? `/${s.controlFlow.kind}` : ''} | ${escCell(s.description)} |`)
+                        .join('\n')
+                : '\n\n_(no steps)_';
+            const versionsBlock = versionCount
+                ? '\n\n**Versions** (newest first):\n\n| name | id | current | execution | review |\n|---|---|---|---|---|\n' +
+                    fn.versions
+                        .map((v) => `| ${escCell(v.name)} | \`${v.id}\` | ${v.isCurrent ? '✓' : ''} | ${v.executionType ?? '-'} | ${v.reviewApproveStatus ?? '-'} |`)
+                        .join('\n')
+                : '';
+            return ok(`${header}${body}${versionsBlock}`, { function: fn });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('delete_function', {
+        title: 'Delete a reusable function (NOT a test case; two-step confirm)',
+        description: 'Soft-delete a reusable FUNCTION in the connected product. NOT for test cases: if the user ' +
+            'asks to delete a TC or TC_* id, use `tc_delete` instead. Trigger words for THIS tool: ' +
+            '"function", "FN_", "reusable function". TWO-STEP CONFIRM: call once with just `id` to preview ' +
+            'the target (name + step count) and get a warning; then call again with `{ id, confirm: true }` ' +
+            "to actually delete. Refuses to delete without `confirm:true`. `id` accepts the function's " +
+            'numeric id or business key. The backend refuses to delete a function that is still referenced ' +
+            'by a test case, another function, or a workflow — this tool surfaces those references so the ' +
+            'user can remove them first.',
+        inputSchema: {
+            id: z.string().describe('The function id (or business key like FN_123) to delete.'),
+            confirm: z.boolean().optional().describe('Set to true on the SECOND call to actually delete.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ id, confirm }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.getFunction || !adapter.deleteFunction) {
+            return err('This product has no reusable-function library.');
+        }
+        if (!confirm) {
+            try {
+                const fn = await adapter.getFunction(id);
+                return ok(`⚠️ About to delete function **${fn.name}**` +
+                    `${fn.code ? ` (${fn.code})` : ''} — ${fn.steps.length} step${fn.steps.length === 1 ? '' : 's'}. ` +
+                    `To proceed, call again with { id: "${id}", confirm: true }. Deletion will be refused if ` +
+                    'the function is still referenced by a test case, another function, or a workflow.', { preview: true, function: fn });
+            }
+            catch (e) {
+                return err(describeError(e));
+            }
+        }
+        try {
+            await adapter.deleteFunction(id);
+            return ok(`Deleted function ${id}.`);
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('fn_clone', {
+        title: 'Clone a reusable function (copy in place with steps, versions, testdata)',
+        description: 'FOR REUSABLE FUNCTIONS ONLY. NOT for test cases: if the user names a `TC_*` key or asks to ' +
+            'clone a test case / scenario / script, use `tc_clone` instead. Trigger words for THIS tool: ' +
+            '"function", "reusable function", "FN_", "FN-".\n\n' +
+            'Save an existing reusable FUNCTION as a NEW copy in the SAME project + module — all steps, ' +
+            'versions, test data (all environments), parameters, object refs, and nested function calls ' +
+            "are carried over. Uses SimplifyQA's native TC/FN copy endpoint with `type:'FN'`. `fnId` " +
+            "accepts the product's id or business key (`FN_*`).\n\n" +
+            'Naming: pass `newName` for a custom title; otherwise the backend auto-names the copy as ' +
+            '`{sourceName}_copy1`, `_copy2`, etc.\n\n' +
+            'VERSIONS — TWO-STEP: call once WITHOUT `versions` to get a preview of the source\'s ' +
+            'versions and confirm with the user which to clone; then call again with `versions` set. ' +
+            '`versions:["*"]` clones every version; `versions:["v1.0","v2.0",...]` clones only those. ' +
+            'The tool REFUSES to clone until `versions` is passed — the preview step is not skippable.\n\n' +
+            'PERMISSION: requires the `copy_function_across_projects` privilege on the project (admins ' +
+            "have it by default; other roles need it granted). If you get a permission error, ask your " +
+            'project admin. Requires a live connection.',
+        inputSchema: {
+            fnId: z.string().describe('The source function id or business key (e.g. FN_123).'),
+            newName: z.string().optional().describe('Custom title for the copy. Omit to let the backend auto-name it (`{sourceName}_copy1`).'),
+            versions: z.array(z.string()).optional().describe('REQUIRED to actually clone. Version NAMES to clone (e.g. ["v1.0"]), or ["*"] to clone every version. Omit on the first call to get a preview + version list; ask the user which they want; then call again with the chosen value.'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ fnId, newName, versions }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.cloneFunction)
+            return err('This product does not support function clone.');
+        if (!adapter.getFunction)
+            return err('This product has no reusable-function library.');
+        // Preview step: no `versions` → fetch the source's version list via get_function (which
+        // hydrates `versions` from `/tm/function/version/:id/:pid`) and hand it back.
+        if (versions === undefined) {
+            try {
+                const fn = await adapter.getFunction(fnId);
+                const names = (fn.versions ?? []).map((v) => v.name);
+                if (names.length === 0) {
+                    return err(`Cannot clone ${fnId}: source has no versions to copy.`);
+                }
+                return ok(`**${fnId}** has ${names.length} version${names.length === 1 ? '' : 's'}: ` +
+                    `${names.map((n) => `\`${n}\``).join(', ')}.\n\n` +
+                    `**Ask the user which version(s) to clone**, then call \`fn_clone\` again:\n` +
+                    `- \`versions: ["*"]\` → clone ALL versions\n` +
+                    `- \`versions: ${JSON.stringify([names[0]])}\` → clone only that version\n` +
+                    `- \`versions: [name1, name2]\` → clone a specific subset`, { preview: true, versions: names, totalCount: names.length });
+            }
+            catch (e) {
+                return err(describeError(e));
+            }
+        }
+        // Explicit sentinel ["*"] = "all versions" — pass through as undefined to the adapter.
+        const isAll = versions.length === 1 && versions[0] === '*';
+        const effectiveVersions = isAll ? undefined : versions;
+        try {
+            const ref = await adapter.cloneFunction(fnId, newName, effectiveVersions);
+            const nameNote = newName ? ` renamed to **${newName}**` : ' (auto-named by the backend)';
+            const versionNote = isAll
+                ? ' All versions were carried over.'
+                : ` Only version(s) ${versions.map((v) => `**${v}**`).join(', ')} were carried over.`;
+            return ok(`Cloned ${fnId} →${nameNote}. New id: **${ref.id}**` +
+                (ref.productUrl ? ` · ${ref.productUrl}` : '') +
+                `.${versionNote}`, { savedRef: ref });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('fn_save_as_new_version', {
+        title: 'Snapshot a reusable function as a new version',
+        description: 'FOR REUSABLE FUNCTIONS ONLY. NOT for test cases: if the user names a `TC_*` key or asks to ' +
+            'snapshot / create a new version of a test case, use `tc_save_as_new_version` instead. ' +
+            'Trigger words for THIS tool: "function", "reusable function", "FN_", "FN-".\n\n' +
+            'Freeze the CURRENT server state of a reusable FUNCTION under a NEW version name — same FN id, a ' +
+            'new version row with cloned steps. Mirrors the SimplifyQA UI "Save as new version" dialog ' +
+            '(operation: SAVENEWVERSION, type: FN). `fnId` accepts the numeric id or business key (`FN_*`).\n\n' +
+            '`versionName` must be unique for this FN — the backend rejects duplicates.\n\n' +
+            '`tdCopy` (default TRUE) clones the source version\'s testdata iterations across every ' +
+            'environment. Pass `false` to copy only the iteration STRUCTURE — values are empty. That ' +
+            'matches the FE\'s "Cancel" button on the testdata-copy prompt.\n\n' +
+            '`sourceVersionId` picks which version to snapshot; omit to snapshot the FN\'s newest ' +
+            'version (the FN doc has no inline current-version marker). Requires a live connection.',
+        inputSchema: {
+            fnId: z.string().describe('The function id or business key (e.g. FN_123).'),
+            versionName: z.string().min(1).describe('Name for the new version (must be unique for this FN).'),
+            tdCopy: z.boolean().optional().describe('Clone testdata iterations from the source version. Default: true.'),
+            sourceVersionId: z.string().optional().describe('Version to snapshot; defaults to the FN\'s newest version.'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ fnId, versionName, tdCopy, sourceVersionId }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.saveAsNewFunctionVersion)
+            return err('This product does not support save-as-new-version for functions.');
+        const effectiveTdCopy = tdCopy ?? true;
+        try {
+            const ref = await adapter.saveAsNewFunctionVersion(fnId, {
+                versionName,
+                tdCopy: effectiveTdCopy,
+                ...(sourceVersionId !== undefined ? { sourceVersionId } : {}),
+            });
+            const tdNote = effectiveTdCopy
+                ? ' Testdata iterations were copied across environments.'
+                : ' Testdata structure was carried over but values are empty (tdCopy:false).';
+            return ok(`Snapshotted ${fnId} as new version **${versionName}**` +
+                (ref.productUrl ? ` · ${ref.productUrl}` : '') +
+                `.${tdNote}`, { savedRef: ref });
         }
         catch (e) {
             return err(describeError(e));
@@ -250,9 +820,10 @@ export function registerDiscoveryTools(server, deps) {
     });
     server.registerTool('list_modules', {
         title: 'List modules / folders (SimplifyQA test-case tree)',
-        description: 'List the MODULES (folder tree) test cases can be filed under in the connected project. ' +
-            'ASK the user which module to file a draft under before tc_draft_create — pass the chosen id ' +
-            'as `folderOrModule`. SimplifyQA-only: Walnut has no module tree. Requires a live connection.',
+        description: 'List the MODULES (folder tree) in the connected project — id, name, parent. Use for any ' +
+            '"list / show / what modules" request. Also the source of the `folderOrModule` id passed to ' +
+            'tc_draft_create (ask the user which one before drafting). SimplifyQA-only: Walnut has no ' +
+            'module tree. Requires a live connection.',
         inputSchema: {},
         annotations: { readOnlyHint: true },
     }, async () => {
@@ -264,11 +835,206 @@ export function registerDiscoveryTools(server, deps) {
         try {
             const rows = await adapter.listModules();
             if (!rows.length)
-                return ok('No modules found.', { modules: [] });
-            const text = `${rows.length} module${rows.length === 1 ? '' : 's'}:\n\n` +
+                return ok('No modules found.', { modules: [], totalCount: totalOf(rows) ?? 0 });
+            const text = `${countHeader(rows, 'module')}:\n\n` +
                 '| id | name | parent |\n|---|---|---|\n' +
                 rows.map((m) => `| ${escCell(m.id)} | ${escCell(m.name)} | ${escCell(m.parentId ?? '-')} |`).join('\n');
-            return ok(text, { modules: rows });
+            return ok(text, { modules: rows, totalCount: totalOf(rows) ?? rows.length });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('get_module', {
+        title: 'View module details',
+        description: 'Fetch full detail for one MODULE — id, name, code, description, parentId, childIds. Use ' +
+            'when list_modules\' summary row isn\'t enough (need description or child tree). SimplifyQA-only. ' +
+            'Requires a live connection.',
+        inputSchema: {
+            id: z.string().describe('Module id (numeric or business key resolvable via list_modules).'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.getModule)
+            return err('This product has no module tree.');
+        try {
+            const m = await adapter.getModule(id);
+            const lines = [
+                `**Module ${m.id}** — ${m.name}`,
+                m.code ? `Code: ${m.code}` : undefined,
+                m.parentId ? `Parent: ${m.parentId}` : 'Parent: (root)',
+                m.description ? `Description: ${m.description}` : undefined,
+                m.childIds?.length ? `Child module ids: ${m.childIds.join(', ')}` : undefined,
+            ].filter(Boolean);
+            return ok(lines.join('\n'), { module: m });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('create_module', {
+        title: 'Create a module (folder) in the test-case tree',
+        description: 'Create a new MODULE under the connected project. Set `isRoot:true` for a top-level folder; ' +
+            'otherwise pass `parentId` (resolve via list_modules). Duplicate name in the same project is ' +
+            'rejected server-side. SimplifyQA-only. Requires a live connection.',
+        inputSchema: {
+            name: z.string().min(1).describe('Module name. Must be unique within the project.'),
+            projectId: z.string().describe('Target project id (see list_projects).'),
+            isRoot: z.boolean().describe('True → top-level folder; false → child of `parentId`.'),
+            parentId: z.string().optional().describe('Parent module id (required when isRoot is false).'),
+            description: z.string().optional().describe('Free-text description.'),
+        },
+    }, async ({ name, projectId, isRoot, parentId, description }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.createModule)
+            return err('This product has no module tree.');
+        if (!isRoot && !parentId) {
+            return err('parentId is required when isRoot is false.');
+        }
+        try {
+            const saved = await adapter.createModule({
+                name,
+                projectId,
+                isRoot,
+                ...(parentId ? { parentId } : {}),
+                ...(description ? { description } : {}),
+            });
+            return ok(`Created module ${saved.id} (${name}).`, { saved });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('delete_module', {
+        title: 'Delete modules (with dependency dry-run)',
+        description: 'Delete one or more MODULES by id. Two phases: call with `confirm:false` (default) for a ' +
+            'DRY RUN that returns each id\'s dependency footprint (test cases, functions, parameters, ' +
+            'objects, defects, user stories that still reference the module). Call again with ' +
+            '`confirm:true` to actually delete; the server drops only ids with EMPTY dependencies and ' +
+            'silently skips the rest — surface those to the caller so they can move/remove the refs first. ' +
+            'SimplifyQA-only. Requires a live connection.',
+        inputSchema: {
+            ids: z.array(z.string()).min(1).describe('Module ids to delete.'),
+            projectId: z.string().describe('Project id the modules belong to.'),
+            confirm: z.boolean().optional().describe('False (default) → dry-run; true → apply delete.'),
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ ids, projectId, confirm }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.deleteModule)
+            return err('This product has no module tree.');
+        try {
+            const result = await adapter.deleteModule({ ids, projectId, ...(confirm !== undefined ? { confirm } : {}) });
+            const blockers = result.dependencies.filter((d) => d.tcArr.length || d.fnArr.length || d.parameterArr.length || d.objArr.length || d.defectArr.length || d.usArr.length);
+            if (result.dryRun) {
+                if (!blockers.length) {
+                    return ok(`Dry-run: ${ids.length} module(s) have NO dependencies — safe to delete. ` +
+                        'Call again with confirm:true to apply.', { result });
+                }
+                const text = `Dry-run: ${blockers.length} of ${ids.length} module(s) still have references. ` +
+                    'Deleting with confirm:true will SKIP these ids:\n\n' +
+                    '| id | test cases | functions | params | objects | defects | user stories |\n' +
+                    '|---|---|---|---|---|---|---|\n' +
+                    blockers
+                        .map((d) => `| ${d.id} | ${d.tcArr.length} | ${d.fnArr.length} | ${d.parameterArr.length} | ${d.objArr.length} | ${d.defectArr.length} | ${d.usArr.length} |`)
+                        .join('\n');
+                return ok(text, { result });
+            }
+            if (blockers.length) {
+                return ok(`Deleted ${ids.length - blockers.length} module(s). ${blockers.length} SKIPPED (still referenced). ` +
+                    'Move or remove the referring rows, then retry those ids.', { result });
+            }
+            return ok(`Deleted ${ids.length} module(s).`, { result });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('delete_version', {
+        title: 'Delete a version of a test case or function (two-step confirm)',
+        description: 'Soft-delete ONE version of a test case (`kind:"tc"`) or a reusable function (`kind:"fn"`) ' +
+            'in the connected product. `versionId` comes from the parent\'s `versions[]` (populated by ' +
+            '`tc_get` for TCs and `get_function` for FNs); pass the version\'s `name` too (backend ' +
+            'validator requires it). TWO-STEP CONFIRM: call once with `confirm:false` (default) to get ' +
+            'a DRY RUN — the response lists every entity still referencing this version (defects, suites, ' +
+            'exec plans, scenarios, schedulers, pipelines, workflows for a TC; TCs, other FNs, workflows ' +
+            'for a FN). Only when EVERY dependency map is empty is the delete allowed; the server itself ' +
+            "REFUSES a `confirm:true` call when refs still exist, so `confirm:true` doesn't guarantee " +
+            'deletion — the tool inspects the response and reports honestly. Refuses to delete the LAST ' +
+            'remaining version (the parent would be orphaned; use `tc_delete` / `delete_function` instead ' +
+            'to remove the whole entity). SimplifyQA-only. Requires a live connection.',
+        inputSchema: {
+            kind: z.enum(['tc', 'fn']).describe("'tc' for a test-case version; 'fn' for a function version."),
+            parentId: z.string().describe('Parent TC or FN id (numeric or business key like TC_123 / FN_45).'),
+            versionId: z.string().describe("The version's uuid (from tc_get.versions[].id or get_function.versions[].id)."),
+            versionName: z.string().describe("The version's human name (e.g. 'v1.0'). Required by the backend validator."),
+            confirm: z.boolean().optional().describe('False (default) → dry-run; true → apply delete (server still refuses if any dependency exists).'),
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ kind, parentId, versionId, versionName, confirm }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.deleteVersion)
+            return err('This product has no per-version delete support.');
+        // Client-side "last version" guard — mirrors the SQA UI (testcase.component.ts:2126,
+        // function.component.ts:1600). Backend cheerfully deletes the sole remaining version and
+        // orphans the parent, so we block it here.
+        try {
+            const parent = kind === 'tc'
+                ? await adapter.getTestCase(parentId)
+                : adapter.getFunction ? await adapter.getFunction(parentId) : null;
+            const versions = parent?.versions ?? [];
+            if (versions.length === 0) {
+                return err(`${kind === 'tc' ? 'Test case' : 'Function'} ${parentId} has no versions to delete.`);
+            }
+            if (versions.length === 1) {
+                return err(`${kind === 'tc' ? 'Test case' : 'Function'} ${parentId} has only one version — ` +
+                    'deleting it would orphan the parent (all steps and testdata go with it). ' +
+                    `Delete the whole ${kind === 'tc' ? 'test case (tc_delete)' : 'function (delete_function)'} ` +
+                    'instead, or add another version first.');
+            }
+            if (!versions.some((v) => v.id === versionId)) {
+                const listing = versions.map((v) => `  - ${v.name} \`${v.id}\``).join('\n');
+                return err(`Version \`${versionId}\` not found on ${parentId}. Known versions:\n${listing}`);
+            }
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+        try {
+            const result = await adapter.deleteVersion({
+                kind,
+                parentId,
+                versionId,
+                versionName,
+                ...(confirm !== undefined ? { confirm } : {}),
+            });
+            if (result.dryRun) {
+                if (!result.hasBlockers) {
+                    return ok(`Dry-run: version \`${versionId}\` (${versionName}) has NO dependencies — safe to delete. ` +
+                        'Call again with confirm:true to apply.', { result });
+                }
+                const rows = result.dependencies.map((d) => renderVersionDepRow(d));
+                return ok(`Dry-run: version \`${versionId}\` (${versionName}) still has references. ` +
+                    'Deleting is blocked until the referring rows are moved or removed:\n\n' +
+                    rows.join('\n'), { result });
+            }
+            if (result.deleted) {
+                return ok(`Deleted version \`${versionId}\` (${versionName}). Cascade: steps, testdata and ` +
+                    'testdata iterations for this version were soft-deleted along with it.', { result });
+            }
+            // confirm:true but server returned deps → refused.
+            const rows = result.dependencies.map((d) => renderVersionDepRow(d));
+            return err(`Server REFUSED to delete version \`${versionId}\` — it is still referenced. ` +
+                'Remove or move the refs, then retry:\n\n' + rows.join('\n'));
         }
         catch (e) {
             return err(describeError(e));
@@ -276,9 +1042,10 @@ export function registerDiscoveryTools(server, deps) {
     });
     server.registerTool('suite_list', {
         title: 'List test suites',
-        description: 'List the test suites in the connected product — id, name, and member (test-case) count. Use ' +
-            'suite_get to read one with its ordered members, or suite_run to execute one. Requires a live ' +
-            'connection (qa_connect). Read-only and product-neutral.',
+        description: 'List the test suites in the connected product — id, name, type (Manual/Automation, where the ' +
+            'provider has a suite-level type — SimplifyQA does, Walnut doesn\'t), and member (test-case) ' +
+            'count. Use suite_get to read one with its ordered members, or suite_run to execute one. ' +
+            'Requires a live connection (qa_connect). Read-only and product-neutral.',
         inputSchema: {},
         annotations: { readOnlyHint: true },
     }, async () => {
@@ -288,11 +1055,49 @@ export function registerDiscoveryTools(server, deps) {
         try {
             const rows = await adapter.listSuites();
             if (!rows.length)
-                return ok('No test suites found.', { suites: [] });
-            const text = `${rows.length} suite${rows.length === 1 ? '' : 's'}:\n\n` +
-                '| id | name | test cases |\n|---|---|---|\n' +
-                rows.map((s) => `| ${escCell(s.id)} | ${escCell(s.name)} | ${s.memberCount ?? '-'} |`).join('\n');
-            return ok(text, { suites: rows });
+                return ok('No test suites found.', { suites: [], totalCount: totalOf(rows) ?? 0 });
+            const text = `${countHeader(rows, 'suite')}:\n\n` +
+                '| id | name | type | test cases |\n|---|---|---|---|\n' +
+                rows.map((s) => `| ${escCell(s.id)} | ${escCell(s.name)} | ${escCell(s.suiteType ?? '-')} | ${s.memberCount ?? '-'} |`).join('\n');
+            return ok(text, { suites: rows, totalCount: totalOf(rows) ?? rows.length });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('list_users', {
+        title: 'List users (resolve a name to a userId)',
+        description: 'List users the caller can see in the connected product — id, name, email, username, status. ' +
+            'Use this to resolve a person\'s NAME to a userId before filtering tc_list / story_list by ' +
+            '`createdBy` / `updatedBy`. Non-admin callers are auto-scoped server-side to users in their ' +
+            'assigned projects. Optional `search` matches on name (case-insensitive substring). Optional ' +
+            '`projectId` narrows further to that project\'s members. Requires a live connection. Read-only.',
+        inputSchema: {
+            search: z.string().optional().describe('Case-insensitive substring over user name.'),
+            projectId: z.string().optional().describe('Only users assigned to this project (from list_projects).'),
+            limit: z.number().int().positive().optional().describe('Max results (default 100).'),
+            offset: z.number().int().nonnegative().optional().describe('Result offset (paging).'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ search, projectId, limit, offset }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.listUsers)
+            return err('This product does not expose a user directory.');
+        try {
+            const rows = await adapter.listUsers({
+                ...(search ? { search } : {}),
+                ...(projectId ? { projectId } : {}),
+                ...(limit != null ? { limit } : {}),
+                ...(offset != null ? { offset } : {}),
+            });
+            if (!rows.length)
+                return ok('No users found.', { users: [], totalCount: totalOf(rows) ?? 0 });
+            const text = `${countHeader(rows, 'user')}:\n\n` +
+                '| id | name | email | username | status |\n|---|---|---|---|---|\n' +
+                rows.map((u) => `| ${escCell(u.id)} | ${escCell(u.name ?? '-')} | ${escCell(u.email ?? '-')} | ${escCell(u.username ?? '-')} | ${escCell(u.status ?? '-')} |`).join('\n');
+            return ok(text, { users: rows, totalCount: totalOf(rows) ?? rows.length });
         }
         catch (e) {
             return err(describeError(e));
@@ -352,7 +1157,18 @@ export function registerDiscoveryTools(server, deps) {
             const ops = tcIds.map((tcId) => ({ op: 'add', tcId }));
             const suite = await adapter.updateSuiteMembers(suiteId, ops);
             const n = suite.members.length;
-            return ok(`Added ${tcIds.length} test case${tcIds.length === 1 ? '' : 's'} to **${suite.name}** — now ${n} member${n === 1 ? '' : 's'}.` +
+            // Resolve titles for the confirmation — membership rows only carry `tcId`.
+            const added = await Promise.all(tcIds.map(async (tcId) => {
+                try {
+                    const tc = await adapter.getTestCase(tcId);
+                    return tc.title ? `${tc.title} (${tcId})` : tcId;
+                }
+                catch {
+                    return tcId;
+                }
+            }));
+            return ok(`Added ${added.length} test case${added.length === 1 ? '' : 's'} to **${suite.name}**: ` +
+                `${added.join(', ')} — now ${n} member${n === 1 ? '' : 's'}.` +
                 membersTable(suite), { suite });
         }
         catch (e) {