callman-mcp 0.1.0 → 0.2.0

package/dist-cjs/tools/scenarios.js

@@ -5,196 +5,313 @@ const zod_1 = require("zod");
 const errors_js_1 = require("../client/errors.js");
 const resolve_js_1 = require("../domain/resolve.js");
 const build_js_1 = require("../domain/scenario/build.js");
+const nodeConfig_js_1 = require("../domain/scenario/nodeConfig.js");
 const summarize_js_1 = require("../domain/scenario/summarize.js");
-const ids_js_1 = require("../lib/ids.js");
 const pagination_js_1 = require("../lib/pagination.js");
+const strict_js_1 = require("../lib/strict.js");
 const lookups_js_1 = require("./lookups.js");
 const shared_js_1 = require("./shared.js");
 const TERMINAL_STATUSES = new Set(["success", "failed", "completed_with_failures", "stopped"]);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const groupArg = zod_1.z
+    .string()
+    .max(200)
+    .optional()
+    .describe('On-prem: the scenario group that owns it (name or id from list_scenarios `groups`, or "personal"). Needed when you belong to several groups; ignored on cloud');
+// The backend's node schemas strip unknown config keys without an error —
+// compare what we sent with what it stored and say which keys vanished.
+const droppedFieldWarnings = (graph, stored) => {
+    const byId = new Map(stored.nodes.map((node) => [node.id, node]));
+    const out = [];
+    for (const [id, sent] of graph.sent) {
+        const node = byId.get(id);
+        if (!node)
+            continue;
+        const dropped = (0, nodeConfig_js_1.droppedPaths)(sent, node.data?.config ?? {});
+        if (dropped.length > 0)
+            out.push(`${id}: the server ignored config.${dropped.join(", config.")} — not a field of a ${node.type} node (callman://docs/scenario-nodes).`);
+    }
+    return out;
+};
+const resolveGroup = async (ctx, ws, ref) => {
+    if (!ref)
+        return undefined;
+    if (ref.trim().toLowerCase() === "personal")
+        return { id: "personal" };
+    const { items } = await ctx.api.listMyScenarioGroups(ws);
+    if (items.length === 0)
+        return { id: null, note: "Scenario groups exist only on-prem — `group` was ignored." };
+    return { id: (0, resolve_js_1.resolveRef)("scenario group", ref, items).item.id };
+};
+const latestScenario = async (ctx, ws, id) => ctx.api.getScenario(ws, id);
 const registerScenarioTools = (server, ctx) => {
     server.registerTool("list_scenarios", {
         title: "List scenarios",
-        description: "List API test scenarios (multi-step flows) with their folder, review status and version. `query` filters by name. Scenarios are scoped by edition (on-prem: your groups), not strictly by workspace.",
+        description: "List API test scenarios (multi-step flows) you can access — regardless of workspace (on-prem: your groups) — with their folder, workspace, review status and version, plus the scenario folders and (on-prem) the groups you can create scenarios in. `query` filters by name.",
         inputSchema: { workspace: shared_js_1.workspaceArg, query: zod_1.z.string().max(200).optional(), folder: zod_1.z.string().max(200).optional(), ...shared_js_1.cursorArgs },
         annotations: shared_js_1.READ,
     }, (0, shared_js_1.guarded)(async ({ workspace, query, folder, cursor, limit }) => {
         const ws = await ctx.resolveWorkspaceOrNull(workspace);
-        const { scenarios, folders } = await (0, lookups_js_1.loadScenarioCatalog)(ctx, ws?.id ?? null);
+        const [{ scenarios, folders }, groups, workspaces] = await Promise.all([
+            (0, lookups_js_1.loadScenarioCatalog)(ctx, ws?.id ?? null),
+            ctx.api.listMyScenarioGroups(ws?.id ?? null).catch(() => ({ items: [] })),
+            ctx.listWorkspaces(),
+        ]);
+        const workspaceName = new Map(workspaces.map((entry) => [entry.id, entry.name]));
         const folderName = new Map(folders.map((entry) => [entry.id, entry.name]));
         const scope = folder ? await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws?.id ?? null, folder) : null;
         const needle = query?.trim().toLowerCase();
         const filtered = scenarios
             .filter((scenario) => !scope || scenario.folderId === scope.item.id)
             .filter((scenario) => !needle || scenario.name.toLowerCase().includes(needle));
-        const page = (0, pagination_js_1.sliceWithCursor)(filtered, cursor, limit);
+        const page = (0, pagination_js_1.sliceWithCursor)(filtered, cursor, limit, `${scope?.item.id ?? ""}|${needle ?? ""}`);
         return (0, shared_js_1.ok)({
             ...(ws ? { workspace: { id: ws.id, name: ws.name } } : {}),
             folders: folders.map((entry) => ({ id: entry.id, name: entry.name })),
-            scenarios: page.items.map((scenario) => (0, summarize_js_1.scenarioSummaryView)(scenario, scenario.folderId ? (folderName.get(scenario.folderId) ?? null) : null)),
+            ...(groups.items.length > 0 ? { groups: groups.items.map((group) => ({ id: group.id, name: group.name, role: group.role })) } : {}),
+            scenarios: page.items.map((scenario) => ({
+                ...(0, summarize_js_1.scenarioSummaryView)(scenario, scenario.folderId ? (folderName.get(scenario.folderId) ?? null) : null),
+                ...(workspaces.length > 1 && scenario.workspaceId ? { workspace: { id: scenario.workspaceId, name: workspaceName.get(scenario.workspaceId) ?? null } } : {}),
+            })),
             total: page.total,
             nextCursor: page.nextCursor,
         });
     }));
     server.registerTool("get_scenario", {
         title: "Get a scenario",
-        description: "Read a scenario: `summary` (metadata), `graph` (nodes with type/label and the edges — enough to understand the flow) or `full` (node configs, secrets masked, clipped at 2 KB per node). Use `graph` before editing with update_scenario.",
+        description: "Read a scenario: `summary` (metadata), `graph` (default — nodes with type/label and the edges), `full` (every node config with secrets masked in place, in the shape the write tools accept; a config over 2 KB comes back as a clipped preview) or one node in full with `node: \"<id or label>\"`. Edit with patch_scenario (one node at a time) or update_scenario.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             scenario: (0, shared_js_1.refArg)("Scenario"),
             view: zod_1.z.enum(["summary", "graph", "full"]).default("graph"),
-            reveal: zod_1.z.boolean().optional().describe("full view: return environment values and auth secrets unmasked (needs environments:reveal)"),
+            node: zod_1.z.string().max(200).optional().describe("Return this one node (id or label) with its complete config, unclipped"),
+            reveal: zod_1.z.boolean().optional().describe("Return environment values and node secrets unmasked (needs environments:reveal)"),
         },
         annotations: shared_js_1.READ,
-    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, view, reveal }) => {
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, view, node, reveal }) => {
         const ws = await ctx.resolveWorkspaceOrNull(workspace);
         const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
         const fresh = resolved.matched === "id" && !reveal ? resolved.item : await ctx.api.getScenario(ws?.id ?? null, resolved.item.id, reveal ?? false);
+        if (node) {
+            const found = (0, summarize_js_1.scenarioNodeView)(fresh, node, { reveal });
+            if (!found) {
+                throw new errors_js_1.ToolInputError("SCENARIO_NODE_NOT_FOUND", `No node "${node}" in "${fresh.name}".`, { nodes: fresh.nodes.map((entry) => ({ id: entry.id, type: entry.type, label: entry.data?.label ?? null })) });
+            }
+            return (0, shared_js_1.ok)({ scenario: { id: fresh.id, name: fresh.name, version: fresh.version }, node: found });
+        }
         const body = view === "summary" ? (0, summarize_js_1.scenarioSummaryView)(fresh) : view === "graph" ? (0, summarize_js_1.scenarioGraphView)(fresh) : (0, summarize_js_1.scenarioFullView)(fresh, { reveal });
         return (0, shared_js_1.ok)({ scenario: body, ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(scenario, resolved)] } : {}) });
     }));
     server.registerTool("get_scenario_report", {
         title: "Get a scenario run report",
-        description: "The result of a scenario run: status, summary counts and a per-node timeline (status, duration, HTTP status, failed tests) with the first failed node expanded. Defaults to the latest run.",
+        description: "The result of a scenario run: status, summary counts, an error outside any node (unexpectedError), a per-node timeline and every failing node expanded (failed tests, assertion checks with expected vs actual, failed contracts, script error with line, the input as resolved at run time, response, logs). `node` returns one node's result in that detail. Defaults to the latest run; `list: true` lists recent runs instead.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             scenario: (0, shared_js_1.refArg)("Scenario"),
             report: zod_1.z.string().max(64).optional().describe("Report id; omit for the latest run"),
+            node: zod_1.z.string().max(200).optional().describe("Return this node's result in detail (id or label)"),
+            list: zod_1.z.boolean().optional().describe("List the last 20 runs (id, status, start, failed node) instead of one report"),
         },
         annotations: shared_js_1.READ,
-    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, report }) => {
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, report, node, list }) => {
         const ws = await ctx.resolveWorkspaceOrNull(workspace);
         const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
+        if (list) {
+            const runs = await ctx.api.listScenarioReports(ws?.id ?? null, resolved.item.id, 20);
+            return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, runs: runs.items });
+        }
         let reportId = report;
         if (!reportId) {
-            const list = await ctx.api.listScenarioReports(ws?.id ?? null, resolved.item.id, 5);
-            const latest = list.items[0];
+            const runs = await ctx.api.listScenarioReports(ws?.id ?? null, resolved.item.id, 5);
+            const latest = runs.items[0];
             if (!latest)
                 return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, report: null, note: "This scenario has not been run on the server yet. Use run_scenario." });
             reportId = latest.reportId;
         }
         const detail = await ctx.api.getScenarioReport(ws?.id ?? null, resolved.item.id, reportId);
