@simonecoelhosfo/optimizely-mcp-server/dist/resources/docs/visual-workflows.md

Optimizely MCP Server for AI assistants with integrated CLI tools

# Optimizely Visual Workflows Guide

## Project Type Detection Workflow

### MANDATORY: Never Skip Project Type Detection

```
STEP 1: List Projects
┌─────────────────┐
│ list_projects   │
└─────────┬───────┘
          │
          ▼
STEP 2: Get Project Details (MANDATORY!)
┌─────────────────────────────────────────┐
│ get_entity_details project PROJECT_ID   │
│ ⚠️  CHECK: is_flags_enabled property    │
└─────────┬───────────────────────────────┘
          │
          ▼
STEP 3: Platform Detection
┌─────────────────────────────────────────┐
│ if (is_flags_enabled === true)          │
│   → Feature Experimentation             │
│   → Use: flags, variable_definitions,   │
│          variations, rulesets, rules    │
│                                         │
│ if (is_flags_enabled === false)         │
│   → Web Experimentation                 │
│   → Use: campaigns, pages, extensions,  │
│          segments, webhooks             │
└─────────┬───────────────────────────────┘
          │
          ▼
STEP 4: Use Platform-Specific Entities
┌─────────────────────────────────────────┐
│ 🚨 CRITICAL: Different platforms have   │
│    completely different entity sets!    │
│ 🚨 NEVER assume entity availability!    │
└─────────────────────────────────────────┘
```

## Checkpoint Validation

Before proceeding with ANY entity operation:
- ✅ Did I call `get_entity_details project PROJECT_ID`?
- ✅ Did I check the `is_flags_enabled` property?
- ✅ Do I know if this is Feature or Web Experimentation?
- ✅ Am I using the correct entity set for this platform?

**🚨 IF ANY ANSWER IS NO → STOP AND FIX IMMEDIATELY!**

## Entity Creation Workflows

### Flag Creation with A/B Test (Feature Experimentation)

```
1. Check Project Type
   └─→ get_entity_details project PROJECT_ID
   
2. Get Template
   └─→ get_entity_templates project_id=PROJECT_ID entity_type=flag
   
3. Fill Template
   └─→ Replace all {FILL: description} placeholders
   
4. Create Flag
   └─→ manage_entity_lifecycle operation=create entity_type=flag mode=template
   
5. Verify Creation
   └─→ get_entity_details flag FLAG_KEY project_id=PROJECT_ID
```

### Campaign Creation (Web Experimentation)

```
1. Check Project Type
   └─→ get_entity_details project PROJECT_ID
   
2. Create Campaign
   └─→ manage_entity_lifecycle operation=create entity_type=campaign
   
3. Create Pages
   └─→ manage_entity_lifecycle operation=create entity_type=page
   
4. Create Experiments
   └─→ manage_entity_lifecycle operation=create entity_type=experiment
```

## Entity Relationship Workflows

### Getting Flag Components (Feature Experimentation)

```
Flag Overview
└─→ get_entity_details flag FLAG_KEY project_id=PROJECT_ID

Variable Definitions (Schema)
└─→ list_entities variable_definition project_id=PROJECT_ID filters={"flag_key": "FLAG_KEY"}

Variations (Values)
└─→ list_entities variation project_id=PROJECT_ID filters={"flag_key": "FLAG_KEY"}

Rulesets (Per Environment)
└─→ get_entity_details flag FLAG_KEY project_id=PROJECT_ID
    └─→ Check environmentData property

Rules (Targeting)
└─→ list_entities rule project_id=PROJECT_ID filters={"flag_key": "FLAG_KEY", "environment_key": "ENV_KEY"}
```

### Getting Campaign Components (Web Experimentation)

```
Campaign Overview
└─→ get_entity_details campaign CAMPAIGN_ID project_id=PROJECT_ID

Experiments in Campaign
└─→ list_entities experiment project_id=PROJECT_ID filters={"campaign_id": CAMPAIGN_ID}

Pages
└─→ list_entities page project_id=PROJECT_ID

Results
└─→ get_campaign_results campaign_id=CAMPAIGN_ID
```

## Common Workflow Patterns

### Pattern 1: Project Analysis
```
1. list_projects
2. get_entity_details project PROJECT_ID
3. Based on is_flags_enabled, determine available entities
```

### Pattern 2: Flag Analysis (Feature Experimentation Only)
```
1. Verify project type: is_flags_enabled === true
2. list_entities flag project_id=PROJECT_ID
3. get_entity_details flag FLAG_KEY project_id=PROJECT_ID
4. Check environmentData for environment-specific configurations
```

### Pattern 3: Cross-Environment Comparison
```
1. get_entity_details flag FLAG_KEY project_id=PROJECT_ID
2. Compare environmentData across environments
3. Or use: compare_environments project_id=PROJECT_ID
```

### Pattern 4: Results Analysis
```
Feature Experimentation:
└─→ get_experiment_results experiment_id=EXPERIMENT_ID

Web Experimentation:
└─→ get_campaign_results campaign_id=CAMPAIGN_ID
```

## Critical Reminders

1. **Always detect project type first** - Never assume platform capabilities
2. **Use proper entity endpoints** - Don't extract from embedded data
3. **Provide required filters** - Flag-scoped entities need flag_key
4. **Check platform availability** - Not all entities exist on all platforms