@simonecoelhosfo/optimizely-mcp-server/dist/resources/docs/entity-examples.md

Optimizely MCP Server for AI assistants with integrated CLI tools

# Optimizely Entity Usage Examples

## Common Usage Patterns

### Initial Project Discovery

```typescript
// Step 1: List all projects
list_projects

// Step 2: Get project details to determine platform
get_entity_details project "12345"

// Step 3: Check is_flags_enabled to determine entity availability
// if is_flags_enabled === true → Feature Experimentation entities
// if is_flags_enabled === false → Web Experimentation entities
```

### Feature Experimentation Examples

#### List All Flags in a Project
```typescript
list_entities flag project_id="12345"
```

#### Get Complete Flag Details
```typescript
get_entity_details flag "my_feature_flag" project_id="12345"
```

#### Get Flag's Variable Definitions (Schema)
```typescript
list_entities variable_definition project_id="12345" filters={"flag_key": "my_feature_flag"}
```

#### Get Flag's Variations (Actual Values)
```typescript
list_entities variation project_id="12345" filters={"flag_key": "my_feature_flag"}
```

#### Get Flag's Rules for Production Environment
```typescript
list_entities rule project_id="12345" filters={"flag_key": "my_feature_flag", "environment_key": "production"}
```

#### Create a New Flag with A/B Test
```typescript
// Step 1: Get template
get_entity_templates project_id="12345" entity_type="flag"

// Step 2: Fill template (replace all {FILL: description} placeholders)
// Step 3: Create using template mode
manage_entity_lifecycle operation="create" entity_type="flag" project_id="12345" mode="template" template_data={...filled template...}
```

#### Enable/Disable Flag in Environment
```typescript
// Enable
enable_flag project_id="12345" flag_key="my_feature_flag" environment_key="production"

// Disable
disable_flag project_id="12345" flag_key="my_feature_flag" environment_key="production"
```

#### Get Flag Change History
```typescript
get_flag_history project_id="12345" flag_key="my_feature_flag"
```

### Web Experimentation Examples

#### List All Campaigns
```typescript
list_entities campaign project_id="67890"
```

#### Get Campaign Details with Experiments
```typescript
// Get campaign
get_entity_details campaign "2000" project_id="67890"

// Get experiments in campaign
list_entities experiment project_id="67890" filters={"campaign_id": "2000"}
```

#### Create a New Page
```typescript
manage_entity_lifecycle 
  operation="create" 
  entity_type="page" 
  project_id="67890" 
  entity_data={
    "name": "Homepage",
    "edit_url": "https://example.com",
    "activation_type": "immediate"
  }
```

#### Get Campaign Results
```typescript
get_campaign_results campaign_id="2000"
```

### Cross-Platform Examples

#### List All Audiences (Works on Both Platforms)
```typescript
list_entities audience project_id="12345"
```

#### Create a Custom Event
```typescript
manage_entity_lifecycle 
  operation="create" 
  entity_type="event" 
  project_id="12345" 
  entity_data={
    "key": "purchase_completed",
    "name": "Purchase Completed",
    "description": "Fires when user completes a purchase"
  }
```

#### Get Recent Changes
```typescript
get_recent_changes project_id="12345" hours=24
```

#### Compare Environments (Feature Experimentation)
```typescript
compare_environments project_id="12345"
```

## Template Mode Examples

### When to Use Template Mode

Use template mode for complex entities with dependencies:
- Flags with A/B tests
- Experiments with custom pages
- Audiences with custom attributes

### Template Workflow Example

```typescript
// 1. Get available templates
get_entity_templates project_id="12345" entity_type="flag"

// 2. Response includes template with placeholders:
{
  "flag_with_ab_test": {
    "flag": {
      "key": "{FILL: Unique flag key, e.g., 'new_checkout_flow'}",
      "name": "{FILL: Human-readable name}",
      "description": "{FILL: What this flag controls}"
    },
    "variables": [...],
    "variations": [...]
  }
}

// 3. Fill all placeholders
const filledTemplate = {
  "flag": {
    "key": "new_checkout_flow",
    "name": "New Checkout Flow",
    "description": "Enables the redesigned checkout experience"
  },
  // ... rest of filled template
}

// 4. Create using template mode
manage_entity_lifecycle 
  operation="create" 
  entity_type="flag" 
  project_id="12345" 
  mode="template" 
  template_data=filledTemplate
```

## Error Handling Examples

### Entity Not Found
```typescript
// Request
get_entity_details flag "non_existent_flag" project_id="12345"

// Error Response
"Flag with key 'non_existent_flag' not found in project 12345"
```

### Missing Required Filter
```typescript
// Request (missing flag_key filter)
list_entities variation project_id="12345"

// Error Response
"Variations require flag_key filter"
```

### Wrong Platform Entity
```typescript
// Request (trying to get campaigns in Feature Experimentation project)
list_entities campaign project_id="12345"  // where is_flags_enabled = true

// Error Response
"Campaigns are only available in Web Experimentation projects"
```

## Performance Tips

1. **Use Specific Filters**
   - Always provide project_id when known
   - Use flag_key filters for flag-scoped entities
   - Limit results with `limit` parameter

2. **Batch Operations**
   - Get all needed entities in one session
   - Use `get_insights` for comprehensive analysis

3. **Cache Management**
   - Use `refresh_cache` if data seems stale
   - Use `incremental` option for faster updates

4. **Resource Efficiency**
   - Don't request embedded data if you need specific entities
   - Use dedicated entity endpoints for accurate data