snow-flow 1.4.49 → 2.0.0

package/src/mcp/servicenow-deployment-mcp-refactored.ts

@@ -0,0 +1,1292 @@
+#!/usr/bin/env node
+/**
+ * ServiceNow Deployment MCP Server - Agent-Integrated Version
+ * Provides specialized deployment tools with full agent coordination
+ * NEW v1.3.1: Complete XML Update Set auto-import with preview and commit controls
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { BaseMCPServer, MCPToolResult } from './shared/base-mcp-server.js';
+import { AgentContext } from './shared/mcp-memory-manager.js';
+import { ScopeManager, DeploymentContext } from '../managers/scope-manager.js';
+import { GlobalScopeStrategy, ScopeType } from '../strategies/global-scope-strategy.js';
+import { artifactTracker } from '../utils/artifact-tracker.js';
+import { promises as fs } from 'fs';
+
+export class ServiceNowDeploymentMCP extends BaseMCPServer {
+  private scopeManager: ScopeManager;
+  private globalScopeStrategy: GlobalScopeStrategy;
+
+  constructor() {
+    super('servicenow-deployment', '2.0.0');
+    
+    // Initialize scope management
+    this.scopeManager = new ScopeManager({
+      defaultScope: ScopeType.GLOBAL,
+      allowFallback: true,
+      validatePermissions: true,
+      enableMigration: false
+    });
+    this.globalScopeStrategy = new GlobalScopeStrategy();
+
+    // Start artifact tracking session
+    artifactTracker.startSession();
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers() {
+    // Define available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: 'snow_deploy',
+          description: 'AGENT-AWARE DEPLOYMENT - Complete deployment workflow with automatic update set management, agent coordination, and memory integration',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              type: {
+                type: 'string',
+                enum: ['widget', 'flow', 'application', 'script', 'business_rule', 'table', 'batch', 'xml_update_set'],
+                description: 'Type of artifact to deploy (use xml_update_set for XML import)'
+              },
+              xml_file_path: {
+                type: 'string',
+                description: 'Path to XML update set file (for xml_update_set type)'
+              },
+              auto_preview: {
+                type: 'boolean',
+                description: 'Automatically preview the update set after import (default: true)',
+                default: true
+              },
+              auto_commit: {
+                type: 'boolean',
+                description: 'Automatically commit the update set if preview is clean (default: true)',
+                default: true
+              },
+              instruction: {
+                type: 'string',
+                description: 'Natural language instruction for what to create (for flows/widgets)'
+              },
+              config: {
+                type: 'object',
+                description: 'Artifact configuration (alternative to instruction for direct config)'
+              },
+              artifacts: {
+                type: 'array',
+                description: 'For batch deployments - array of artifacts',
+                items: {
+                  type: 'object',
+                  properties: {
+                    type: { type: 'string' },
+                    config: { type: 'object' },
+                    instruction: { type: 'string' }
+                  }
+                }
+              },
+              // Agent context parameters
+              session_id: {
+                type: 'string',
+                description: 'Agent session ID for coordination'
+              },
+              agent_id: {
+                type: 'string',
+                description: 'Deploying agent ID'
+              },
+              agent_type: {
+                type: 'string',
+                description: 'Type of agent performing deployment'
+              },
+              // Deployment options
+              auto_update_set: {
+                type: 'boolean',
+                description: 'Automatically ensure active Update Set session (default: true)',
+                default: true
+              },
+              fallback_strategy: {
+                type: 'string',
+                enum: ['manual_steps', 'update_set_only', 'none'],
+                description: 'Strategy when direct deployment fails (default: manual_steps)',
+                default: 'manual_steps'
+              },
+              permission_escalation: {
+                type: 'string',
+                enum: ['auto_request', 'manual', 'none'],
+                description: 'How to handle permission errors (default: auto_request)',
+                default: 'auto_request'
+              },
+              deployment_context: {
+                type: 'string',
+                description: 'Context for Update Set naming (e.g., "incident widget", "approval flow")'
+              },
+              // Batch options
+              parallel: {
+                type: 'boolean',
+                description: 'Deploy batch artifacts in parallel',
+                default: false
+              },
+              transaction_mode: {
+                type: 'boolean',
+                description: 'All-or-nothing batch deployment',
+                default: true
+              },
+              dry_run: {
+                type: 'boolean',
+                description: 'Validate without deploying',
+                default: false
+              }
+            },
+            required: ['type']
+          }
+        },
+        {
+          name: 'snow_deployment_status',
+          description: 'Check deployment status and history with agent tracking',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              session_id: { type: 'string', description: 'Session ID to filter by' },
+              limit: { type: 'number', description: 'Number of recent deployments to show', default: 10 },
+            }
+          }
+        },
+        {
+          name: 'snow_validate_deployment',
+          description: 'Validate a deployment before executing with agent coordination',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              type: { type: 'string', enum: ['widget', 'workflow', 'application'] },
+              artifact: { type: 'object', description: 'The artifact to validate' },
+              session_id: { type: 'string' },
+              agent_id: { type: 'string' }
+            },
+            required: ['type', 'artifact']
+          }
+        },
+        {
+          name: 'snow_rollback_deployment',
+          description: 'Rollback a deployment with agent coordination',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              update_set_id: { type: 'string', description: 'Update set sys_id to rollback' },
+              reason: { type: 'string', description: 'Reason for rollback' },
+              session_id: { type: 'string' },
+              agent_id: { type: 'string' }
+            },
+            required: ['update_set_id', 'reason']
+          }
+        }
+      ]
+    }));
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        switch (name) {
+          case 'snow_deploy':
+            return await this.deployWithAgentCoordination(args);
+          case 'snow_deployment_status':
+            return await this.getDeploymentStatusWithContext(args);
+          case 'snow_validate_deployment':
+            return await this.validateDeploymentWithContext(args);
+          case 'snow_rollback_deployment':
+            return await this.rollbackDeploymentWithContext(args);
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        return this.createErrorResponse(
+          `Tool execution failed: ${name}`,
+          error
+        );
+      }
+    });
+  }
+
+  /**
+   * Main deployment method with full agent integration and intelligent workflow
+   */
+  private async deployWithAgentCoordination(args: any): Promise<MCPToolResult> {
+    return await this.executeWithAgentContext(
+      'snow_deploy',
+      args,
+      async (context) => {
+        // 🔧 STEP 1: MANDATORY Authentication and Connection Validation
+        this.logger.info('🔍 Step 1: Validating ServiceNow connection...');
+        const connectionResult = await this.validateServiceNowConnection();
+        if (!connectionResult.success) {
+          return this.createAuthenticationError(connectionResult.error);
+        }
+        
+        // Assert no mock data
+        this.assertNoMockData('deployment');
+
+        // 🔧 STEP 2: Update Set Management
+        this.logger.info('📦 Step 2: Ensuring Update Set for tracking...');
+        await this.reportProgress(context, 15, 'Setting up Update Set');
+        
+        const purpose = args.type === 'batch' ? 'Batch Deployment' : `${args.type} Deployment`;
+        const updateSetId = await this.ensureUpdateSet(context, purpose);
+        
+        if (!updateSetId) {
+          this.logger.warn('⚠️ No Update Set created - changes will not be tracked');
+        }
+
+        // 🔧 STEP 3: Smart Artifact Discovery (DRY principle)
+        if (args.type !== 'batch' && (args.config?.name || args.instruction)) {
+          this.logger.info('🔍 Step 3: Discovering existing artifacts...');
+          await this.reportProgress(context, 25, 'Checking for existing artifacts');
+          
+          const artifactName = args.config?.name || this.extractNameFromInstruction(args.instruction);
+          if (artifactName) {
+            const discovery = await this.discoverExistingArtifacts(
+              args.type,
+              artifactName,
+              this.extractSearchTermsFromInstruction(args.instruction)
+            );
+            
+            if (discovery.found) {
+              this.logger.info(`🔍 Found ${discovery.artifacts.length} existing artifacts`);
+              // Store discovery info in memory for reference
+              await this.memory.updateSharedContext({
+                session_id: context.session_id,
+                context_key: `discovery_${args.type}`,
+                context_value: JSON.stringify({
+                  artifacts: discovery.artifacts,
+                  suggestions: discovery.suggestions,
+                  timestamp: new Date().toISOString()
+                }),
+                created_by_agent: context.agent_id
+              });
+            }
+          }
+        }
+
+        // Get session context for coordination
+        const sessionContext = await this.getSessionContext(context.session_id);
+        
+        // Report progress
+        await this.reportProgress(context, 35, 'Starting deployment');
+
+        try {
+          // Handle different deployment types
+          let result;
+          if (args.type === 'batch') {
+            result = await this.deployBatch(args, context, updateSetId);
+          } else if (args.type === 'xml_update_set') {
+            result = await this.deployXMLUpdateSet(args, context);
+          } else {
+            result = await this.deploySingleArtifact(args, context, updateSetId);
+          }
+          
+          // Add discovery information to successful results (from memory context)
+          try {
+            const discoveryResults = await this.memory.query(
+              'SELECT context_value FROM shared_context WHERE session_id = ? AND context_key = ?',
+              [context.session_id, `discovery_${args.type}`]
+            );
+            
+            if (discoveryResults.length > 0) {
+              const discovery = JSON.parse(discoveryResults[0].context_value);
+              if (discovery.artifacts && discovery.artifacts.length > 0) {
+                result.content.push({
+                  type: 'text',
+                  text: `\n📋 Artifact Discovery Results:\n${discovery.suggestions?.join('\n') || ''}`
+                });
+              }
+            }
+          } catch (discoveryError) {
+            this.logger.warn('Could not retrieve discovery information', discoveryError);
+          }
+          
+          return result;
+          
+        } catch (error) {
+          this.logger.error('Deployment failed, attempting intelligent recovery...', error);
+          
+          // Use enhanced error handling with fallback options
+          const fallbackOptions = {
+            enableRetry: true,
+            enableScopeEscalation: args.permission_escalation === 'auto_request',
+            enableManualSteps: args.fallback_strategy === 'manual_steps'
+          };
+          
+          const errorResult = await this.handleServiceNowError(
+            error,
+            `${args.type} deployment`,
+            context,
+            fallbackOptions
+          );
+          
+          // If error handling provided a recovery solution
+          if (errorResult.content.some(c => c.text?.includes('can_continue: true'))) {
+            this.logger.info('✅ Error recovered - retrying deployment...');
+            
+            try {
+              // Retry the deployment after recovery
+              await this.reportProgress(context, 85, 'Retrying after error recovery');
+              
+              let retryResult;
+              if (args.type === 'batch') {
+                retryResult = await this.deployBatch(args, context, updateSetId);
+              } else {
+                retryResult = await this.deploySingleArtifact(args, context, updateSetId);
+              }
+              
+              // Add recovery note to success result
+              retryResult.content.push({
+                type: 'text',
+                text: '\n✅ Deployment succeeded after automatic error recovery'
+              });
+              
+              return retryResult;
+              
+            } catch (retryError) {
+              this.logger.error('Retry after recovery also failed', retryError);
+              
+              // Request Queen intervention for persistent failures
+              await this.requestQueenIntervention(context, {
+                type: 'deployment_failure_persistent',
+                priority: 'critical',
+                description: `Failed to deploy ${args.type} even after error recovery: ${retryError instanceof Error ? retryError.message : String(retryError)}`,
+                attempted_solutions: ['direct_deployment', 'error_recovery', 'retry_after_recovery']
+              });
+              
+              return errorResult; // Return the error recovery guidance
+            }
+          }
+          
+          // If no automatic recovery possible, request Queen intervention
+          await this.requestQueenIntervention(context, {
+            type: 'deployment_failure',
+            priority: 'high', 
+            description: `Failed to deploy ${args.type}: ${error instanceof Error ? error.message : String(error)}`,
+            attempted_solutions: ['direct_deployment', 'intelligent_error_handling']
+          });
+
+          return errorResult; // Return the error recovery guidance instead of throwing
+        }
+      }
+    );
+  }
+
+  /**
+   * Deploy a single artifact with memory tracking
+   */
+  private async deploySingleArtifact(args: any, context: AgentContext, updateSetId?: string): Promise<MCPToolResult> {
+    const { type, config, instruction } = args;
+
+    // Report planning phase
+    await this.reportProgress(context, 20, 'Planning deployment');
+
+    // Ensure update set if requested
+    let finalUpdateSetId = updateSetId;
+    if (args.auto_update_set !== false && !finalUpdateSetId) {
+      finalUpdateSetId = await this.ensureUpdateSet(context, config?.name || 'artifact');
+      
+      await this.reportProgress(context, 30, 'Update set ready');
+    }
+
+    // Deploy based on type
+    let result: any;
+    await this.reportProgress(context, 50, `Deploying ${type}`);
+
+    switch (type) {
+      case 'widget':
+        result = await this.deployWidget(config, context, finalUpdateSetId);
+        break;
+      case 'flow':
+        result = await this.deployFlow(config || { instruction }, context, finalUpdateSetId);
+        break;
+      case 'application':
+        result = await this.deployApplication(config, context, finalUpdateSetId);
+        break;
+      case 'script':
+      case 'business_rule':
+        result = await this.deployScript(type, config, context, finalUpdateSetId);
+        break;
+      case 'xml_update_set':
+        result = await this.deployXMLUpdateSet(config, context);
+        break;
+      default:
+        throw new Error(`Unsupported deployment type: ${type}`);
+    }
+
+    // Store artifact in memory
+    await this.storeArtifact(context, {
+      sys_id: result.sys_id,
+      type,
+      name: result.name || config?.name || 'unnamed',
+      description: config?.description,
+      config,
+      update_set_id: finalUpdateSetId
+    });
+
+    // Record deployment in history
+    await this.memory.recordDeployment(
+      context.session_id,
+      result.sys_id,
+      type,
+      true,
+      context.agent_id
+    );
+
+    await this.reportProgress(context, 90, 'Finalizing deployment');
+
+    // Notify next agent if needed
+    if (result.next_agent) {
+      await this.notifyHandoff(context, result.next_agent, {
+        type,
+        sys_id: result.sys_id,
+        next_steps: result.next_steps || []
+      });
+    }
+
+    await this.reportProgress(context, 100, 'Deployment complete');
+
+    return this.createSuccessResponse(
+      `Successfully deployed ${type}: ${result.name}`,
+      {
+        sys_id: result.sys_id,
+        name: result.name,
+        update_set_id: finalUpdateSetId,
+        deployment_details: result
+      },
+      {
+        agent_id: context.agent_id,
+        session_id: context.session_id,
+        artifacts_created: [result.sys_id]
+      }
+    );
+  }
+
+  /**
+   * Deploy multiple artifacts in batch
+   */
+  private async deployBatch(args: any, context: AgentContext, updateSetId?: string): Promise<MCPToolResult> {
+    const { artifacts, parallel, transaction_mode, dry_run } = args;
+    
+    if (!artifacts || !Array.isArray(artifacts)) {
+      throw new Error('Batch deployment requires artifacts array');
+    }
+
+    await this.reportProgress(context, 10, `Preparing batch deployment of ${artifacts.length} artifacts`);
+
+    // Dry run validation
+    if (dry_run) {
+      const validationResults = await Promise.all(
+        artifacts.map(artifact => this.validateArtifact(artifact, context))
+      );
+      
+      return this.createSuccessResponse(
+        'Dry run completed - all artifacts validated',
+        { validationResults }
+      );
+    }
+
+    // Create update set for batch
+    const batchUpdateSetId = await this.ensureUpdateSet(context, `Batch deployment`);
+
+    const results: any[] = [];
+    const errors: any[] = [];
+
+    try {
+      if (parallel) {
+        // Deploy in parallel
+        await this.reportProgress(context, 30, 'Deploying artifacts in parallel');
+        
+        const deploymentPromises = artifacts.map((artifact, index) => 
+          this.deploySingleArtifact(
+            { ...artifact, auto_update_set: false },
+            context
+          ).catch(error => {
+            errors.push({ artifact, error: error.message });
+            return null;
+          })
+        );
+
+        const parallelResults = await Promise.all(deploymentPromises);
+        results.push(...parallelResults.filter(r => r !== null));
+
+      } else {
+        // Deploy sequentially
+        for (let i = 0; i < artifacts.length; i++) {
+          const artifact = artifacts[i];
+          await this.reportProgress(
+            context, 
+            30 + (60 * i / artifacts.length), 
+            `Deploying artifact ${i + 1} of ${artifacts.length}`
+          );
+
+          try {
+            const result = await this.deploySingleArtifact(
+              { ...artifact, auto_update_set: false },
+              context
+            );
+            results.push(result);
+          } catch (error) {
+            errors.push({ artifact, error: error instanceof Error ? error.message : String(error) });
+            
+            if (transaction_mode) {
+              // Rollback on error in transaction mode
+              await this.rollbackBatch(results, batchUpdateSetId, context);
+              throw new Error(`Batch deployment failed at artifact ${i + 1}: ${error}`);
+            }
+          }
+        }
+      }
+
+      // Check if we need to rollback
+      if (transaction_mode && errors.length > 0) {
+        await this.rollbackBatch(results, batchUpdateSetId, context);
+        throw new Error(`Batch deployment failed with ${errors.length} errors`);
+      }
+
+      await this.reportProgress(context, 100, 'Batch deployment complete');
+
+      return this.createSuccessResponse(
+        `Batch deployment completed: ${results.length} succeeded, ${errors.length} failed`,
+        {
+          successful: results.length,
+          failed: errors.length,
+          errors: errors.length > 0 ? errors : undefined,
+          update_set_id: batchUpdateSetId
+        }
+      );
+
+    } catch (error) {
+      // Record failed deployment
+      await this.memory.recordDeployment(
+        context.session_id,
+        'batch_deployment',
+        'batch',
+        false,
+        context.agent_id,
+        error instanceof Error ? error.message : String(error)
+      );
+
+      throw error;
+    }
+  }
+
+  /**
+   * Deploy XML Update Set to ServiceNow
+   */
+  private async deployXMLUpdateSet(args: any, context: AgentContext): Promise<MCPToolResult> {
+    const { xml_file_path, auto_preview = true, auto_commit = true } = args;
+    
+    if (!xml_file_path) {
+      throw new Error('XML file path is required for xml_update_set deployment');
+    }
+
+    this.logger.info('🚀 Deploying XML Update Set', { 
+      file: xml_file_path,
+      auto_preview,
+      auto_commit
+    });
+
+    try {
+      // Read XML file
+      await this.reportProgress(context, 20, 'Reading XML file');
+      const xmlContent = await fs.readFile(xml_file_path, 'utf-8');
+
+      // Import XML as remote update set
+      await this.reportProgress(context, 40, 'Importing XML to ServiceNow');
+      const importResponse = await this.client.makeRequest({
+        method: 'POST',
+        url: '/api/now/table/sys_remote_update_set',
+        headers: {
+          'Content-Type': 'application/xml',
+          'Accept': 'application/json'
+        },
+        data: xmlContent
+      });
+
+      if (!importResponse.result || !importResponse.result.sys_id) {
+        throw new Error('Failed to import XML update set');
+      }
+
+      const remoteUpdateSetId = importResponse.result.sys_id;
+      this.logger.info('✅ XML imported successfully', { sys_id: remoteUpdateSetId });
+
+      // Load the update set
+      await this.reportProgress(context, 60, 'Loading update set');
+      await this.client.makeRequest({
+        method: 'PUT',
+        url: `/api/now/table/sys_remote_update_set/${remoteUpdateSetId}`,
+        data: {
+          state: 'loaded'
+        }
+      });
+
+      // Find the loaded update set
+      const loadedResponse = await this.client.makeRequest({
+        method: 'GET',
+        url: '/api/now/table/sys_update_set',
+        params: {
+          sysparm_query: `remote_sys_id=${remoteUpdateSetId}`,
+          sysparm_limit: 1
+        }
+      });
+
+      if (!loadedResponse.result || loadedResponse.result.length === 0) {
+        throw new Error('Failed to find loaded update set');
+      }
+
+      const updateSetId = loadedResponse.result[0].sys_id;
+      const updateSetName = loadedResponse.result[0].name;
+
+      // Preview if requested
+      if (auto_preview) {
+        await this.reportProgress(context, 80, 'Previewing update set');
+        
+        const previewResponse = await this.client.makeRequest({
+          method: 'POST',
+          url: `/api/now/table/sys_update_set/${updateSetId}/preview`
+        });
+
+        // Check preview results
+        const previewProblems = await this.client.makeRequest({
+          method: 'GET',
+          url: '/api/now/table/sys_update_preview_problem',
+          params: {
+            sysparm_query: `update_set=${updateSetId}`,
+            sysparm_limit: 100
+          }
+        });
+
+        if (previewProblems.result && previewProblems.result.length > 0) {
+          const problems = previewProblems.result.map((p: any) => 
+            `- ${p.type}: ${p.description}`
+          ).join('\n');
+
+          if (auto_commit) {
+            this.logger.warn('Preview found problems, skipping auto-commit', { problems });
+          }
+
+          return this.createSuccessResponse(
+            'XML imported and previewed with problems',
+            {
+              update_set_id: updateSetId,
+              update_set_name: updateSetName,
+              preview_status: 'problems_found',
+              problems: previewProblems.result,
+              next_steps: [
+                '1. Review preview problems in ServiceNow',
+                '2. Resolve any issues',
+                '3. Commit manually when ready'
+              ]
+            }
+          );
+        }
+
+        // Commit if clean and requested
+        if (auto_commit) {
+          await this.reportProgress(context, 95, 'Committing update set');
+          
+          await this.client.makeRequest({
+            method: 'POST',
+            url: `/api/now/table/sys_update_set/${updateSetId}/commit`
+          });
+
+          return this.createSuccessResponse(
+            '✅ XML Update Set imported, previewed, and committed successfully!',
+            {
+              update_set_id: updateSetId,
+              update_set_name: updateSetName,
+              status: 'committed',
+              flow_location: 'Flow Designer > Designer',
+              next_steps: [
+                '1. Navigate to Flow Designer',
+                '2. Your flow should be visible in the list',
+                '3. Open the flow to verify all components'
+              ]
+            }
+          );
+        }
+      }
+
+      // Return success without preview/commit
+      return this.createSuccessResponse(
+        'XML Update Set imported successfully',
+        {
+          update_set_id: updateSetId,
+          update_set_name: updateSetName,
+          status: 'imported',
+          next_steps: [
+            '1. Navigate to System Update Sets > Local Update Sets',
+            '2. Find your update set: ' + updateSetName,
+            '3. Click Preview Update Set',
+            '4. Review and commit when ready'
+          ]
+        }
+      );
+
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      
+      if (errorMsg.includes('ENOENT')) {
+        throw new Error(`XML file not found: ${xml_file_path}`);
+      }
+      
+      throw new Error(`Failed to deploy XML update set: ${errorMsg}`);
+    }
+  }
+
+  /**
+   * Deploy widget with agent tracking and intelligent error handling
+   */
+  private async deployWidget(config: any, context: AgentContext, updateSetId?: string): Promise<any> {
+    this.logger.info('Deploying widget', { 
+      name: config.name,
+      agent_id: context.agent_id 
+    });
+
+    try {
+      // Validate widget configuration first
+      const validationErrors = this.validateWidgetConfig(config);
+      if (validationErrors.length > 0) {
+        throw new Error(`Widget validation failed: ${validationErrors.join(', ')}`);
+      }
+
+      // Create widget in ServiceNow
+      const widgetData = {
+        name: config.name,
+        id: config.name,
+        template: config.template || '<div>Widget Template</div>',
+        css: config.css || '',
+        server_script: config.server_script || '',
+        client_script: config.client_script || '',
+        public: false,
+        roles: '',
+        active: true
+      };
+
+      const response = await this.client.createRecord('sp_widget', widgetData);
+      
+      if (!response.success || !response.result) {
+        // Try to provide more specific error information
+        const errorMsg = response.error || 'Unknown error creating widget';
+        
+        // Check for common widget creation issues
+        if (errorMsg.includes('duplicate') || errorMsg.includes('already exists')) {
+          throw new Error(`Widget '${config.name}' already exists. Consider using a different name or updating the existing widget.`);
+        }
+        
+        if (errorMsg.includes('permission') || errorMsg.includes('access') || errorMsg.includes('403')) {
+          throw new Error(`
+🚫 Service Portal Permission Error (403)
+
+Even with sp_admin role, this can happen due to:
+
+1. **OAuth Scope Restrictions**
+   - Go to: System OAuth > Application Registry
+   - Set "Accessible from" to "All application scopes"
+
+2. **Cross-Scope Access** 
+   - Switch to Global scope and try again
+   - Check ACLs on sp_widget table
+
+3. **Missing System Properties**
+   - Ensure: glide.service_portal.enable_api_access = true
+
+4. **Update Set Required**
+   - Widgets must be created in an active Update Set
+   - Use: snow_ensure_active_update_set() first
+
+🔧 Quick Fix: Try deployment with global scope:
+await snow_deploy({
+  type: "widget", 
+  config: {...},
+  scope_preference: "global"
+});
+
+📚 See SERVICE_PORTAL_403_FIX.md for detailed troubleshooting.
+          `);
+        }
+        
+        throw new Error(`Failed to create widget in ServiceNow: ${errorMsg}`);
+      }
+
+      const result = response.result as any;
+      const widgetSysId = Array.isArray(result) ? result[0]?.sys_id : result?.sys_id;
+
+      // 🔧 Track artifact in Update Set
+      if (updateSetId) {
+        try {
+          await this.trackArtifact(widgetSysId, 'widget', config.name, updateSetId);
+        } catch (trackingError) {
+          this.logger.warn('Update Set tracking failed (widget created but not tracked)', trackingError);
+          // Don't fail the deployment, just warn
+        }
+      }
+
+      // Determine next agent based on widget complexity
+      let nextAgent: string | undefined;
+      let nextSteps: string[] = [];
+
+      if (config.requires_styling || config.template?.includes('class=')) {
+        nextAgent = 'ui_specialist';
+        nextSteps = ['responsive_styling', 'accessibility_compliance'];
+      } else if (config.requires_testing) {
+        nextAgent = 'test_agent';
+        nextSteps = ['functional_testing', 'performance_testing'];
+      }
+
+      // Log successful deployment
+      this.logger.info(`✅ Widget deployed successfully: ${config.name} (${widgetSysId})`);
+
+      return {
+        sys_id: widgetSysId,
+        name: config.name,
+        table: 'sp_widget',
+        next_agent: nextAgent,
+        next_steps: nextSteps,
+        success: true
+      };
+
+    } catch (error) {
+      this.logger.error('Widget deployment failed', error);
+      
+      // Use intelligent error handling for specific recovery guidance
+      const errorResult = await this.handleServiceNowError(
+        error,
+        'widget deployment',
+        context,
+        {
+          enableRetry: true,
+          enableScopeEscalation: true,
+          enableManualSteps: true
+        }
+      );
+      
+      // Re-throw with enhanced error information for higher-level handling
+      const enhancedError = new Error(`Widget deployment failed: ${error instanceof Error ? error.message : String(error)}`);
+      (enhancedError as any).errorRecoveryGuidance = errorResult;
+      throw enhancedError;
+    }
+  }
+
+  /**
+   * Validate widget configuration before deployment
+   */
+  private validateWidgetConfig(config: any): string[] {
+    const errors: string[] = [];
+    
+    if (!config.name) {
+      errors.push('Widget name is required');
+    } else {
+      // Check for valid widget naming
+      if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(config.name)) {
+        errors.push('Widget name must start with letter and contain only letters, numbers, and underscores');
+      }
+      
+      if (config.name.length > 40) {
+        errors.push('Widget name must be 40 characters or less');
+      }
+    }
+    
+    if (!config.template) {
+      errors.push('Widget template is required');
+    } else {
+      // Basic HTML validation
+      if (config.template.length > 100000) {
+        errors.push('Widget template is too large (max 100KB)');
+      }
+    }
+    
+    // Validate scripts if provided
+    if (config.server_script && config.server_script.length > 1000000) {
+      errors.push('Server script is too large (max 1MB)');
+    }
+    
+    if (config.client_script && config.client_script.length > 1000000) {
+      errors.push('Client script is too large (max 1MB)');
+    }
+    
+    return errors;
+  }
+
+  /**
+   * Deploy flow with agent tracking
+   */
+  private async deployFlow(config: any, context: AgentContext, updateSetId?: string): Promise<any> {
+    // For flows with natural language instructions, delegate to flow composer
+    if (config.instruction) {
+      // Store instruction in shared context for flow builder agent
+      await this.memory.updateSharedContext({
+        session_id: context.session_id,
+        context_key: 'flow_instruction',
+        context_value: config.instruction,
+        created_by_agent: context.agent_id
+      });
+
+      return {
+        sys_id: `pending_flow_${Date.now()}`,
+        name: 'Flow from instruction',
+        instruction: config.instruction,
+        next_agent: 'flow_builder',
+        next_steps: ['analyze_requirements', 'create_flow_structure', 'deploy_flow']
+      };
+    }
+
+    // Direct flow deployment
+    const flowData = {
+      name: config.name,
+      description: config.description,
+      active: config.active !== false,
+      sys_scope: 'global'
+    };
+
+    const response = await this.client.createRecord('sys_hub_flow', flowData);
+    
+    if (!response.success || !response.result) {
+      throw new Error('Failed to create flow in ServiceNow');
+    }
+
+    const result = response.result as any;
+    return {
+      sys_id: Array.isArray(result) ? result[0]?.sys_id : result?.sys_id,
+      name: config.name,
+      table: 'sys_hub_flow'
+    };
+  }
+
+  /**
+   * Deploy application with scope management
+   */
+  private async deployApplication(config: any, context: AgentContext, updateSetId?: string): Promise<any> {
+    // Determine deployment scope (simplified)
+    const scopeStrategy = config.scope_strategy || 'auto';
+    const targetScope = scopeStrategy === 'auto' ? 'global' : (config.scope || 'global');
+    
+    const appData = {
+      name: config.name,
+      scope: targetScope,
+      short_description: config.short_description,
+      version: config.version,
+      vendor: config.vendor || 'Custom',
+      vendor_prefix: config.vendor_prefix || 'x',
+      active: config.active !== false
+    };
+
+    const response = await this.client.createRecord('sys_app', appData);
+    
+    if (!response.success || !response.result) {
+      throw new Error('Failed to create application in ServiceNow');
+    }
+
+    const result = response.result as any;
+    return {
+      sys_id: Array.isArray(result) ? result[0]?.sys_id : result?.sys_id,
+      name: config.name,
+      scope: targetScope,
+      table: 'sys_app'
+    };
+  }
+
+  /**
+   * Deploy script or business rule
+   */
+  private async deployScript(type: string, config: any, context: AgentContext, updateSetId?: string): Promise<any> {
+    const table = type === 'script' ? 'sys_script' : 'sys_script';
+    
+    const scriptData = {
+      name: config.name,
+      script: config.script,
+      active: config.active !== false,
+      description: config.description
+    };
+
+    const response = await this.client.createRecord(table, scriptData);
+    
+    if (!response.success || !response.result) {
+      throw new Error(`Failed to create ${type} in ServiceNow`);
+    }
+
+    // Scripts often need testing
+    const result = response.result as any;
+    return {
+      sys_id: Array.isArray(result) ? result[0]?.sys_id : result?.sys_id,
+      name: config.name,
+      table,
+      next_agent: 'test_agent',
+      next_steps: ['syntax_validation', 'unit_testing']
+    };
+  }
+
+  /**
+   * Get deployment status with session filtering
+   */
+  private async getDeploymentStatusWithContext(args: any): Promise<MCPToolResult> {
+    return await this.executeWithAgentContext(
+      'snow_deployment_status',
+      args,
+      async (context) => {
+        const session_id = args.session_id || context.session_id;
+        
+        // Get artifacts from memory
+        const artifacts = await this.memory.getSessionArtifacts(session_id);
+        
+        // Get active agents
+        const activeAgents = await this.memory.query(`
+          SELECT * FROM agent_coordination 
+          WHERE session_id = ? 
+          ORDER BY last_activity DESC
+        `, [session_id]);
+
+        // Get recent deployments
+        const deployments = await this.memory.query(`
+          SELECT * FROM deployment_history 
+          WHERE session_id = ? 
+          ORDER BY deployment_time DESC 
+          LIMIT ?
+        `, [session_id, args.limit || 10]);
+
+        return this.createSuccessResponse(
+          `Deployment status for session ${session_id}`,
+          {
+            artifacts: artifacts.length,
+            active_agents: activeAgents.length,
+            recent_deployments: deployments,
+            session_summary: {
+              total_artifacts: artifacts.length,
+              artifact_types: this.groupByType(artifacts),
+              success_rate: this.calculateSuccessRate(deployments)
+            }
+          }
+        );
+      }
+    );
+  }
+
+  /**
+   * Validate deployment with agent context
+   */
+  private async validateDeploymentWithContext(args: any): Promise<MCPToolResult> {
+    return await this.executeWithAgentContext(
+      'snow_validate_deployment',
+      args,
+      async (context) => {
+        const { type, artifact } = args;
+        
+        const validationResult = await this.validateArtifact(
+          { type, config: artifact },
+          context
+        );
+
+        if (validationResult.valid) {
+          return this.createSuccessResponse(
+            `Validation passed for ${type}`,
+            validationResult
+          );
+        } else {
+          // Store validation failure in context
+          await this.memory.updateSharedContext({
+            session_id: context.session_id,
+            context_key: `validation_failure_${type}`,
+            context_value: JSON.stringify(validationResult),
+            created_by_agent: context.agent_id
+          });
+
+          return this.createErrorResponse(
+            `Validation failed for ${type}`,
+            validationResult.errors
+          );
+        }
+      }
+    );
+  }
+
+  /**
+   * Rollback deployment with coordination
+   */
+  private async rollbackDeploymentWithContext(args: any): Promise<MCPToolResult> {
+    return await this.executeWithAgentContext(
+      'snow_rollback_deployment',
+      args,
+      async (context) => {
+        const { update_set_id, reason } = args;
+
+        // Notify all agents about rollback
+        await this.memory.sendAgentMessage({
+          session_id: context.session_id,
+          from_agent: context.agent_id,
+          to_agent: 'all',
+          message_type: 'status_update',
+          content: JSON.stringify({
+            action: 'rollback_initiated',
+            update_set_id,
+            reason
+          })
+        });
+
+        // Perform rollback
+        const rollbackResult = await this.client.updateRecord('sys_update_set', update_set_id, {
+          state: 'reverted',
+          description: `Rolled back: ${reason}`
+        });
+
+        if (rollbackResult.success) {
+          // Update deployment history
+          await this.memory.recordDeployment(
+            context.session_id,
+            update_set_id,
+            'rollback',
+            true,
+            context.agent_id
+          );
+
+          return this.createSuccessResponse(
+            `Successfully rolled back update set ${update_set_id}`,
+            { reason }
+          );
+        } else {
+          throw new Error('Rollback failed');
+        }
+      }
+    );
+  }
+
+  // Helper methods
+
+  private async validateArtifact(artifact: any, context: AgentContext): Promise<any> {
+    // Simplified validation logic
+    const errors: string[] = [];
+    
+    if (!artifact.type) errors.push('Missing artifact type');
+    if (!artifact.config && !artifact.instruction) errors.push('Missing configuration or instruction');
+    
+    if (artifact.type === 'widget') {
+      if (!artifact.config?.name) errors.push('Widget name is required');
+      if (!artifact.config?.template) errors.push('Widget template is required');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: []
+    };
+  }
+
+  private async rollbackBatch(results: any[], updateSetId: string, context: AgentContext): Promise<void> {
+    // Rollback logic for batch deployments
+    for (const result of results) {
+      if (result?.data?.sys_id) {
+        try {
+          await this.client.deleteRecord(result.data.table || 'sys_metadata', result.data.sys_id);
+        } catch (error) {
+          this.logger.error('Failed to rollback artifact', error);
+        }
+      }
+    }
+  }
+
+  private groupByType(artifacts: any[]): Record<string, number> {
+    return artifacts.reduce((acc, artifact) => {
+      acc[artifact.artifact_type] = (acc[artifact.artifact_type] || 0) + 1;
+      return acc;
+    }, {});
+  }
+
+  private calculateSuccessRate(deployments: any[]): number {
+    if (deployments.length === 0) return 0;
+    const successful = deployments.filter(d => d.success).length;
+    return Math.round((successful / deployments.length) * 100);
+  }
+
+  /**
+   * Extract artifact name from natural language instruction
+   */
+  private extractNameFromInstruction(instruction: string): string | null {
+    if (!instruction) return null;
+    
+    // Look for patterns like "create a widget called X" or "make a flow named Y"
+    const patterns = [
+      /(?:create|make|build)\s+(?:a|an)?\s*\w+\s+(?:called|named|for)\s+["']?([^"']+)["']?/i,
+      /(?:create|make|build)\s+["']([^"']+)["']\s+\w+/i,
+      /(?:widget|flow|script|rule|table|application)\s+(?:called|named|for)\s+["']?([^"']+)["']?/i,
+      /"([^"]+)"\s+(?:widget|flow|script|rule|table|application)/i,
+      /'([^']+)'\s+(?:widget|flow|script|rule|table|application)/i
+    ];
+    
+    for (const pattern of patterns) {
+      const match = instruction.match(pattern);
+      if (match && match[1]) {
+        return match[1].trim();
+      }
+    }
+    
+    // Fallback: look for quoted text that might be a name
+    const quotedMatch = instruction.match(/["']([^"']{3,30})["']/);
+    if (quotedMatch && quotedMatch[1]) {
+      return quotedMatch[1].trim();
+    }
+    
+    return null;
+  }
+
+  /**
+   * Extract search terms from instruction for discovery
+   */
+  private extractSearchTermsFromInstruction(instruction: string): string[] {
+    if (!instruction) return [];
+    
+    const terms: string[] = [];
+    
+    // Common keywords that might indicate similar functionality
+    const keywords = [
+      'incident', 'dashboard', 'report', 'approval', 'notification', 'user', 'profile',
+      'management', 'tracking', 'monitoring', 'analytics', 'workflow', 'request',
+      'ticket', 'service', 'catalog', 'portal', 'form', 'table', 'list', 'chart',
+      'graph', 'widget', 'flow', 'automation', 'integration', 'api', 'rest',
+      'email', 'alert', 'escalation', 'assignment', 'routing', 'sla', 'metric'
+    ];
+    
+    const lowercaseInstruction = instruction.toLowerCase();
+    
+    // Extract keywords that appear in the instruction
+    for (const keyword of keywords) {
+      if (lowercaseInstruction.includes(keyword)) {
+        terms.push(keyword);
+      }
+    }
+    
+    // Extract quoted terms
+    const quotedTerms = instruction.match(/["']([^"']{2,20})["']/g);
+    if (quotedTerms) {
+      quotedTerms.forEach(quoted => {
+        const term = quoted.replace(/["']/g, '').trim();
+        if (term.length >= 2 && !terms.includes(term.toLowerCase())) {
+          terms.push(term.toLowerCase());
+        }
+      });
+    }
+    
+    // Extract important words (3+ characters, not common words)
+    const words = lowercaseInstruction.match(/\b[a-z]{3,}\b/g) || [];
+    const commonWords = ['the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'can', 'had', 'her', 'was', 'one', 'our', 'out', 'day', 'get', 'has', 'him', 'his', 'how', 'man', 'new', 'now', 'old', 'see', 'two', 'who', 'boy', 'did', 'its', 'let', 'put', 'say', 'she', 'too', 'use'];
+    
+    for (const word of words) {
+      if (!commonWords.includes(word) && word.length >= 3 && !terms.includes(word)) {
+        terms.push(word);
+      }
+    }
+    
+    return terms.slice(0, 5); // Limit to 5 terms to avoid too many searches
+  }
+}
+
+// Start the server
+if (require.main === module) {
+  const server = new ServiceNowDeploymentMCP();
+  server.start().catch(console.error);
+}