+        if (node) {
+            const result = (detail.nodeResults ?? []).find((entry) => entry.nodeId === node || entry.label === node);
+            if (!result)
+                throw new errors_js_1.ToolInputError("SCENARIO_NODE_NOT_FOUND", `No result for node "${node}" in this run.`, { nodes: (detail.nodeResults ?? []).map((entry) => ({ nodeId: entry.nodeId, label: entry.label, status: entry.status })) });
+            return (0, shared_js_1.ok)({ reportId: detail.id, node: (0, summarize_js_1.nodeDetailView)(result) });
+        }
         return (0, shared_js_1.ok)({ report: (0, summarize_js_1.compactReportView)(detail), ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(scenario, resolved)] } : {}) });
     }));
     server.registerTool("create_scenario", {
         title: "Create a scenario",
-        description: "Create a multi-step API test scenario from compact nodes and edges. Node configs are merged over the type's defaults, so partial configs are fine (a request node needs at least method + url). Read callman://docs/scenario-nodes for every node type and config field. Positions are laid out automatically. dryRun: true returns the resolved graph without saving. On-prem: new scenarios start as drafts and need approval before scheduled/CI runs.",
+        description: "Create a multi-step API test scenario from compact nodes and edges. READ callman://docs/scenario-nodes first: it lists every node type, its config fields, defaults and which are required. Configs are merged over the type's defaults (send what you set; arrays you send must be complete). Request nodes also accept the request tools' shapes (auth { type: \"bearer\", token }, a JSON body) and are converted. Labels are generated when omitted and must be unique. db/redis/kafka/notification/ai nodes need a connectionId (list_connections). Config keys the server does not know come back as warnings. dryRun: true returns the complete resolved nodes without saving. On-prem: new scenarios start as drafts — submit_scenario sends them for approval; personal-token runs use the approved version.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             folder: zod_1.z.string().max(200).optional().describe("Scenario folder id or name"),
+            group: groupArg,
             ...build_js_1.scenarioInputSchema.shape,
             dryRun: shared_js_1.dryRunArg,
         },
         annotations: shared_js_1.WRITE,
-    }, (0, shared_js_1.guarded)(async ({ workspace, folder, dryRun, ...input }) => {
+    }, (0, shared_js_1.guarded)(async ({ workspace, folder, group, dryRun, ...input }) => {
         const ws = await ctx.resolveWorkspace(workspace);
         const targetFolder = folder ? await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws.id, folder) : null;
-        const body = (0, build_js_1.buildScenarioCreateBody)(input, targetFolder?.item.id ?? null);
+        const targetGroup = await resolveGroup(ctx, ws.id, group);
+        const { body, graph } = (0, build_js_1.buildScenarioCreateBody)(input, targetFolder?.item.id ?? null, targetGroup?.id === null ? undefined : targetGroup?.id);
         if (dryRun) {
-            const nodes = body.nodes;
-            return (0, shared_js_1.ok)({ dryRun: true, scenario: { name: body.name, nodeCount: nodes.length, edgeCount: body.edges.length, nodes: nodes.map((node) => ({ id: node.id, type: node.type, label: node.data.label ?? null })), edges: body.edges } });
+            return (0, shared_js_1.ok)({ dryRun: true, scenario: { name: body.name, nodes: graph.nodes.map((node) => ({ id: node.id, type: node.type, label: node.data.label, config: node.data.config })), edges: graph.edges }, warnings: graph.warnings });
         }
         const created = await ctx.api.createScenario(ws.id, body);
         ctx.invalidate("scenarios:");
+        const warnings = [...graph.warnings, ...droppedFieldWarnings(graph, created), ...(created.graph?.warnings ?? []), ...(targetGroup?.note ? [targetGroup.note] : [])];
         return (0, shared_js_1.ok)({
             scenario: (0, summarize_js_1.scenarioGraphView)(created),
-            ...(created.graph?.warnings?.length ? { warnings: created.graph.warnings } : {}),
-            note: created.reviewStatus === "draft" ? "Created as a draft. Run it with run_scenario; on-prem, submit it for approval in the desktop app before scheduling." : "Created.",
+            ...(warnings.length > 0 ? { warnings } : {}),
+            note: created.reviewStatus === "draft"
+                ? "Created as a draft. On-prem, run_scenario with a personal token runs the APPROVED version — submit_scenario and have it approved first; on cloud it runs as is."
+                : "Created.",
             ...(targetFolder ? { resolved: [(0, resolve_js_1.resolvedSummary)(folder, targetFolder)] } : {}),
         });
     }));
