mcp-cohesity 2.0.0

package/dist/cohesity-client.js

@@ -0,0 +1,126 @@
+/**
+ * Cohesity REST API client supporting V1 and V2 endpoints
+ * with automatic bearer token authentication and retry on expiry.
+ */
+export class CohesityClient {
+    v2Base;
+    v1Base;
+    cfg;
+    bearer = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.v2Base = `https://${cfg.cluster}/v2`;
+        this.v1Base = `https://${cfg.cluster}/irisservices/api/v1/public`;
+        if (cfg.allowSelfSigned) {
+            process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        }
+    }
+    /** Obtain a bearer token from the V2 access-tokens endpoint. */
+    async authenticate() {
+        const resp = await fetch(`${this.v2Base}/access-tokens`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                username: this.cfg.username,
+                password: this.cfg.password,
+                domain: this.cfg.domain,
+            }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Authentication failed (${resp.status}): ${await resp.text()}`);
+        }
+        const data = (await resp.json());
+        const tok = data.accessToken ?? data.token;
+        if (!tok)
+            throw new Error("No access token in authentication response");
+        this.bearer = tok;
+    }
+    /** Return current token, authenticating first if needed. */
+    async token() {
+        if (!this.bearer)
+            await this.authenticate();
+        return this.bearer;
+    }
+    /** Build headers for an authenticated request. */
+    authHeaders(tok) {
+        return {
+            Authorization: `Bearer ${tok}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+    }
+    /** Parse a fetch Response into JSON, text, or null (for 204). */
+    async parseResponse(resp) {
+        if (resp.status === 204)
+            return null;
+        const ct = resp.headers.get("content-type") ?? "";
+        return ct.includes("application/json") ? resp.json() : resp.text();
+    }
+    /**
+     * Core HTTP method. Builds URL with query params, attaches auth,
+     * and retries once on 401 (token expiry).
+     */
+    async http(method, url, body, params) {
+        const target = new URL(url);
+        if (params) {
+            for (const [k, v] of Object.entries(params))
+                target.searchParams.set(k, v);
+        }
+        const buildOpts = (tok) => {
+            const opts = { method, headers: this.authHeaders(tok) };
+            if (body && ["POST", "PUT", "PATCH"].includes(method)) {
+                opts.body = JSON.stringify(body);
+            }
+            return opts;
+        };
+        let tok = await this.token();
+        let resp = await fetch(target.toString(), buildOpts(tok));
+        // Retry once on 401 — token may have expired
+        if (resp.status === 401) {
+            this.bearer = null;
+            tok = await this.token();
+            resp = await fetch(target.toString(), buildOpts(tok));
+        }
+        if (!resp.ok) {
+            throw new Error(`Cohesity API ${method} ${target.pathname} failed (${resp.status}): ${await resp.text()}`);
+        }
+        return this.parseResponse(resp);
+    }
+    // ── V2 convenience methods ──────────────────────────────────────────
+    getV2(path, params) {
+        return this.http("GET", `${this.v2Base}/${path}`, undefined, params);
+    }
+    postV2(path, body, params) {
+        return this.http("POST", `${this.v2Base}/${path}`, body, params);
+    }
+    putV2(path, body) {
+        return this.http("PUT", `${this.v2Base}/${path}`, body);
+    }
+    patchV2(path, body) {
+        return this.http("PATCH", `${this.v2Base}/${path}`, body);
+    }
+    deleteV2(path) {
+        return this.http("DELETE", `${this.v2Base}/${path}`);
+    }
+    // ── V1 convenience methods ──────────────────────────────────────────
+    getV1(path, params) {
+        return this.http("GET", `${this.v1Base}/${path}`, undefined, params);
+    }
+    postV1(path, body) {
+        return this.http("POST", `${this.v1Base}/${path}`, body);
+    }
+    putV1(path, body) {
+        return this.http("PUT", `${this.v1Base}/${path}`, body);
+    }
+    // ── Source refresh ──────────────────────────────────────────────────
+    /**
+     * Refresh every registered protection source in parallel.
+     * Called automatically before CRUD operations to ensure current inventory.
+     */
+    async refreshAllSources() {
+        const data = (await this.getV2("data-protect/sources/registrations"));
+        const ids = (data.registrations ?? []).map((r) => r.id).filter(Boolean);
+        await Promise.allSettled(ids.map((id) => this.postV2(`data-protect/sources/${id}/refresh`, {})));
+        return { refreshed: ids.length, sourceIds: ids };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * mcp-cohesity — MCP server for Cohesity DataProtect
+ * Entry point: validates configuration, wires up tool modules, launches STDIO transport.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * mcp-cohesity — MCP server for Cohesity DataProtect
+ * Entry point: validates configuration, wires up tool modules, launches STDIO transport.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CohesityClient } from "./cohesity-client.js";
+import { registerClusterTools } from "./tools/cluster.js";
+import { registerProtectionTools } from "./tools/protection.js";
+import { registerRunsTools } from "./tools/runs.js";
+import { registerSourcesTools } from "./tools/sources.js";
+import { registerSourceRegistrationTools } from "./tools/source-registration.js";
+import { registerAuditLogTools } from "./tools/audit-logs.js";
+import { registerClusterReportTools } from "./tools/cluster-reports.js";
+import { registerRunActionTools } from "./tools/run-actions.js";
+import { registerUserTools } from "./tools/users.js";
+import { registerRoleTools } from "./tools/roles.js";
+import { registerActiveDirectoryTools } from "./tools/active-directory.js";
+import { registerAntivirusTools } from "./tools/antivirus.js";
+import { registerKmsTools } from "./tools/kms.js";
+import { registerCloneTools } from "./tools/clones.js";
+import { registerRecoveryTools } from "./tools/recovery.js";
+import { registerAlertsTools } from "./tools/alerts.js";
+import { registerStorageTools } from "./tools/storage.js";
+import { registerRestoreTools } from "./tools/restore.js";
+import { registerReportTools } from "./tools/reports.js";
+import { registerExternalTargetTools } from "./tools/external-targets.js";
+import { registerTieringTools } from "./tools/tiering.js";
+import { registerNotificationTools } from "./tools/notifications.js";
+import { registerStatsTools } from "./tools/stats.js";
+/**
+ * Load credentials from an external JSON file if one is provided or found
+ * at a default location. Reading is best-effort — if the file is missing,
+ * unreadable, or malformed we just return an empty object and let env
+ * vars do the work.
+ *
+ * Resolution order:
+ *   1. $COHESITY_CONFIG_FILE if set (absolute or ~/-expanded path)
+ *   2. ~/.cohesity-mcp/config.json (if it exists)
+ */
+function loadConfigFile() {
+    const home = homedir();
+    const expand = (p) => (p.startsWith("~") ? resolve(home, p.slice(p.startsWith("~/") ? 2 : 1)) : p);
+    const explicit = process.env.COHESITY_CONFIG_FILE;
+    const candidates = [
+        explicit && expand(explicit),
+        resolve(home, ".cohesity-mcp", "config.json"),
+    ].filter((p) => !!p);
+    for (const path of candidates) {
+        try {
+            const data = readFileSync(path, "utf8");
+            const parsed = JSON.parse(data);
+            console.error(`Loaded Cohesity credentials from ${path}`);
+            return parsed;
+        }
+        catch (err) {
+            // ENOENT (file missing) at the default path is silent; explicit
+            // file path being missing or malformed is a hard error.
+            const e = err;
+            if (path === explicit) {
+                console.error(`Error reading COHESITY_CONFIG_FILE=${path}: ${e.message}`);
+                process.exit(1);
+            }
+            if (e.code !== "ENOENT") {
+                console.error(`Error reading ${path}: ${e.message}`);
+            }
+        }
+    }
+    return {};
+}
+/**
+ * Merge external config file and process env vars, with env vars taking
+ * precedence so users can override individual fields without editing the
+ * file. Returns the typed config object or exits with a clear message
+ * if required fields are still missing.
+ */
+function loadConfig() {
+    const file = loadConfigFile();
+    const cluster = process.env.COHESITY_CLUSTER ?? file.cluster;
+    const username = process.env.COHESITY_USERNAME ?? file.username;
+    const password = process.env.COHESITY_PASSWORD ?? file.password;
+    const domain = process.env.COHESITY_DOMAIN ?? file.domain ?? "LOCAL";
+    // allowSelfSigned defaults to true unless explicitly disabled
+    const envAllow = process.env.COHESITY_ALLOW_SELF_SIGNED;
+    const allowSelfSigned = envAllow !== undefined ? envAllow !== "false" : file.allowSelfSigned !== false;
+    const missing = [];
+    if (!cluster)
+        missing.push("cluster (COHESITY_CLUSTER)");
+    if (!username)
+        missing.push("username (COHESITY_USERNAME)");
+    if (!password)
+        missing.push("password (COHESITY_PASSWORD)");
+    if (missing.length > 0) {
+        console.error(`Missing required Cohesity credentials: ${missing.join(", ")}.\n` +
+            `Provide them via env vars, or via a JSON file pointed to by COHESITY_CONFIG_FILE\n` +
+            `(or the default ~/.cohesity-mcp/config.json). See README for details.`);
+        process.exit(1);
+    }
+    return { cluster: cluster, username: username, password: password, domain, allowSelfSigned };
+}
+/** Wire every tool module to the MCP server instance. */
+function wireTools(server, client) {
+    const registrations = [
+        registerClusterTools,
+        registerProtectionTools,
+        registerRunsTools,
+        registerSourcesTools,
+        registerSourceRegistrationTools,
+        registerRecoveryTools,
+        registerAlertsTools,
+        registerStorageTools,
+        registerRestoreTools,
+        registerReportTools,
+        registerExternalTargetTools,
+        registerTieringTools,
+        registerNotificationTools,
+        registerStatsTools,
+        registerAuditLogTools,
+        registerClusterReportTools,
+        registerRunActionTools,
+        registerUserTools,
+        registerRoleTools,
+        registerActiveDirectoryTools,
+        registerAntivirusTools,
+        registerKmsTools,
+        registerCloneTools,
+    ];
+    for (const register of registrations) {
+        register(server, client);
+    }
+}
+/** Bootstrap the MCP server and begin listening on STDIO. */
+async function bootstrap() {
+    const cfg = loadConfig();
+    const client = new CohesityClient(cfg);
+    const mcp = new McpServer({ name: "cohesity", version: "2.0.0" });
+    wireTools(mcp, client);
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+    console.error("Cohesity MCP server running");
+}
+bootstrap().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/tools/active-directory.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Active Directory management tools — join, list, and remove AD domains from
+ * the Cohesity cluster.
+ *
+ *   GET    /v2/active-directories          — list
+ *   POST   /v2/active-directories          — CreateActiveDirectoryRequest
+ *   DELETE /v2/active-directories/{id}     — leave domain
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CohesityClient } from "../cohesity-client.js";
+export declare function registerActiveDirectoryTools(server: McpServer, client: CohesityClient): void;

