@simonecoelhosfo/optimizely-mcp-server
Version:
Optimizely MCP Server for AI assistants with integrated CLI tools
403 lines • 14 kB
JavaScript
/**
* Simplified Entity Creation Templates
* @description Minimal templates for creating Optimizely entities with only required fields.
* AI agents should use these templates to avoid adding unnecessary complexity.
*
* Template Philosophy:
* - Start with minimal required fields only
* - Use progressive enhancement for complex scenarios
* - Avoid fields that might confuse AI agents
* - Platform-specific requirements clearly marked
*
* @author Optimizely MCP Server
* @version 2.0.0
*/
/**
* Minimal Entity Creation Templates
* Start with these before moving to advanced templates
*/
export const MINIMAL_ENTITY_TEMPLATES = {
// =============================================================================
// FEATURE EXPERIMENTATION MINIMAL TEMPLATES
// =============================================================================
/**
* Minimal Flag - Just creates the flag without variables or A/B test
*/
flag_minimal: {
metadata: {
platform: 'feature',
complexity: 'minimal',
description: 'Create a basic feature flag without variables or A/B test',
requiredFields: ['key', 'name'],
apiCalls: 1,
notes: [
'Creates flag in OFF state by default',
'Add variables separately if needed',
'Configure A/B test separately if needed'
]
},
template: {
key: '{FILL: unique_flag_key_no_spaces}',
name: '{FILL: human_readable_name}'
}
},
/**
* Flag with Variables - Includes variable definitions
*/
flag_with_variables: {
metadata: {
platform: 'feature',
complexity: 'basic',
description: 'Create a feature flag with variable definitions',
requiredFields: ['key', 'name'],
apiCalls: 2, // flag + variables
notes: [
'Variables define dynamic configuration',
'Each variable needs: key, type, default_value'
]
},
template: {
key: '{FILL: unique_flag_key}',
name: '{FILL: display_name}',
variables: [
{
key: '{FILL: variable_key}',
type: '{FILL_ENUM: string|boolean|integer|double|json}',
default_value: '{FILL: default_value_matching_type}'
}
]
}
},
/**
* Minimal Event - Creates a simple metric
*/
event_minimal: {
metadata: {
platform: 'feature',
complexity: 'minimal',
description: 'Create a basic event for measuring metrics',
requiredFields: [], // All fields optional!
apiCalls: 1,
notes: [
'All event fields are optional',
'Key and name are recommended for clarity'
]
},
template: {
key: '{FILL: unique_event_key}',
name: '{FILL: display_name}',
event_type: '{FILL_ENUM: custom|click|pageview|conversion}'
}
},
// =============================================================================
// WEB EXPERIMENTATION MINIMAL TEMPLATES
// =============================================================================
/**
* Minimal Page - Just the required fields
*/
page_minimal: {
metadata: {
platform: 'web',
complexity: 'minimal',
description: 'Create a basic page for targeting',
requiredFields: ['name', 'edit_url'],
apiCalls: 1,
notes: [
'project_id added automatically',
'Uses immediate activation by default',
'Add conditions separately if needed'
]
},
template: {
name: '{FILL: page_name}',
edit_url: '{FILL: target_url}'
}
},
/**
* Minimal Experiment - Container only, no variations
* WARNING: This creates an experiment shell - you MUST add variations separately
*/
experiment_minimal: {
metadata: {
platform: 'web',
complexity: 'minimal',
description: 'Create experiment container only - variations must be added separately',
requiredFields: [], // Only project_id required, added automatically
apiCalls: 1,
dependencies: ['page'],
notes: [
'WARNING: Creates experiment without variations',
'You MUST add variations with changes for Web experiments',
'Use experiment_with_variations for complete setup'
]
},
template: {
name: '{FILL: experiment_name}',
page_ids: ['{FILL: page_id_from_page_creation}']
}
},
/**
* Experiment with Variations - Includes required variation structure
* CRITICAL: All Web variations MUST have at least one change
*/
experiment_with_variations: {
metadata: {
platform: 'web',
complexity: 'basic',
description: 'Create a complete Web experiment with variations',
requiredFields: ['variations[].weight'],
apiCalls: 2,
dependencies: ['page'],
notes: [
'CRITICAL: Every variation MUST have changes array',
'Even Control variations need a change (use attribute)',
'Weights must sum to 10000 (basis points)'
]
},
template: {
name: '{FILL: experiment_name}',
page_ids: ['{FILL: page_id}'],
variations: [
{
name: 'Control',
weight: 5000, // 50%
actions: [{
page_id: '{FILL: same_page_id}',
changes: [{
type: 'attribute',
selector: 'body',
value: 'data-experiment="control"' // No-op change required
}]
}]
},
{
name: 'Treatment',
weight: 5000, // 50%
actions: [{
page_id: '{FILL: same_page_id}',
changes: [{
type: '{FILL_ENUM: replace_html|insert_html|attribute}',
selector: '{FILL: css_selector}',
value: '{FILL: html_or_attribute_value}'
}]
}]
}
]
}
},
/**
* Minimal Campaign
*/
campaign_minimal: {
metadata: {
platform: 'web',
complexity: 'minimal',
description: 'Create a basic campaign',
requiredFields: [], // Only project_id required
apiCalls: 1
},
template: {
name: '{FILL: campaign_name}'
}
},
// =============================================================================
// SHARED MINIMAL TEMPLATES (Both platforms)
// =============================================================================
/**
* Minimal Audience
*/
audience_minimal: {
metadata: {
platform: 'both',
complexity: 'minimal',
description: 'Create a basic audience segment',
requiredFields: [], // Only project_id required
apiCalls: 1,
notes: [
'Conditions are optional but needed for functionality',
'Use audience_with_conditions for targeting rules'
]
},
template: {
name: '{FILL: audience_name}'
}
},
/**
* Audience with Conditions
*/
audience_with_conditions: {
metadata: {
platform: 'both',
complexity: 'basic',
description: 'Create an audience with targeting conditions',
requiredFields: [],
apiCalls: 1
},
template: {
name: '{FILL: audience_name}',
conditions: [
'and',
{
type: '{FILL_ENUM: browser|location|custom_attribute|device}',
name: '{FILL: condition_parameter}',
value: '{FILL: condition_value}'
}
]
}
},
/**
* Minimal Attribute
*/
attribute_minimal: {
metadata: {
platform: 'both',
complexity: 'minimal',
description: 'Create a custom attribute',
requiredFields: ['key'],
apiCalls: 1
},
template: {
key: '{FILL: attribute_key_no_spaces}',
name: '{FILL: display_name}'
}
},
/**
* Minimal Webhook
*/
webhook_minimal: {
metadata: {
platform: 'both',
complexity: 'minimal',
description: 'Create a webhook for notifications',
requiredFields: ['name', 'url'],
apiCalls: 1
},
template: {
name: '{FILL: webhook_name}',
url: '{FILL: https_endpoint_url}',
event_types: ['{FILL_ENUM: experiment.created|experiment.modified}']
}
},
/**
* Minimal Extension
*/
extension_minimal: {
metadata: {
platform: 'web',
complexity: 'minimal',
description: 'Create a JavaScript extension',
requiredFields: ['name', 'edit_url', 'implementation'],
apiCalls: 1
},
template: {
name: '{FILL: extension_name}',
edit_url: '{FILL: editor_url}',
implementation: '{FILL: javascript_code_string}'
}
}
};
/**
* Advanced templates for complex scenarios
* Only use these when minimal templates are insufficient
*/
export const ADVANCED_ENTITY_TEMPLATES = {
/**
* ❌ REMOVED: flag_complete_ab_test template - INVALID PATTERN
*
* This template was teaching agents to use the incorrect 'ab_test' structure
* on Feature Experimentation flags, which doesn't exist in the API.
*
* ✅ CORRECT APPROACH for A/B tests in Feature Experimentation:
* Use the multi-step approach with separate entity operations:
* 1. Create flag with flag_with_variables template
* 2. Create variations with variation_minimal template
* 3. Update ruleset with ruleset operation
* 4. Create experiment with experiment_minimal template
*/
/**
* Flag with Variables - Ready for A/B Testing
* Creates flag with variables, the correct first step for A/B tests
*/
flag_with_variables: {
metadata: {
platform: 'feature',
complexity: 'basic',
description: 'Create a feature flag with variables (correct first step for A/B tests)',
requiredFields: ['key', 'name'],
apiCalls: 1,
dependencies: [],
notes: [
'First step for A/B testing - create variations and ruleset separately',
'Variables enable different values per variation',
'Use manage_entity_lifecycle for subsequent steps'
]
},
template: {
flag: {
key: '{FILL: flag_key}',
name: '{FILL: flag_name}',
description: '{OPTIONAL: flag_description}'
},
variables: [
{
key: '{FILL: variable_key}',
type: '{FILL_ENUM: string|boolean|integer|double|json}',
default_value: '{FILL: default_value}',
description: '{OPTIONAL: variable_description}'
}
]
}
}
};
/**
* Get appropriate templates based on use case
*/
export function getTemplateRecommendation(entityType, requirements = {}) {
// Feature Experimentation
if (entityType === 'flag') {
// ❌ REMOVED: flag_complete_ab_test template recommendation - INVALID PATTERN
// A/B tests require multi-step approach, not single template with ab_test structure
if (requirements.hasABTest || requirements.hasVariables)
return 'flag_with_variables';
return 'flag_minimal';
}
// Web Experimentation
if (entityType === 'experiment') {
if (requirements.hasVariations)
return 'experiment_with_variations';
return 'experiment_minimal';
}
if (entityType === 'audience') {
if (requirements.hasConditions)
return 'audience_with_conditions';
return 'audience_minimal';
}
// Default to minimal template
return `${entityType}_minimal`;
}
/**
* Validation warnings for common mistakes
*/
export const TEMPLATE_WARNINGS = {
experiment: [
'Web experiments MUST have variations with changes',
'Every variation needs at least one change, even Control',
'Use attribute changes for no-op Control variations'
],
flag: [
'Start with minimal flag, add complexity later',
'Variables and A/B tests are optional',
'Flag key must not contain spaces'
],
variation: [
'Web variations require weight and actions.changes',
'Feature variations do NOT require weight',
'Weights must sum to 10000 (basis points)'
],
event: [
'All event fields are optional',
'Key and name recommended for clarity',
'Events must exist before use in metrics'
]
};
//# sourceMappingURL=EntityTemplates.simplified.js.map