@salesforce/magen-mcp-workflow 0.0.1

package/README.md

@@ -0,0 +1,168 @@
+# @salesforce/magen-mcp-workflow
+
+A reusable workflow orchestration framework for building deterministic, multi-step workflows with LangGraph and the Model Context Protocol (MCP).
+
+## Overview
+
+`mcp-workflow` is a **framework for MCP server authors** who need to orchestrate complex, multi-step processes involving LLM interactions. It provides the infrastructure for workflow execution, state management, and MCP tool coordination, while allowing consumers to define their own domain-specific logic.
+
+### What This Framework Provides
+
+✅ **Infrastructure**:
+
+- `OrchestratorTool`: Manages workflow execution and coordinates MCP tool invocations
+- Base classes for MCP tools (`AbstractTool`, `AbstractWorkflowTool`)
+- Base classes for workflow nodes (`BaseNode`, `AbstractToolNode`)
+- State persistence and checkpointing (via `.magen/` directory)
+- Logging infrastructure
+- Dependency injection patterns for testability
+
+### What Consumers Provide
+
+❌ **Domain Logic**:
+
+- Your own `StateGraph` definition (workflow structure)
+- Your own state annotations (`Annotation.Root`)
+- Your own workflow nodes (business operations)
+- Your own MCP server tools (domain capabilities)
+- Your own MCP server instance
+
+## Installation
+
+```bash
+npm install @salesforce/magen-mcp-workflow
+```
+
+## Quick Start
+
+```typescript
+import { Annotation, StateGraph, START, END } from '@langchain/langgraph';
+import { OrchestratorTool, OrchestratorConfig, BaseNode } from '@salesforce/magen-mcp-workflow';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// 1. Define your state
+const MyWorkflowState = Annotation.Root({
+  userMessage: Annotation<string>,
+  response: Annotation<string>,
+});
+
+type State = typeof MyWorkflowState.State;
+
+// 2. Create workflow nodes
+class ProcessMessageNode extends BaseNode<State> {
+  constructor() {
+    super('ProcessMessage');
+  }
+
+  execute = (state: State): Partial<State> => {
+    return {
+      response: `Processed: ${state.userMessage}`,
+    };
+  };
+}
+
+// 3. Build the workflow (uncompiled StateGraph)
+const processNode = new ProcessMessageNode();
+const workflow = new StateGraph(MyWorkflowState)
+  .addNode(processNode.name, processNode.execute)
+  .addEdge(START, processNode.name)
+  .addEdge(processNode.name, END);
+
+// 4. Configure the orchestrator
+const orchestratorConfig: OrchestratorConfig<typeof MyWorkflowState> = {
+  toolId: 'my-orchestrator',
+  title: 'My Orchestrator',
+  description: 'Orchestrates my workflow',
+  workflow, // Pass uncompiled StateGraph
+  // context defaults to { environment: 'production' }
+};
+
+// 5. Create and register the orchestrator
+const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+const orchestrator = new OrchestratorTool(server, orchestratorConfig);
+orchestrator.register({ readOnlyHint: false });
+```
+
+## Core Concepts
+
+### The `.magen` Directory
+
+By convention, workflow state and logs are stored in a well-known directory (`.magen/`):
+
+- **Workflow state**: `~/.magen/workflow-state.json`
+- **Workflow logs**: `~/.magen/workflow_logs.json`
+
+This can be overridden via the `PROJECT_PATH` environment variable:
+
+```bash
+export PROJECT_PATH=/path/to/project
+# State stored in: /path/to/project/.magen/
+```
+
+### Environment Contexts
+
+The orchestrator supports two execution environments:
+
+- **`production`** (default): Uses `JsonCheckpointSaver` with `.magen/` directory persistence
+- **`test`**: Uses `MemorySaver` for in-memory checkpointing (no file I/O)
+
+```typescript
+const config: OrchestratorConfig<typeof MyWorkflowState> = {
+  // ...
+  context: { environment: 'test' }, // For testing
+};
+```
+
+### Workflow State Management
+
+Workflows maintain session continuity across stateless MCP tool invocations using lightweight state data (`thread_id`). The orchestrator handles:
+
+- Starting new workflow sessions
+- Resuming in-progress workflows
+- Persisting state between invocations
+- Managing LangGraph checkpoints
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Your MCP Server                                             │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │ Domain Logic                                         │   │
+│  │ - StateGraph (workflow structure)                    │   │
+│  │ - Nodes (business operations)                        │   │
+│  │ - Tools (domain capabilities)                        │   │
+│  └──────────────────────────────────────────────────────┘   │
+│                          │                                  │
+│                          │ depends on                       │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │ @salesforce/magen-mcp-workflow                       │   │
+│  │ - OrchestratorTool                                   │   │
+│  │ - Base Classes                                       │   │
+│  │ - Checkpointing                                      │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Design Philosophy
+
+This is a **framework, not a library**. Every API is designed with consumers in mind:
+
+1. **Configurability**: Consumers configure the workflow engine with their workflows
+2. **Genericity**: All components are generic over state types
+3. **Encapsulation**: Implementation details are hidden
+4. **Convention over Configuration**: Sensible defaults with escape hatches
+5. **Testability**: Dependency injection patterns throughout
+
+## Documentation
+
+For comprehensive documentation, examples, and API references, see the [documentation directory](../../docs/README.md).
+
+## Contributing
+
+This package is part of the `mobile-mcp-tools` monorepo. See the [main README](../../README.md) for contribution guidelines.
+
+## License
+
+MIT

