mcp-workflow-server

MCP Workflow Server

A comprehensive MCP (Model Context Protocol) server ecosystem implementing a structured AI workflow with 7 specialized functions for enhanced development processes.

Overview

The MCP Workflow Server provides a complete workflow system that transforms user prompts into actionable implementation plans through a systematic 7-step process:

• Improve Prompt - Enhances user prompts for clarity and actionability
• Research - Conducts comprehensive research on topics and technologies
• Cognitive Analysis - Performs deep analysis and pattern recognition
• Planning - Creates detailed implementation plans with phases and tasks
• Task Generation - Converts plans into specific, executable tasks
• Implementation - Executes tasks with progress tracking and validation
• Problem Solving - Resolves issues without compromising existing functionality

🎯 Features

🚀 Complete AI Workflow System (v2.0.0)

• 100% Guide Integration: All 13 maxims, 3 heuristics, and advanced features implemented
• Interactive Validation: Each workflow stage requires user validation before proceeding
• Domain-Specific Analysis: Specialized analysis for macro recording, web development, API development
• Advanced Features: Artifact management, context management, nested workflows
• MCP Protocol Compliant: Works seamlessly with any MCP-compatible client

📋 All 13 Maxims Implemented:

• ✅ PrimedCognition - Creative, structured internal thinking
• ✅ AppropriateComplexity - Minimum necessary complexity with robustness
• ✅ FullyUnleashedPotential - Thorough analysis without brevity restrictions
• ✅ ClearCommunication - Comprehensive explanation with readability
• ✅ PurposefulToolLeveraging - Strategic tool use with clear justification
• ✅ ToolAssistedDiagnosis - Autonomous issue diagnosis and resolution
• ✅ Autonomy - Prefer autonomous execution over user querying
• ✅ PurityAndCleanliness - Remove obsolete elements, no backwards compatibility
• ✅ Perceptivity - Change impact awareness (security, performance, etc.)
• ✅ Impenetrability - Security vulnerability mitigation
• ✅ Resilience - Error handling and robustness implementation
• ✅ Consistency - Reuse existing patterns and elements
• ✅ OperationalFlexibility - Handle user input during workflow operation

🎯 All 3 Heuristics Implemented:

• ✅ SOLID Principles - Maintainable, modular code architecture
• ✅ SMART Goals - Specific, Measurable, Assignable, Realistic, Time-related
• ✅ Responsive UI - Resilient, user-friendly workflow experience

🔧 Advanced Features:

• ✅ Artifact Management - Track all created/modified elements
• ✅ Context Management - Handle ProvCTX and ObtaCTX
• ✅ Nested Workflows - Sub-investigations for verification
• ✅ Autonomous Problem Solving - OOTBProblemSolving with creative alternatives
• ✅ Hammering Detection - Strategy changes when stuck
• ✅ ClarificationProtocol - Only when essential input genuinely needed

🛠️ Technical Features:

• Unified MCP Server: All workflow functions in a single, well-integrated package
• TypeScript First: Built with TypeScript for type safety and modern development practices
• Comprehensive Testing: Full test coverage with Vitest
• Quality Focused: ESLint, Prettier, and strict quality standards
• Modern Tooling: Uses tsup for building, semantic versioning, and automated workflows
• Individual Guidelines: Each function has specialized AI agent guidelines
• Flexible Configuration: Configurable workflow steps and error handling

Installation

npm install mcp-workflow-server

Quick Start

As an MCP Server

# Run the server directly
npx mcp-workflow-server

# Or install globally
npm install -g mcp-workflow-server
mcp-workflow-server

MCP Client Configuration

Add this configuration to your MCP client (e.g., Claude Desktop, Cline, etc.):

{
  "mcpServers": {
    "mcp-workflow-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-workflow-server@latest"
      ]
    }
  }
}

This will automatically install and run the latest version of the MCP Workflow Server when your MCP client starts.

Programmatic Usage

import { MCPWorkflowServer, WorkflowOrchestrator } from 'mcp-workflow-server';

// Create and start MCP server
const server = new MCPWorkflowServer();
await server.start();

// Or use the orchestrator directly
const orchestrator = new WorkflowOrchestrator({
  enabledFunctions: ['improve-prompt', 'research', 'cognitive', 'planner'],
  autoAdvance: true,
  errorHandling: 'retry',
  maxRetries: 3,
});

