MCP Workflow

An extension of the Model Context Protocol (MCP) SDK to enable MCP servers to function as workflow engines. Build complex, multi-step workflows with activities that have lifecycle hooks, automatic state management, and seamless integration with MCP tools.

Installation

npm i @p0u4a/mcp-workflow

Features

• Activity Tools: Wrap individual units of work with lifecycle hooks (onSuccess, onFailure, onComplete)
• Workflow Orchestration: Chain activities together into sequential workflows
• State Management: Automatic session management with shared memory across workflow steps
• Validation: Built-in input/output validation using Zod schemas
• Error Handling: Robust error handling with retry logic and optional steps
• Conditional Execution: Skip steps based on runtime conditions
• Branching Workflows: Activities can suggest multiple next steps, allowing for dynamic workflow paths
• Pause and Resume: Workflows can be paused and resumed at any step
• Cancel: Workflows can be cancelled at any point, stopping further execution
• Persistent Storage: Pluggable storage layer for session persistence (default is in-memory)
• Typesafety: Activities and workflows are strongly typed
• MCP Integration: Seamlessly register workflows as MCP tools

Architecture

High-Level Overview

The mcp-workflow library provides a structured way to define and execute complex, multi-step processes on top of the Model Context Protocol. It introduces the concepts of “Workflows” and “Activities” to orchestrate a series of tool calls, manage state, and handle errors.

┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                           │
│                     (e.g., Gemini)                          │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ JSON-RPC
                         │
┌────────────────────────▼────────────────────────────────────┐
│                     MCP Server                              │
│                (with mcp-workflow)                          │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Workflow Tools                          │   │
│  │  • {workflow}_start                                  │   │
│  │  • {workflow}_continue                               │   │
│  └────────────────────┬─────────────────────────────────┘   │
│                       │                                     │
│  ┌────────────────────▼─────────────────────────────────┐   │
│  │           McpWorkflow Instance                       │   │
│  │  • Orchestrates activity execution                   │   │
│  │  • Manages workflow state                            │   │