package/dist/checkpointing/index.d.ts

@@ -0,0 +1,3 @@
+export { JsonCheckpointSaver } from './jsonCheckpointer.js';
+export { WorkflowStatePersistence } from './statePersistence.js';
+export { WorkflowStateManager, type WorkflowStateManagerConfig, type WorkflowEnvironment, } from './workflowStateManager.js';

package/dist/checkpointing/index.js

@@ -0,0 +1,10 @@
+/*
+ * 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
+ */
+export { JsonCheckpointSaver } from './jsonCheckpointer.js';
+export { WorkflowStatePersistence } from './statePersistence.js';
+export { WorkflowStateManager, } from './workflowStateManager.js';
+//# sourceMappingURL=index.js.map

package/dist/checkpointing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkpointing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EACL,oBAAoB,GAGrB,MAAM,2BAA2B,CAAC"}

package/dist/checkpointing/jsonCheckpointer.d.ts

@@ -0,0 +1,19 @@
+import { RunnableConfig } from '@langchain/core/runnables';
+import { BaseCheckpointSaver, Checkpoint, CheckpointMetadata, CheckpointTuple } from '@langchain/langgraph';
+import { CheckpointListOptions, PendingWrite } from '@langchain/langgraph-checkpoint';
+export declare class JsonCheckpointSaver extends BaseCheckpointSaver {
+    private state;
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Exports the entire state of the checkpointer as a single JSON string.
+     */
+    exportState(): Promise<string>;
+    /**
+     * Imports and overwrites the entire state of the checkpointer.
+     */
+    importState(jsonState: string): Promise<void>;
+}

package/dist/checkpointing/jsonCheckpointer.js

