@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.10

package/lib/mcp/tools/profile-tools.js

@@ -0,0 +1,213 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { ProfilingDefinitionService } from '../../services/ProfilingDefinitionService.js';
+import { ProfilingExecutionService } from '../../services/ProfilingExecutionService.js';
+import { ProfileRequestService } from '../../services/ProfileRequestService.js';
+import { ServiceErrorCodes } from '../../adapters/errors.js';
+import { McpErrorCodes } from '../errors.js';
+import { serviceResultToMcp, createMcpError, extractErrorMessage } from './tool-factory.js';
+/**
+ * Handler for cuneiform_request_list tool invocation.
+ *
+ * Lists profiling requests with optional status filtering and pagination.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleRequestList(adapters, params) {
+    try {
+        const profileRequestService = new ProfileRequestService({
+            soqlAdapter: adapters.soql,
+            restAdapter: adapters.rest,
+        });
+        const result = await profileRequestService.listRequests({
+            status: params.status,
+            limit: params.limit,
+            offset: params.offset,
+        });
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to list profiling requests: ${extractErrorMessage(error, 'handleRequestList')}`);
+    }
+}
+/**
+ * Handler for cuneiform_profile_execute tool invocation.
+ *
+ * Executes profiling for a definition and optionally waits for completion.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleProfileExecute(adapters, params) {
+    try {
+        const { soql: soqlAdapter, rest: restAdapter } = adapters;
+        const definitionService = new ProfilingDefinitionService({
+            soqlAdapter,
+            restAdapter,
+        });
+        // Build polling config if custom timeout provided
+        const pollingConfig = params.timeoutMs ? { timeoutMs: params.timeoutMs } : undefined;
+        // Initialize ProfilingExecutionService
+        const executionService = new ProfilingExecutionService({
+            restAdapter,
+            soqlAdapter,
+            profilingDefinitionService: definitionService,
+            pollingConfig,
+        });
+        // Execute profiling
+        const executeResult = await executionService.execute(params.definitionId);
+        if (!executeResult.success) {
+            return serviceResultToMcp(executeResult);
+        }
+        const requestId = executeResult.data;
+        // If wait=false, return immediately with request ID
+        if (!params.wait) {
+            return serviceResultToMcp({
+                success: true,
+                data: {
+                    requestId,
+                    status: 'Queued',
+                    definitionId: params.definitionId,
+                    success: null, // Pending
+                    message: 'Profiling request enqueued. Use cuneiform_profile_status to check progress.',
+                },
+                message: executeResult.message,
+                metadata: executeResult.metadata,
+            });
+        }
+        // Wait for completion
+        const completionResult = await executionService.waitForCompletion(requestId);
+        return serviceResultToMcp(completionResult);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to execute profiling: ${extractErrorMessage(error, 'handleProfileExecute')}`);
+    }
+}
+/**
+ * Handler for cuneiform_profile_status tool invocation.
+ *
+ * Retrieves status for one or more profiling requests in parallel.
+ * Not-found IDs are surfaced as a "Not Found" row — no hard error.
+ * Other service errors (e.g. SOQL failure) propagate as hard errors.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult with statuses array and summary counts
+ */
+export async function handleProfileStatus(adapters, params) {
+    try {
+        const executionService = new ProfilingExecutionService({
+            restAdapter: adapters.rest,
+            soqlAdapter: adapters.soql,
+        });
+        const statusEntries = await Promise.all(params.requestIds.map(async (requestId) => {
+            const result = await executionService.getStatus(requestId);
+            if (result.success) {
+                return result.data;
+            }
+            if (result.errorCode === ServiceErrorCodes.PROFILING_REQUEST_NOT_FOUND) {
+                return { requestId, status: 'Not Found', definitionId: '' };
+            }
+            throw new Error(result.message ?? `Status check failed for ${requestId}`);
+        }));
+        const summary = {
+            completed: statusEntries.filter((s) => s.status === 'Completed').length,
+            inProgress: statusEntries.filter((s) => s.status === 'Queued').length,
+            failed: statusEntries.filter((s) => s.status === 'Rejected' || s.status === 'Canceled').length,
+            notFound: statusEntries.filter((s) => s.status === 'Not Found').length,
+        };
+        return serviceResultToMcp({
+            success: true,
+            data: { statuses: statusEntries, summary },
+            message: `${statusEntries.length} request(s) checked — ${summary.completed} completed, ${summary.inProgress} in progress, ${summary.failed} failed, ${summary.notFound} not found`,
+        });
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to get profiling status: ${extractErrorMessage(error, 'handleProfileStatus')}`);
+    }
+}
+/**
+ * Handler for cuneiform_profile_cancel tool invocation.
+ *
+ * Cancels profiling jobs by request ID (single cancellation) or definition ID
+ * (bulk cancellation — queries active requests for the definition, then cancels them).
+ *
+ * Uses ProfileRequestService directly instead of the ProfilingExecutionService facade.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleProfileCancel(adapters, params) {
+    try {
+        const profileRequestService = new ProfileRequestService({
+            soqlAdapter: adapters.soql,
+            restAdapter: adapters.rest,
+        });
+        // Execute appropriate method based on input mode
+        if (params.requestId) {
+            // Single request cancellation via ProfileRequestService
+            const result = await profileRequestService.cancelRequests({ requestIds: [params.requestId] });
+            return serviceResultToMcp(result);
+        }
+        else if (params.definitionId) {
+            // Definition-wide cancellation: list all cancellable requests for the definition,
+            // then cancel them via ProfileRequestService
+            const listResult = await profileRequestService.listRequests({ status: ['Queued'] });
+            if (!listResult.success) {
+                return serviceResultToMcp(listResult);
+            }
+            // Filter to requests belonging to this definition
+            const definitionRequests = listResult.data.filter((r) => r.definitionId === params.definitionId);
+            if (definitionRequests.length === 0) {
+                return serviceResultToMcp({
+                    success: true,
+                    data: 0,
+                    message: 'No active requests to cancel for this definition',
+                    metadata: { duration: 0 },
+                });
+            }
+            const requestIds = definitionRequests.map((r) => r.id);
+            const cancelResult = await profileRequestService.cancelRequests({ requestIds });
+            return serviceResultToMcp(cancelResult);
+        }
+        else {
+            return createMcpError(McpErrorCodes.INVALID_TOOL_INPUT, 'Either requestId or definitionId must be provided');
+        }
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to cancel profiling: ${extractErrorMessage(error, 'handleProfileCancel')}`);
+    }
+}
+/**
+ * Handler for cuneiform_profile_delete tool invocation.
+ *
+ * Deletes terminal (Canceled) profiling requests by ID. This operation is irreversible.
+ * Only requests in the Canceled state can be deleted — the service enforces this constraint.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleProfileDelete(adapters, params) {
+    try {
+        const profileRequestService = new ProfileRequestService({
+            soqlAdapter: adapters.soql,
+            restAdapter: adapters.rest,
+        });
+        const result = await profileRequestService.deleteRequests({ requestIds: params.requestIds });
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to delete profiling requests: ${extractErrorMessage(error, 'handleProfileDelete')}`);
+    }
+}
+//# sourceMappingURL=profile-tools.js.map

package/lib/mcp/tools/profile-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-tools.js","sourceRoot":"","sources":["../../../src/mcp/tools/profile-tools.ts"],"names":[],"mappings":"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"}

package/lib/mcp/tools/summary-tools.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpAdapters } from '../config/mcp-config.js';
+import type { SummaryListInput } from '../schemas/input-schemas.js';
+/**
+ * Handler for cuneiform_summary_list tool invocation.
+ *
+ * Retrieves profiling summary statistics for a specific definition ID.
+ * Supports pagination via limit and offset parameters.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult containing ProfilingSummary[] or error
+ */
+export declare function handleSummaryList(adapters: McpAdapters, params: SummaryListInput): Promise<CallToolResult>;