const result = await orchestrator.executeWorkflow('Create a TypeScript MCP server');

🔧 MCP Tools

The server provides the following comprehensive MCP tools with 100% guide integration:

execute-workflow

Execute the complete 7-step workflow process.

Input:

• userPrompt (string): The user prompt to process
• config (optional): Workflow configuration
• startStep (optional): Step to start from

Output:

• Complete workflow results with session ID and step results

execute-step

Execute a single workflow step.

Input:

• stepName: The workflow step to execute
• input: Input data for the step
• context (optional): Existing workflow context

get-workflow-status

Get the current status of a workflow execution.

Input:

• sessionId: The workflow session ID

configure-workflow

Update workflow configuration settings.

Input:

• config: New workflow configuration

Workflow Functions

1. Improve Prompt

Enhances user prompts for maximum clarity, specificity, and actionability.

Capabilities:

• Analyzes prompt quality metrics (clarity, specificity, actionability)
• Identifies vague language and suggests improvements
• Extracts requirements, constraints, and goals
• Generates research topics for subsequent phases

2. Research

Conducts comprehensive research on identified topics and technologies.

Capabilities:

• Researches current tools and best practices (2024 focus)
• Analyzes code structures and architectural patterns
• Identifies technology landscape and trends
• Provides tool recommendations with rationale

3. Cognitive Analysis

Performs deep cognitive analysis and pattern recognition.

Capabilities:

• Synthesizes research findings into actionable insights
• Recognizes architectural and design patterns
• Assesses project complexity and feasibility
• Generates strategic recommendations

4. Planning

Creates detailed implementation plans with phases and tasks.

Capabilities:

• Breaks down projects into logical phases
• Defines tasks with clear acceptance criteria
• Identifies dependencies and critical paths
• Assesses resource requirements and timelines

5. Task Generation

Converts implementation plans into specific, executable tasks.

Capabilities:

• Generates detailed tasks with implementation steps
• Creates validation criteria and quality gates
• Determines execution order and dependencies
• Provides task templates and guidelines

6. Implementation

Executes generated tasks with systematic progress tracking.

Capabilities:

• Executes tasks according to dependencies
• Validates completion against acceptance criteria
• Tracks progress and identifies issues
• Provides comprehensive execution reporting

7. Problem Solving

Resolves implementation issues without compromising functionality.

Capabilities:

• Investigates problems with root cause analysis
• Develops constructive solutions (no shortcuts/removals)
• Implements solutions with thorough validation
• Creates prevention strategies for future issues

Configuration

interface WorkflowConfig {
  enabledFunctions: string[];     // Functions to include in workflow
  autoAdvance: boolean;           // Automatically proceed to next step
  errorHandling: 'stop' | 'retry' | 'skip';  // Error handling strategy
  maxRetries: number;             // Maximum retry attempts
}

Development

Setup

git clone <repository>
cd mcp-workflow-server
npm install

Scripts

npm run build          # Build the project
npm run dev           # Run in development mode
npm test              # Run tests
npm run test:coverage # Run tests with coverage
npm run lint          # Lint code
npm run format        # Format code

Project Structure

src/
├── server.ts              # Main MCP server
├── functions/             # Individual workflow functions
│   ├── improve-prompt.ts
│   ├── research.ts
│   ├── cognitive.ts
│   ├── planner.ts
│   ├── task-generation.ts
│   ├── implementation.ts
│   └── problem-solver.ts
├── shared/               # Shared utilities and types
│   ├── types.ts
│   ├── utils.ts
│   └── workflow.ts
└── guidelines/           # AI agent guidelines
    ├── improve-prompt-guide.ts
    ├── research-guide.ts
    ├── cognitive-guide.ts
    ├── planner-guide.ts
    ├── implementation-guide.ts
    └── problem-solver-guide.ts

Guidelines and AI Agents

Each workflow function includes specialized AI agent guidelines that define:

• Identity and personality traits
• Core functions and processes
• Quality standards and heuristics
• Output formats and requirements

These guidelines ensure consistent, high-quality outputs from each workflow step.

Contributing

• Fork the repository
• Create a feature branch
• Make your changes with tests
• Ensure all tests pass and code is formatted
• Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues, questions, or contributions, please visit the GitHub repository or contact the maintainers.