@simonecoelhosfo/optimizely-mcp-server
Version:
Optimizely MCP Server for AI assistants with integrated CLI tools
1,302 lines (1,298 loc) • 52 kB
JavaScript
// Complete tool reference data from audit
const TOOL_REFERENCE_DATA = {
"analyze_data": {
name: "analyze_data",
category: "Analytics",
primaryUse: "🔎 ANALYTICS ENGINE for SQL-like queries over Optimizely data",
responseTime: "1-5s",
parameters: {
structured_query: {
type: "object",
required: true,
properties: {
from: "string - View name (REQUIRED)",
select: "string[] - Field names to return",
where: "object - Filter conditions",
group_by: "string[] - MUST match select fields for aggregations",
aggregate: "object - count, sum, avg, min, max functions",
order_by: "object - {field: string, direction: 'asc'|'desc'}",
limit: "number - Max rows (default: 10)",
offset: "number - Skip rows for pagination"
}
},
project_id: "string - Optional for better performance",
options: {
bypass_pagination: "boolean - Get all data",
page: "number - Page number",
page_size: "number - Results per page",
simplified: "boolean - Simplified response format"
}
},
returns: {
success: {
result: "success",
entities: "DataRecord[]",
pagination: {
consent_required: "boolean - Triggers consent if true",
has_more: "boolean - More pages available",
total_count: "number - Total records",
current_page: "number",
page_size: "number"
}
},
fieldError: {
result: "error",
error_type: "FieldNotFoundError",
available_fields: "string[]",
suggested_views: "string[]",
hint: "string"
},
aggregationError: {
result: "error",
error_type: "AggregationError",
corrected_query: "object - Fixed query structure",
explanation: "string"
}
},
useCases: [
"Complex data filtering and aggregation",
"Cross-entity analytics queries",
"Statistical analysis of experiment data"
],
criticalNotes: [
"MUST call get_entity_documentation first to get valid field names",
"When using aggregate, ALWAYS include group_by",
"group_by MUST list ALL fields from select",
"Booleans use 0/1 NOT true/false in where clause"
]
},
"list_projects": {
name: "list_projects",
category: "Discovery",
primaryUse: "📋 DISCOVER all available projects and their platform types",
responseTime: "<1s",
parameters: {
random_string: "string - Dummy parameter for no-parameter tools"
},
returns: {
result: "success",
projects: [{
id: "string",
name: "string",
platform: "string - 'web' | 'custom'",
is_flags_enabled: "boolean - Platform type indicator",
account_id: "string",
flag_count: "number",
experiment_count: "number",
environment_count: "number",
last_modified: "string",
platform_type: "'Feature Experimentation' | 'Web Experimentation'",
experiment_explanation: "string - Platform-specific guidance"
}],
summary: {
total_projects: "number",
feature_experimentation_projects: "number",
web_experimentation_projects: "number"
}
},
useCases: [
"Initial project discovery",
"Platform type identification",
"Account-level overview"
],
decisionPattern: [
"is_flags_enabled: true OR platform: 'custom' = Feature Experimentation",
"is_flags_enabled: false AND platform: 'web' = Web Experimentation"
]
},
"get_entity_details": {
name: "get_entity_details",
category: "Discovery",
primaryUse: "🔍 GET single entity details by ID or key (fastest existence check)",
responseTime: "<1s",
parameters: {
entity_type: "string - REQUIRED: flag, experiment, audience, etc.",
entity_id: "string - REQUIRED: accepts ID or key",
project_id: "string - Enables template enhancement",
options: {
include_templates: "boolean - Default: true",
template_complexity: "1|2|3 - Default: 2",
enhanced_details: "boolean - Use specialized formatters",
include_results: "boolean - For experiments"
}
},
returns: {
entity_data: "EntityRecord",
model_friendly_template: {
description: "string",
usage: "string",
template: "TemplateStructure",
complexity_level: "number",
platform: "'feature' | 'web'"
},
project_context: "ProjectInfo",
_mcp_guidance: "object - Agent hints"
},
useCases: [
"Get complete details for a single entity",
"Retrieve creation templates",
"Understand entity structure"
],
criticalNotes: [
"Much faster than list_entities for single item lookup",
"Templates show how to recreate the entity"
]
},
"get_optimization_analysis": {
name: "get_optimization_analysis",
category: "Analytics",
primaryUse: "🎯 UNIFIED project performance analysis",
responseTime: "3-8s",
parameters: {
project_id: "string - REQUIRED",
analysis_type: "'experiment_performance' | 'flag_usage' | 'audience_effectiveness' | 'comprehensive'",
options: {
include_recommendations: "boolean - Default: true",
include_visualizations: "boolean - Default: false",
time_period_days: "number - Default: 30",
specific_entities: "string[] - Entity IDs to focus on"
}
},
returns: {
result: "success",
analysis_type: "string",
insights: [{
category: "string",
finding: "string",
impact: "'high' | 'medium' | 'low'",
recommendation: "string",
affected_entities: "string[]",
metrics: "object"
}],
recommendations: [{
action: "string",
priority: "'high' | 'medium' | 'low'",
expected_impact: "string",
implementation_steps: "string[]"
}],
summary: "object - High-level metrics"
},
useCases: [
"Deep performance analysis",
"Identify optimization opportunities",
"Data-driven recommendations"
],
decisionPattern: [
"Use for AI-powered insights and trends",
"Prefer over get_recommendations for deeper analysis"
]
},
"get_recommendations": {
name: "get_recommendations",
category: "Analytics",
primaryUse: "💡 RULE-BASED optimization recommendations and opportunities",
responseTime: "2-5s",
parameters: {
project_id: "string - REQUIRED",
focus_area: "'experiments' | 'flags' | 'audiences' | 'performance' | 'all'",
include_historical: "boolean - Default: true",
timeframe_days: "number - Default: 30",
limit: "number - Max recommendations"
},
returns: {
result: "success",
recommendations: [{
id: "string",
type: "'optimization' | 'configuration' | 'experimentation' | 'governance'",
priority: "'high' | 'medium' | 'low'",
title: "string",
description: "string",
impact: "string",
effort: "'low' | 'medium' | 'high'",
category: "string",
related_entities: "string[]",
actions: [{
action: "string",
tool: "string",
parameters: "object"
}]
}],
focus_area: "string",
summary: {
total_recommendations: "number",
high_priority: "number",
medium_priority: "number",
low_priority: "number"
}
},
useCases: [
"Rule-based optimization guidance",
"Best practice compliance",
"Project improvement suggestions"
],
criticalNotes: [
"Uses pattern-based analysis, not AI",
"Lighter weight than get_optimization_analysis"
]
},
"compare_environments": {
name: "compare_environments",
category: "Analytics",
primaryUse: "⚖️ COMPARE flag configurations across environments",
responseTime: "1-3s",
parameters: {
project_id: "string - REQUIRED",
flag_key: "string - Optional: single flag vs all flags",
environments: "string[] - Optional: defaults to all environments"
},
returns: {
result: "success",
comparison: {
project_id: "string",
environments: "string[]",
flag_key: "string",
differences: [{
flag_key: "string",
flag_name: "string",
difference_type: "'enabled_state' | 'traffic_allocation' | 'audience_targeting' | 'variable_values'",
environments: "object - env_key: value mapping",
severity: "'major' | 'minor'",
impact: "string"
}],
summary: {
total_flags_compared: "number",
flags_with_differences: "number",
environments_compared: "number",
major_differences: "number",
minor_differences: "number"
}
}
},
useCases: [
"Environment drift detection",
"Configuration validation",
"Deployment verification"
]
},
"manage_cache": {
name: "manage_cache",
category: "System",
primaryUse: "🚀 UNIFIED cache management for all data operations",
responseTime: "5s-30min",
parameters: {
operation: "'initialize' | 'refresh' | 'clear' - REQUIRED",
project_id: "string - For refresh only",
options: {
force: "boolean - Clear before refresh (REQUIRES CONSENT)",
incremental: "boolean - Fast incremental sync",
views_only: "boolean - Recreate views only",
wait_for_completion: "boolean - Block until finished"
}
},
returns: {
success: {
result: "success",
operation: "string",
duration_ms: "number",
projects_synced: "number",
entities_synced: "object - counts by type",
cache_size_mb: "number",
next_sync_time: "string"
},
clear: {
result: "success",
operation: "clear",
cache_cleared: "boolean",
freed_space_mb: "number"
},
running: {
status: "running",
operation: "string",
progress_percentage: "number",
current_step: "string",
estimated_completion: "string"
}
},
useCases: [
"Initial data sync (7-30 minutes)",
"Incremental updates (1-3 minutes)",
"Cache troubleshooting"
],
criticalNotes: [
"initialize, clear, and force operations REQUIRE user consent",
"Empty cache requires initialize first"
]
},
"export_data": {
name: "export_data",
category: "Export",
primaryUse: "📊 DATA EXPORTER - Export to CSV, JSON, or YAML with smart routing",
responseTime: "2-10s",
parameters: {
format: "'csv' | 'json' | 'yaml' - REQUIRED",
entity_type: "string - Simple entity export",
structured_query: "object - Complex analytics export",
query: "string - DEPRECATED - DO NOT USE",
project_id: "string - Recommended",
filename: "string",
output_directory: "string - Default: ./exports",
custom_fields: "string[] - Only these fields",
exclude_fields: "string[] - Exclude these fields",
include_metadata: "boolean - Default: true",
pretty_print: "boolean - Default: true",
options: {
limit: "number",
bypass_pagination: "boolean - Auto-enabled for exports"
}
},
returns: {
success: {
result: "success",
export: {
file_path: "string",
filename: "string",
format: "string",
size_bytes: "number",
record_count: "number",
created_at: "string"
},
metadata: "object",
summary: "object"
},
parameterGuidance: {
result: "error",
error_type: "ParameterGuidance",
message: "string",
suggestion: "object"
}
},
useCases: [
"Bulk data extraction",
"Reporting and analysis",
"Data backup"
],
criticalNotes: [
"Natural language queries no longer supported",
"Use entity_type for simple exports",
"Use structured_query for complex exports"
]
},
"get_results": {
name: "get_results",
category: "Analytics",
primaryUse: "📊 UNIFIED A/B test results with statistical analysis",
responseTime: "2-5s",
parameters: {
result_type: "string - REQUIRED: experiment, campaign, bulk_experiments",
experiment_id: "string - For single experiment results",
campaign_id: "string - For single campaign results",
project_id: "string - For bulk experiment results",
experiment_ids: "string[] - Filter bulk results",
include_paused: "boolean - Include paused experiments",
start_date: "string - YYYY-MM-DD format",
end_date: "string - YYYY-MM-DD format",
stats_config: "string - Statistical configuration"
},
returns: {
success: {
result: "success",
results: "StatisticalResults[]",
metrics: "MetricData[]",
winner: "VariationInfo",
confidence: "number",
summary: "ResultsSummary"
}
},
useCases: [
"View experiment performance metrics",
"Statistical significance analysis",
"Bulk results comparison"
]
},
"list_entities": {
name: "list_entities",
category: "Discovery",
primaryUse: "📋 LIST multiple entities with pagination (WARNING: can be slow for large datasets)",
responseTime: "1-10s",
parameters: {
entity_type: "string - REQUIRED: flag, experiment, audience, etc.",
project_id: "string - Required for most entities",
filters: "object - Entity-specific filters"
},
returns: {
success: {
result: "success",
entities: "EntityRecord[]",
pagination: "PaginationInfo",
total_count: "number"
},
paginationRequired: {
status: "HARD_STOP_REQUIRED",
pagination_params: "object"
}
},
useCases: [
"Browse multiple entities",
"Filtered entity lists",
"Bulk entity operations"
],
criticalNotes: [
"Use get_entity_details for single entity lookup (much faster)",
"Large datasets trigger pagination HARD_STOP",
"Rulesets/rules require flag_key AND environment_key filters"
]
},
"manage_flag_state": {
name: "manage_flag_state",
category: "Flag Ops",
primaryUse: "🎛️ ENABLE/DISABLE flags in specific environments (state changes only)",
responseTime: "1-2s",
parameters: {
project_id: "string - REQUIRED",
flag_key: "string - REQUIRED: Flag identifier",
environment_key: "string - REQUIRED: production, development, etc.",
action: "string - REQUIRED: enable | disable"
},
returns: {
success: {
result: "success",
flag_key: "string",
environment_key: "string",
enabled: "boolean",
previous_state: "boolean"
}
},
useCases: [
"Enable/disable flags in environments",
"Quick flag state changes",
"Emergency flag shutoff"
],
criticalNotes: [
"NOT for creating flags - use manage_entity_lifecycle",
"Changes take effect immediately for users"
]
},
"get_flag_history": {
name: "get_flag_history",
category: "Analytics",
primaryUse: "📜 AUDIT TRAIL for specific flag changes and modifications",
responseTime: "1-3s",
parameters: {
project_id: "string - REQUIRED",
flag_key: "string - REQUIRED: Flag identifier",
start_date: "string - ISO 8601 format",
end_date: "string - ISO 8601 format",
per_page: "number - Results per page"
},
returns: {
success: {
result: "success",
history: [{
timestamp: "string",
user: "string",
action: "string",
changes: "object",
before: "object",
after: "object"
}],
total_changes: "number"
}
},
useCases: [
"Audit flag modifications",
"Track who changed what",
"Compliance and debugging"
]
},
"get_entity_templates": {
name: "get_entity_templates",
category: "Templates",
primaryUse: "🎓 DISCOVER entity templates schema and structures for all CRUD operations",
responseTime: "<1s",
parameters: {
project_id: "string - REQUIRED: numeric or TEMPLATE:web/TEMPLATE:feature",
entity_type: "string - Optional specific entity type",
complexity: "number - 1-5 template detail level",
format: "string - traditional | model_friendly (default)"
},
returns: {
available_templates: "TemplateInfo[]",
templates: "EntityTemplate[]",
platform: "string",
usage_instructions: "string"
},
useCases: [
"Learn entity creation patterns",
"Get creation templates",
"Educational exploration"
],
criticalNotes: [
"ALWAYS call before manage_entity_lifecycle",
"Educational IDs work without auth"
]
},
"validate_template": {
name: "validate_template",
category: "Templates",
primaryUse: "Validate Direct Template Architecture templates without executing them",
responseTime: "1-2s",
parameters: {
entity_type: "string - REQUIRED",
template_data: "object - REQUIRED: Template to validate",
project_id: "string - Optional context",
platform: "string - web | feature",
parameters: "object - Template parameters",
options: {
validate_structure: "boolean - Default: true",
validate_entities: "boolean - Default: true",
include_fixes: "boolean - Default: true",
verbose: "boolean - Default: false"
}
},
returns: {
valid: {
valid: "true",
message: "string",
details: "ValidationDetails"
},
invalid: {
valid: "false",
errors: "ValidationError[]",
fixes: "SuggestedFix[]"
}
},
useCases: [
"Validate before execution",
"Test template structure",
"Debug template issues"
],
criticalNotes: [
"Only validates Direct Template format (version 2)",
"Steps must use entity_type, not system_template_id"
]
},
"update_ruleset": {
name: "update_ruleset",
category: "CRUD",
primaryUse: "🔧 UPDATE flag ruleset (rulesets belong to parent flags in specific environments)",
responseTime: "2-5s",
parameters: {
project_id: "string - REQUIRED",
flag_key: "string - REQUIRED: Parent flag",
environment_key: "string - REQUIRED: Environment",
ruleset_data: "array - REQUIRED: JSON Patch operations"
},
returns: {
success: {
result: "success",
ruleset: "UpdatedRuleset",
changes_applied: "number"
}
},
useCases: [
"Update flag targeting rules",
"Modify traffic allocation",
"Change rule priorities"
],
criticalNotes: [
"Uses JSON Patch format",
"Hierarchy: project → flag → environment → ruleset → rules"
]
},
"get_openapi_reference": {
name: "get_openapi_reference",
category: "Documentation",
primaryUse: "📖 GET OpenAPI schemas, validation rules & examples for entities",
responseTime: "<1s",
parameters: {
entity_type: "string - REQUIRED",
information_type: "string - REQUIRED: schema | operations | field_details | examples | validation | dependencies | relationships",
operation: "string - For operations info: create | update | delete | list | get",
field_name: "string - For field_details",
project_id: "string - For platform-specific schemas"
},
returns: {
schema: "OpenAPISchema",
operations: "OperationDetails",
field_details: "FieldSpecification",
examples: "ExampleData[]",
validation: "ValidationRules"
},
useCases: [
"Get entity field schemas",
"Understand API requirements",
"View working examples"
]
},
"get_system_status": {
name: "get_system_status",
category: "System",
primaryUse: "🏥 SYSTEM health check with progressive diagnostic levels",
responseTime: "1-3s",
parameters: {
include_diagnostics: "boolean - Include cache/sync details",
detailed: "boolean - Full analysis with recommendations"
},
returns: {
basic: {
status: "healthy | degraded | unhealthy",
api_connected: "boolean",
cache_initialized: "boolean"
},
diagnostic: {
cache_details: "CacheInfo",
sync_status: "SyncStatus",
storage_info: "StorageMetrics"
},
detailed: {
performance_metrics: "PerformanceData",
recommendations: "string[]",
troubleshooting: "TroubleshootingGuide"
}
},
useCases: [
"Health monitoring",
"Troubleshoot issues",
"Performance analysis"
]
},
"get_project_data": {
name: "get_project_data",
category: "Discovery",
primaryUse: "🎯 FETCH complete project snapshot - all entities in one call",
responseTime: "2-8s",
parameters: {
project_id: "string - REQUIRED",
include_flags: "boolean - Default: true",
include_experiments: "boolean - Default: true",
include_audiences: "boolean - Default: true",
include_attributes: "boolean - Default: true",
include_events: "boolean - Default: true",
include_environments: "boolean - Default: true",
include_rulesets: "boolean - Default: true"
},
returns: {
success: {
result: "success",
project: "ProjectInfo",
flags: "FlagData[]",
experiments: "ExperimentData[]",
audiences: "AudienceData[]",
attributes: "AttributeData[]",
events: "EventData[]",
environments: "EnvironmentData[]"
}
},
useCases: [
"Complete project backup",
"Cross-entity analysis",
"Migration preparation"
],
criticalNotes: [
"Large projects can return 10MB+ of data",
"Use selective includes for better performance"
]
},
"get_flag_entities": {
name: "get_flag_entities",
category: "Discovery",
primaryUse: "🔗 DISCOVER all entities connected to a specific flag",
responseTime: "1-2s",
parameters: {
project_id: "string - REQUIRED",
flag_id: "string - REQUIRED: Flag ID or key"
},
returns: {
success: {
result: "success",
flag: "FlagInfo",
experiments: "ExperimentReference[]",
rulesets: "RulesetReference[]",
variables: "VariableReference[]",
environments: "EnvironmentUsage[]"
}
},
useCases: [
"Impact analysis before changes",
"Dependency checking",
"Flag deletion safety"
],
criticalNotes: [
"Always check before deleting flags"
]
},
"update_flags_bulk": {
name: "update_flags_bulk",
category: "CRUD",
primaryUse: "⚡ UPDATE multiple flags in single batch operation",
responseTime: "3-10s",
parameters: {
project_id: "string - REQUIRED",
flags_data: "array - REQUIRED: [{key: string, data: object}]"
},
returns: {
success: {
result: "success",
updated: "number",
failed: "number",
results: "UpdateResult[]"
}
},
useCases: [
"Mass flag updates",
"Bulk traffic changes",
"Environment synchronization"
],
criticalNotes: [
"Validate flag_keys exist first",
"Consider rollback plan"
]
},
"archive_flags_bulk": {
name: "archive_flags_bulk",
category: "CRUD",
primaryUse: "📦 ARCHIVE multiple flags in single batch operation",
responseTime: "2-8s",
parameters: {
project_id: "string - REQUIRED",
flag_keys: "string[] - REQUIRED: Array of flag keys"
},
returns: {
success: {
result: "success",
archived: "number",
failed: "number",
results: "ArchiveResult[]"
}
},
useCases: [
"Cleanup old flags",
"Seasonal flag removal",
"Mass archival operations"
],
criticalNotes: [
"IRREVERSIBLE operation",
"Get user confirmation first",
"Check dependencies before archiving"
]
},
"migrate_entities": {
name: "migrate_entities",
category: "Migration",
primaryUse: "🚀 ORCHESTRATE multi-project entity migration with dependency resolution",
responseTime: "10s-10min",
parameters: {
source: "object - REQUIRED: {projectId: string, token?: string}",
destination: "object - REQUIRED: {projectId: string, token?: string}",
entities: "object - Entity selection configuration",
mappings: "object - ID/key mappings",
options: {
dryRun: "boolean - Preview without changes",
validateOnly: "boolean - Only validate",
continueOnError: "boolean",
rollbackStrategy: "partial | all-or-nothing",
conflictResolution: "skip | update | create-copy | ask",
interactiveMode: "boolean - Prompt for confirmations"
}
},
returns: {
validation: {
valid: "boolean",
dependencies: "DependencyMap",
conflicts: "ConflictInfo[]"
},
migration: {
result: "success",
migrated: "EntityCount",
checkpoint_file: "string",
duration: "string"
}
},
useCases: [
"Cross-project entity transfer",
"Environment promotion",
"Project consolidation"
],
criticalNotes: [
"Always validateOnly first",
"Use dryRun before real migration",
"Supports checkpoint/resume for large migrations"
]
},
"get_migration_status": {
name: "get_migration_status",
category: "Migration",
primaryUse: "📊 CHECK migration progress and status from checkpoint file",
responseTime: "<1s",
parameters: {
checkpoint_path: "string - REQUIRED: Path to checkpoint file"
},
returns: {
status: {
phase: "string",
progress: "number",
entities_migrated: "number",
entities_total: "number",
errors: "MigrationError[]",
can_resume: "boolean"
}
},
useCases: [
"Monitor migration progress",
"Check for errors",
"Resume failed migrations"
]
},
"orchestrate_template": {
name: "orchestrate_template",
category: "Orchestration",
primaryUse: "🎭 EXECUTE multi-step workflows for complex entity operations",
responseTime: "5-60s",
parameters: {
template_id: "string - Template ID to execute",
template_name: "string - Alternative to template_id",
parameters: "object - Template parameters",
options: {
dry_run: "boolean - Test without changes",
debug: "boolean - Detailed execution info",
continue_on_error: "boolean",
project_id: "string - Default project",
environment: "string - Default environment"
}
},
returns: {
success: {
result: "success",
execution_id: "string",
steps_completed: "number",
entities_created: "EntityReference[]",
outputs: "object"
},
dryRun: {
result: "dry_run",
would_create: "EntityInfo[]",
validation_results: "ValidationResult[]"
}
},
useCases: [
"Campaign launch workflows",
"A/B test setup automation",
"Progressive rollout orchestration",
"Multi-environment deployments"
],
criticalNotes: [
"Only for multi-entity operations",
"Use manage_entity_lifecycle for single entities",
"Always test with dry_run first"
]
},
"manage_orchestration_templates": {
name: "manage_orchestration_templates",
category: "Orchestration",
primaryUse: "Comprehensive management of Direct Template Architecture orchestration templates",
responseTime: "1-5s",
parameters: {
operation: "string - REQUIRED: list | get | create | update | delete | history",
project_id: "string - Project context",
template_id: "string - For get/update/delete/history",
template_name: "string - Alternative to template_id",
filters: "object - For list operation",
template_data: "object - For create/update",
history_type: "string - execution | changes | all",
status: "string - Filter history by status",
limit: "number - Max results",
options: "object - Operation-specific options"
},
returns: {
list: {
templates: "TemplateInfo[]",
total: "number"
},
get: {
template: "FullTemplate",
execution_history: "ExecutionSummary[]"
},
create: {
result: "success",
template_id: "string",
version: "number"
}
},
useCases: [
"Browse workflow templates",
"Create custom workflows",
"View execution history",
"Template version management"
],
criticalNotes: [
"All templates must use Direct Template format (version 2)",
"Steps use entity_type directly, not system_template_id"
]
},
"get_orchestration_samples": {
name: "get_orchestration_samples",
category: "Orchestration",
primaryUse: "Get orchestration samples, system templates, documentation, and troubleshooting guides",
responseTime: "<1s",
parameters: {
operation: "string - get | list | registry | search | troubleshoot | concepts",
sample_type: "string - skeleton | pattern | complete_example",
workflow_type: "string - Specific workflow type",
complexity: "number - 1-3 complexity level",
platform: "string - web | feature | both",
include_explanations: "boolean - Default: true",
search_query: "string - For search operation",
registry_filter: "object - Filter system templates"
},
returns: {
samples: "WorkflowSample[]",
registry: "SystemTemplate[]",
documentation: "ConceptGuide[]",
troubleshooting: "TroubleshootingInfo"
},
useCases: [
"Learn orchestration patterns",
"View system templates",
"Get workflow examples",
"Troubleshoot issues"
]
},
"get_optimizely_api_reference": {
name: "get_optimizely_api_reference",
category: "Documentation",
primaryUse: "📚 SEARCH Optimizely SDK/API documentation with natural language",
responseTime: "<1s",
parameters: {
entity_type: "string - REQUIRED: search | method | sdk | platform | overview",
information_type: "string - REQUIRED: general | details | methods | installation | etc.",
product_type: "string - SDK/platform type",
method_name: "string - Specific method name",
concept_name: "string - Concept to explore",
search_query: "string - Natural language search"
},
returns: {
search_results: "SearchResult[]",
method_details: "MethodDocumentation",
sdk_info: "SDKDocumentation",
examples: "CodeExample[]"
},
useCases: [
"Search SDK documentation",
"Method reference lookup",
"SDK installation guides",
"API usage examples"
]
},
"get_tool_reference": {
name: "get_tool_reference",
category: "Documentation",
primaryUse: "🔧 DISCOVER tool capabilities, parameters, and return structures",
responseTime: "<1s",
parameters: {
operation: "string - REQUIRED: list | details | search | matrix",
tool_name: "string - For details operation",
capability: "string - For search operation",
category: "string - Filter by category"
},
returns: {
list: {
tools: "ToolSummary[]",
categories: "CategoryCount"
},
details: {
tool: "CompleteToolSpec",
examples: "UsageExample[]"
},
search: {
matches: "ToolMatch[]"
},
matrix: {
decision_matrix: "DecisionRule[]",
usage_guide: "UsageGuide"
}
},
useCases: [
"Discover available tools",
"Understand tool parameters",
"Find tools by capability",
"Tool selection guidance"
]
},
"manage_entity_lifecycle": {
name: "manage_entity_lifecycle",
category: "CRUD",
primaryUse: "🎯 CREATE, UPDATE & MANAGE all Optimizely entities (flags, experiments, campaigns, etc.)",
responseTime: "1-15s",
parameters: {
operation: "'create' | 'update' | 'delete' - REQUIRED",
entity_type: "string - REQUIRED",
project_id: "string - Required for most operations",
entity_id: "string - Required for update/delete",
entity_data: "object - Entity-specific fields",
template_data: "object - For template mode",
mode: "'direct' | 'template' - Default: direct",
options: {
validate_only: "boolean - Dry run",
auto_orchestrate: "boolean - Auto-create dependencies",
skip_validation: "boolean"
}
},
returns: {
create: {
result: "success",
entity: "CreatedEntity",
orchestration: {
auto_orchestrated: "boolean",
created_dependencies: "object[]"
}
},
update: {
result: "success",
entity: "UpdatedEntity",
changes: "object"
},
delete: {
result: "success",
entity_type: "string",
entity_id: "string",
deleted: "boolean"
}
},
useCases: [
"Entity creation with dependencies",
"Bulk entity updates",
"Safe entity deletion"
],
criticalNotes: [
"Template mode auto-orchestrates complex entities",
"Delete operations require explicit consent",
"Auto-creates audiences, events, pages when referenced"
]
},
"get_entity_documentation": {
name: "get_entity_documentation",
category: "Documentation",
primaryUse: "📖 DISCOVER available fields & schemas for queries and operations",
responseTime: "<1s",
parameters: {
entity_type: "string - View name or entity type"
},
returns: {
documentation: {
entity_type: "string",
description: "string",
fields: [{
name: "string",
type: "string",
description: "string",
required: "boolean",
example: "any"
}],
examples: "object[]",
notes: "string[]"
}
},
useCases: [
"Get available fields before analyze_data",
"Understand entity schemas",
"View documentation for analytics"
],
criticalNotes: [
"ALWAYS call before analyze_data queries",
"Returns all 18 analytics views when called without params"
]
}
};
// Decision matrix for tool selection
const TOOL_DECISION_MATRIX = [
{ userSays: "List my projects", useTool: "list_projects", reason: "Project discovery" },
{ userSays: "Show all flags in project X", useTool: "list_entities", reason: "Entity browsing" },
{ userSays: "Get details about flag Y", useTool: "get_entity_details", reason: "Single entity deep dive" },
{ userSays: "Analyze flag performance", useTool: "analyze_data + get_entity_documentation", reason: "Analytics queries" },
{ userSays: "Export all experiments to CSV", useTool: "export_data", reason: "Bulk data export" },
{ userSays: "Create a new audience", useTool: "manage_entity_lifecycle", reason: "Entity creation" },
{ userSays: "Enable flag Z in production", useTool: "manage_flag_state", reason: "Flag state control" },
{ userSays: "Who changed this flag?", useTool: "get_flag_history", reason: "Audit trail" },
{ userSays: "How do I create an experiment?", useTool: "get_entity_templates", reason: "Creation guidance" },
{ userSays: "Compare environments", useTool: "compare_environments", reason: "Configuration drift" },
{ userSays: "Show experiment results", useTool: "get_results", reason: "A/B test analysis" },
{ userSays: "System health check", useTool: "get_system_status", reason: "Monitoring" },
{ userSays: "What uses this flag?", useTool: "get_flag_entities", reason: "Dependency analysis" },
{ userSays: "Bulk update traffic allocation", useTool: "update_flags_bulk", reason: "Mass operations" },
{ userSays: "Remove old flags", useTool: "archive_flags_bulk", reason: "Cleanup" },
{ userSays: "Move entities to another project", useTool: "migrate_entities", reason: "Cross-project transfer" },
{ userSays: "Create campaign with experiments", useTool: "orchestrate_template", reason: "Multi-step workflows" },
{ userSays: "What REST endpoints are available?", useTool: "get_openapi_reference", reason: "API documentation" },
{ userSays: "How to use JavaScript SDK?", useTool: "get_optimizely_api_reference", reason: "SDK documentation" }
];
// Tool implementation
export const getToolReferenceTool = {
name: "get_tool_reference",
description: `🔧 DISCOVER tool capabilities, parameters, and return structures
⚡ OPERATIONS:
• list → Overview of all 30 MCP tools with categories
• details → Complete specs for a specific tool
• search → Find tools by capability or use case
• matrix → Decision guide for tool selection
🤖 DECISION PATTERN:
• "What tools are available?" → list
• "How does analyze_data work?" → details
• "Which tool for experiments?" → search
• "Tool selection guide?" → matrix
📊 RETURNS:
• Parameters-first structure for agent parsing
• Complete return type documentation
• Real-world usage examples
• Performance characteristics
💡 EXAMPLES:
• List all: {"operation": "list"}
• Tool details: {"operation": "details", "tool_name": "analyze_data"}
• Find tools: {"operation": "search", "capability": "export"}
• Decision help: {"operation": "matrix"}`,
inputSchema: {
type: "object",
properties: {
operation: {
type: "string",
enum: ["list", "details", "search", "matrix"],
description: "Operation to perform"
},
tool_name: {
type: "string",
description: "Tool name for details operation"
},
capability: {
type: "string",
description: "Capability to search for (search operation)"
},
category: {
type: "string",
enum: ["Analytics", "Discovery", "CRUD", "Export", "System", "Documentation", "Flag Ops", "Migration", "Orchestration", "Templates"],
description: "Filter by category (list operation)"
}
},
required: ["operation"],
additionalProperties: false
},
async handler(args) {
const { operation, tool_name, capability, category } = args;
switch (operation) {
case "list":
return handleListOperation(category);
case "details":
if (!tool_name) {
return {
error: "tool_name is required for details operation",
available_tools: Object.keys(TOOL_REFERENCE_DATA)
};
}
return handleDetailsOperation(tool_name);
case "search":
if (!capability) {
return {
error: "capability is required for search operation",
example_capabilities: ["export", "analytics", "create", "flag", "experiment", "cache"]
};
}
return handleSearchOperation(capability);
case "matrix":
return handleMatrixOperation();
default:
return {
error: "Invalid operation",
valid_operations: ["list", "details", "search", "matrix"]
};
}
}
};
// Handler functions
function handleListOperation(category) {
const tools = Object.values(TOOL_REFERENCE_DATA);
const filteredTools = category
? tools.filter(tool => tool.category === category)
: tools;
const categorySummary = filteredTools.reduce((acc, tool) => {
acc[tool.category] = (acc[tool.category] || 0) + 1;
return acc;
}, {});
return {
result: "success",
total_tools: filteredTools.length,
category_filter: category || "all",
categories: categorySummary,
tools: filteredTools.map(tool => ({
name: tool.name,
category: tool.category,
primary_use: tool.primaryUse,
response_time: tool.responseTime,
parameter_count: Object.keys(tool.parameters).length,
has_complex_returns: Object.keys(tool.returns).length > 1
})),
usage_hint: "Use 'details' operation for complete tool documentation"
};
}
function handleDetailsOperation(toolName) {
const tool = TOOL_REFERENCE_DATA[toolName];
if (!tool) {
return {
error: `Tool '${toolName}' not found`,
available_tools: Object.keys(TOOL_REFERENCE_DATA),
suggestion: `Did you mean: ${findClosestToolName(toolName)}?`
};
}
return {
result: "success",
tool: {
// Parameters first for agent attention
parameters: tool.parameters,
returns: tool.returns,
// Metadata
name: tool.name,
category: tool.category,
primary_use: tool.primaryUse,
response_time: tool.responseTime,
// Usage guidance
use_cases: tool.useCases,
critical_notes: tool.criticalNotes || [],
decision_pattern: tool.decisionPattern || [],
// Quick examples
example_calls: generateExampleCalls(tool)
}
};
}
function handleSearchOperation(capability) {
const searchTerm = capability.toLowerCase();
const matches = Object.values(TOOL_REFERENCE_DATA).filter(tool => {
const searchableText = [
tool.name,
tool.primaryUse,
tool.category,
...tool.useCases
].join(" ").toLowerCase();
return searchableText.includes(searchTerm);
});
return {
result: "success",
search_term: capability,
matches_found: matches.length,
tools: matches.map(tool => ({
name: tool.name,
category: tool.category,
primary_use: tool.primaryUse,
relevance_reason: tool.useCases.find(uc => uc.toLowerCase().includes(searchTerm)) || tool.primaryUse
})),
alternative_searches: matches.length === 0 ? [
"Try searching for: analytics, export, create, flag, experiment"
] : []
};
}
function handleMatrixOperation() {
return {
result: "success",
decision_matrix: TOOL_DECISION_MATRIX,
usage_guide: {
instruction: "Match user intent to tool selection",
example: "If user says 'Show all flags', use 'list_entities' tool",
categories: {
analytics: ["analyze_data", "get_optimization_analysis", "get_recommendations", "compare_environments", "get_results"],
discovery: ["list_projects", "list_entities", "get_entity_details", "get_project_data"],