package/dist/tools/active-directory.js

@@ -0,0 +1,82 @@
+/**
+ * Active Directory management tools — join, list, and remove AD domains from
+ * the Cohesity cluster.
+ *
+ *   GET    /v2/active-directories          — list
+ *   POST   /v2/active-directories          — CreateActiveDirectoryRequest
+ *   DELETE /v2/active-directories/{id}     — leave domain
+ */
+import { z } from "zod";
+const reply = (text, isError = false) => ({
+    content: [{ type: "text", text }],
+    isError,
+});
+export function registerActiveDirectoryTools(server, client) {
+    // ── List Active Directories ────────────────────────────────────────────
+    server.tool("list_active_directories", "List Active Directory domains joined to the Cohesity cluster", {
+        domain_names: z.array(z.string()).optional().describe("Filter by domain names"),
+        ids: z.array(z.number()).optional().describe("Filter by AD IDs"),
+        tenant_ids: z.array(z.string()).optional().describe("Restrict to these tenant IDs"),
+        include_tenants: z.boolean().optional().describe("Include nested-tenant ADs"),
+    }, async (args) => {
+        try {
+            const qp = {};
+            if (args.domain_names?.length)
+                qp.domainNames = args.domain_names.join(",");
+            if (args.ids?.length)
+                qp.ids = args.ids.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("active-directories", qp);
+            return reply(JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            return reply(`Error listing active directories: ${err}`, true);
+        }
+    });
+    // ── Join Active Directory ──────────────────────────────────────────────
+    // CreateActiveDirectoryRequest requires { domainName, activeDirectoryAdminParams }.
+    server.tool("join_active_directory", "Join the cluster to an Active Directory domain using admin credentials with rights to add a computer to the domain.", {
+        domain_name: z
+            .string()
+            .describe("AD domain FQDN (e.g. corp.example.com)"),
+        admin_username: z
+            .string()
+            .describe("Username of an AD admin able to join machines to the domain"),
+        admin_password: z.string().describe("Password for the admin account"),
+        overwrite_machine_accounts: z
+            .boolean()
+            .optional()
+            .describe("Overwrite existing computer accounts in the domain if needed"),
+    }, async (args) => {
+        try {
+            const body = {
+                domainName: args.domain_name,
+                activeDirectoryAdminParams: {
+                    username: args.admin_username,
+                    password: args.admin_password,
+                },
+                ...(args.overwrite_machine_accounts !== undefined && {
+                    overwriteMachineAccounts: args.overwrite_machine_accounts,
+                }),
+            };
+            const result = await client.postV2("active-directories", body);
+            return reply(`Joined AD ${args.domain_name}.\n${JSON.stringify(result, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error joining Active Directory: ${err}`, true);
+        }
+    });
+    // ── Leave Active Directory ─────────────────────────────────────────────
+    server.tool("leave_active_directory", "Remove an Active Directory from the Cohesity cluster", { id: z.number().describe("AD ID to remove") }, async (args) => {
+        try {
+            await client.deleteV2(`active-directories/${args.id}`);
+            return reply(`Active Directory ${args.id} removed.`);
+        }
+        catch (err) {
+            return reply(`Error removing AD: ${err}`, true);
+        }
+    });
+}

package/dist/tools/alerts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Alert management tools — list and resolve Cohesity cluster alerts.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CohesityClient } from "../cohesity-client.js";
+export declare function registerAlertsTools(server: McpServer, client: CohesityClient): void;