+    server.registerTool("patch_scenario", {
+        title: "Edit a scenario incrementally",
+        description: "Apply operations to a scenario without resending it: updateNode (config MERGED into the stored node — only the keys you send change; label; position), addNode, removeNode (drops its edges), addEdge, removeEdge. A masked secret sent back unchanged keeps the stored value. Version-checked like update_scenario.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            scenario: (0, shared_js_1.refArg)("Scenario"),
+            expectedVersion: zod_1.z.number().int().nonnegative().optional(),
+            ops: zod_1.z
+                .array(zod_1.z.discriminatedUnion("op", [
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("updateNode"), id: zod_1.z.string().min(1).max(64), label: zod_1.z.string().max(200).optional(), config: zod_1.z.record(zod_1.z.unknown()).optional(), position: zod_1.z.object({ x: zod_1.z.number(), y: zod_1.z.number() }).strict().optional() }, "field", "updateNode ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("addNode"), node: build_js_1.scenarioNodeInputSchema }, "field", "addNode ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("removeNode"), id: zod_1.z.string().min(1).max(64) }, "field", "removeNode ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("addEdge"), edge: build_js_1.scenarioEdgeInputSchema }, "field", "addEdge ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("removeEdge"), id: zod_1.z.string().min(1).max(64).optional(), source: zod_1.z.string().max(64).optional(), target: zod_1.z.string().max(64).optional() }, "field", "removeEdge ops"),
+            ]))
+                .min(1)
+                .max(200),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, expectedVersion, ops }) => {
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
+        const current = await latestScenario(ctx, ws?.id ?? null, resolved.item.id);
+        const nodes = new Map(current.nodes.map((node) => [node.id, { id: node.id, type: node.type }]));
+        let edges = current.edges.map((edge) => ({ id: edge.id, source: edge.source, target: edge.target, ...(edge.type ? { type: edge.type } : {}) }));
+        for (const op of ops) {
+            switch (op.op) {
+                case "updateNode": {
+                    const node = nodes.get(op.id);
+                    if (!node)
+                        throw new errors_js_1.ToolInputError("SCENARIO_NODE_NOT_FOUND", `No node "${op.id}".`, { nodes: [...nodes.keys()] });
+                    nodes.set(op.id, { ...node, ...(op.label !== undefined ? { label: op.label } : {}), ...(op.position ? { position: op.position } : {}), ...(op.config ? { config: { ...(node.config ?? {}), ...op.config } } : {}) });
+                    break;
+                }
+                case "addNode": {
+                    const id = op.node.id;
+                    if (id && nodes.has(id))
+                        throw new errors_js_1.ToolInputError("SCENARIO_DUPLICATE_NODE_ID", `A node "${id}" already exists — use updateNode.`);
+                    nodes.set(id ?? `__new${nodes.size}`, op.node);
+                    break;
+                }
+                case "removeNode":
+                    if (!nodes.delete(op.id))
+                        throw new errors_js_1.ToolInputError("SCENARIO_NODE_NOT_FOUND", `No node "${op.id}".`);
+                    edges = edges.filter((edge) => edge.source !== op.id && edge.target !== op.id);
+                    break;
+                case "addEdge":
+                    edges.push(op.edge);
+                    break;
+                case "removeEdge": {
+                    const before = edges.length;
+                    edges = edges.filter((edge) => !(op.id ? edge.id === op.id : edge.source === op.source && edge.target === op.target));
+                    if (edges.length === before)
+                        throw new errors_js_1.ToolInputError("SCENARIO_EDGE_NOT_FOUND", "No such edge — give its id, or source + target.");
+                    break;
+                }
+            }
+        }
+        const graph = (0, build_js_1.buildScenarioGraph)([...nodes.values()], edges, { existing: current.nodes });
+        return saveGraph(ctx, ws?.id ?? null, current, graph, { expectedVersion, annotation: resolved.annotation ? (0, resolve_js_1.resolvedSummary)(scenario, resolved) : undefined });
+    }));
     server.registerTool("update_scenario", {
         title: "Update a scenario",
-        description: "Update a scenario's name/description/priority/folder and/or replace its graph (send nodes AND edges together; node configs merge over defaults like create_scenario). Version-checked: pass the `version` you read (expectedVersion) or it is fetched first; a 409 conflict comes back structured — re-read and retry. On-prem: editing an approved scenario returns it to draft.",
+        description: "Update a scenario's name / description / priority / folder / environments / dataset / dbSettings and/or replace its graph (nodes AND edges together). A node whose id already exists MERGES into the stored node (only the config keys you send change, its position is kept); new ids merge over the type's defaults; nodes you leave out are removed. `environments` replaces the whole list (stored ids are kept by name; a masked value sent back unchanged keeps the stored one). For small edits prefer patch_scenario. Version-checked: pass the `version` you read (expectedVersion) or it is fetched first; a conflict comes back structured. On-prem: editing an approved scenario returns it to draft.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             scenario: (0, shared_js_1.refArg)("Scenario"),
             expectedVersion: zod_1.z.number().int().nonnegative().optional(),
             force: zod_1.z.boolean().optional().describe("Overwrite even if someone changed it since expectedVersion"),
-            name: zod_1.z.string().min(1).max(200).optional(),
+            name: zod_1.z.string().trim().min(1).max(200).optional(),
             description: zod_1.z.string().max(5000).optional(),
             priority: zod_1.z.enum(["critical", "high", "medium", "low"]).optional(),
             folder: zod_1.z.string().max(200).nullable().optional().describe("Scenario folder id or name; null = no folder"),
             nodes: zod_1.z.array(build_js_1.scenarioNodeInputSchema).min(1).max(1000).optional(),
             edges: zod_1.z.array(build_js_1.scenarioEdgeInputSchema).max(2000).optional(),
-            environments: zod_1.z.array(build_js_1.scenarioEnvironmentInputSchema).max(20).optional(),
+            environments: zod_1.z.array(build_js_1.scenarioEnvironmentInputSchema).max(100).optional(),
+            dataset: build_js_1.scenarioDatasetSchema.optional(),
+            dbSettings: build_js_1.scenarioDbSettingsSchema.optional(),
         },
         annotations: shared_js_1.IDEMPOTENT_WRITE,
-    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, expectedVersion, force, name, description, priority, folder, nodes, edges, environments }) => {
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, expectedVersion, force, name, description, priority, folder, nodes, edges, environments, dataset, dbSettings }) => {
         if ((nodes === undefined) !== (edges === undefined)) {
-            throw new errors_js_1.ToolInputError("GRAPH_INCOMPLETE", "Send nodes and edges together when replacing the graph.");
+            throw new errors_js_1.ToolInputError("GRAPH_INCOMPLETE", "Send nodes and edges together when replacing the graph (or use patch_scenario for single edits).");
         }
         const ws = await ctx.resolveWorkspaceOrNull(workspace);
         const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
-        const current = resolved.item;
+        const current = await latestScenario(ctx, ws?.id ?? null, resolved.item.id);
         const targetFolder = folder ? await (0, lookups_js_1.resolveScenarioFolder)(ctx, ws?.id ?? null, folder) : null;
-        const body = {
-            ...(name !== undefined ? { name: name.trim() } : {}),
+        const graph = nodes && edges ? (0, build_js_1.buildScenarioGraph)(nodes, edges, { existing: current.nodes }) : null;
+        const extra = {
+            ...(name !== undefined ? { name } : {}),
             ...(description !== undefined ? { description } : {}),
             ...(priority !== undefined ? { priority } : {}),
             ...(folder !== undefined ? { folderId: targetFolder?.item.id ?? null } : {}),
-            expectedVersion: expectedVersion ?? current.version,
-            ...(force ? { force: true } : {}),
+            ...(environments ? { environments: (0, build_js_1.buildEnvironments)(environments, current.environments) } : {}),
+            ...(dataset !== undefined ? { dataset } : {}),
+            ...(dbSettings !== undefined ? { dbSettings } : {}),
         };
-        if (nodes && edges) {
-            const graph = (0, build_js_1.buildScenarioGraph)(nodes, edges);
-            body.nodes = graph.nodes;
-            body.edges = graph.edges;
-        }
-        if (environments) {
-            const nextEnvId = (0, ids_js_1.sequentialIds)("env", current.environments.map((environment) => environment.id));
-            body.environments = environments.map((environment) => {
-                const nextVarId = (0, ids_js_1.sequentialIds)("v");
-                return {
-                    id: environment.id ?? nextEnvId(),
-                    name: environment.name,
-                    variables: environment.variables.filter((variable) => variable.key.trim()).map((variable) => ({ id: nextVarId(), key: variable.key.trim(), value: variable.value ?? "", enabled: variable.enabled ?? true })),
-                };
-            });
-        }
-        if (Object.keys(body).filter((key) => key !== "expectedVersion" && key !== "force").length === 0) {
+        if (!graph && Object.keys(extra).length === 0)
             throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass at least one field to change.");
-        }
-        try {
-            const updated = await ctx.api.patchScenario(ws?.id ?? null, current.id, body);
-            ctx.invalidate("scenarios:");
-            return (0, shared_js_1.ok)({
-                scenario: (0, summarize_js_1.scenarioGraphView)(updated),
-                previousVersion: current.version,
-                ...(current.reviewStatus === "approved" && updated.reviewStatus !== "approved" ? { note: "The scenario was approved and is now a draft again; schedules keep using the last approved version until it is re-approved." } : {}),
-                ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(scenario, resolved)] } : {}),
+        return saveGraph(ctx, ws?.id ?? null, current, graph, { expectedVersion, force, extra, annotation: resolved.annotation ? (0, resolve_js_1.resolvedSummary)(scenario, resolved) : undefined });
+    }));
+    server.registerTool("submit_scenario", {
+        title: "Submit a scenario for approval",
+        description: "Send a draft scenario for review (on-prem approval flow). Personal-token and scheduled runs use the APPROVED version, so a new or edited scenario must be approved before run_scenario runs the change. Optionally name approvers by email (default: every eligible approver is notified). Approval itself happens in the desktop app.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            scenario: (0, shared_js_1.refArg)("Scenario"),
+            approvers: zod_1.z.array(zod_1.z.string().max(255)).max(100).optional().describe("Approver emails; omit to notify all eligible approvers"),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, scenario, approvers }) => {
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
+        let approverIds;
+        if (approvers && approvers.length > 0) {
+            const { items } = await ctx.api.listApproverCandidates(ws?.id ?? null, resolved.item.id);
+            approverIds = approvers.map((email) => {
+                const match = items.find((candidate) => candidate.email.toLowerCase() === email.trim().toLowerCase());
+                if (!match)
+                    throw new errors_js_1.ToolInputError("APPROVER_NOT_ELIGIBLE", `"${email}" cannot approve this scenario.`, { candidates: items.map((candidate) => candidate.email) });
+                return match.userId;
             });
         }
-        catch (error) {
-            if (error instanceof errors_js_1.CallmanApiError && error.code === "SCENARIO_VERSION_CONFLICT") {
-                const details = (error.details ?? {});
-                return (0, shared_js_1.ok)({
-                    conflict: true,
-                    code: error.code,
-                    message: error.message,
-                    currentVersion: details.currentScenario?.version ?? null,
-                    hint: "Re-read the scenario (get_scenario view:graph), reapply your change and call update_scenario with expectedVersion set to currentVersion — or force: true to overwrite.",
-                });
-            }
-            throw error;
-        }
+        const submitted = await ctx.api.submitScenario(ws?.id ?? null, resolved.item.id, approverIds ? { approverIds } : {});
+        ctx.invalidate("scenarios:");
+        return (0, shared_js_1.ok)({ scenario: { id: submitted.id ?? resolved.item.id, name: submitted.name ?? resolved.item.name, reviewStatus: submitted.reviewStatus ?? null, version: submitted.version ?? null }, note: "Submitted — an approver approves it in the desktop app." });
     }));
     server.registerTool("delete_scenario", {
         title: "Delete a scenario",
-        description: "Delete a scenario and its run history. Permanent — confirm with the user first.",
+        description: "Delete a scenario and its run history (exact name or id). Permanent — confirm with the user first.",
         inputSchema: { workspace: shared_js_1.workspaceArg, scenario: (0, shared_js_1.refArg)("Scenario"), confirm: shared_js_1.confirmArg },
         annotations: shared_js_1.DESTRUCTIVE,
     }, (0, shared_js_1.guarded)(async ({ workspace, scenario, confirm }) => {
         (0, shared_js_1.requireConfirm)(confirm, "a scenario");
         const ws = await ctx.resolveWorkspaceOrNull(workspace);
-        const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario);
+        const resolved = await (0, lookups_js_1.resolveScenario)(ctx, ws?.id ?? null, scenario, { exact: true });
         await ctx.api.deleteScenario(ws?.id ?? null, resolved.item.id);
         ctx.invalidate("scenarios:");
         return (0, shared_js_1.ok)({ deleted: { id: resolved.item.id, name: resolved.item.name }, resolved: [(0, resolve_js_1.resolvedSummary)(scenario, resolved)] });
     }));
     server.registerTool("run_scenario", {
         title: "Run a scenario on the server",
-        description: "Start a server-side run of a scenario (with one of its inline environments, by name or id) and wait for the result (default up to 5 minutes, max 30). Returns the compact report; if it times out you get the reportId to check later with get_scenario_report.",
+        description: "Start a server-side run of a scenario (with one of its inline environments, by name or id; the first one when omitted) and wait for the result (default up to 5 minutes, max 30). Returns the report as in get_scenario_report. A personal token runs the scenario's APPROVED version on-prem — the result says when that differs from the version you edited. If it times out you get the reportId to check later.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             scenario: (0, shared_js_1.refArg)("Scenario"),
@@ -239,7 +356,53 @@ const registerScenarioTools = (server, ctx) => {
         if (!last || !TERMINAL_STATUSES.has(last.status)) {
             return (0, shared_js_1.ok)({ scenario: { id: resolved.item.id, name: resolved.item.name }, reportId: trigger.reportId, status: last?.status ?? "running", timedOut: true, note: `Still running after ${timeoutSec}s — call get_scenario_report with this reportId later.` });
         }
-        return (0, shared_js_1.ok)({ report: (0, summarize_js_1.compactReportView)(last), ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(scenario, resolved)] } : {}) });
+        const warnings = [];
+        if (typeof last.scenarioVersion === "number" && last.scenarioVersion !== resolved.item.version) {
+            warnings.push(`This run executed version ${last.scenarioVersion} (the approved one); the live scenario is version ${resolved.item.version}. Edits since then run only after submit_scenario + approval.`);
+        }
+        if (environmentId && last.environmentId !== undefined && last.environmentId !== environmentId) {
+            warnings.push(`The server ran environment ${last.environmentId ?? "(first)"} instead of the one you picked — this backend ignores the choice; update the server.`);
+        }
+        return (0, shared_js_1.ok)({ report: (0, summarize_js_1.compactReportView)(last), ...(warnings.length > 0 ? { warnings } : {}), ...(resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(scenario, resolved)] } : {}) });
     }));
 };
 exports.registerScenarioTools = registerScenarioTools;
