coalesce-transform-mcp 0.1.0

package/dist/mcp/repo-node-types.js

@@ -0,0 +1,387 @@
+import { z } from "zod";
+import { buildSetWorkspaceNodeTemplateFromDefinition, compareGeneratedTemplateToWorkspaceNode, renderYaml, } from "../services/templates/nodes.js";
+import { sanitizeNodeDefinitionSqlOverridePolicy } from "../services/policies/sql-override.js";
+import { getWorkspaceNode } from "../coalesce/api/nodes.js";
+import { buildJsonToolResponse, handleToolError, READ_ONLY_ANNOTATIONS, } from "../coalesce/types.js";
+import { parseRepo, resolveRepoNodeType, } from "../services/repo/parser.js";
+import { resolveRepoPathInput } from "../services/repo/path.js";
+import { isPlainObject } from "../utils.js";
+function compareStrings(left, right) {
+    return left.localeCompare(right, undefined, {
+        numeric: true,
+        sensitivity: "case",
+    });
+}
+function requireComparisonPair(params) {
+    if ((params.workspaceID && !params.nodeID) || (!params.workspaceID && params.nodeID)) {
+        throw new Error("workspaceID and nodeID must be provided together when requesting a live node comparison.");
+    }
+}
+function summarizePackageRecord(record) {
+    return {
+        alias: record.alias,
+        aliasSource: record.aliasSource,
+        packageFilePath: record.packageFilePath,
+        packageID: record.packageID,
+        releaseID: record.releaseID,
+        packageVariables: record.packageVariables,
+        enabledNodeTypeIDs: record.enabledNodeTypeIDs,
+        resolvedDefinitionIDs: record.resolvedDefinitionIDs,
+        missingDefinitionIDs: record.missingDefinitionIDs,
+        ambiguousDefinitionIDs: record.ambiguousDefinitionIDs,
+        usageByNodeTypeID: record.usageByNodeTypeID,
+        usageCount: record.usageCount,
+        warnings: record.warnings,
+    };
+}
+function buildRepoSummary(parsedRepo) {
+    return {
+        repoPath: parsedRepo.summary.repoPath,
+        resolvedRepoPath: parsedRepo.summary.resolvedRepoPath,
+        packageCount: parsedRepo.summary.packageCount,
+        uniquePackageAliasCount: parsedRepo.summary.uniquePackageAliasCount,
+        nodeTypeDefinitionCount: parsedRepo.summary.nodeTypeDefinitionCount,
+        uniqueNodeTypeIDCount: parsedRepo.summary.uniqueNodeTypeIDCount,
+        nodeCount: parsedRepo.summary.nodeCount,
+        warnings: parsedRepo.summary.warnings,
+    };
+}
+function buildNodeTypeRow(resolution) {
+    return {
+        nodeType: resolution.resolvedNodeType,
+        outerID: resolution.nodeTypeRecord.outerDefinition.id,
+        displayName: resolution.nodeTypeRecord.outerDefinition.name,
+        resolutionKind: resolution.resolutionKind,
+        ...(resolution.resolutionKind === "package"
+            ? { packageAlias: resolution.packageAlias }
+            : {}),
+        definitionPath: resolution.nodeTypeRecord.definitionPath,
+        createPath: resolution.nodeTypeRecord.createPath,
+        runPath: resolution.nodeTypeRecord.runPath,
+        usageCount: resolution.usageCount,
+        parseError: resolution.nodeTypeRecord.parseError,
+        warnings: resolution.nodeTypeRecord.warnings,
+    };
+}
+function buildResolutionMetadata(resolution) {
+    if (resolution.resolutionKind === "package") {
+        return {
+            resolutionKind: resolution.resolutionKind,
+            requestedNodeType: resolution.requestedNodeType,
+            resolvedNodeType: resolution.resolvedNodeType,
+            packageAlias: resolution.packageAlias,
+            packageFilePath: resolution.packageRecord.packageFilePath,
+            packageID: resolution.packageRecord.packageID,
+            releaseID: resolution.packageRecord.releaseID,
+            enabledNodeTypeID: resolution.nodeTypeRecord.outerDefinition.id,
+            usageCount: resolution.usageCount,
+        };
+    }
+    return {
+        resolutionKind: resolution.resolutionKind,
+        requestedNodeType: resolution.requestedNodeType,
+        resolvedNodeType: resolution.resolvedNodeType,
+        usageCount: resolution.usageCount,
+    };
+}
+function sanitizeRepoNodeDefinition(nodeDefinition, nodeMetadataSpec, warnings) {
+    if (!isPlainObject(nodeDefinition)) {
+        return {
+            nodeDefinition,
+            nodeMetadataSpecYaml: nodeMetadataSpec,
+            warnings,
+        };
+    }
+    const sanitized = sanitizeNodeDefinitionSqlOverridePolicy(nodeDefinition);
+    return {
+        nodeDefinition: sanitized.nodeDefinition,
+        nodeMetadataSpecYaml: renderYaml(sanitized.nodeDefinition),
+        warnings: Array.from(new Set([...warnings, ...sanitized.warnings])),
+    };
+}
+export function listRepoPackages(params) {
+    const repoPath = resolveRepoPathInput(params.repoPath);
+    const parsedRepo = parseRepo(repoPath);
+    return {
+        summary: buildRepoSummary(parsedRepo),
+        packages: parsedRepo.packages
+            .slice()
+            .sort((left, right) => compareStrings(left.alias, right.alias))
+            .map(summarizePackageRecord),
+    };
+}
+export function listRepoNodeTypes(params) {
+    const repoPath = resolveRepoPathInput(params.repoPath);
+    const parsedRepo = parseRepo(repoPath);
+    const rows = [];
+    const warnings = [...parsedRepo.summary.warnings];
+    if (params.packageAlias) {
+        const packageMatches = parsedRepo.packagesByAlias.get(params.packageAlias) ?? [];
+        if (packageMatches.length === 0) {
+            warnings.push(`No package alias ${params.packageAlias} was found under packages/.`);
+        }
+        else if (packageMatches.length > 1) {
+            warnings.push(`Package alias ${params.packageAlias} is ambiguous across ${packageMatches
+                .map((match) => match.packageFilePath)
+                .join(", ")}.`);
+        }
+        else {
+            for (const definitionID of packageMatches[0].resolvedDefinitionIDs) {
+                const resolution = resolveRepoNodeType(parsedRepo, `${params.packageAlias}:::${definitionID}`);
+                rows.push(buildNodeTypeRow(resolution));
+            }
+        }
+    }
+    else {
+        for (const [id, matches] of parsedRepo.nodeTypesByID.entries()) {
+            if (matches.length !== 1) {
+                continue;
+            }
+            rows.push(buildNodeTypeRow(resolveRepoNodeType(parsedRepo, id)));
+        }
+        for (const packageRecord of parsedRepo.packages) {
+            const packageMatches = parsedRepo.packagesByAlias.get(packageRecord.alias) ?? [];
+            if (packageMatches.length !== 1) {
+                continue;
+            }
+            for (const definitionID of packageRecord.resolvedDefinitionIDs) {
+                rows.push(buildNodeTypeRow(resolveRepoNodeType(parsedRepo, `${packageRecord.alias}:::${definitionID}`)));
+            }
+        }
+    }
+    const filteredRows = (params.inUseOnly ? rows.filter((row) => row.usageCount > 0) : rows)
+        .sort((left, right) => right.usageCount === left.usageCount
+        ? compareStrings(left.nodeType, right.nodeType)
+        : right.usageCount - left.usageCount);
+    return {
+        summary: {
+            ...buildRepoSummary(parsedRepo),
+            warnings: Array.from(new Set(warnings)).sort(compareStrings),
+            packageAlias: params.packageAlias ?? null,
+            inUseOnly: params.inUseOnly ?? false,
+            matchedCount: filteredRows.length,
+        },
+        nodeTypes: filteredRows,
+    };
+}
+export function getRepoNodeTypeDefinition(params) {
+    const repoPath = resolveRepoPathInput(params.repoPath);
+    const parsedRepo = parseRepo(repoPath);
+    const resolution = resolveRepoNodeType(parsedRepo, params.nodeType);
+    const sanitized = sanitizeRepoNodeDefinition(resolution.nodeTypeRecord.nodeDefinition, resolution.nodeTypeRecord.nodeMetadataSpec, resolution.nodeTypeRecord.warnings);
+    return {
+        repoPath,
+        resolvedRepoPath: parsedRepo.summary.resolvedRepoPath,
+        repoWarnings: parsedRepo.summary.warnings,
+        requestedNodeType: params.nodeType,
+        resolvedNodeType: resolution.resolvedNodeType,
+        resolution: buildResolutionMetadata(resolution),
+        ...(resolution.resolutionKind === "package"
+            ? {
+                package: summarizePackageRecord(resolution.packageRecord),
+            }
+            : {}),
+        outerDefinition: resolution.nodeTypeRecord.outerDefinition,
+        nodeMetadataSpecYaml: sanitized.nodeMetadataSpecYaml,
+        nodeDefinition: sanitized.nodeDefinition,
+        parseError: resolution.nodeTypeRecord.parseError,
+        filePaths: {
+            definitionPath: resolution.nodeTypeRecord.definitionPath,
+            createPath: resolution.nodeTypeRecord.createPath,
+            runPath: resolution.nodeTypeRecord.runPath,
+        },
+        usageSummary: {
+            exactNodeType: resolution.resolvedNodeType,
+            usageCount: resolution.usageCount,
+        },
+        warnings: sanitized.warnings,
+    };
+}
+async function maybeBuildComparison(client, generated, params) {
+    requireComparisonPair(params);
+    if (!params.workspaceID || !params.nodeID) {
+        return undefined;
+    }
+    const workspaceNode = await getWorkspaceNode(client, {
+        workspaceID: params.workspaceID,
+        nodeID: params.nodeID,
+    });
+    if (!isPlainObject(workspaceNode)) {
+        throw new Error("Workspace node comparison target was not an object");
+    }
+    return {
+        workspaceID: params.workspaceID,
+        nodeID: params.nodeID,
+        result: compareGeneratedTemplateToWorkspaceNode(generated, workspaceNode),
+    };
+}
+export async function generateSetWorkspaceNodeTemplate(client, params) {
+    const usingDefinition = params.definition !== undefined;
+    if (usingDefinition && params.repoPath !== undefined) {
+        throw new Error("Provide exactly one input mode: either definition for raw mode or repoPath with nodeType for repo mode.");
+    }
+    if (usingDefinition && !isPlainObject(params.definition)) {
+        throw new Error("definition must be an object when using raw mode.");
+    }
+    if (!usingDefinition && !params.nodeType) {
+        throw new Error("nodeType is required when using repo mode.");
+    }
+    let generated;
+    let result;
+    if (usingDefinition) {
+        const sanitizedDefinition = sanitizeNodeDefinitionSqlOverridePolicy(params.definition);
+        generated = buildSetWorkspaceNodeTemplateFromDefinition(params.definition, {
+            nodeName: params.nodeName,
+            nodeType: params.nodeType,
+            locationName: params.locationName,
+            database: params.database,
+            schema: params.schema,
+        });
+        result = {
+            definitionSource: {
+                mode: "raw",
+            },
+            nodeDefinition: sanitizedDefinition.nodeDefinition,
+            ...generated,
+            warnings: Array.from(new Set([...generated.warnings, ...sanitizedDefinition.warnings])),
+            setWorkspaceNodeBodyTemplateYaml: renderYaml(generated.setWorkspaceNodeBodyTemplate),
+        };
+    }
+    else {
+        const repoPath = resolveRepoPathInput(params.repoPath);
+        const definition = getRepoNodeTypeDefinition({
+            repoPath,
+            nodeType: params.nodeType,
+        });
+        if (!isPlainObject(definition.nodeDefinition)) {
+            const parseError = typeof definition.parseError === "string" ? definition.parseError : "unknown";
+            throw new Error(`Repo-backed definition could not be resolved for template generation because metadata.nodeMetadataSpec could not be parsed. Parse error: ${parseError} Use the corpus tools (search-node-type-variants, get-node-type-variant, or generate-set-workspace-node-template-from-variant) as the next step.`);
+        }
+        generated = buildSetWorkspaceNodeTemplateFromDefinition(definition.nodeDefinition, {
+            nodeName: params.nodeName,
+            nodeType: definition.resolvedNodeType,
+            locationName: params.locationName,
+            database: params.database,
+            schema: params.schema,
+        });
+        result = {
+            definitionSource: {
+                mode: "repo",
+            },
+            repoPath,
+            resolvedRepoPath: definition.resolvedRepoPath,
+            requestedNodeType: definition.requestedNodeType,
+            resolvedNodeType: definition.resolvedNodeType,
+            resolution: definition.resolution,
+            ...(definition.package ? { package: definition.package } : {}),
+            outerDefinition: definition.outerDefinition,
+            nodeMetadataSpecYaml: definition.nodeMetadataSpecYaml,
+            nodeDefinition: definition.nodeDefinition,
+            filePaths: definition.filePaths,
+            usageSummary: definition.usageSummary,
+            repoWarnings: definition.repoWarnings,
+            ...generated,
+            warnings: Array.from(new Set([...definition.warnings, ...generated.warnings])),
+            setWorkspaceNodeBodyTemplateYaml: renderYaml(generated.setWorkspaceNodeBodyTemplate),
+        };
+    }
+    const comparison = await maybeBuildComparison(client, generated, params);
+    return comparison ? { ...result, comparison } : result;
+}
+export function registerRepoNodeTypeTools(server, client) {
+    server.tool("list-repo-packages", "Inspect a committed local Coalesce repo and list package aliases from packages/*.yml. Use this when a local repo is available and you want repo-backed node-type discovery before falling back to the corpus.", {
+        repoPath: z
+            .string()
+            .optional()
+            .describe("Optional absolute or relative path to the local committed Coalesce repo. Falls back to COALESCE_REPO_PATH when omitted."),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            return buildJsonToolResponse("list-repo-packages", listRepoPackages(params));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("list-repo-node-types", "Inspect a committed local Coalesce repo and list exact resolvable node-type identifiers from nodeTypes/, optionally filtered to one package alias. Repo-backed discovery is preferred when the repo contains the committed definition; otherwise use the corpus tools.", {
+        repoPath: z
+            .string()
+            .optional()
+            .describe("Optional absolute or relative path to the local committed Coalesce repo. Falls back to COALESCE_REPO_PATH when omitted."),
+        packageAlias: z
+            .string()
+            .optional()
+            .describe("Optional exact package alias filter sourced from package YAML name."),
+        inUseOnly: z
+            .boolean()
+            .optional()
+            .describe("When true, return only identifiers currently referenced by committed nodes/*.yml operation.sqlType values."),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            return buildJsonToolResponse("list-repo-node-types", listRepoNodeTypes(params));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get-repo-node-type-definition", "Resolve one exact node type from a committed local Coalesce repo. Supports direct identifiers like Stage or 65 and package-backed identifiers like alias:::id. If the repo cannot resolve the definition exactly, use the corpus tools as the fallback path.", {
+        repoPath: z
+            .string()
+            .optional()
+            .describe("Optional absolute or relative path to the local committed Coalesce repo. Falls back to COALESCE_REPO_PATH when omitted."),
+        nodeType: z
+            .string()
+            .describe("Exact direct node type identifier or exact package-backed alias:::id value."),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            return buildJsonToolResponse("get-repo-node-type-definition", getRepoNodeTypeDefinition(params));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("generate-set-workspace-node-template", "Generate a YAML-friendly set-workspace-node body template either from a raw node definition object or by resolving a committed node type from a local repo. Prefer repo mode when a local committed repo contains the definition; use the corpus tools when repo-backed resolution is unavailable. SQL override controls are removed from returned templates because they are disallowed in this project.", {
+        definition: z
+            .record(z.unknown())
+            .optional()
+            .describe("Raw parsed node definition object for template generation in raw mode."),
+        repoPath: z
+            .string()
+            .optional()
+            .describe("Optional local committed repo path for repo mode. Falls back to COALESCE_REPO_PATH when omitted."),
+        nodeType: z
+            .string()
+            .optional()
+            .describe("Exact repo node type identifier in repo mode, or optional nodeType override in raw mode."),
+        nodeName: z
+            .string()
+            .optional()
+            .describe("Optional node name to inject into the generated template."),
+        locationName: z
+            .string()
+            .optional()
+            .describe("Optional storage location name to include in the template."),
+        database: z
+            .string()
+            .optional()
+            .describe("Optional database value to include in the template."),
+        schema: z
+            .string()
+            .optional()
+            .describe("Optional schema value to include in the template."),
+        workspaceID: z
+            .string()
+            .optional()
+            .describe("Optional workspace ID for comparing inferred mappings to a live workspace node."),
+        nodeID: z
+            .string()
+            .optional()
+            .describe("Optional node ID for comparing inferred mappings to a live workspace node."),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            return buildJsonToolResponse("generate-set-workspace-node-template", await generateSetWorkspaceNodeTemplate(client, params));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/mcp/runs.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CoalesceClient } from "../client.js";
+export declare function registerRunTools(server: McpServer, client: CoalesceClient): void;

package/dist/mcp/runs.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { listRuns, getRun, getRunResults, startRun, runStatus, retryRun, cancelRun, } from "../coalesce/api/runs.js";
+import { PaginationParams, StartRunParams, RerunParams, buildJsonToolResponse, handleToolError, sanitizeResponse, READ_ONLY_ANNOTATIONS, WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS, } from "../coalesce/types.js";
+export function registerRunTools(server, client) {
+    server.tool("list-runs", "List all Coalesce runs. Supports filtering by runType, runStatus, and environmentID.", PaginationParams.extend({
+        runType: z.enum(["deploy", "refresh"]).optional().describe("Filter by run type"),
+        runStatus: z.enum(["completed", "failed", "canceled", "running", "waitingToRun"]).optional().describe("Filter by run status"),
+        environmentID: z.string().optional().describe("Filter by environment ID"),
+        detail: z.boolean().optional().describe("Include full run details in response"),
+    }).shape, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await listRuns(client, params);
+            return buildJsonToolResponse("list-runs", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get-run", "Get details of a specific Coalesce run", {
+        runID: z.string().describe("The numeric run ID (integer, e.g. '401'). Use the runCounter value from start-run or run-status responses — not the UUID from run URLs."),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await getRun(client, params);
+            return buildJsonToolResponse("get-run", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get-run-results", "Get the results of a specific Coalesce run", {
+        runID: z.string().describe("The numeric run ID (integer, e.g. '401'). Use the runCounter value from start-run or run-status responses — not the UUID from run URLs."),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await getRunResults(client, params);
+            return buildJsonToolResponse("get-run-results", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("start-run", "Start a new Coalesce run. Requires a numeric environmentID and optionally a jobID (not job name). " +
+        "If the user provides a job name instead of an ID, ask them for the job ID. " +
+        "If the user doesn't know the environment ID, use list-environments to look it up by name. " +
+        "Requires Snowflake Key Pair auth; credentials are read from environment variables.", StartRunParams.shape, WRITE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await startRun(client, params);
+            return buildJsonToolResponse("start-run", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("run-status", "Get the status of a Coalesce run by run counter", {
+        runCounter: z.number().describe("The run counter number"),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await runStatus(client, params);
+            return buildJsonToolResponse("run-status", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("retry-run", "Retry a failed Coalesce run. Requires the runID from the original run. " +
+        "Requires Snowflake Key Pair auth; credentials are read from environment variables.", RerunParams.shape, WRITE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await retryRun(client, params);
+            return buildJsonToolResponse("retry-run", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("cancel-run", "Cancel an in-progress Coalesce run. Requires the runID and environmentID. " +
+        "Provide orgID explicitly, or omit it to use COALESCE_ORG_ID from the environment. " +
+        "If the user does not know the orgID, they can find it in Coalesce Support Information.", {
+        runID: z.string().describe("The numeric run ID (integer) of the run to cancel"),
+        orgID: z
+            .string()
+            .optional()
+            .describe("The organization ID. Optional if COALESCE_ORG_ID is set."),
+        environmentID: z.string().describe("The environment ID the run belongs to"),
+    }, DESTRUCTIVE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await cancelRun(client, params);
+            return buildJsonToolResponse("cancel-run", sanitizeResponse(result));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/mcp/subgraphs.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CoalesceClient } from "../client.js";
+export declare function registerSubgraphTools(server: McpServer, client: CoalesceClient): void;

package/dist/mcp/subgraphs.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { getWorkspaceSubgraph, createWorkspaceSubgraph, updateWorkspaceSubgraph, deleteWorkspaceSubgraph, } from "../coalesce/api/subgraphs.js";
+import { buildJsonToolResponse, handleToolError, READ_ONLY_ANNOTATIONS, WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS, } from "../coalesce/types.js";
+export function registerSubgraphTools(server, client) {
+    server.tool("get-workspace-subgraph", "Get details of a specific subgraph in a Coalesce workspace.", {
+        workspaceID: z.string().describe("The workspace ID"),
+        subgraphID: z.string().describe("The subgraph ID"),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await getWorkspaceSubgraph(client, params);
+            return buildJsonToolResponse("get-workspace-subgraph", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("create-workspace-subgraph", "Create a subgraph in a Coalesce workspace. A subgraph groups nodes together visually. The steps array contains node IDs to include in the subgraph.", {
+        workspaceID: z.string().describe("The workspace ID"),
+        name: z.string().describe("Name for the subgraph"),
+        steps: z
+            .array(z.string())
+            .describe("Array of node IDs to include in the subgraph"),
+    }, WRITE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await createWorkspaceSubgraph(client, params);
+            return buildJsonToolResponse("create-workspace-subgraph", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("update-workspace-subgraph", "Update a subgraph in a Coalesce workspace. Replaces the subgraph's name and steps (node IDs).", {
+        workspaceID: z.string().describe("The workspace ID"),
+        subgraphID: z.string().describe("The subgraph ID to update"),
+        name: z.string().describe("Updated name for the subgraph"),
+        steps: z
+            .array(z.string())
+            .describe("Updated array of node IDs to include in the subgraph"),
+    }, WRITE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await updateWorkspaceSubgraph(client, params);
+            return buildJsonToolResponse("update-workspace-subgraph", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("delete-workspace-subgraph", "Delete a subgraph from a Coalesce workspace. This is a destructive operation — the subgraph will be permanently removed. The nodes within it are NOT deleted.", {
+        workspaceID: z.string().describe("The workspace ID"),
+        subgraphID: z.string().describe("The subgraph ID to delete"),
+    }, DESTRUCTIVE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await deleteWorkspaceSubgraph(client, params);
+            return buildJsonToolResponse("delete-workspace-subgraph", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/mcp/users.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CoalesceClient } from "../client.js";
+export declare function registerUserTools(server: McpServer, client: CoalesceClient): void;

package/dist/mcp/users.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { listOrgUsers, getUserRoles, listUserRoles, setOrgRole, setProjectRole, deleteProjectRole, setEnvRole, deleteEnvRole, } from "../coalesce/api/users.js";
+import { PaginationParams, buildJsonToolResponse, handleToolError, READ_ONLY_ANNOTATIONS, IDEMPOTENT_WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS, } from "../coalesce/types.js";
+export function registerUserTools(server, client) {
+    server.tool("list-org-users", "List all users in the Coalesce organization", PaginationParams.shape, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await listOrgUsers(client, params);
+            return buildJsonToolResponse("list-org-users", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get-user-roles", "Get roles assigned to a specific user", {
+        userID: z.string().describe("The user ID"),
+        projectID: z.string().optional().describe("Optional project scope filter"),
+        environmentID: z.string().optional().describe("Optional environment scope filter"),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await getUserRoles(client, params);
+            return buildJsonToolResponse("get-user-roles", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("list-user-roles", "List roles for all users in the organization", {
+        projectID: z.string().optional().describe("Optional project scope filter"),
+        environmentID: z.string().optional().describe("Optional environment scope filter"),
+    }, READ_ONLY_ANNOTATIONS, async (params) => {
+        try {
+            const result = await listUserRoles(client, params);
+            return buildJsonToolResponse("list-user-roles", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("set-org-role", "Set the organization-level role for a user", {
+        userID: z.string().describe("The user ID"),
+        body: z
+            .record(z.unknown())
+            .describe("The organization role assignment body"),
+    }, IDEMPOTENT_WRITE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await setOrgRole(client, params);
+            return buildJsonToolResponse("set-org-role", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("set-project-role", "Set a user's role for a specific project", {
+        userID: z.string().describe("The user ID"),
+        projectID: z.string().describe("The project ID"),
+        body: z
+            .record(z.unknown())
+            .describe("The project role assignment body"),
+    }, IDEMPOTENT_WRITE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await setProjectRole(client, params);
+            return buildJsonToolResponse("set-project-role", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("delete-project-role", "Remove a user's role from a specific project", {
+        userID: z.string().describe("The user ID"),
+        projectID: z.string().describe("The project ID"),
+    }, DESTRUCTIVE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await deleteProjectRole(client, params);
+            return buildJsonToolResponse("delete-project-role", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("set-env-role", "Set a user's role for a specific environment", {
+        userID: z.string().describe("The user ID"),
+        environmentID: z.string().describe("The environment ID"),
+        body: z
+            .record(z.unknown())
+            .describe("The environment role assignment body"),
+    }, IDEMPOTENT_WRITE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await setEnvRole(client, params);
+            return buildJsonToolResponse("set-env-role", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("delete-env-role", "Remove a user's role from a specific environment", {
+        userID: z.string().describe("The user ID"),
+        environmentID: z.string().describe("The environment ID"),
+    }, DESTRUCTIVE_ANNOTATIONS, async (params) => {
+        try {
+            const result = await deleteEnvRole(client, params);
+            return buildJsonToolResponse("delete-env-role", result);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/prompts/index.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;