@simonecoelhosfo/optimizely-mcp-server
Version:
Optimizely MCP Server for AI assistants with integrated CLI tools
157 lines • 8.65 kB
JavaScript
/**
* Get Entity Documentation Tool - Individual Module
* @description Provides static documentation and information about entity types
* @since 2025-08-04
* @author Tool Modularization Team
*
* Migration Status: COMPLETED
* Original Method: OptimizelyMCPTools.getEntityDocumentation
* Complexity: MEDIUM
* Dependencies: logger, errorMapper, EntityDocumentationHelper, FIELDS, various template imports
*/
import { FIELDS } from '../../generated/fields.generated.js';
/**
* Creates the Get Entity Documentation tool with injected dependencies
* @param deps - Injected dependencies (storage, logger, errorMapper, etc.)
* @returns Tool definition with handler
*/
export function createGetEntityDocumentationTool(deps) {
return {
name: 'get_entity_documentation',
requiresCache: false, // Documentation is static, no cache needed
category: 'documentation',
description: 'Provides static documentation and information about entity types',
handler: async (args) => {
try {
const { entity_type: entityType, aspect } = args;
// Check if requesting analytics view documentation
const analyticsViews = [
'flags_unified_view', 'flag_variations_flat', 'flag_variation_variables',
'flag_variables_summary', 'experiments_unified_view', 'audiences_flat',
'pages_flat', 'experiment_audiences_flat', 'experiment_events_flat',
'experiment_pages_flat', 'entity_usage_view', 'flag_state_history_view',
'analytics_summary_view', 'change_history_flat',
'experiment_code_analysis_view', 'experiment_code_snippets_flat',
'project_code_security_view', 'code_search_patterns_view'
];
if (analyticsViews.includes(entityType)) {
return deps.getAnalyticsViewDocumentation(entityType);
}
// Check if requesting update templates documentation
if (entityType.endsWith('_update_templates')) {
const baseEntityType = entityType.replace('_update_templates', '');
return deps.getUpdateTemplatesDocumentation(baseEntityType);
}
// Check if requesting all update templates
if (entityType === 'update_templates') {
return deps.getAllUpdateTemplatesDocumentation();
}
// Check if requesting workflow template documentation
const { isWorkflowTemplate, getWorkflowTemplate } = await import('../../templates/ModelFriendlyTemplates.js');
if (isWorkflowTemplate(entityType)) {
const workflowTemplate = getWorkflowTemplate(entityType);
if (!workflowTemplate) {
throw new Error(`No workflow template available for '${entityType}'`);
}
// Return workflow template with basic project info (no specific project needed)
const mockProjectInfo = {
id: 'example_project',
name: 'Example Project',
is_flags_enabled: true // Assume Feature Experimentation for workflow examples
};
return deps.formatWorkflowTemplateResponse(workflowTemplate, mockProjectInfo, 'example_project');
}
// Import helper lazily to avoid circular dependencies
const { EntityDocumentationHelper } = await import('../EntityDocumentationHelper.js');
const docs = EntityDocumentationHelper.getEntityDocumentation(entityType);
if (!docs) {
return {
error: `Unknown entity type: ${entityType}`,
available_entities: Object.keys(FIELDS).sort(),
available_analytics_views: analyticsViews.sort()
};
}
// Return specific aspect if requested
if (aspect && aspect !== 'all') {
switch (aspect) {
case 'operations':
return {
entity_type: docs.entity_type,
operations: docs.operations,
endpoints: docs.endpoints
};
case 'fields':
return {
entity_type: docs.entity_type,
required_fields: docs.required_fields,
optional_fields: docs.optional_fields
};
case 'examples':
return {
entity_type: docs.entity_type,
examples: docs.examples || {}
};
case 'validation':
return {
entity_type: docs.entity_type,
validation: docs.validation || {}
};
}
}
// Return full documentation with template mode info highlighted
const result = { ...docs };
// Add template mode summary if available
if (docs.template_mode_info?.supported) {
result.template_mode_summary = {
level: "info", // advisory banner
headline: "Template mode builds all dependencies.",
action: 'Describe what you need → manage_entity_lifecycle(mode="template")',
notes: "Never create pages, events, or variations manually in template mode."
};
}
// TOOL HANDLER OPTIMIZATION: Mark documentation as read for complexity enforcement
deps.markDocsReadFor(entityType);
// Add acknowledgment confirmation
result._usage_acknowledgment = {
entity_type: entityType,
timestamp: new Date().toISOString(),
session_status: "documentation_read",
enabled_operations: [
"create (with _acknowledged_complexity: true for complex entities)",
"update",
"delete",
"archive"
],
complexity_understanding: {
message: `You now understand ${entityType} creation workflows and can proceed with operations`,
template_mode_benefit: deps.isComplexEntityType(entityType) ?
"Template mode automatically handles all dependencies for complex configurations" :
"Simple creation available for basic configurations",
manual_creation_note: deps.isComplexEntityType(entityType) ?
"For manual creation of complex configurations, add '_acknowledged_complexity: true' to entity_data" :
"Manual creation works well for basic configurations"
},
next_steps: {
simple: `manage_entity_lifecycle(operation='create', entity_type='${entityType}', entity_data={...})`,
complex: deps.isComplexEntityType(entityType) ?
`For complex configs: Use template mode OR add '_acknowledged_complexity: true'` :
"Template mode available for enhanced workflows"
}
};
deps.logger.debug({
entityType,
isComplex: deps.isComplexEntityType(entityType)
}, 'OptimizelyMCPTools.getEntityDocumentation: Marked documentation as read for complexity enforcement');
return result;
}
catch (error) {
deps.logger.error({
error: error.message,
stack: error.stack
}, 'OptimizelyMCPTools.getEntityDocumentation: Failed to get entity documentation');
throw deps.errorMapper.toMCPError(error, 'Failed to get entity documentation');
}
}
};
}
//# sourceMappingURL=GetEntityDocumentation.js.map