@salesforce/magen-mcp-workflow 0.0.1

package/dist/tools/utilities/inputExtraction/tool.js

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { createInputExtractionMetadata, } from './metadata.js';
+import { AbstractWorkflowTool } from '../../base/abstractWorkflowTool.js';
+export class InputExtractionTool extends AbstractWorkflowTool {
+    constructor(server, toolId, orchestratorToolId, logger) {
+        super(server, createInputExtractionMetadata(toolId), orchestratorToolId, 'InputExtractionTool', logger);
+    }
+    handleRequest = async (input) => {
+        try {
+            const guidance = this.generateInputExtractionGuidance(input);
+            return this.finalizeWorkflowToolOutput(guidance, input.workflowStateData, input.resultSchema);
+        }
+        catch (error) {
+            const toolError = error instanceof Error ? error : new Error('Unknown error occurred');
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${toolError.message}`,
+                    },
+                ],
+            };
+        }
+    };
+    generateInputExtractionGuidance(input) {
+        return `
+# ROLE
+You are a highly accurate and precise data extraction tool.
+
+# TASK
+
+Your task is to analyze a user utterance and extract values for a given list of properties.
+For each property you are asked to find, you must provide its extracted value or \`null\`
+if no value is found.
+
+---
+# CONTEXT
+
+## USER UTTERANCE TO ANALYZE
+${JSON.stringify(input.userUtterance)}
+
+## PROPERTIES TO EXTRACT
+Here is the list of properties you need to find values for. Use each property's description
+to understand what to look for.
+
+\`\`\`json
+${JSON.stringify(input.propertiesToExtract)}
+\`\`\`
+
+---
+# INSTRUCTIONS
+1. Carefully read the "USER UTTERANCE TO ANALYZE".
+2. For each property listed in "PROPERTIES TO EXTRACT", search the text for a  
+   corresponding value.
+3. If a clear value is found for a property, place it in your output.
+4. If a property's value is not ABSOLUTELY INFERABLE from USER UTTERANCE TO ANALYZE, you
+   MUST use \`null\` as the value for that property. You MAY NOT infer your own property
+   values, in the absence of their clear specification in the USER UTTERANCE TO ANALYZE.
+5. Ensure the keys in your output JSON object exactly match the \`propertyName\` values  
+   from the input list.
+6. The exact format of your output object will be given in the section below.
+`;
+    }
+}
+//# sourceMappingURL=tool.js.map

package/dist/tools/utilities/inputExtraction/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../../../src/tools/utilities/inputExtraction/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAGL,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE1E,MAAM,OAAO,mBAAoB,SAAQ,oBAAiD;IACxF,YAAY,MAAiB,EAAE,MAAc,EAAE,kBAA0B,EAAE,MAAe;QACxF,KAAK,CACH,MAAM,EACN,6BAA6B,CAAC,MAAM,CAAC,EACrC,kBAAkB,EAClB,qBAAqB,EACrB,MAAM,CACP,CAAC;IACJ,CAAC;IAEM,aAAa,GAAG,KAAK,EAAE,KAAmC,EAAE,EAAE;QACnE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,+BAA+B,CAAC,KAAK,CAAC,CAAC;YAC7D,OAAO,IAAI,CAAC,0BAA0B,CAAC,QAAQ,EAAE,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;QAChG,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;YACvF,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,UAAU,SAAS,CAAC,OAAO,EAAE;qBACpC;iBACF;aACF,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;IAEM,+BAA+B,CAAC,KAAmC;QACzE,OAAO;;;;;;;;;;;;;;EAcT,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC;;;;;;;EAOnC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mBAAmB,CAAC;;;;;;;;;;;;;;;CAe1C,CAAC;IACA,CAAC;CACF"}

package/dist/utils/toolExecutionUtils.d.ts

@@ -0,0 +1,55 @@
+import z from 'zod';
+import { MCPToolInvocationData } from '../common/metadata.js';
+import { Logger } from '../logging/logger.js';
+import { ToolExecutor } from '../nodes/toolExecutor.js';
+/**
+ * Executes a tool with logging and validation.
+ *
+ * This utility provides a standardized pattern for tool execution that includes:
+ * - Pre-execution logging of tool invocation data
+ * - Tool execution via the provided executor
+ * - Post-execution logging of results
+ * - Result validation using Zod schemas
+ * - Optional custom validation logic
+ *
+ * This function is used by both workflow nodes (via AbstractToolNode) and
+ * services (via AbstractService) to ensure consistent tool execution patterns
+ * across the codebase.
+ *
+ * @param toolExecutor - The executor to use for running the tool
+ * @param logger - Logger instance for recording execution details
+ * @param toolInvocationData - The tool invocation data including metadata and input
+ * @param resultSchema - Zod schema to validate the result against
+ * @param validator - Optional custom validator function for additional validation logic
+ * @returns The validated result from the tool execution
+ *
+ * @throws {z.ZodError} If the result does not match the schema (when using default validation)
+ * @throws {Error} If tool execution fails or custom validator throws
+ *
+ * @example
+ * // Basic usage with schema validation
+ * const result = executeToolWithLogging(
+ *   toolExecutor,
+ *   logger,
+ *   toolInvocationData,
+ *   MyToolResultSchema
+ * );
+ *
+ * @example
+ * // With custom validator
+ * const result = executeToolWithLogging(
+ *   toolExecutor,
+ *   logger,
+ *   toolInvocationData,
+ *   MyToolResultSchema,
+ *   (result, schema) => {
+ *     const validated = schema.parse(result);
+ *     // Additional custom validation or transformation
+ *     if (validated.someField < 0) {
+ *       throw new Error('Value must be positive');
+ *     }
+ *     return validated;
+ *   }
+ * );
+ */
+export declare function executeToolWithLogging<TResultSchema extends z.ZodObject<z.ZodRawShape>>(toolExecutor: ToolExecutor, logger: Logger, toolInvocationData: MCPToolInvocationData<z.ZodObject<z.ZodRawShape>>, resultSchema: TResultSchema, validator?: (result: unknown, schema: TResultSchema) => z.infer<TResultSchema>): z.infer<TResultSchema>;

package/dist/utils/toolExecutionUtils.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+/**
+ * Executes a tool with logging and validation.
+ *
+ * This utility provides a standardized pattern for tool execution that includes:
+ * - Pre-execution logging of tool invocation data
+ * - Tool execution via the provided executor
+ * - Post-execution logging of results
+ * - Result validation using Zod schemas
+ * - Optional custom validation logic
+ *
+ * This function is used by both workflow nodes (via AbstractToolNode) and
+ * services (via AbstractService) to ensure consistent tool execution patterns
+ * across the codebase.
+ *
+ * @param toolExecutor - The executor to use for running the tool
+ * @param logger - Logger instance for recording execution details
+ * @param toolInvocationData - The tool invocation data including metadata and input
+ * @param resultSchema - Zod schema to validate the result against
+ * @param validator - Optional custom validator function for additional validation logic
+ * @returns The validated result from the tool execution
+ *
+ * @throws {z.ZodError} If the result does not match the schema (when using default validation)
+ * @throws {Error} If tool execution fails or custom validator throws
+ *
+ * @example
+ * // Basic usage with schema validation
+ * const result = executeToolWithLogging(
+ *   toolExecutor,
+ *   logger,
+ *   toolInvocationData,
+ *   MyToolResultSchema
+ * );
+ *
+ * @example
+ * // With custom validator
+ * const result = executeToolWithLogging(
+ *   toolExecutor,
+ *   logger,
+ *   toolInvocationData,
+ *   MyToolResultSchema,
+ *   (result, schema) => {
+ *     const validated = schema.parse(result);
+ *     // Additional custom validation or transformation
+ *     if (validated.someField < 0) {
+ *       throw new Error('Value must be positive');
+ *     }
+ *     return validated;
+ *   }
+ * );
+ */
+export function executeToolWithLogging(toolExecutor, logger, toolInvocationData, resultSchema, validator) {
+    logger.debug('Tool invocation data (pre-execution)', { toolInvocationData });
+    const result = toolExecutor.execute(toolInvocationData);
+    logger.debug('Tool execution result (post-execution)', { result });
+    if (validator) {
+        return validator(result, resultSchema);
+    }
+    else {
+        const validatedResult = resultSchema.parse(result);
+        logger.debug('Validated tool result', { validatedResult });
+        return validatedResult;
+    }
+}
+//# sourceMappingURL=toolExecutionUtils.js.map

package/dist/utils/toolExecutionUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolExecutionUtils.js","sourceRoot":"","sources":["../../src/utils/toolExecutionUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,sBAAsB,CACpC,YAA0B,EAC1B,MAAc,EACd,kBAAqE,EACrE,YAA2B,EAC3B,SAA8E;IAE9E,MAAM,CAAC,KAAK,CAAC,sCAAsC,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAE7E,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAExD,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAEnE,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACzC,CAAC;SAAM,CAAC;QACN,MAAM,eAAe,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACnD,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;QAC3D,OAAO,eAAe,CAAC;IACzB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@salesforce/magen-mcp-workflow",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "description": "MCP Workflow Engine - A framework for building deterministic workflows with LangGraph and Model Context Protocol",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "eslint --max-warnings 0 --config ../../eslint.config.mjs \"{src,tests}/**/*.ts\"",
+    "format": "prettier --write \"{src,tests}/**/*.ts\""
+  },
+  "dependencies": {
+    "@langchain/langgraph": "^0.4.9",
+    "@langchain/langgraph-checkpoint": "^0.0.11",
+    "@langchain/core": "^0.3.28",
+    "@modelcontextprotocol/sdk": "^1.21.1",
+    "pino": "^9.9.5",
+    "zod": "^3.25.67",
+    "zod-to-json-schema": "^3.24.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.8.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.3"
+  }
+}