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.