MCPuppet

A proof of concept MCP Workflow Orchestrator that demonstrates workflow monitoring, audit logging, and policy-based execution ordering for AI applications using MCP tools.

Features

• Workflow Orchestration: Acts as MCP server to AI applications and MCP client to downstream servers
• Policy Enforcement: Sequential dependencies, parallel restrictions, conditional execution, and approval gates
• Comprehensive Audit Logging: Complete audit trail of all tool calls and workflow activities
• Real-time Monitoring: Live workflow status tracking and progress monitoring
• Template-based Workflows: Predefined workflow patterns for common operations
• Policy Violation Detection: Automatic blocking of rule violations with detailed reporting

Architecture

AI Application → MCPuppet → Multiple MCP Servers → Tool Execution
                    ↓
              Audit Trail + Policy Enforcement

Prerequisites

• Python 3.9+
• Virtual environment (recommended)

Installation

1. Clone and navigate to the project directory
2. Create and activate virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

Claude Desktop Integration

To use this as an MCP server with Claude Desktop:

1. Test the MCP server:

   source venv/bin/activate
   python test_mcp_server.py
   

2. Configure Claude Desktop by adding this to your claude_desktop_config.json:

   {
     "mcpServers": {
       "workflow-orchestrator": {
         "command": "/path/to/your/project/venv/bin/python",
         "args": ["/path/to/your/project/mcp_server.py"]
       }
     }
   }
   

3. Restart Claude Desktop to load the MCP server

See CLAUDE_SETUP.md for detailed setup instructions.

Quick Start

Run All Demos

python main.py demo

Run Specific Demos

python main.py demo-success    # Successful customer onboarding workflow
python main.py demo-violation  # Policy violation enforcement demo
python main.py demo-approval   # Financial processing with approval gates
python main.py demo-monitoring # Real-time workflow monitoring
python main.py demo-audit      # Comprehensive audit trail

Interactive Mode

python main.py interactive

System Status

python main.py status

Demo Scenarios

1. Successful Workflow

Demonstrates a complete customer onboarding workflow:

• Data validation → Processing → Backup → Notification
• Shows proper dependency ordering and successful completion

2. Policy Violation

Shows what happens when workflow rules are violated:

• Attempts to process data before validation
• Demonstrates automatic blocking and audit logging

3. Approval Workflow

Financial processing workflow with manual approval gates:

• Validation → Approval → Processing → Backup & Notification
• Shows approval request/response cycle

4. Real-time Monitoring

Live dashboard showing workflow progress:

• Progress bars and status updates
• Real-time metrics and completion tracking

5. Comprehensive Audit

Complete audit trail across all sessions:

• Policy violations summary
• Performance metrics
• Compliance reporting

Configuration

Edit config.json to customize:

• Downstream server URLs
• Policy rules (dependencies, restrictions, conditions)
• Workflow templates
• Audit settings

Project Structure

MCPuppet/
├── main.py                    # Main entry point
├── orchestrator.py            # Core workflow orchestrator
├── workflow_policies.py       # Policy engine
├── audit_monitor.py          # Audit logging and monitoring
├── workflow_templates.py     # Predefined workflow templates
├── demo_workflows.py         # Demo scenarios
├── config.json              # Configuration
├── requirements.txt         # Dependencies
├── downstream_servers/      # Simulated MCP servers
│   ├── validation_server.py
│   ├── processing_server.py
│   ├── backup_server.py
│   ├── notification_server.py
│   └── approval_server.py
└── audit_logs/              # Audit output directory

Key Components

MCPuppet Core (orchestrator.py)

• Acts as MCP server to AI applications
• Acts as MCP client to downstream servers
• Enforces workflow policies and call ordering
• Provides comprehensive audit logging
• Tracks workflow state and dependencies

Workflow Policy Engine (workflow_policies.py)

• Sequential Dependencies: Tool A must be called before Tool B
• Parallel Restrictions: Some tools cannot run simultaneously
• Conditional Execution: Tool C only available after Tool A succeeds
• Approval Gates: Some tools require manual approval before execution

Audit Monitor (audit_monitor.py)

• Comprehensive logging of all tool calls
• Workflow compliance tracking
• Performance metrics (duration, success rates)
• Policy violation detection and reporting
• Real-time workflow status

Workflow Templates (workflow_templates.py)

• Predefined sequences for common operations
• Template-based workflow execution
• Progress tracking and validation

Monitoring Dashboard

The system provides a real-time monitoring dashboard showing:

┌─ Workflow Status Dashboard ─────────────────────┐
│ Active Workflows: 3                             │
│ Completed Today: 47                             │ 
│ Policy Violations: 2                            │
│                                                 │
│ Current Workflow: customer_onboarding          │
│ Progress: ████████░░ 80% (4/5 steps)           │
│ Duration: 3.2s                                  │
│ Next Step: send_notification                    │
└─────────────────────────────────────────────────┘

Security & Compliance

• Complete audit trail for all MCP tool interactions
• Policy-based access control and workflow enforcement
• Comprehensive logging with structured output
• Compliance reporting and violation tracking
• Approval workflows for sensitive operations

Testing

The system includes comprehensive demos that test:

• Workflow orchestration and execution
• Policy enforcement and violation detection
• Audit logging and compliance reporting
• Real-time monitoring and status tracking
• Template-based workflow management
• Approval gate functionality

Example Usage

# Create MCPuppet orchestrator
orchestrator = MCPOrchestrator()

# Execute workflow step
result = await orchestrator.call_tool(
    session_id="customer_123",
    tool_name="validate_data",
    arguments={"data": {"name": "John Doe", "email": "john@example.com"}}
)

# Check workflow status
status = orchestrator.get_session_status("customer_123")

Contributing

This is a proof of concept demonstrating MCPuppet's workflow orchestration capabilities. The focus is on showing the value proposition of comprehensive workflow monitoring and audit capabilities for AI tool usage.

License

This project is a demonstration/proof of concept for MCPuppet workflow orchestration.

---

Key Value Propositions

For Enterprises:

• "Show me exactly what our AI did and prove it followed our policies"
• "Prevent AI from doing dangerous things in the wrong order"
• "Audit compliance for AI tool usage"

For Developers:

• "I can see the full workflow trace when things go wrong"
• "I can enforce business logic without changing every tool"
• "I can gradually add workflow rules without breaking existing tools"

For AI Safety:

• "AI can't accidentally skip safety checks"
• "Dangerous tool combinations are blocked by policy"
• "Complete audit trail for accountability"