mcp-cohesity 2.0.0

package/dist/tools/restore.js

@@ -0,0 +1,220 @@
+import { z } from "zod";
+function toolResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+export function registerRestoreTools(server, client) {
+    // ── Recover VM ───────────────────────────────────────────────────────
+    server.tool("recover_vm", "Recover a VMware VM from a Cohesity snapshot. By default restores to the original location (overwrite). Use list_snapshots to find the snapshot ID. For in-place recovery, only snapshot_id and name are required.", {
+        name: z
+            .string()
+            .describe("Name for this recovery task"),
+        snapshot_id: z
+            .string()
+            .describe("Snapshot ID to recover from (obtained from list_snapshots)"),
+        recover_to_new_source: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, recover to a different vCenter/datastore instead of original location"),
+        power_on_vms: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Power on the VM after recovery"),
+        restore_network: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Restore network settings on the recovered VM"),
+        prefix: z
+            .string()
+            .optional()
+            .describe("Prefix to add to the recovered VM name (useful to avoid conflicts)"),
+        suffix: z
+            .string()
+            .optional()
+            .describe("Suffix to add to the recovered VM name"),
+    }, async ({ name, snapshot_id, recover_to_new_source, power_on_vms, restore_network, prefix, suffix }) => {
+        try {
+            const recoveryTargetConfig = {
+                recoverToNewSource: recover_to_new_source,
+            };
+            if (!recover_to_new_source && (prefix || suffix)) {
+                recoveryTargetConfig.originalSourceConfig = {
+                    ...(prefix ? { prefix } : {}),
+                    ...(suffix ? { suffix } : {}),
+                };
+            }
+            const body = {
+                name,
+                snapshotEnvironment: "kVMware",
+                vmwareParams: {
+                    objects: [{ snapshotId: snapshot_id }],
+                    recoveryAction: "RecoverVMs",
+                    recoverVmParams: {
+                        targetEnvironment: "kVMware",
+                        powerOnVms: power_on_vms,
+                        restoreNetwork: restore_network,
+                        vmwareTargetParams: {
+                            recoveryTargetConfig,
+                        },
+                    },
+                },
+            };
+            const result = await client.postV2("data-protect/recoveries", body);
+            return toolResult(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return toolResult(`Error recovering VM: ${error}`, true);
+        }
+    });
+    // ── Search Files in Snapshots ───────────────────────────────────────
+    server.tool("search_files", "Search for files and folders across Cohesity snapshots by name. Returns matching files with their paths, source VM, and snapshot info. NOTE: Cohesity prefixes VMware file paths with a volume label (e.g. 'lvol_2/home/user/file') — pass these paths as-is to recover_files, which will automatically strip the prefix when restoring to the original location.", {
+        search_string: z
+            .string()
+            .describe("File or folder name to search for (supports partial matches)"),
+        source_environments: z
+            .array(z.enum(["kVMware", "kPhysical", "kGenericNas", "kIsilon", "kNetapp", "kFlashBlade"]))
+            .optional()
+            .default(["kVMware"])
+            .describe("Source environment types to search within"),
+        object_ids: z
+            .array(z.number())
+            .optional()
+            .describe("Limit search to specific object (VM) IDs"),
+        max_results: z
+            .number()
+            .optional()
+            .default(25)
+            .describe("Maximum number of results to return"),
+    }, async ({ search_string, source_environments, object_ids, max_results }) => {
+        try {
+            const body = {
+                objectType: "Files",
+                searchString: search_string,
+                count: max_results,
+                fileParams: {
+                    sourceEnvironments: source_environments,
+                },
+            };
+            if (object_ids) {
+                body.fileParams.objectIds = object_ids;
+            }
+            const result = await client.postV2("data-protect/search/indexed-objects", body);
+            return toolResult(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return toolResult(`Error searching files: ${error}`, true);
+        }
+    });
+    // ── Recover Files ────────────────────────────────────────────────────
+    server.tool("recover_files", "Recover specific files or folders from a VMware VM snapshot back to the original VM. Use list_snapshots to get a snapshot ID and search_files to find file paths. Pass file paths exactly as returned by search_files (e.g. 'lvol_2/home/user/file') — the volume prefix is automatically stripped when restoring to original path. The recover_method 'UseExistingAgent' requires a Cohesity agent installed on the VM; 'UseHypervisorApis' uses VMware Tools (requires VM credentials).", {
+        name: z
+            .string()
+            .describe("Name for this recovery task"),
+        snapshot_id: z
+            .string()
+            .describe("Snapshot ID to recover files from (obtained from list_snapshots)"),
+        file_paths: z
+            .array(z.string())
+            .describe("Absolute paths of files or folders to recover (e.g. ['/etc/hosts', '/var/log'])"),
+        recover_to_original_path: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true, restore to original path. If false, alternate_path must be provided."),
+        alternate_path: z
+            .string()
+            .optional()
+            .describe("Alternate path to restore files to (used when recover_to_original_path is false)"),
+        recover_method: z
+            .enum(["UseExistingAgent", "UseHypervisorApis", "AutoDeploy"])
+            .optional()
+            .default("UseExistingAgent")
+            .describe("Method to deliver files to the VM. UseExistingAgent requires Cohesity agent. UseHypervisorApis requires VMware Tools + credentials."),
+        overwrite_existing: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Overwrite existing files at the destination"),
+        preserve_attributes: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Preserve original file timestamps and permissions"),
+        vm_username: z
+            .string()
+            .optional()
+            .describe("VM guest OS username (required for UseHypervisorApis method)"),
+        vm_password: z
+            .string()
+            .optional()
+            .describe("VM guest OS password (required for UseHypervisorApis method)"),
+    }, async ({ name, snapshot_id, file_paths, recover_to_original_path, alternate_path, recover_method, overwrite_existing, preserve_attributes, vm_username, vm_password, }) => {
+        try {
+            // Cohesity indexes VMware files with a volume prefix (e.g. "lvol_2/home/user/file").
+            // When restoring to original path, recoverToOriginalPath:true fails for LVM volumes
+            // because Cohesity strips the prefix and can't resolve which physical volume to write to.
+            // Workaround: keep lvol_N/ prefix in paths, use recoverToOriginalPath:false, and set
+            // alternatePath to the real parent directory (e.g. /home/zerto). This bypasses the
+            // volume mapping logic while placing the file in its original location.
+            let resolvedPaths = file_paths;
+            let resolvedOriginalPath = recover_to_original_path;
+            let resolvedAlternatePath = alternate_path;
+            if (recover_to_original_path) {
+                // Derive the common parent directory (stripped of lvol prefix) as the alternate path.
+                // For a single file "lvol_2/home/zerto/file.sh" → alternatePath = "/home/zerto"
+                // For a directory "lvol_2/home/zerto" → alternatePath = "/home/zerto"
+                const parents = file_paths.map((p) => {
+                    const stripped = p.replace(/^lvol_\d+\//, "/").replace(/\/+/g, "/");
+                    // If it looks like a file (has extension or no trailing slash), use its parent dir
+                    const lastSlash = stripped.lastIndexOf("/");
+                    return lastSlash > 0 ? stripped.substring(0, lastSlash) : "/";
+                });
+                // Use the shortest common parent so all files land in the right place
+                resolvedAlternatePath = parents.reduce((a, b) => (a.length <= b.length ? a : b));
+                resolvedOriginalPath = false; // use alternate_path workaround
+                // Keep lvol_N/ prefix in paths — Cohesity needs it to locate the volume
+                resolvedPaths = file_paths;
+            }
+            const originalTargetConfig = {
+                recoverMethod: recover_method,
+                recoverToOriginalPath: resolvedOriginalPath,
+            };
+            if (!resolvedOriginalPath && resolvedAlternatePath) {
+                originalTargetConfig.alternatePath = resolvedAlternatePath;
+            }
+            if (vm_username && vm_password) {
+                originalTargetConfig.targetVmCredentials = {
+                    username: vm_username,
+                    password: vm_password,
+                };
+            }
+            const body = {
+                name,
+                snapshotEnvironment: "kVMware",
+                vmwareParams: {
+                    objects: [{ snapshotId: snapshot_id }],
+                    recoveryAction: "RecoverFiles",
+                    recoverFileAndFolderParams: {
+                        filesAndFolders: resolvedPaths.map((p) => ({ absolutePath: p })),
+                        targetEnvironment: "kVMware",
+                        vmwareTargetParams: {
+                            recoverToOriginalTarget: true,
+                            overwriteExisting: overwrite_existing,
+                            preserveAttributes: preserve_attributes,
+                            originalTargetConfig,
+                        },
+                    },
+                },
+            };
+            const result = await client.postV2("data-protect/recoveries", body);
+            return toolResult(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            return toolResult(`Error recovering files: ${error}`, true);
+        }
+    });
+    // cancel_protection_run lives in tools/run-actions.ts (spec-driven version);
+    // intentionally not re-registered here.
+}

package/dist/tools/roles.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Role management tools — list, create, update, and delete Cohesity roles.
+ *
+ *   GET    /v2/roles               — Roles
+ *   POST   /v2/roles               — CreateRoleParameters { name, privileges[], description? }
+ *   PUT    /v2/roles/{name}        — UpdateRoleParameters { privileges[], description? }
+ *   DELETE /v2/roles/{name}        — 204 No Content
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CohesityClient } from "../cohesity-client.js";
+export declare function registerRoleTools(server: McpServer, client: CohesityClient): void;

package/dist/tools/roles.js

@@ -0,0 +1,95 @@
+/**
+ * Role management tools — list, create, update, and delete Cohesity roles.
+ *
+ *   GET    /v2/roles               — Roles
+ *   POST   /v2/roles               — CreateRoleParameters { name, privileges[], description? }
+ *   PUT    /v2/roles/{name}        — UpdateRoleParameters { privileges[], description? }
+ *   DELETE /v2/roles/{name}        — 204 No Content
+ */
+import { z } from "zod";
+const reply = (text, isError = false) => ({
+    content: [{ type: "text", text }],
+    isError,
+});
+export function registerRoleTools(server, client) {
+    // ── List Roles ─────────────────────────────────────────────────────────
+    server.tool("list_roles", "List Cohesity roles (both built-in and user-created). Each role bundles a set of privileges.", {
+        names: z.array(z.string()).optional().describe("Restrict to roles with these names"),
+        tenant_ids: z.array(z.string()).optional().describe("Restrict to these tenant IDs"),
+        include_tenants: z
+            .boolean()
+            .optional()
+            .describe("Include roles from nested tenants the caller can see"),
+    }, async (args) => {
+        try {
+            const qp = {};
+            if (args.names?.length)
+                qp.names = args.names.join(",");
+            if (args.tenant_ids?.length)
+                qp.tenantIds = args.tenant_ids.join(",");
+            if (args.include_tenants !== undefined)
+                qp.includeTenants = String(args.include_tenants);
+            const data = await client.getV2("roles", qp);
+            return reply(JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            return reply(`Error listing roles: ${err}`, true);
+        }
+    });
+    // ── Create Role ────────────────────────────────────────────────────────
+    // CreateRoleParameters = { name (required) } + UpdateRoleParameters
+    // UpdateRoleParameters requires `privileges` (min 1 item).
+    server.tool("create_role", "Create a custom Cohesity role with a specific set of privileges. Privilege names are the same strings shown in the cluster's Role configuration UI (e.g., PROTECTION_VIEW, PROTECTION_MODIFY, CLUSTER_VIEW).", {
+        name: z.string().describe("Role name (must be unique on the cluster)"),
+        privileges: z
+            .array(z.string())
+            .min(1)
+            .describe("List of privilege strings to grant"),
+        description: z.string().optional().describe("Free-form description"),
+    }, async (args) => {
+        try {
+            const body = {
+                name: args.name,
+                privileges: args.privileges,
+            };
+            if (args.description)
+                body.description = args.description;
+            const result = await client.postV2("roles", body);
+            return reply(`Role '${args.name}' created.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error creating role: ${err}`, true);
+        }
+    });
+    // ── Update Role ────────────────────────────────────────────────────────
+    // PUT /v2/roles/{name} — privileges array must always be supplied.
+    server.tool("update_role", "Update a Cohesity role's privileges and/or description. The full privilege list must be supplied (this is a replace, not a merge).", {
+        name: z.string().describe("Role name to update"),
+        privileges: z
+            .array(z.string())
+            .min(1)
+            .describe("Full replacement list of privileges"),
+        description: z.string().optional().describe("New description"),
+    }, async (args) => {
+        try {
+            const body = { privileges: args.privileges };
+            if (args.description !== undefined)
+                body.description = args.description;
+            const result = await client.putV2(`roles/${encodeURIComponent(args.name)}`, body);
+            return reply(`Role '${args.name}' updated.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error updating role: ${err}`, true);
+        }
+    });
+    // ── Delete Role ────────────────────────────────────────────────────────
+    server.tool("delete_role", "Delete a Cohesity role by name. Built-in roles cannot be deleted.", { name: z.string().describe("Role name to delete") }, async (args) => {
+        try {
+            await client.deleteV2(`roles/${encodeURIComponent(args.name)}`);
+            return reply(`Role '${args.name}' deleted.`);
+        }
+        catch (err) {
+            return reply(`Error deleting role: ${err}`, true);
+        }
+    });
+}

package/dist/tools/run-actions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Protection run actions and snapshot management tools:
+ *   - cancel a running protection run (or specific objects within it)
+ *   - cancel a recovery task
+ *   - set DataLock/WORM on a snapshot (Compliance or Administrative)
+ *   - place a snapshot on Legal Hold (or release it)
+ *   - extend or shorten snapshot retention
+ *   - delete a snapshot immediately
+ *
+ * Endpoints used (all verified against cluster_v2_api.yaml):
+ *   POST /v2/data-protect/protection-groups/{id}/runs/actions
+ *   POST /v2/data-protect/recoveries/{id}/cancel
+ *   PUT  /v2/data-protect/protection-groups/{id}/runs
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CohesityClient } from "../cohesity-client.js";
+export declare function registerRunActionTools(server: McpServer, client: CohesityClient): void;

package/dist/tools/run-actions.js

@@ -0,0 +1,190 @@
+/**
+ * Protection run actions and snapshot management tools:
+ *   - cancel a running protection run (or specific objects within it)
+ *   - cancel a recovery task
+ *   - set DataLock/WORM on a snapshot (Compliance or Administrative)
+ *   - place a snapshot on Legal Hold (or release it)
+ *   - extend or shorten snapshot retention
+ *   - delete a snapshot immediately
+ *
+ * Endpoints used (all verified against cluster_v2_api.yaml):
+ *   POST /v2/data-protect/protection-groups/{id}/runs/actions
+ *   POST /v2/data-protect/recoveries/{id}/cancel
+ *   PUT  /v2/data-protect/protection-groups/{id}/runs
+ */
+import { z } from "zod";
+const reply = (text, isError = false) => ({
+    content: [{ type: "text", text }],
+    isError,
+});
+const RUN_ID_PATTERN = /^\d+:\d+$/;
+const TASK_ID_PATTERN = /^\d+:\d+:\d+$/;
+export function registerRunActionTools(server, client) {
+    // ── Cancel Protection Run ──────────────────────────────────────────────
+    // POST /v2/data-protect/protection-groups/{id}/runs/actions
+    // body: PerformActionOnProtectionGroupRunRequest { action: "Cancel", cancelParams: [...] }
+    server.tool("cancel_protection_run", "Cancel a running protection group run. Can cancel the entire run or a subset of objects/copies (local snapshot, archival, replication). Already-completed object tasks are not cancelled.", {
+        protection_group_id: z.string().describe("Protection group ID owning the run"),
+        run_id: z
+            .string()
+            .regex(RUN_ID_PATTERN, "Run ID must be in the form <number>:<number>")
+            .describe("Run ID to cancel"),
+        local_task_id: z
+            .string()
+            .regex(TASK_ID_PATTERN)
+            .optional()
+            .describe("Local backup task ID — cancel just the local copy"),
+        archival_task_ids: z
+            .array(z.string().regex(TASK_ID_PATTERN))
+            .optional()
+            .describe("Archival task IDs — cancel just these archival copies"),
+        replication_task_ids: z
+            .array(z.string().regex(TASK_ID_PATTERN))
+            .optional()
+            .describe("Replication task IDs — cancel just these replication copies"),
+        object_ids: z
+            .array(z.number())
+            .optional()
+            .describe("Entity IDs — cancel just these objects within the run"),
+    }, async (args) => {
+        try {
+            const cancelEntry = { runId: args.run_id };
+            if (args.local_task_id)
+                cancelEntry.localTaskId = args.local_task_id;
+            if (args.archival_task_ids?.length)
+                cancelEntry.archivalTaskId = args.archival_task_ids;
+            if (args.replication_task_ids?.length)
+                cancelEntry.replicationTaskId = args.replication_task_ids;
+            if (args.object_ids?.length)
+                cancelEntry.objectIds = args.object_ids;
+            const body = {
+                action: "Cancel",
+                cancelParams: [cancelEntry],
+            };
+            const result = await client.postV2(`data-protect/protection-groups/${args.protection_group_id}/runs/actions`, body);
+            return reply(`Cancel request submitted.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error cancelling protection run: ${err}`, true);
+        }
+    });
+    // ── Cancel Recovery Task ───────────────────────────────────────────────
+    // POST /v2/data-protect/recoveries/{id}/cancel — 204 No Content on success.
+    server.tool("cancel_recovery_task", "Cancel an in-flight recovery task by its ID. Returns 204 No Content on success.", {
+        recovery_id: z
+            .string()
+            .regex(TASK_ID_PATTERN)
+            .describe("Recovery task ID to cancel"),
+    }, async (args) => {
+        try {
+            await client.postV2(`data-protect/recoveries/${args.recovery_id}/cancel`, {});
+            return reply(`Recovery ${args.recovery_id} cancelled.`);
+        }
+        catch (err) {
+            return reply(`Error cancelling recovery ${args.recovery_id}: ${err}`, true);
+        }
+    });
+    // ── Set DataLock (WORM) on a Snapshot ──────────────────────────────────
+    // PUT /v2/data-protect/protection-groups/{id}/runs (UpdateProtectionGroupRunRequestBody).
+    // Sets localSnapshotConfig.dataLock = "Compliance" | "Administrative".
+    server.tool("set_snapshot_datalock", "Apply DataLock (WORM) protection to a protection group run's local snapshot. Once locked, the snapshot cannot be deleted until its retention expires. Compliance lock is even more restrictive — it cannot be released by an administrator.", {
+        protection_group_id: z.string().describe("Protection group ID owning the run"),
+        run_id: z
+            .string()
+            .regex(RUN_ID_PATTERN)
+            .describe("Run ID whose snapshot will be locked"),
+        data_lock_mode: z
+            .enum(["Compliance", "Administrative"])
+            .describe("Compliance is permanent; Administrative can be released by an admin"),
+    }, async (args) => {
+        try {
+            const body = {
+                updateProtectionGroupRunParams: [
+                    {
+                        runId: args.run_id,
+                        localSnapshotConfig: { dataLock: args.data_lock_mode },
+                    },
+                ],
+            };
+            const result = await client.putV2(`data-protect/protection-groups/${args.protection_group_id}/runs`, body);
+            return reply(`DataLock '${args.data_lock_mode}' applied.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error setting DataLock: ${err}`, true);
+        }
+    });
+    // ── Legal Hold ─────────────────────────────────────────────────────────
+    // localSnapshotConfig.enableLegalHold = true/false.
+    // Requires Data Security Role on the caller.
+    server.tool("set_snapshot_legal_hold", "Place a snapshot on legal hold (or release it). While on hold, the snapshot cannot be deleted regardless of retention policy. Requires Data Security Role.", {
+        protection_group_id: z.string().describe("Protection group ID owning the run"),
+        run_id: z.string().regex(RUN_ID_PATTERN).describe("Run ID whose snapshot to hold"),
+        enable: z.boolean().describe("true to place on hold, false to release"),
+    }, async (args) => {
+        try {
+            const body = {
+                updateProtectionGroupRunParams: [
+                    {
+                        runId: args.run_id,
+                        localSnapshotConfig: { enableLegalHold: args.enable },
+                    },
+                ],
+            };
+            const result = await client.putV2(`data-protect/protection-groups/${args.protection_group_id}/runs`, body);
+            return reply(`Legal hold ${args.enable ? "applied" : "released"}.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error updating legal hold: ${err}`, true);
+        }
+    });
+    // ── Extend / Shorten Snapshot Retention ────────────────────────────────
+    // localSnapshotConfig.daysToKeep — positive extends, negative shortens.
+    // If the resulting expiry is before now, the snapshot is deleted immediately.
+    server.tool("extend_snapshot_retention", "Extend or shorten a snapshot's retention. Positive days_delta extends, negative shortens. If the resulting expiry falls before now, the snapshot is deleted immediately.", {
+        protection_group_id: z.string().describe("Protection group ID owning the run"),
+        run_id: z.string().regex(RUN_ID_PATTERN).describe("Run ID to adjust"),
+        days_delta: z
+            .number()
+            .int()
+            .describe("Days to add (positive) or subtract (negative) from current retention"),
+    }, async (args) => {
+        try {
+            const body = {
+                updateProtectionGroupRunParams: [
+                    {
+                        runId: args.run_id,
+                        localSnapshotConfig: { daysToKeep: args.days_delta },
+                    },
+                ],
+            };
+            const result = await client.putV2(`data-protect/protection-groups/${args.protection_group_id}/runs`, body);
+            return reply(`Retention adjusted by ${args.days_delta} days.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error adjusting retention: ${err}`, true);
+        }
+    });
+    // ── Delete Snapshot Immediately ────────────────────────────────────────
+    // localSnapshotConfig.deleteSnapshot = true. All other params ignored.
+    // Will be rejected if the snapshot is on legal hold or under DataLock.
+    server.tool("delete_snapshot", "Delete a protection group run's local snapshot immediately. WARNING: irreversible. Will fail if the snapshot is under DataLock or Legal Hold.", {
+        protection_group_id: z.string().describe("Protection group ID owning the run"),
+        run_id: z.string().regex(RUN_ID_PATTERN).describe("Run ID whose snapshot to delete"),
+    }, async (args) => {
+        try {
+            const body = {
+                updateProtectionGroupRunParams: [
+                    {
+                        runId: args.run_id,
+                        localSnapshotConfig: { deleteSnapshot: true },
+                    },
+                ],
+            };
+            const result = await client.putV2(`data-protect/protection-groups/${args.protection_group_id}/runs`, body);
+            return reply(`Snapshot delete requested.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error deleting snapshot: ${err}`, true);
+        }
+    });
+}

package/dist/tools/runs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Protection run tools — list and inspect backup run history.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CohesityClient } from "../cohesity-client.js";
+export declare function registerRunsTools(server: McpServer, client: CohesityClient): void;

package/dist/tools/runs.js

@@ -0,0 +1,94 @@
+/**
+ * Protection run tools — list and inspect backup run history.
+ */
+import { z } from "zod";
+/** Shorthand for building MCP tool return values. */
+const reply = (text, isError = false) => ({
+    content: [{ type: "text", text }],
+    isError,
+});
+/** Run type identifiers accepted by the V2 protection runs endpoint. */
+const RUN_TYPES = ["kRegular", "kFull", "kLog", "kSystem"];
+/** Status values accepted by the V2 protection runs endpoint for filtering. */
+const RUN_STATUSES = [
+    "Accepted",
+    "Running",
+    "Canceled",
+    "Canceling",
+    "Failed",
+    "Missed",
+    "Succeeded",
+    "SucceededWithWarning",
+    "OnHold",
+    "Finalizing",
+    "Skipped",
+    "LegalHold",
+];
+export function registerRunsTools(server, client) {
+    // ── List Protection Runs ───────────────────────────────────────────────
+    server.tool("list_protection_runs", "List recent backup runs for a Cohesity protection group with status, duration, and data size", {
+        protection_group_id: z.string().describe("Protection group ID to list runs for"),
+        run_types: z
+            .array(z.enum(RUN_TYPES))
+            .optional()
+            .describe("Filter by run type (incremental, full, log, system)"),
+        local_backup_run_status: z
+            .array(z.enum(RUN_STATUSES))
+            .optional()
+            .describe("Filter by run status"),
+        start_time_usecs: z
+            .number()
+            .optional()
+            .describe("Only return runs started after this timestamp (microseconds)"),
+        end_time_usecs: z
+            .number()
+            .optional()
+            .describe("Only return runs ended before this timestamp (microseconds)"),
+        max_results: z
+            .number()
+            .optional()
+            .default(25)
+            .describe("Cap on the number of runs returned"),
+    }, async (args) => {
+        try {
+            const qp = {
+                maxCount: String(args.max_results),
+                includeObjectDetails: "false",
+            };
+            if (args.run_types)
+                qp.runTypes = args.run_types.join(",");
+            if (args.local_backup_run_status)
+                qp.localBackupRunStatus = args.local_backup_run_status.join(",");
+            if (args.start_time_usecs !== undefined)
+                qp.startTimeUsecs = String(args.start_time_usecs);
+            if (args.end_time_usecs !== undefined)
+                qp.endTimeUsecs = String(args.end_time_usecs);
+            const data = await client.getV2(`data-protect/protection-groups/${args.protection_group_id}/runs`, qp);
+            return reply(JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            return reply(`Error fetching runs for group ${args.protection_group_id}: ${err}`, true);
+        }
+    });
+    // ── Get Protection Run ─────────────────────────────────────────────────
+    server.tool("get_protection_run", "Get detailed information about a specific Cohesity backup run including per-object status and statistics", {
+        protection_group_id: z.string().describe("Protection group ID the run belongs to"),
+        run_id: z.string().describe("Run ID to retrieve details for"),
+        include_object_details: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Include per-object backup details"),
+    }, async (args) => {
+        try {
+            const qp = {
+                includeObjectDetails: String(args.include_object_details),
+            };
+            const data = await client.getV2(`data-protect/protection-groups/${args.protection_group_id}/runs/${args.run_id}`, qp);
+            return reply(JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            return reply(`Error fetching run ${args.run_id} for group ${args.protection_group_id}: ${err}`, true);
+        }
+    });
+}

package/dist/tools/source-registration.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Source registration tools — register, update, and unregister protection sources.
+ * Covers VMware (vCenter / ESXi / vCloud), Physical, Azure, AWS, M365, and Generic NAS.
+ *
+ * All payload shapes are derived from the cluster's OpenAPI v2 spec
+ * (cluster_v2_api.yaml). Field names match the spec exactly; deviating from
+ * the spec produces KValidationError from the cluster.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CohesityClient } from "../cohesity-client.js";
+export declare function registerSourceRegistrationTools(server: McpServer, client: CohesityClient): void;