@@ -0,0 +1,164 @@
+/*
+ * 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 { BaseCheckpointSaver, } from '@langchain/langgraph';
+import { WRITES_IDX_MAP, } from '@langchain/langgraph-checkpoint';
+function createCheckpointKey(config) {
+    const threadId = config.configurable?.thread_id;
+    const checkpointId = config.configurable?.checkpoint_id;
+    if (!threadId || !checkpointId) {
+        throw new Error(`Invalid config, missing thread_id or checkpoint_id: ${JSON.stringify(config.configurable)}`);
+    }
+    return `${threadId}:${checkpointId}`;
+}
+export class JsonCheckpointSaver extends BaseCheckpointSaver {
+    state = { version: 1, storage: {}, writes: {} };
+    async getTuple(config) {
+        const threadId = config.configurable?.thread_id;
+        if (!threadId) {
+            throw new Error('thread_id not found in config');
+        }
+        const checkpoints = this.state.storage[threadId];
+        if (!checkpoints || checkpoints.length === 0) {
+            return undefined;
+        }
+        // This logic correctly gets the latest checkpoint.
+        // In this implementation, the latest is always at index 0.
+        const latest = checkpoints[0];
+        const checkpointPromise = this.serde.loadsTyped('json', Buffer.from(latest.checkpoint, 'base64'));
+        const metadataPromise = this.serde.loadsTyped('json', Buffer.from(latest.metadata, 'base64'));
+        const [checkpoint, metadata] = await Promise.all([checkpointPromise, metadataPromise]);
+        // Rehydrate pending writes associated with this checkpoint
+        const pendingWrites = [];
+        const checkpointKey = createCheckpointKey({
+            configurable: { thread_id: threadId, checkpoint_id: checkpoint.id },
+        });
+        const savedWrites = this.state.writes[checkpointKey];
+        if (savedWrites) {
+            const parsedWrites = JSON.parse(savedWrites);
+            for (const [taskId, channel, valueBase64] of Object.values(parsedWrites)) {
+                pendingWrites.push([
+                    taskId,
+                    channel,
+                    await this.serde.loadsTyped('json', Buffer.from(valueBase64, 'base64')),
+                ]);
+            }
+        }
+        const checkpointTuple = {
+            config,
+            checkpoint,
+            metadata,
+            pendingWrites,
+        };
+        if (latest.parentId) {
+            checkpointTuple.parentConfig = {
+                configurable: { thread_id: threadId, checkpoint_id: latest.parentId },
+            };
+        }
+        return checkpointTuple;
+    }
+    async put(config, checkpoint, metadata) {
+        const threadId = config.configurable?.thread_id;
+        if (!threadId) {
+            throw new Error('thread_id not found in config');
+        }
+        if (!this.state.storage[threadId]) {
+            this.state.storage[threadId] = [];
+        }
+        const checkpointPromise = this.serde.dumpsTyped(checkpoint);
+        const metadataPromise = this.serde.dumpsTyped(metadata);
+        const [[, checkpointBytes], [, metadataBytes]] = await Promise.all([
+            checkpointPromise,
+            metadataPromise,
+        ]);
+        const parentId = config.configurable?.checkpoint_id;
+        // unshift() adds to the beginning, ensuring the latest is always at index 0.
+        this.state.storage[threadId].unshift({
+            checkpoint: Buffer.from(checkpointBytes).toString('base64'),
+            metadata: Buffer.from(metadataBytes).toString('base64'),
+            parentId: parentId,
+        });
+        return {
+            configurable: { thread_id: threadId, checkpoint_id: checkpoint.id },
+        };
+    }
+    async putWrites(config, writes, taskId) {
+        const key = createCheckpointKey(config);
+        const existingWritesString = this.state.writes[key];
+        const existingWrites = existingWritesString
+            ? JSON.parse(existingWritesString)
+            : {};
+        for (const [index, [channel, value]] of writes.entries()) {
+            const [, serializedValue] = await this.serde.dumpsTyped(value);
+            const valueBase64 = Buffer.from(serializedValue).toString('base64');
+            const innerKey = `${taskId}:${WRITES_IDX_MAP[channel] ?? index}`;
+            existingWrites[innerKey] = [taskId, channel, valueBase64];
+        }
+        this.state.writes[key] = JSON.stringify(existingWrites);
+    }
+    async *list(config, options) {
+        const threadId = config.configurable?.thread_id;
+        if (!threadId) {
+            return;
+        }
+        const checkpoints = this.state.storage[threadId] ?? [];
+        let count = 0;
+        for (const saved of checkpoints) {
+            const metadataPromise = this.serde.loadsTyped('json', Buffer.from(saved.metadata, 'base64'));
+            const metadata = (await metadataPromise);
+            // Apply filter if provided
+            if (options?.filter &&
+                !Object.entries(options.filter).every(([key, value]) => metadata[key] === value)) {
+                continue;
+            }
+            // Apply limit if provided
+            if (options?.limit && count >= options.limit) {
+                return;
+            }
+            count++;
+            const checkpoint = (await this.serde.loadsTyped('json', Buffer.from(saved.checkpoint, 'base64')));
+            const tuple = {
+                config: {
+                    configurable: { thread_id: threadId, checkpoint_id: checkpoint.id },
+                },
+                checkpoint,
+                metadata,
+            };
+            if (saved.parentId) {
+                tuple.parentConfig = {
+                    configurable: { thread_id: threadId, checkpoint_id: saved.parentId },
+                };
+            }
+            yield tuple;
+        }
+    }
+    async deleteThread(threadId) {
+        delete this.state.storage[threadId];
+        for (const key of Object.keys(this.state.writes)) {
+            if (key.startsWith(`${threadId}:`)) {
+                delete this.state.writes[key];
+            }
+        }
+    }
+    /**
+     * Exports the entire state of the checkpointer as a single JSON string.
+     */
+    async exportState() {
+        return JSON.stringify(this.state);
+    }
+    /**
+     * Imports and overwrites the entire state of the checkpointer.
+     */
+    async importState(jsonState) {
+        const parsedState = JSON.parse(jsonState);
+        // Basic check for future migration logic
+        if (!parsedState.version) {
+            parsedState.version = 1;
+        }
+        this.state = parsedState;
+    }
+}
+//# sourceMappingURL=jsonCheckpointer.js.map