+// PATCH with the version check; a conflict comes back structured instead of
+// as an error so the model can re-read and retry.
+const saveGraph = async (ctx, ws, current, graph, options) => {
+    const body = {
+        ...(options.extra ?? {}),
+        ...(graph ? { nodes: graph.nodes, edges: graph.edges } : {}),
+        expectedVersion: options.expectedVersion ?? current.version,
+        ...(options.force ? { force: true } : {}),
+    };
+    try {
+        const updated = await ctx.api.patchScenario(ws, current.id, body);
+        ctx.invalidate("scenarios:");
+        const warnings = [...(graph?.warnings ?? []), ...(graph ? droppedFieldWarnings(graph, updated) : []), ...(updated.graph?.warnings ?? [])];
+        const removed = graph ? current.nodes.filter((node) => !graph.nodes.some((entry) => entry.id === node.id)).map((node) => node.id) : [];
+        return (0, shared_js_1.ok)({
+            scenario: (0, summarize_js_1.scenarioGraphView)(updated),
+            previousVersion: current.version,
+            ...(removed.length > 0 ? { removedNodes: removed } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
+            ...(current.reviewStatus === "approved" && updated.reviewStatus !== "approved"
+                ? { note: "The scenario was approved and is now a draft again; runs with a personal token and schedules keep using the last approved version until it is re-approved (submit_scenario)." }
+                : {}),
+            ...(options.annotation ? { resolved: [options.annotation] } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.CallmanApiError && error.code === "SCENARIO_VERSION_CONFLICT") {
+            const details = (error.details ?? {});
+            return (0, shared_js_1.ok)({
+                conflict: true,
+                code: error.code,
+                message: error.message,
+                currentVersion: details.currentScenario?.version ?? null,
+                hint: "Re-read the scenario (get_scenario), reapply your change and retry with expectedVersion set to currentVersion — or force: true to overwrite.",
+            });
+        }
+        throw error;
+    }
+};

package/dist-cjs/tools/shared.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireConfirm = exports.dryRunArg = exports.confirmArg = exports.cursorArgs = exports.refArg = exports.workspaceArg = exports.RUN = exports.DESTRUCTIVE = exports.IDEMPOTENT_WRITE = exports.WRITE = exports.READ = exports.guarded = exports.toolFailure = exports.ok = void 0;
+exports.requireConfirm = exports.dryRunArg = exports.confirmArg = exports.cursorArgs = exports.refArg = exports.workspaceArg = exports.RUN = exports.DESTRUCTIVE = exports.IDEMPOTENT_WRITE = exports.WRITE = exports.READ = exports.guarded = exports.failureOf = exports.toolFailure = exports.ok = void 0;
 const zod_1 = require("zod");
 const errors_js_1 = require("../client/errors.js");
 const truncate_js_1 = require("../lib/truncate.js");
@@ -42,6 +42,15 @@ const toolFailure = (error) => {
     return { isError: true, content: [{ type: "text", text: (0, truncate_js_1.safeStringify)(structured) }], structuredContent: structured };
 };
 exports.toolFailure = toolFailure;
+// One failed item of a batch (bulk create, move, delete, env writes): the
+// same code / hint / details / candidates a single call would return, so a
+// model can fix the item instead of guessing from "Validation failed".
+const failureOf = (error) => {
+    const payload = (0, exports.toolFailure)(error).structuredContent.error;
+    const { request: _request, status: _status, ...rest } = payload;
+    return rest;
+};
+exports.failureOf = failureOf;
 const guarded = (fn) => async (args) => {
     try {
         return await fn(args);
@@ -62,7 +71,7 @@ exports.workspaceArg = zod_1.z
     .string()
     .max(200)
     .optional()
-    .describe("Workspace id or name. Defaults to CALLMAN_WORKSPACE_ID, or the only workspace you have; call list_workspaces to see them.");
+    .describe('Workspace id or name to narrow to. Omit it: lists/searches cover ALL your workspaces and names are found in whichever workspace has them; creating uses the session default (use_workspace). "all" = every workspace.');
 const refArg = (what, extra = "") => zod_1.z.string().min(1).max(500).describe(`${what} id or name${extra ? ` ${extra}` : ""}`);
 exports.refArg = refArg;
 exports.cursorArgs = {

package/dist-cjs/tools/workspaces.js

@@ -9,7 +9,7 @@ const shared_js_1 = require("./shared.js");
 const registerWorkspaceTools = (server, ctx) => {
     server.registerTool("list_workspaces", {
         title: "List workspaces",
-        description: "List the workspaces you belong to, with your role in each (owner / editor / viewer). A token keeps your role: writes are refused where you are a viewer.",
+        description: "List the workspaces you belong to, with your role in each (owner / editor / viewer) and which one is the session default. The token works in all of them; a token keeps your role: writes are refused where you are a viewer.",
         inputSchema: {},
         annotations: shared_js_1.READ,
     }, (0, shared_js_1.guarded)(async () => {
@@ -20,10 +20,26 @@ const registerWorkspaceTools = (server, ctx) => {
                 name: workspace.name,
                 role: workspace.role,
                 memberCount: workspace.memberCount ?? null,
-                isDefault: workspace.id === ctx.config.defaultWorkspaceId,
+                isDefault: workspace.id === ctx.getDefaultWorkspaceId(),
             })),
         });
     }));
+    server.registerTool("use_workspace", {
+        title: "Set the default workspace for this session",
+        description: "Pick the workspace new things go to for the rest of this session (collections, environments, scenarios, imports — anything created without `workspace`), and the one that wins when a name exists in several workspaces. It never hides the others: lists and searches still cover every workspace. `workspace: null` clears the default. Lasts until the MCP server restarts; CALLMAN_WORKSPACE_ID sets it at start.",
+        inputSchema: { workspace: zod_1.z.string().max(200).nullable().describe("Workspace name or id; null = no default") },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace }) => {
+        const previous = ctx.getDefaultWorkspaceId();
+        if (workspace === null || !workspace.trim()) {
+            ctx.setDefaultWorkspaceId(null);
+            return (0, shared_js_1.ok)({ defaultWorkspace: null, previousDefaultId: previous, note: "No default workspace: creating something now needs `workspace`; reads still cover all workspaces." });
+        }
+        const target = await ctx.resolveWorkspace(workspace);
+        ctx.setDefaultWorkspaceId(target.id);
+        ctx.invalidate();
+        return (0, shared_js_1.ok)({ defaultWorkspace: { id: target.id, name: target.name, role: target.role }, previousDefaultId: previous });
+    }));
     server.registerTool("list_workspace_members", {
         title: "List workspace members",
         description: "List the members of a workspace with their role and status (active / invited).",
@@ -39,7 +55,7 @@ const registerWorkspaceTools = (server, ctx) => {
     }));
     server.registerTool("add_workspace_member", {
         title: "Add a workspace member",
-        description: "Add a person to a workspace by email with a role (editor can write collections/requests/scenarios; viewer is read-only; owner manages the workspace). Requires the owner role in that workspace. The person must already have a Callman account — the server does not send invitations to unknown emails.",
+        description: "Add a person to a workspace by email with a role (editor can write collections/requests/scenarios; viewer is read-only; owner manages the workspace). Requires the owner role in that workspace. The person must already have a Callman account — the server does not send invitations to unknown emails. Change a role later with update_workspace_member.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             email: zod_1.z.string().email().max(255),
@@ -53,12 +69,33 @@ const registerWorkspaceTools = (server, ctx) => {
         return (0, shared_js_1.ok)({
             workspace: { id: target.id, name: target.name },
             member: { id: member.id, email: member.email, role: member.role, status: member.status },
-            note: member.status === "invited" ? "Pending — the person gets access when they sign in." : "Added.",
+            note: "Added — the person has access now.",
         });
     }));
+    server.registerTool("update_workspace_member", {
+        title: "Change a member's role",
+        description: "Change a workspace member's role (owner / editor / viewer) by exact email or membership id. Requires the owner role; the last owner cannot be demoted.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            member: zod_1.z.string().min(1).max(255).describe("Member email or membership id"),
+            role: zod_1.z.enum(["owner", "editor", "viewer"]),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, member, role }) => {
+        const target = await ctx.resolveWorkspace(workspace);
+        const { items } = await ctx.api.listMembers(target.id);
+        const needle = (0, ids_js_1.normalizeName)(member);
+        const byEmail = items.filter((entry) => (0, ids_js_1.normalizeName)(entry.email) === needle);
+        const resolved = byEmail.length === 1 ? byEmail[0] : (0, resolve_js_1.resolveRef)("member", member, items.map((entry) => ({ ...entry, name: entry.email })), { exact: true }).item;
+        if (resolved.role === role)
+            return (0, shared_js_1.ok)({ workspace: { id: target.id, name: target.name }, member: { id: resolved.id, email: resolved.email, role }, note: "Already that role — nothing changed." });
+        const updated = await ctx.api.updateMemberRole(target.id, resolved.id, role);
+        ctx.invalidate(`members:${target.id}`);
+        return (0, shared_js_1.ok)({ workspace: { id: target.id, name: target.name }, member: { id: updated.id ?? resolved.id, email: updated.email ?? resolved.email, role: updated.role ?? role, previousRole: resolved.role } });
+    }));
     server.registerTool("remove_workspace_member", {
         title: "Remove a workspace member",
-        description: "Remove a member from a workspace (by email or membership id). Requires the owner role. Permanent — confirm with the user first.",
+        description: "Remove a member from a workspace (by exact email or membership id). Owners can remove anyone; any member can remove themselves (leave). The last owner cannot be removed. Permanent — confirm with the user first.",
         inputSchema: {
             workspace: shared_js_1.workspaceArg,
             member: zod_1.z.string().min(1).max(255).describe("Member email or membership id"),
@@ -73,7 +110,7 @@ const registerWorkspaceTools = (server, ctx) => {
         const byEmail = items.filter((entry) => (0, ids_js_1.normalizeName)(entry.email) === needle);
         const resolved = byEmail.length === 1
             ? byEmail[0]
-            : (0, resolve_js_1.resolveRef)("member", member, items.map((entry) => ({ ...entry, name: entry.email }))).item;
+            : (0, resolve_js_1.resolveRef)("member", member, items.map((entry) => ({ ...entry, name: entry.email })), { exact: true }).item;
         if (!resolved)
             throw new errors_js_1.ToolInputError("REF_NOT_FOUND", `No member matches "${member}".`);
         await ctx.api.removeMember(target.id, resolved.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "callman-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Callman: lets Claude Code, Claude Desktop, Cursor, Codex and Gemini CLI manage collections, requests, environments, test scenarios and system-design diagrams in your Callman workspace — cloud or on-prem.",
   "keywords": [
     "callman",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "callman-core": "^1.28.0",
+    "callman-core": "^1.28.1",
     "elkjs": "^0.12.0",
     "js-yaml": "^4.1.0",
     "zod": "^3.25.0"