mcp-workflow

MCP Workflow is a library that extends the MCP SDK to enable workflows built from discrete, lifecycle-aware activities. Each activity wraps a unit of work with input/output validation, and each workflow orchestrates those activities in a sequence with automatic state management, memory sharing, and lifecycle hooks. You attach a McpWorkflow instance to your MCP server to automatically register four tools for external clients: start, continue, pause, and cancel. This makes it easy for MCP clients (like Gemini) to drive complex processes that can branch, retry failed steps, and resume after interruptions. The framework supports typed input/output via Zod schemas, persistent storage (with a pluggable store), and robust error handling with retry and optional steps.

To use it, define your activities using McpActivityTool, then assemble a McpWorkflow by chaining steps. Each step can specify input mappings, branching logic, and conditions for execution. Once you attach the workflow to your MCP server, clients can initiate a workflow with the start tool, let it progress with continue calls, pause if needed, and cancel to stop execution. Activities emit lifecycle events (onSuccess, onFailure, onComplete) for observable hooks and side effects. The design emphasizes type safety and predictable state transitions, making it suitable for complex, multi-step processes such as data processing pipelines, user onboarding flows, or multi-service orchestrations.

Prerequisites:

• Node.js (recommended latest LTS) and npm installed
• A project using MCP SDK already set up (or install the MCP SDK where you plan to host the workflow)

Install the MCP Workflow package:

npm install @p0u4a/mcp-workflow

Example setup (TypeScript):

import { McpWorkflow } from "@p0u4a/mcp-workflow";
import { McpActivityTool } from "@p0u4a/mcp-workflow";
import { z } from "zod";

// Define an activity
const addActivity = new McpActivityTool("add", "Adds two numbers", {
  inputSchema: { a: z.number(), b: z.number() },
  outputSchema: { result: z.number() },
  callbacks: {
    run: async (context) => {
      const { a, b } = context.input;
      return { success: true, data: { result: a + b } };
    }
  }
});

// Define a workflow and attach steps
const calculatorWorkflow = new McpWorkflow("calculator", "A calculator workflow", {
  onSuccess: async (memory, sessionId) => {
    console.log("Workflow completed", Object.fromEntries(memory));
  }
}).step(addActivity);

// Attach to MCP server (example server code provided by MCP SDK)
// const server = new McpServer({ name: "my-workflow-server", version: "1.0.0" }, { capabilities: { tools: {} } });
// calculatorWorkflow.attachToServer(server);

If you are integrating as a library into an existing Node project, include the relevant import paths and attach the workflow to your MCP server instance as shown in the example above.

Tips and common considerations:

• Storage: The default in-memory store is great for development and testing. For production, configure a persistent WorkflowStore (e.g., Redis, PostgreSQL) to ensure workflows survive restarts.
• Validation: Use Zod schemas for strict input/output validation to catch errors early.
• Error handling: Leverage built-in retry logic and optional steps to design resilient workflows.
• Branching and conditions: Define input mappings and conditional steps to support dynamic workflow paths based on runtime data.
• Lifecycle hooks: Use onSuccess, onFailure, and onComplete to integrate logging, side effects, or notifications at each activity boundary.
• Observability: Emit memory/trace data at key points to aid debugging and auditing of long-running workflows.
• MCP integration: After attaching to your server, the workflow exposes standard tools named {workflowName}_start, {workflowName}_continue, {workflowName}_pause, and {workflowName}_cancel for client control.