package/dist/tools/alerts.js

@@ -0,0 +1,111 @@
+/**
+ * Alert management tools — list and resolve Cohesity cluster alerts.
+ */
+import { z } from "zod";
+/** Shorthand for building MCP tool return values. */
+const reply = (text, isError = false) => ({
+    content: [{ type: "text", text }],
+    isError,
+});
+/** Valid alert state values accepted by the Cohesity V2 API. */
+const ALERT_STATES = ["kOpen", "kSuppressed", "kResolved", "kNote"];
+/** Valid severity levels for alert filtering. */
+const ALERT_SEVERITIES = ["kCritical", "kWarning", "kInfo"];
+/** Full set of alert category identifiers supported by the V2 alerts endpoint. */
+const ALERT_CATEGORIES = [
+    "kDisk",
+    "kNode",
+    "kCluster",
+    "kNodeHealth",
+    "kClusterHealth",
+    "kBackupRestore",
+    "kEncryption",
+    "kArchivalRestore",
+    "kRemoteReplication",
+    "kQuota",
+    "kLicense",
+    "kHeliosProActiveWellness",
+    "kHeliosAnalyticsJobs",
+    "kHeliosSignatureJobs",
+    "kSecurity",
+    "kAppsInfra",
+    "kAntivirus",
+    "kArchivalCopy",
+];
+export function registerAlertsTools(server, client) {
+    // ── List Alerts ────────────────────────────────────────────────────────
+    server.tool("list_alerts", "List Cohesity cluster alerts with severity, description, and resolution status", {
+        alert_states: z
+            .array(z.enum(ALERT_STATES))
+            .optional()
+            .default(["kOpen"])
+            .describe("Filter by alert state (default: open alerts only)"),
+        alert_severities: z
+            .array(z.enum(ALERT_SEVERITIES))
+            .optional()
+            .describe("Filter by severity level"),
+        alert_categories: z
+            .array(z.enum(ALERT_CATEGORIES))
+            .optional()
+            .describe("Filter by alert category"),
+        start_date_usecs: z
+            .number()
+            .optional()
+            .describe("Only return alerts created after this timestamp (microseconds)"),
+        end_date_usecs: z
+            .number()
+            .optional()
+            .describe("Only return alerts created before this timestamp (microseconds)"),
+        max_results: z
+            .number()
+            .optional()
+            .default(50)
+            .describe("Cap on the number of alerts returned"),
+    }, async (args) => {
+        try {
+            const qp = { maxAlerts: String(args.max_results) };
+            if (args.alert_states)
+                qp.alertStates = args.alert_states.join(",");
+            if (args.alert_severities)
+                qp.alertSeverityList = args.alert_severities.join(",");
+            if (args.alert_categories)
+                qp.alertCategoryList = args.alert_categories.join(",");
+            if (args.start_date_usecs !== undefined)
+                qp.startDateUsecs = String(args.start_date_usecs);
+            if (args.end_date_usecs !== undefined)
+                qp.endDateUsecs = String(args.end_date_usecs);
+            const data = await client.getV2("alerts", qp);
+            return reply(JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            return reply(`Error fetching alerts: ${err}`, true);
+        }
+    });
+    // ── Resolve Alert ──────────────────────────────────────────────────────
+    server.tool("resolve_alert", "Mark a Cohesity alert as resolved", {
+        alert_id: z.string().describe("Alert ID to resolve"),
+        resolution_summary: z
+            .string()
+            .optional()
+            .describe("Short summary of how the alert was resolved"),
+        resolution_details: z
+            .string()
+            .optional()
+            .describe("Detailed description of the resolution actions taken"),
+    }, async (args) => {
+        try {
+            const payload = {
+                alertIdList: [args.alert_id],
+                resolutionDetails: {
+                    resolutionSummary: args.resolution_summary ?? "Resolved via MCP",
+                    resolutionDetails: args.resolution_details ?? "",
+                },
+            };
+            const data = await client.postV2("alerts/resolutions", payload);
+            return reply(`Alert ${args.alert_id} resolved.\n${JSON.stringify(data, null, 2)}`);
+        }
+        catch (err) {
+            return reply(`Error resolving alert ${args.alert_id}: ${err}`, true);
+        }
+    });
+}

package/dist/tools/antivirus.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Antivirus / threat-detection tools — manage antivirus service integrations
+ * (e.g., ICAP-based scanners) and review infected/quarantined files.
+ *
+ * Notes:
+ *   - Cohesity's "anomaly detection" (ransomware behavioural analysis) is a
+ *     Helios SaaS feature and is NOT exposed on standalone on-prem clusters.
+ *     For on-prem threat detection, the cluster integrates with ICAP-compliant
+ *     antivirus servers via Antivirus Service Groups. This module exposes
+ *     those endpoints.
+ *
+ *   Endpoints (verified against cluster_v2_api.yaml):
+ *     GET    /v2/antivirus-service/groups
+ *     POST   /v2/antivirus-service/groups
+ *     GET    /v2/antivirus-service/groups/{id}
+ *     PUT    /v2/antivirus-service/groups/{id}
+ *     DELETE /v2/antivirus-service/groups/{id}
+ *     GET    /v2/antivirus-service/icap-uri-connection-status
+ *     GET    /v2/antivirus-service/infected-files
+ *     POST   /v2/antivirus-service/infected-files/actions  (quarantine/unquarantine/delete)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CohesityClient } from "../cohesity-client.js";
+export declare function registerAntivirusTools(server: McpServer, client: CohesityClient): void;