package/lib/mcp/tools/summary-tools.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { ProfilingSummaryService } from '../../services/ProfilingSummaryService.js';
+import { McpErrorCodes } from '../errors.js';
+import { serviceResultToMcp, createMcpError, extractErrorMessage } from './tool-factory.js';
+/**
+ * Handler for cuneiform_summary_list tool invocation.
+ *
+ * Retrieves profiling summary statistics for a specific definition ID.
+ * Supports pagination via limit and offset parameters.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult containing ProfilingSummary[] or error
+ */
+export async function handleSummaryList(adapters, params) {
+    try {
+        const summaryService = new ProfilingSummaryService({
+            soqlAdapter: adapters.soql,
+        });
+        // Get summaries with pagination
+        const result = await summaryService.getSummaries({
+            definitionId: params.definitionId,
+            limit: params.limit,
+            offset: params.offset,
+        });
+        return serviceResultToMcp(result);
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to list summaries: ${extractErrorMessage(error, 'handleSummaryList')}`);
+    }
+}
+//# sourceMappingURL=summary-tools.js.map

package/lib/mcp/tools/summary-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-tools.js","sourceRoot":"","sources":["../../../src/mcp/tools/summary-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE5F;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAqB,EAAE,MAAwB;IACrF,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,IAAI,uBAAuB,CAAC;YACjD,WAAW,EAAE,QAAQ,CAAC,IAAI;SAC3B,CAAC,CAAC;QAEH,gCAAgC;QAChC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,YAAY,CAAC;YAC/C,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QAEH,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,6BAA6B,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,CAAC,EAAE,CAC/E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/lib/mcp/tools/tool-factory.d.ts

@@ -0,0 +1,63 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ServiceResult } from '../../models/service-result.js';
+import type { PaginationMetadata } from '../config/pagination.js';
+import type { McpAdapters } from '../config/mcp-config.js';
+import { type McpErrorCode } from '../errors.js';
+/**
+ * Creates a typed MCP tool handler that narrows `unknown` input to type `T`.
+ *
+ * The McpServer SDK validates input via Zod schemas before calling handlers,
+ * so the cast from `unknown` to `T` is runtime-safe. This wrapper centralizes
+ * the single cast point instead of scattering `input as T` across 18 handlers.
+ *
+ * @template T The validated input type (inferred from the handler parameter)
+ * @param handler - Typed handler function accepting validated input
+ * @returns Untyped handler matching the ToolHandler signature
+ */
+export declare function typedHandler<T>(handler: (adapters: McpAdapters, input: T) => Promise<CallToolResult>): (adapters: McpAdapters, input: unknown) => Promise<CallToolResult>;
+/**
+ * Converts a ServiceResult to MCP CallToolResult format.
+ *
+ * Maps success/failure to MCP's content/isError structure.
+ * Preserves warnings and metadata in the response.
+ *
+ * @template T The type of the service result data
+ * @param result - ServiceResult from a service call
+ * @returns MCP-formatted CallToolResult
+ *
+ * @example
+ * ```typescript
+ * const serviceResult = await orgInfoService.getOrgIdentity();
+ * return serviceResultToMcp(serviceResult);
+ * ```
+ */
+export declare function serviceResultToMcp<T>(result: ServiceResult<T>): CallToolResult;
+/**
+ * Converts a ServiceResult to a paginated MCP CallToolResult.
+ *
+ * Includes `_pagination` metadata in the response envelope for
+ * cursor-based pagination through large result sets.
+ *
+ * @template T The type of the service result data
+ * @param result - ServiceResult from a service call
+ * @param pagination - Pagination metadata for the response
+ * @returns MCP-formatted CallToolResult with pagination envelope
+ */
+export declare function serviceResultToMcpPaginated<T>(result: ServiceResult<T>, pagination: PaginationMetadata): CallToolResult;
+/**
+ * Extracts a user-facing error message from a caught error and logs the
+ * full stack trace to stderr for post-mortem debugging.
+ *
+ * @param error - The caught error (may be Error or non-Error value)
+ * @param context - Tool/handler name for the log prefix
+ * @returns The error message string
+ */
+export declare function extractErrorMessage(error: unknown, context: string): string;
+/**
+ * Creates an MCP error response.
+ *
+ * @param errorCode - MCP error code
+ * @param message - Error message
+ * @returns MCP-formatted error CallToolResult
+ */
+export declare function createMcpError(errorCode: McpErrorCode, message: string): CallToolResult;

package/lib/mcp/tools/tool-factory.js

@@ -0,0 +1,146 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { McpErrorCodes } from '../errors.js';
+/**
+ * Creates a typed MCP tool handler that narrows `unknown` input to type `T`.
+ *
+ * The McpServer SDK validates input via Zod schemas before calling handlers,
+ * so the cast from `unknown` to `T` is runtime-safe. This wrapper centralizes
+ * the single cast point instead of scattering `input as T` across 18 handlers.
+ *
+ * @template T The validated input type (inferred from the handler parameter)
+ * @param handler - Typed handler function accepting validated input
+ * @returns Untyped handler matching the ToolHandler signature
+ */
+export function typedHandler(handler) {
+    return (adapters, input) => handler(adapters, input);
+}
+/**
+ * Converts a ServiceResult to MCP CallToolResult format.
+ *
+ * Maps success/failure to MCP's content/isError structure.
+ * Preserves warnings and metadata in the response.
+ *
+ * @template T The type of the service result data
+ * @param result - ServiceResult from a service call
+ * @returns MCP-formatted CallToolResult
+ *
+ * @example
+ * ```typescript
+ * const serviceResult = await orgInfoService.getOrgIdentity();
+ * return serviceResultToMcp(serviceResult);
+ * ```
+ */
+export function serviceResultToMcp(result) {
+    if (result.success) {
+        const content = {
+            type: 'text',
+            text: JSON.stringify({
+                success: true,
+                data: result.data,
+                message: result.message,
+                warnings: result.warnings,
+                metadata: result.metadata,
+            }, null, 2),
+        };
+        return {
+            content: [content],
+            isError: false,
+        };
+    }
+    // Failure case
+    const errorContent = {
+        type: 'text',
+        text: JSON.stringify({
+            success: false,
+            errorCode: result.errorCode ?? McpErrorCodes.SERVICE_CALL_FAILED,
+            message: result.message ?? 'Service call failed',
+            data: result.data,
+            metadata: result.metadata,
+        }, null, 2),
+    };
+    return {
+        content: [errorContent],
+        isError: true,
+    };
+}
+/**
+ * Converts a ServiceResult to a paginated MCP CallToolResult.
+ *
+ * Includes `_pagination` metadata in the response envelope for
+ * cursor-based pagination through large result sets.
+ *
+ * @template T The type of the service result data
+ * @param result - ServiceResult from a service call
+ * @param pagination - Pagination metadata for the response
+ * @returns MCP-formatted CallToolResult with pagination envelope
+ */
+export function serviceResultToMcpPaginated(result, pagination) {
+    if (result.success) {
+        const content = {
+            type: 'text',
+            text: JSON.stringify({
+                success: true,
+                data: result.data,
+                _pagination: pagination,
+                message: result.message,
+                warnings: result.warnings,
+                metadata: result.metadata,
+            }, null, 2),
+        };
+        return {
+            content: [content],
+            isError: false,
+        };
+    }
+    // Failure case — no pagination on errors
+    return serviceResultToMcp(result);
+}
+/**
+ * Extracts a user-facing error message from a caught error and logs the
+ * full stack trace to stderr for post-mortem debugging.
+ *
+ * @param error - The caught error (may be Error or non-Error value)
+ * @param context - Tool/handler name for the log prefix
+ * @returns The error message string
+ */
+/* eslint-disable no-console -- MCP uses stderr for logging */
+export function extractErrorMessage(error, context) {
+    if (error instanceof Error) {
+        if (error.stack) {
+            console.error(`[MCP] ${context} error:\n${error.stack}`);
+        }
+        return error.message;
+    }
+    const message = String(error);
+    console.error(`[MCP] ${context} non-Error thrown: ${message}`);
+    return message;
+}
+/* eslint-enable no-console */
+/**
+ * Creates an MCP error response.
+ *
+ * @param errorCode - MCP error code
+ * @param message - Error message
+ * @returns MCP-formatted error CallToolResult
+ */
+export function createMcpError(errorCode, message) {
+    const errorContent = {
+        type: 'text',
+        text: JSON.stringify({
+            success: false,
+            errorCode,
+            message,
+        }, null, 2),
+    };
+    return {
+        content: [errorContent],
+        isError: true,
+    };
+}
+//# sourceMappingURL=tool-factory.js.map

package/lib/mcp/tools/tool-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-factory.js","sourceRoot":"","sources":["../../../src/mcp/tools/tool-factory.ts"],"names":[],"mappings":"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"}

package/lib/mcp/tools/user-tools.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpAdapters } from '../config/mcp-config.js';
+import type { UserDetailsInput, UserConfigureInput } from '../schemas/input-schemas.js';
+/**
+ * Handler for cuneiform_user_details tool invocation.
+ *
+ * Returns user identity, readiness, and org context directly from service data.
+ * Builds the MCP response inline rather than delegating to the command layer.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export declare function handleUserDetails(adapters: McpAdapters, params: UserDetailsInput): Promise<CallToolResult>;
+/**
+ * Handler for cuneiform_user_configure tool invocation.
+ *
+ * Includes a prerequisite guard that checks Cuneiform installation
+ * before attempting configuration.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export declare function handleUserConfigure(adapters: McpAdapters, params: UserConfigureInput): Promise<CallToolResult>;