mcp-workflow-server/README.md

Complete AI workflow system with 100% guide integration - all 13 maxims, 3 heuristics, operational flexibility, artifact management, and nested workflows

# 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:

1. **Improve Prompt** - Enhances user prompts for clarity and actionability
2. **Research** - Conducts comprehensive research on topics and technologies
3. **Cognitive Analysis** - Performs deep analysis and pattern recognition
4. **Planning** - Creates detailed implementation plans with phases and tasks
5. **Task Generation** - Converts plans into specific, executable tasks
6. **Implementation** - Executes tasks with progress tracking and validation
7. **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:**
1. ✅ **PrimedCognition** - Creative, structured internal thinking
2. ✅ **AppropriateComplexity** - Minimum necessary complexity with robustness
3. ✅ **FullyUnleashedPotential** - Thorough analysis without brevity restrictions
4. ✅ **ClearCommunication** - Comprehensive explanation with readability
5. ✅ **PurposefulToolLeveraging** - Strategic tool use with clear justification
6. ✅ **ToolAssistedDiagnosis** - Autonomous issue diagnosis and resolution
7. ✅ **Autonomy** - Prefer autonomous execution over user querying
8. ✅ **PurityAndCleanliness** - Remove obsolete elements, no backwards compatibility
9. ✅ **Perceptivity** - Change impact awareness (security, performance, etc.)
10. ✅ **Impenetrability** - Security vulnerability mitigation
11. ✅ **Resilience** - Error handling and robustness implementation
12. ✅ **Consistency** - Reuse existing patterns and elements
13. ✅ **OperationalFlexibility** - Handle user input during workflow operation

### **🎯 All 3 Heuristics Implemented:**
1. ✅ **SOLID Principles** - Maintainable, modular code architecture
2. ✅ **SMART Goals** - Specific, Measurable, Assignable, Realistic, Time-related
3. ✅ **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

```bash
npm install mcp-workflow-server
```

## Quick Start

### As an MCP Server

```bash
# 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.):

```json
{
  "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

```typescript
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

```typescript
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

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

### Scripts

```bash
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

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure all tests pass and code is formatted
5. 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.