@simonecoelhosfo/optimizely-mcp-server
Version:
Optimizely MCP Server for AI assistants with integrated CLI tools
777 lines • 30.4 kB
JavaScript
/**
* UPDATE Entity Templates
*
* Defines template structures for UPDATE operations across all entity types.
* These templates enable agents to perform complex multi-step updates using
* the same orchestration patterns as CREATE operations.
*
* Template Structure:
* - metadata: Operation details, platform, complexity, requirements
* - template: Template structure with placeholder types
*
* Placeholder Types:
* - {EXISTING: field} - Reference existing entity field/ID
* - {CURRENT: field} - Show current value for context
* - {FILL: field} - Required update field
* - {OPTIONAL: field} - Optional update field
* - {FILL_ENUM: option1|option2} - Enum selection
* - {ADD_TO: array_field} - Add to existing array
* - {UPDATE: field} - Required update field
* - {REMOVE: identifier} - Mark element for removal
* - {REBALANCE: weights} - Auto-calculate traffic weights
*
* @author Optimizely MCP Server
* @version 1.0.0
*/
/**
* Core UPDATE templates for all entity types
*/
export const UPDATE_ENTITY_TEMPLATES = {
// =================================================================
// FEATURE EXPERIMENTATION PLATFORM - UPDATE TEMPLATES
// =================================================================
/**
* Add A/B testing capability to an existing Feature Flag
*/
flag_add_ab_test: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 5,
description: 'Add A/B testing to existing flag with variations, metrics, and traffic allocation',
update_type: 'additive',
requires_existing: ['flag'],
creates_entities: ['variation', 'event', 'experiment'],
affects_entities: ['ruleset'],
warning: 'Flag updates work through rulesets, not direct property updates. The template system handles this automatically - just provide your desired configuration.'
},
template: {
flag_key: '{EXISTING: flag_identifier}',
environment: '{FILL: environment_key}',
variations: [
{
key: '{FILL: variation_key}',
name: '{FILL: variation_name}',
weight: '{FILL: traffic_percentage}',
feature_enabled: '{FILL_ENUM: true|false}',
variable_values: '{OPTIONAL: variable_overrides}'
}
],
metrics: [
{
key: '{FILL: metric_key}',
name: '{OPTIONAL: metric_name}',
event_key: '{FILL: event_key}',
aggregator: '{FILL_ENUM: count|sum|unique}',
event_type: '{FILL_ENUM: custom|click|pageview}'
}
],
audience_conditions: '{OPTIONAL: audience_targeting}'
}
},
/**
* Update traffic allocation for existing flag variations
*/
flag_update_traffic: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 3,
description: 'Rebalance traffic allocation across flag variations',
update_type: 'rebalance',
requires_existing: ['flag', 'variation'],
affects_entities: ['ruleset'],
warning: 'Traffic allocation is managed through rulesets. Template handles the complexity.'
},
template: {
flag_key: '{EXISTING: flag_identifier}',
environment: '{FILL: environment_key}',
traffic_allocation: [
{
variation_key: '{EXISTING: variation_key}',
weight: '{FILL: new_traffic_percentage}'
}
]
}
},
/**
* Add new variation to existing flag
* WARNING: When rebalance_existing=true, weight is IGNORED and traffic is split EQUALLY
* To set custom weights, use flag_add_variation first, then flag_update_traffic
*/
flag_add_variation: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 4,
description: 'Add new variation to existing flag. IMPORTANT: rebalance_existing=true splits traffic EQUALLY, ignoring weight!',
update_type: 'additive',
requires_existing: ['flag'],
creates_entities: ['variation'],
affects_entities: ['ruleset'],
warning: 'rebalance_existing=true divides traffic EQUALLY among ALL variations. The weight field is IGNORED when rebalancing! To set custom weights: 1) Add variation with rebalance_existing=false, 2) Use flag_update_traffic separately.'
},
template: {
flag_key: '{EXISTING: flag_identifier}',
environment: '{FILL: environment_key}',
new_variation: {
key: '{FILL: variation_key}',
name: '{FILL: variation_name}',
feature_enabled: '{FILL_ENUM: true|false}',
variable_values: '{OPTIONAL: variable_overrides}'
},
rebalance_existing: '{FILL_ENUM: true|false}'
}
},
/**
* Add variation with custom traffic split (combines add + traffic update)
* Use this when you want to add a variation AND set specific traffic percentages
*/
flag_add_variation_custom_traffic: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 5,
description: 'Add new variation with custom traffic distribution (NOT equal split)',
update_type: 'additive',
requires_existing: ['flag'],
creates_entities: ['variation'],
affects_entities: ['ruleset'],
warning: 'This performs TWO operations: 1) Adds the variation, 2) Updates ALL traffic weights as specified'
},
template: {
flag_key: '{EXISTING: flag_identifier}',
environment: '{FILL: environment_key}',
new_variation: {
key: '{FILL: variation_key}',
name: '{FILL: variation_name}',
feature_enabled: '{FILL_ENUM: true|false}',
variable_values: '{OPTIONAL: variable_overrides}'
},
traffic_allocation: [
{
variation_key: '{EXISTING: existing_variation_1}',
weight: '{FILL: weight_for_existing_1}'
},
{
variation_key: '{EXISTING: existing_variation_2}',
weight: '{FILL: weight_for_existing_2}'
},
{
variation_key: '{FILL: new_variation_key_must_match_above}',
weight: '{FILL: weight_for_new_variation}'
}
]
}
},
/**
* Update variable definitions for a flag
*/
flag_update_variables: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 3,
description: 'Modify variable definitions and default values',
update_type: 'merge',
requires_existing: ['flag'],
affects_entities: ['variable_definition', 'variation']
},
template: {
flag_key: '{EXISTING: flag_identifier}',
variables: [
{
key: '{FILL: variable_key}',
type: '{FILL_ENUM: string|boolean|integer|double|json}',
default_value: '{FILL: default_value}',
description: '{OPTIONAL: variable_description}'
}
]
}
},
/**
* Change audience targeting for a flag
*/
flag_change_audience: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 2,
description: 'Update flag audience targeting conditions',
update_type: 'replace',
requires_existing: ['flag'],
affects_entities: ['ruleset']
},
template: {
flag_key: '{EXISTING: flag_identifier}',
environment: '{FILL: environment_key}',
audience_conditions: '{FILL: new_audience_conditions}'
}
},
/**
* Update existing A/B test configuration (metrics, variations, etc.)
* Use this to modify an existing A/B test without creating a new one
*/
flag_update_ab_test: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 4,
description: 'Update existing A/B test configuration (metrics, variations, audience)',
update_type: 'merge',
requires_existing: ['flag', 'rule'],
affects_entities: ['rule', 'metric', 'variation'],
warning: 'This updates the existing A/B test rule. To add a new A/B test, use flag_add_ab_test instead.'
},
template: {
flag_key: '{EXISTING: flag_identifier}',
environment: '{FILL: environment_key}',
rule_key: '{OPTIONAL: specific_rule_key_or_first_ab_test}',
variations: '{OPTIONAL: variations_to_update}',
metrics: '{OPTIONAL: metrics_to_update}',
audience_conditions: '{OPTIONAL: new_audience_conditions}',
traffic_allocation: '{OPTIONAL: new_traffic_weights}'
}
},
/**
* Update metrics on existing rules
* Use this to change aggregators, add/remove metrics, or update metric properties
*/
flag_update_metrics: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 3,
description: 'Update metrics on existing flag rules (aggregator, event_key, etc.)',
update_type: 'merge',
requires_existing: ['flag', 'rule'],
affects_entities: ['rule', 'metric', 'event'],
warning: 'Updates metrics on ALL rules unless rule_key is specified'
},
template: {
flag_key: '{EXISTING: flag_identifier}',
environment: '{FILL: environment_key}',
rule_key: '{OPTIONAL: specific_rule_or_update_all}',
metrics: [
{
key: '{EXISTING: metric_key}',
aggregator: '{OPTIONAL_ENUM: count|sum|unique}',
event_key: '{OPTIONAL: new_event_key}',
winning_direction: '{OPTIONAL_ENUM: increasing|decreasing}'
}
],
add_metrics: '{OPTIONAL: new_metrics_to_add}',
remove_metrics: '{OPTIONAL: metric_keys_to_remove}'
}
},
/**
* Update properties of existing variations
* Use this to change variation names, feature_enabled, or variable values
*/
flag_update_variations: {
metadata: {
operation: 'update',
entity_type: 'flag',
platform: 'feature',
complexity_score: 3,
description: 'Update properties of existing flag variations',
update_type: 'merge',
requires_existing: ['flag', 'variation'],
affects_entities: ['variation'],
warning: 'Only updates existing variations. To add new variations, use flag_add_variation.'
},
template: {
flag_key: '{EXISTING: flag_identifier}',
variations: [
{
key: '{EXISTING: variation_key}',
name: '{OPTIONAL: new_variation_name}',
feature_enabled: '{OPTIONAL_ENUM: true|false}',
description: '{OPTIONAL: variation_description}',
variable_values: '{OPTIONAL: updated_variable_overrides}'
}
]
}
},
// =================================================================
// WEB EXPERIMENTATION PLATFORM - UPDATE TEMPLATES
// =================================================================
/**
* Add new variation to existing Web experiment
*/
experiment_add_variation: {
metadata: {
operation: 'update',
entity_type: 'experiment',
platform: 'web',
complexity_score: 4,
description: 'Add new variation to existing Web experiment. ⚠️ IMPORTANT: Use entity_id with NUMERIC ID, NOT experiment_key!',
update_type: 'additive',
requires_existing: ['experiment'],
creates_entities: ['variation'],
affects_entities: ['experiment'],
common_mistakes: [
'DO NOT include experiment_key in template_data for updates',
'Use entity_id parameter with numeric ID (e.g., 6250648178524160)',
'experiment_key is ONLY for CREATE operations'
]
},
template: {
// ⚠️ NO experiment_key field here - entity identification via entity_id parameter
variation: {
key: '{FILL: variation_key}',
name: '{FILL: variation_name}',
weight: '{FILL: traffic_percentage}',
actions: [
{
page_id: '{EXISTING: page_identifier}',
changes: [] // Simplified - most experiments just need empty changes array
}
]
},
rebalance_existing: '{FILL_ENUM: true|false}'
}
},
/**
* Update traffic allocation for Web experiment variations
*/
experiment_update_traffic: {
metadata: {
operation: 'update',
entity_type: 'experiment',
platform: 'web',
complexity_score: 3,
description: 'Update traffic weights for experiment variations. Must use variation_id, not variation_key.',
update_type: 'rebalance',
requires_existing: ['experiment', 'variation'],
affects_entities: ['experiment'],
warning: 'This updates variation weights WITHIN the experiment. To change overall experiment traffic %, use traffic_allocation field in experiment_update template.'
},
template: {
// Updates how traffic is split BETWEEN variations (must sum to 10000)
variations: [
{
variation_id: '{EXISTING: variation_id_number}', // e.g., 6734938221838336
weight: '{FILL: traffic_percentage}' // e.g., 2500 for 25%
}
]
}
},
/**
* Change page targeting for Web experiment
*/
experiment_change_pages: {
metadata: {
operation: 'update',
entity_type: 'experiment',
platform: 'web',
complexity_score: 3,
description: 'Update page targeting for Web experiment',
update_type: 'replace',
requires_existing: ['experiment'],
affects_entities: ['experiment']
},
template: {
page_ids: ['{FILL: page_id}'],
url_targeting: {
activation_type: '{FILL_ENUM: immediate|polling|callback}',
conditions: [
{
type: '{FILL_ENUM: url|element|custom_code}',
match_type: '{FILL_ENUM: exact|substring|regex}',
value: '{FILL: match_value}'
}
]
}
}
},
/**
* Add NEW metrics to existing Web experiment (not for updating existing metrics)
*
* 🎯 USE THIS WHEN: You want to track a completely new event/metric that isn't already being tracked
* ❌ DON'T USE THIS WHEN: You want to change how an existing metric is calculated
*
* DECISION GUIDE:
* - Adding a new conversion event to track? → Use THIS template with event_key
* - Changing aggregator of existing metric? → Use experiment_update with event_id
*/
experiment_add_metrics: {
metadata: {
operation: 'update',
entity_type: 'experiment',
platform: 'web',
complexity_score: 3,
description: 'Add NEW tracking metrics to existing experiment (creates new metric tracking)',
update_type: 'additive',
requires_existing: ['experiment'],
creates_entities: ['event'],
affects_entities: ['experiment'],
critical_distinction: 'Uses event_key because we are CREATING new metric tracking. For MODIFYING existing metrics, use experiment_update with event_id.'
},
template: {
metrics: [
{
event_key: '{FILL: event_key}',
name: '{OPTIONAL: metric_name}',
aggregator: '{FILL_ENUM: count|sum|unique}',
event_type: '{FILL_ENUM: custom|click|pageview}',
is_primary: '{FILL_ENUM: true|false}'
}
]
}
},
/**
* Update EXISTING experiment properties including modifying existing metrics
*
* 🎯 METRIC UPDATE USE CASES:
* - Change aggregator (e.g., from 'unique' to 'count')
* - Change winning direction (e.g., from 'increasing' to 'decreasing')
* - Update other properties of metrics that are ALREADY being tracked
*
* ⚠️ CRITICAL FOR METRICS:
* - Use event_id (numeric) for metrics - NOT event_key
* - To find event_id: list_entities(entity_type="event") or get experiment details
* - This updates EXISTING metrics only - to ADD new metrics use experiment_add_metrics
*/
experiment_update: {
metadata: {
operation: 'update',
entity_type: 'experiment',
platform: 'web',
complexity_score: 4,
description: 'Update EXISTING experiment properties (variations, metrics, targeting, traffic)',
update_type: 'merge',
requires_existing: ['experiment'],
affects_entities: ['experiment', 'variation'],
warning: 'Use variation_id (not variation_key) when updating variations. Use event_id (not event_key) when updating metrics.',
metric_guidance: {
use_cases: [
'Change how existing metric calculates (aggregator)',
'Change winning direction of existing metric',
'Update other properties of already-tracked metrics'
],
required_field: 'event_id (numeric ID of the event)',
how_to_find_event_id: 'Use list_entities(entity_type="event") or check experiment details for existing metric IDs'
}
},
template: {
// Basic fields
name: '{OPTIONAL: new_experiment_name}',
description: '{OPTIONAL: new_description}',
status: '{OPTIONAL_ENUM: active|paused|archived}',
// Traffic allocation
traffic_allocation: '{OPTIONAL: overall_traffic_percentage}',
// Variations update - MUST use variation_id (get from experiment details)
// Example: Remove one variation and rebalance traffic equally
variations: [
{
variation_id: '{EXISTING: variation_id_number}', // e.g., 6734938221838336
weight: '{FILL: traffic_percentage}' // e.g., 2500 for 25%
}
],
// Remove variations (use with variations array to rebalance)
remove_variations: ['{OPTIONAL: variation_id_to_remove}'], // e.g., [5697315596402688]
// Metrics - FOR UPDATING EXISTING METRICS ONLY
// To ADD new metrics, use experiment_add_metrics template instead
metrics: [
{
event_id: '{EXISTING: event_id}', // REQUIRED: Numeric ID (not event_key!)
aggregator: '{OPTIONAL_ENUM: count|sum|unique}', // Change how metric calculates
winning_direction: '{OPTIONAL_ENUM: increasing|decreasing}' // Change optimization direction
}
],
// Audience targeting
audience_conditions: '{OPTIONAL: audience_expression}',
// Page targeting
page_ids: ['{OPTIONAL: page_id}'],
// Schedule
schedule: {
start_time: '{OPTIONAL: ISO_8601_timestamp}',
stop_time: '{OPTIONAL: ISO_8601_timestamp}'
}
}
},
/**
* Update targeting conditions for a Web page
*/
page_update_conditions: {
metadata: {
operation: 'update',
entity_type: 'page',
platform: 'web',
complexity_score: 3,
description: 'Modify page targeting and activation conditions',
update_type: 'replace',
requires_existing: ['page'],
affects_entities: ['page']
},
template: {
conditions: [
{
type: '{FILL_ENUM: url|element|custom_code}',
match_type: '{FILL_ENUM: exact|substring|regex}',
value: '{FILL: match_value}'
}
],
activation_type: '{FILL_ENUM: immediate|polling|callback}'
}
},
/**
* Change activation rules for a Web page
*/
page_change_activation: {
metadata: {
operation: 'update',
entity_type: 'page',
platform: 'web',
complexity_score: 2,
description: 'Update page activation rules and triggers',
update_type: 'replace',
requires_existing: ['page'],
affects_entities: ['page']
},
template: {
activation_type: '{FILL_ENUM: immediate|polling|callback}',
activation_code: '{OPTIONAL: custom_javascript}'
}
},
/**
* Add experiments to existing campaign
*/
campaign_add_experiments: {
metadata: {
operation: 'update',
entity_type: 'campaign',
platform: 'web',
complexity_score: 4,
description: 'Add new experiments to existing campaign',
update_type: 'additive',
requires_existing: ['campaign'],
creates_entities: ['experiment'],
affects_entities: ['campaign'],
warning: 'This will modify the campaign and create new experiments'
},
template: {
campaign_key: '{EXISTING: campaign_identifier}',
new_experiments: [
{
name: '{FILL: experiment_name}',
page_ids: ['{EXISTING: page_identifier}'],
variations: [
{
key: '{FILL: variation_key}',
name: '{FILL: variation_name}',
weight: '{FILL: traffic_percentage}',
actions: [
{
page_id: '{EXISTING: page_identifier}',
change_type: '{FILL_ENUM: text|html|css|redirect|javascript}',
selector: '{FILL: css_selector}',
value: '{FILL: new_content}'
}
]
}
],
traffic_allocation: [
{
variation_key: '{FILL: variation_key}',
weight: '{FILL: traffic_percentage}'
}
]
}
]
}
},
/**
* Update campaign page targeting and URL conditions
*/
campaign_update_targeting: {
metadata: {
operation: 'update',
entity_type: 'campaign',
platform: 'web',
complexity_score: 3,
description: 'Update campaign page targeting and URL conditions',
update_type: 'replace',
requires_existing: ['campaign'],
affects_entities: ['campaign']
},
template: {
campaign_key: '{EXISTING: campaign_identifier}',
page_ids: ['{FILL: page_id}'],
url_targeting: {
activation_type: '{FILL_ENUM: immediate|polling|callback}',
conditions: [
{
type: '{FILL_ENUM: url|element|custom_code}',
match_type: '{FILL_ENUM: exact|substring|regex}',
value: '{FILL: match_value}'
}
]
}
}
},
/**
* Update campaign experiment priorities
*/
campaign_update_priorities: {
metadata: {
operation: 'update',
entity_type: 'campaign',
platform: 'web',
complexity_score: 2,
description: 'Reorder experiment priorities within campaign',
update_type: 'replace',
requires_existing: ['campaign', 'experiment'],
affects_entities: ['campaign']
},
template: {
campaign_key: '{EXISTING: campaign_identifier}',
experiment_priorities: [
{
experiment_key: '{EXISTING: experiment_identifier}',
priority: '{FILL: priority_number}'
}
]
}
},
// =================================================================
// SHARED ENTITIES (BOTH PLATFORMS) - UPDATE TEMPLATES
// =================================================================
/**
* Update audience targeting conditions
*/
audience_update_conditions: {
metadata: {
operation: 'update',
entity_type: 'audience',
platform: 'both',
complexity_score: 4,
description: 'Modify audience targeting logic and conditions',
update_type: 'replace',
requires_existing: ['audience'],
affects_entities: ['audience']
},
template: {
audience_key: '{EXISTING: audience_identifier}',
conditions: '{FILL: audience_conditions_json_string}',
description: '{OPTIONAL: updated_description}'
}
},
/**
* Add new custom attributes to audience
*/
audience_add_attributes: {
metadata: {
operation: 'update',
entity_type: 'audience',
platform: 'both',
complexity_score: 3,
description: 'Add new custom attributes to audience targeting',
update_type: 'additive',
requires_existing: ['audience'],
creates_entities: ['attribute'],
affects_entities: ['audience']
},
template: {
audience_key: '{EXISTING: audience_identifier}',
new_attributes: [
{
key: '{FILL: attribute_key}',
name: '{FILL: attribute_name}',
type: '{FILL_ENUM: string|integer|boolean|double}'
}
]
}
},
/**
* Update project platform settings
*/
project_update_settings: {
metadata: {
operation: 'update',
entity_type: 'project',
platform: 'both',
complexity_score: 2,
description: 'Modify project platform configuration and settings',
update_type: 'merge',
requires_existing: ['project'],
affects_entities: ['project']
},
template: {
project_id: '{EXISTING: project_identifier}',
settings: {
platform: '{OPTIONAL: platform_type}',
confidence_threshold: '{OPTIONAL: confidence_level}',
description: '{OPTIONAL: project_description}'
}
}
}
};
/**
* Get UPDATE template by template key
*/
export function getUpdateTemplate(templateKey) {
return UPDATE_ENTITY_TEMPLATES[templateKey];
}
/**
* Get all UPDATE templates for a specific entity type
*/
export function getUpdateTemplatesForEntity(entityType) {
const templates = {};
for (const [key, template] of Object.entries(UPDATE_ENTITY_TEMPLATES)) {
if (template.metadata.entity_type === entityType) {
templates[key] = template;
}
}
return templates;
}
/**
* Get all UPDATE templates for a specific platform
*/
export function getUpdateTemplatesForPlatform(platform) {
const templates = {};
for (const [key, template] of Object.entries(UPDATE_ENTITY_TEMPLATES)) {
if (template.metadata.platform === platform || template.metadata.platform === 'both') {
templates[key] = template;
}
}
return templates;
}
/**
* Get UPDATE templates by complexity score
*/
export function getUpdateTemplatesByComplexity(maxComplexity) {
const templates = {};
for (const [key, template] of Object.entries(UPDATE_ENTITY_TEMPLATES)) {
if (template.metadata.complexity_score <= maxComplexity) {
templates[key] = template;
}
}
return templates;
}
/**
* List all available UPDATE template keys
*/
export function listUpdateTemplateKeys() {
return Object.keys(UPDATE_ENTITY_TEMPLATES);
}
/**
* Get template metadata without the full template structure
*/
export function getUpdateTemplateMetadata() {
const metadata = {};
for (const [key, template] of Object.entries(UPDATE_ENTITY_TEMPLATES)) {
metadata[key] = template.metadata;
}
return metadata;
}
//# sourceMappingURL=UpdateEntityTemplates.js.map