package/dist/checkpointing/jsonCheckpointer.js.map

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

package/dist/checkpointing/statePersistence.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Utility class for persisting and recalling LangGraph checkpointer state
+ */
+export declare class WorkflowStatePersistence {
+    private readonly storePath;
+    private readonly logger;
+    constructor(storePath: string);
+    /**
+     * Reads the serialized state from disk if it exists
+     * @returns The serialized state string, or undefined if the file doesn't exist or is invalid
+     */
+    readState(): Promise<string | undefined>;
+    /**
+     * Writes the serialized state to disk
+     * @param serializedState The state to persist
+     */
+    writeState(serializedState: string): Promise<void>;
+    /**
+     * Deletes the persisted state file
+     */
+    clearState(): Promise<void>;
+    /**
+     * Checks if a persisted state file exists
+     */
+    stateExists(): Promise<boolean>;
+}

package/dist/checkpointing/statePersistence.js

@@ -0,0 +1,117 @@
+/*
+ * 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 * as fs from 'fs/promises';
+import * as path from 'path';
+import { createComponentLogger } from '../logging/logger.js';
+/**
+ * Utility class for persisting and recalling LangGraph checkpointer state
+ */
+export class WorkflowStatePersistence {
+    storePath;
+    logger;
+    constructor(storePath) {
+        this.storePath = storePath;
+        this.logger = createComponentLogger('WorkflowStatePersistence');
+    }
+    /**
+     * Reads the serialized state from disk if it exists
+     * @returns The serialized state string, or undefined if the file doesn't exist or is invalid
+     */
+    async readState() {
+        try {
+            // Check if the file exists
+            await fs.access(this.storePath);
+            this.logger.info(`Reading checkpointer state from: ${this.storePath}`);
+            // Read the file content
+            const content = await fs.readFile(this.storePath, 'utf-8');
+            // Validate that it's valid JSON
+            JSON.parse(content);
+            this.logger.debug('Successfully read and validated checkpointer state', {
+                stateSize: content.length,
+                path: this.storePath,
+            });
+            return content;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.logger.info(`Checkpointer state file not found: ${this.storePath}. Starting with fresh state.`);
+                return undefined;
+            }
+            else if (error instanceof SyntaxError) {
+                this.logger.warn(`Invalid JSON in state file: ${this.storePath}. Starting with fresh state.`, error);
+                return undefined;
+            }
+            else {
+                this.logger.error(`Failed to read checkpointer state from: ${this.storePath}`, error);
+                return undefined;
+            }
+        }
+    }
+    /**
+     * Writes the serialized state to disk
+     * @param serializedState The state to persist
+     */
+    async writeState(serializedState) {
+        try {
+            // Ensure the directory exists
+            const storeDir = path.dirname(this.storePath);
+            await fs.mkdir(storeDir, { recursive: true });
+            // Validate that the state is valid JSON before writing
+            JSON.parse(serializedState);
+            this.logger.info(`Saving checkpointer state to: ${this.storePath}`);
+            // Write the state to a temporary file first, then rename for atomicity
+            const tempPath = `${this.storePath}.tmp`;
+            await fs.writeFile(tempPath, serializedState, 'utf-8');
+            await fs.rename(tempPath, this.storePath);
+            this.logger.debug('Successfully saved checkpointer state', {
+                stateSize: serializedState.length,
+                path: this.storePath,
+            });
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                this.logger.error(`Invalid JSON state provided for persistence. State not saved.`, error);
+                throw new Error(`Invalid serialized state: ${error.message}`);
+            }
+            else {
+                this.logger.error(`Failed to save checkpointer state to: ${this.storePath}`, error);
+                throw error;
+            }
+        }
+    }
+    /**
+     * Deletes the persisted state file
+     */
+    async clearState() {
+        try {
+            await fs.unlink(this.storePath);
+            this.logger.info(`Cleared checkpointer state file: ${this.storePath}`);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.logger.debug(`State file already doesn't exist: ${this.storePath}`);
+            }
+            else {
+                this.logger.error(`Failed to clear state file: ${this.storePath}`, error);
+                throw error;
+            }
+        }
+    }
+    /**
+     * Checks if a persisted state file exists
+     */
+    async stateExists() {
+        try {
+            const stat = await fs.stat(this.storePath);
+            return stat.isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=statePersistence.js.map

package/dist/checkpointing/statePersistence.js.map

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

package/dist/checkpointing/workflowStateManager.d.ts

@@ -0,0 +1,99 @@
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { Logger } from '../logging/logger.js';
+import { FileSystemOperations } from '../common/fileSystem.js';
+/**
+ * Workflow execution environment
+ */
+export type WorkflowEnvironment = 'production' | 'test';
+/**
+ * Configuration for WorkflowStateManager
+ */
+export interface WorkflowStateManagerConfig {
+    /**
+     * Execution environment - determines checkpointing strategy
+     * - 'production': Uses JsonCheckpointSaver with .magen/ directory persistence
+     * - 'test': Uses MemorySaver for isolated, in-memory state (no file I/O)
+     * Default: 'production'
+     */
+    environment?: WorkflowEnvironment;
+    /**
+     * Optional project path for well-known directory (.magen/)
+     * Used to customize the location of workflow state files
+     * Defaults to os.homedir() if not specified
+     */
+    projectPath?: string;
+    /**
+     * Optional filesystem operations implementation for dependency injection
+     * Defaults to NodeFileSystemOperations for production use
+     */
+    fileSystemOperations?: FileSystemOperations;
+    /**
+     * Optional logger for state management operations
+     */
+    logger?: Logger;
+}
+/**
+ * Manages workflow state persistence and checkpointer lifecycle
+ *
+ * This service encapsulates all workflow state management responsibilities:
+ * - Creating and configuring checkpointers (MemorySaver vs JsonCheckpointSaver)
+ * - Loading existing state from disk
+ * - Saving state to disk
+ * - Managing well-known directory paths
+ *
+ * This separation allows the orchestrator to focus on workflow execution logic
+ * while delegating all state management concerns to this service.
+ */
+export declare class WorkflowStateManager {
+    private readonly logger;
+    private readonly environment;
+    private readonly wellKnownDirectoryManager;
+    private readonly fileSystemOperations;
+    constructor(config?: WorkflowStateManagerConfig);
+    /**
+     * Creates a checkpointer configured for the current environment
+     *
+     * For 'test' environment:
+     * - Returns MemorySaver (in-memory, no file I/O)
+     *
+     * For 'production' environment:
+     * - Returns JsonCheckpointSaver
+     * - Automatically loads existing state from disk if available
+     * - Creates fresh checkpointer if no state exists
+     *
+     * @returns A configured checkpointer ready for use
+     */
+    createCheckpointer(): Promise<BaseCheckpointSaver>;
+    /**
+     * Saves checkpointer state to disk (production mode only)
+     *
+     * Only applies to JsonCheckpointSaver. MemorySaver (used in test mode)
+     * intentionally does not persist state.
+     *
+     * @param checkpointer - The checkpointer to save
+     * @throws Error if test environment unexpectedly has JsonCheckpointSaver
+     */
+    saveCheckpointerState(checkpointer: BaseCheckpointSaver): Promise<void>;
+    /**
+     * Reads the serialized state from disk if it exists
+     * @returns The serialized state string, or undefined if the file doesn't exist or is invalid
+     */
+    private readState;
+    /**
+     * Writes the serialized state to disk
+     * @param serializedState The state to persist
+     */
+    private writeState;
+    /**
+     * Deletes the persisted state file
+     */
+    clearState(): Promise<void>;
+    /**
+     * Checks if a persisted state file exists
+     */
+    stateExists(): Promise<boolean>;
+    /**
+     * Gets the file path for workflow state storage
+     */
+    private getStatePath;
+}