snow-flow 1.4.23 → 1.4.25

package/README.md

@@ -12,7 +12,7 @@
 
 ## 🚀 **What is Snow-Flow?**
 
-Snow-Flow is the **most advanced ServiceNow intelligence platform** available, combining **14 AI-powered analysis tools** with **multi-agent orchestration** to revolutionize how you work with ServiceNow. Built entirely on **real ServiceNow APIs** with **zero mock data**, Snow-Flow delivers production-ready insights that actually matter.
+Snow-Flow is the **most advanced ServiceNow intelligence platform** available, combining **50+ real MCP tools** with **AI-powered swarm orchestration** to revolutionize how you work with ServiceNow. Built entirely on **real ServiceNow APIs** with **zero mock data**, Snow-Flow delivers production-ready insights through natural language commands.
 
 ### ⚡ **Why Snow-Flow Changes Everything**
 
@@ -24,10 +24,10 @@ Snow-Flow is the **most advanced ServiceNow intelligence platform** available, c
 ❌ Single-threaded workflows
 
 # Snow-Flow approach: AI-powered, fast, accurate
-✅ 80% API call reduction through intelligent batching
+✅ 50+ MCP tools across 8 categories
 ✅ 100% real ServiceNow data analysis
 ✅ Multi-agent parallel execution
-✅ Predictive insights with 90%+ accuracy
+✅ 70% tool success rate (35+ working tools)
 ```
 
 ---
@@ -39,7 +39,7 @@ Snow-Flow is the **most advanced ServiceNow intelligence platform** available, c
 ### ⚡ **The Only Command You Need**
 
 ```bash
-# Instead of manually using 14 different tools...
+# Instead of manually using 50+ different tools...
 snow-flow swarm "Your natural language request here"
 
 # Examples:
@@ -50,8 +50,8 @@ snow-flow swarm "Create documentation for all my custom workflows"
 ```
 
 **Behind the scenes:** Our AI swarm automatically:
-- 🎯 **Analyzes your request** and determines which of the 14 tools to use
-- 🤖 **Spawns specialist agents** (Performance, Process Mining, Security, Analytics)
+- 🎯 **Analyzes your request** and determines which of the 50+ tools to use
+- 🤖 **Spawns specialist agents** (Operations, Analytics, Security, Development)
 - ⚡ **Executes in parallel** for maximum speed and efficiency
 - 🧠 **Learns from each interaction** to improve future responses
 - 📊 **Delivers comprehensive results** with actionable insights
@@ -63,7 +63,7 @@ snow-flow swarm "Create documentation for all my custom workflows"
 <td width="50%">
 
 ### **❌ Traditional Approach**
-- Learn 14 different tool syntaxes
+- Learn 50+ different tool syntaxes
 - Manually coordinate multiple analyses
 - Sequential execution (slow)
 - Miss connections between insights
@@ -85,212 +85,121 @@ snow-flow swarm "Create documentation for all my custom workflows"
 
 ---
 
-## 🛠️ **Underlying AI Capabilities (Automatically Used by Swarm)**
+## 🛠️ **Real Snow-Flow MCP Tools (Automatically Used by Swarm)**
 
 *You don't need to learn these - the swarm uses them automatically based on your natural language requests*
 
-### 📊 **Performance & Analytics**
-
-<details>
-<summary><strong>🚀 Smart Batch API Operations</strong> - 80% API call reduction</summary>
-
-Execute multiple ServiceNow operations in optimized batches with parallel processing and intelligent caching.
-
-```bash
-snow-flow tool snow_batch_api --operations '[
-  {"operation": "query", "table": "incident", "query": "state=1"},
-  {"operation": "update", "table": "incident", "sys_id": "xxx", "data": {"urgency": "1"}}
-]' --parallel true
-```
-
-**Benefits:** Massive performance gains, reduced API limits, transaction safety
-</details>
-
-<details>
-<summary><strong>⚡ Query Performance Analyzer</strong> - Real-time optimization</summary>
-
-Analyze query performance, detect bottlenecks, and get intelligent index recommendations.
-
-```bash
-snow-flow tool snow_analyze_query \
-  --query 'state=1^priority<=2^assigned_to.manager=javascript:gs.getUserID()' \
-  --table incident --analyze_indexes true
-```
-
-**Benefits:** Faster queries, better user experience, reduced system load
-</details>
-
-<details>
-<summary><strong>🔗 Table Relationship Mapping</strong> - Visual dependency insights</summary>
-
-Discover deep relationships across table hierarchies with visual Mermaid diagrams.
-
-```bash
-snow-flow tool snow_get_table_relationships \
-  --table incident --max_depth 3 --generate_visualization true
-```
-
-**Benefits:** Impact analysis, schema understanding, change planning
-</details>
-
-<details>
-<summary><strong>📋 Field Usage Intelligence</strong> - Eliminate technical debt</summary>
-
-Comprehensive field usage analysis across all ServiceNow components with deprecation recommendations.
-
-```bash
-snow-flow tool snow_analyze_field_usage \
-  --table incident --analyze_queries true --unused_threshold_days 90
-```
-
-**Benefits:** Reduced complexity, better performance, cleaner data model
-</details>
-
-### 🔮 **AI-Powered Intelligence**
-
-<details>
-<summary><strong>🎯 Predictive Impact Analysis</strong> - AI-powered change prediction</summary>
-
-Predict the impact of changes with 90%+ accuracy using advanced AI models.
-
-```bash
-snow-flow tool snow_predict_change_impact \
-  --change_type field_change --target_object incident \
-  --change_details '{"field_changes": ["urgency"]}'
-```
-
-**Benefits:** Risk mitigation, confident deployments, reduced downtime
-</details>
-
-<details>
-<summary><strong>🔍 Code Pattern Detector</strong> - Security and performance scanning</summary>
-
-Advanced pattern recognition across all script types with security vulnerability detection.
-
-```bash
-snow-flow tool snow_detect_code_patterns \
-  --analysis_scope '["business_rules", "script_includes"]' \
-  --pattern_categories '["performance", "security"]'
-```
-
-**Benefits:** Better code quality, security hardening, maintainability
-</details>
-
-<details>
-<summary><strong>📚 Auto Documentation Generator</strong> - Intelligent docs from code</summary>
-
-Generate comprehensive documentation automatically from your ServiceNow configuration.
-
-```bash
-snow-flow tool snow_generate_documentation \
-  --documentation_scope '["tables", "workflows"]' --output_format markdown
-```
-
-**Benefits:** Always up-to-date docs, knowledge retention, onboarding acceleration
-</details>
-
-<details>
-<summary><strong>🔧 Intelligent Refactoring</strong> - AI-driven code optimization</summary>
-
-Automatically refactor ServiceNow scripts with modern patterns and security improvements.
-
-```bash
-snow-flow tool snow_refactor_code \
-  --refactoring_scope '["business_rules"]' \
-  --refactoring_goals '["performance", "security"]'
-```
-
-**Benefits:** Modern code patterns, improved performance, enhanced security
-</details>
-
-### 🔄 **Process Mining & Discovery**
-
-<details>
-<summary><strong>🔍 Process Mining Engine</strong> - Real process discovery</summary>
-
-Discover actual processes from ServiceNow event logs with bottleneck identification.
-
-```bash
-snow-flow tool snow_discover_process \
-  --process_type incident_management --analysis_period 30d
-```
-
-**Benefits:** Process optimization, bottleneck elimination, compliance monitoring
-</details>
-
-<details>
-<summary><strong>📊 Workflow Reality Analyzer</strong> - Design vs. reality analysis</summary>
-
-Compare designed workflows with actual execution patterns and performance.
-
-```bash
-snow-flow tool snow_analyze_workflow_execution \
-  --workflow_type incident --analysis_period 7d
-```
-
-**Benefits:** Process improvement, SLA compliance, resource optimization
-</details>
-
-<details>
-<summary><strong>🔗 Cross Table Process Discovery</strong> - Multi-table flow analysis</summary>
-
-Discover processes that span multiple ServiceNow tables with data lineage tracking.
+Snow-Flow provides **50+ real MCP tools** across 8 categories. All tools work directly with your ServiceNow instance via OAuth authentication.
+
+### 🐝 **AI Swarm Orchestration** (4 tools working)
+- `swarm_init` - Initialize AI swarm coordination topology  
+- `agent_spawn` - Create specialized AI agents for different tasks
+- `memory_usage` - Persistent memory across sessions
+- `neural_status` - Neural network pattern effectiveness
+
+### 📊 **ServiceNow Operations** (12+ tools working)
+- ✅ `snow_operational_metrics` - Retrieve operational metrics and analytics
+- ✅ `snow_user_lookup` - Analyze user information with groups and roles
+- ✅ `snow_query_incidents` - Advanced incident querying with filters
+- ✅ `snow_catalog_item_search` - Search catalog items with fuzzy matching
+- ✅ `snow_catalog_item_manager` - Manage service catalog items
+- ✅ `snow_test_flow_with_mock` - Test flows with mock data
+- ✅ `snow_create_user_group` - Create ServiceNow user groups
+- ✅ `snow_create_user` - Create ServiceNow users
+- ✅ `snow_assign_user_to_group` - Manage group memberships
+- ✅ `snow_list_group_members` - List group members
+- Plus 5+ additional operations tools
+
+### 🔧 **Platform Development** (2+ tools working)
+- ✅ `snow_discover_platform_tables` - Discover UI, script, policy tables
+- ✅ `snow_table_schema_discovery` - Comprehensive table schema analysis
+
+### 🔗 **Integration** (10+ tools)
+- ✅ `snow_discover_integration_endpoints` - Find REST/SOAP endpoints
+- `snow_create_rest_message` - Create REST Message endpoints
+- `snow_create_rest_method` - Create REST methods
+- `snow_create_transform_map` - Create Transform Maps
+- `snow_test_integration` - Test integration endpoints
+- Plus 5+ additional integration tools
+
+### 📈 **Reporting & Analytics** (12+ tools)
+- ✅ `snow_discover_reporting_tables` - Table discovery for reporting
+- ✅ `snow_analyze_data_quality` - Data quality assessment (49.3% score example)
+- `snow_create_report` - Create reports with dynamic discovery
+- `snow_create_dashboard` - Create dashboards
+- `snow_create_kpi` - Create KPIs
+- `snow_generate_insights` - Generate data insights
+- Plus 6+ additional analytics tools
+
+### ⚙️ **Automation** (11+ tools)
+- ✅ `snow_discover_automation_jobs` - Find scheduled jobs, notifications, SLAs (54 found)
+- ✅ `snow_discover_events` - Discover ServiceNow events (50 found)
+- ✅ `snow_discover_schedules` - Find system schedules (50 found)
+- `snow_create_scheduled_job` - Create scheduled jobs
+- `snow_create_notification` - Create notifications
+- `snow_create_sla_definition` - Create SLA definitions
+- Plus 5+ additional automation tools
+
+### 🛡️ **Security & Compliance** (12+ tools)
+- `snow_create_security_policy` - Create security policies
+- `snow_create_compliance_rule` - Create compliance rules
+- `snow_run_compliance_scan` - Run compliance scans
+- `snow_security_risk_assessment` - Security risk assessment
+- Plus 8+ additional security tools
+
+### 📦 **Update Set Management** (9+ tools)
+- ✅ `snow_update_set_current` - Get current update set
+- ✅ `snow_update_set_list` - List update sets (5 found)
+- `snow_update_set_create` - Create new update sets
+- `snow_ensure_active_update_set` - Ensure active session
+- Plus 5+ additional update set tools
+
+### 📊 **Tool Status Summary**
+- **✅ Working Tools**: 35+ tools (70% success rate)
+- **⚠️ Limited Tools**: 8 tools (permission/config issues)
+- **🔧 Available Tools**: 50+ total across 8 categories
+
+### 🎯 **Natural Language Examples**
 
 ```bash
-snow-flow tool snow_discover_cross_table_process \
-  --start_table incident --end_tables '["problem", "change_request"]'
-```
+# AI orchestration with real results
+snow-flow swarm "Initialize a 5-agent swarm to analyze my ServiceNow instance"
 
-**Benefits:** End-to-end process visibility, integration optimization
-</details>
+# User management (creates real users)
+snow-flow swarm "Create incident manager group and add 3 users"
 
-<details>
-<summary><strong>📡 Real-Time Process Monitoring</strong> - Live anomaly detection</summary>
+# Data analysis (real quality scores)
+snow-flow swarm "Check data quality for incident table" # Result: 49.3% score
 
-Monitor processes in real-time with ML-powered anomaly detection and predictive alerts.
+# Discovery (finds real endpoints)
+snow-flow swarm "Find all integration endpoints" # Result: 31 REST/SOAP endpoints
 
-```bash
-snow-flow tool snow_monitor_process \
-  --process_name incident_resolution --tables_to_monitor '["incident", "task"]'
+# Automation analysis (real counts)
+snow-flow swarm "Show all automation jobs" # Result: 54 jobs found
 ```
 
-**Benefits:** Proactive issue detection, performance optimization, predictive maintenance
-</details>
+---
 
-### 🏗️ **Architecture & Migration**
+## ⚡ **Quick Start: From Zero to AI-Powered Analysis in 5 Minutes**
 
-<details>
-<summary><strong>📦 Migration Helper</strong> - Automated migration planning</summary>
+### 0. **Prerequisites**
 
-Create comprehensive migration plans with risk assessment and rollback strategies.
+⚠️ **IMPORTANT: Claude Code must be installed first** (Snow-Flow orchestrates through Claude Code):
 
 ```bash
-snow-flow tool snow_create_migration_plan \
-  --migration_type field_restructure --source_table incident
-```
-
-**Benefits:** Safe migrations, reduced risk, automated planning
-</details>
-
-<details>
-<summary><strong>🔍 Deep Table Analysis</strong> - Multi-dimensional insights</summary>
+# 1. Install Claude Code globally
+npm install -g @anthropic-ai/claude-code
 
-Comprehensive table analysis covering structure, data quality, performance, and security.
-
-```bash
-snow-flow tool snow_analyze_table_deep \
-  --table_name incident \
-  --analysis_scope '["structure", "data_quality", "performance"]'
+# 2. (Optional) Skip permissions check for faster setup
+# Only use if you understand the security implications
+claude --dangerously-skip-permissions
 ```
 
-**Benefits:** Complete table understanding, optimization opportunities, quality improvements
-</details>
+**Platform Support:**
+- ✅ **macOS**: Extensively tested and fully supported
+- ⚙️ **Linux/Windows**: Should work but not extensively tested yet
 
----
-
-## ⚡ **Quick Start: From Zero to AI-Powered Analysis in 3 Minutes**
-
-### 1. **Installation**
+### 1. **Install Snow-Flow**
 
 ```bash
 # Install Snow-Flow globally
@@ -311,6 +220,8 @@ snow-flow auth login
 
 ### 3. **Start Using Swarm (The Magic Begins)**
 
+**How it works:** Snow-Flow orchestrates through Claude Code, giving you natural language control over 14 advanced ServiceNow tools.
+
 ```bash
 # Just tell Snow-Flow what you want in natural language:
 
@@ -330,7 +241,7 @@ snow-flow swarm "Create documentation for all my custom workflows and scripts"
 snow-flow swarm "Analyze my instance for security vulnerabilities and compliance issues"
 ```
 
-**That's literally it!** No complex command syntax, no manual tool selection, no configuration. Just natural language requests and Snow-Flow's AI swarm handles everything.
+**That's literally it!** No complex command syntax, no manual tool selection, no configuration. Just natural language requests and Snow-Flow's AI swarm handles everything through Claude Code's intelligent orchestration.
 
 ### 🎯 **What Happens Behind the Scenes**
 
@@ -598,9 +509,9 @@ npm test
 
 ### **Future Vision (2025-2026)**
 - 🧠 **Q4 2025**: Advanced ML models for process optimization and prediction
-- 🎯 **Q1 2026**: Natural language query interface for direct ServiceNow interaction  
-- 🔮 **Q2 2026**: Predictive maintenance capabilities with anomaly detection
-- 🌟 **Q3 2026**: Multi-platform ITSM integration (Jira, Azure DevOps, etc.)
+- 🔮 **Q1 2026**: Predictive maintenance capabilities with anomaly detection  
+- 🌟 **Q2 2026**: Multi-platform ITSM integration (Jira, Azure DevOps, etc.)
+- 🚀 **Q3 2026**: Enhanced natural language processing with domain-specific understanding
 
 ---
 

package/dist/mcp/servicenow-deployment-mcp.js

@@ -682,76 +682,68 @@ class ServiceNowDeploymentMCP {
             if (!args.template || !args.name || !args.title) {
                 throw new Error('Widget must have name, title, and template');
             }
-            // Validate Service Portal permissions before deployment
+            // IMPROVED: Softer Service Portal permissions check with graceful fallback
+            let hasServicePortalAccess = false;
             try {
-                this.logger.info('Validating Service Portal permissions...');
-                // Test access to sp_widget table by attempting to query it
-                const permissionTest = await this.client.searchRecords('sp_widget', 'sys_idISNOTEMPTY', 1);
-                if (!permissionTest.success) {
-                    this.logger.warn('Service Portal read access test failed', permissionTest.error);
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `🚫 **Service Portal Permission Check Failed**
-
-**Issue:** Cannot access Service Portal widgets table (sp_widget)
-
-**Possible Solutions:**
-1. **Re-authenticate with proper scopes:**
-   \`\`\`bash
-   snow-flow auth login
-   \`\`\`
-   (Now includes 'write' and 'admin' permissions)
-
-2. **Verify ServiceNow user roles:**
-   - admin
-   - service_portal_admin 
-   - sp_admin
-   - sp_portal_manager
-
-3. **Check OAuth Application scope:**
-   - Navigate to: System OAuth > Application Registry
-   - Verify "Accessible from" is set to "All application scopes"
-
-**Error:** ${permissionTest.error}
-
-**Alternative:** Use manual deployment - widget code has been prepared for you to copy-paste into ServiceNow manually.`,
-                            },
-                        ],
-                    };
+                this.logger.info('Testing Service Portal access...');
+                // Light permission test - just check if table exists
+                const permissionTest = await this.client.makeRequest({
+                    method: 'GET',
+                    url: '/api/now/table/sp_widget',
+                    params: {
+                        sysparm_limit: 1,
+                        sysparm_fields: 'sys_id'
+                    }
+                });
+                hasServicePortalAccess = permissionTest && !permissionTest.error;
+                if (hasServicePortalAccess) {
+                    this.logger.info('✅ Service Portal access confirmed');
+                }
+                else {
+                    this.logger.warn('⚠️ Limited Service Portal access, will use alternative deployment methods');
                 }
-                this.logger.info('Service Portal permissions validated successfully');
             }
             catch (permissionError) {
-                this.logger.warn('Permission validation failed, proceeding with deployment attempt', permissionError);
+                this.logger.warn('⚠️ Service Portal access test failed, using fallback deployment', permissionError);
+                hasServicePortalAccess = false;
             }
-            // Create widget in ServiceNow with fallback strategies
+            // IMPROVED: Smart deployment strategy based on permissions
             let result;
-            let deploymentMethod = 'direct';
-            try {
-                // Primary deployment strategy: Direct API call
-                result = await this.client.createWidget({
-                    name: args.name,
-                    id: args.name,
-                    title: args.title,
-                    description: args.description || '',
-                    template: args.template,
-                    css: args.css || '',
-                    client_script: args.client_script || '',
-                    server_script: args.server_script || '',
-                    option_schema: args.option_schema || '[]',
-                    demo_data: args.demo_data || '{}',
-                    has_preview: true,
-                    category: args.category || 'custom',
-                });
-                deploymentMethod = 'direct_api';
+            let deploymentMethod = 'unknown';
+            let deploymentSuccess = false;
+            let directError = null;
+            let tableError = null;
+            // Strategy 1: Direct API call (if we have Service Portal access)
+            if (hasServicePortalAccess) {
+                try {
+                    this.logger.info('🚀 Attempting direct widget deployment...');
+                    result = await this.client.createWidget({
+                        name: args.name,
+                        id: args.name,
+                        title: args.title,
+                        description: args.description || '',
+                        template: args.template,
+                        css: args.css || '',
+                        client_script: args.client_script || '',
+                        server_script: args.server_script || '',
+                        option_schema: args.option_schema || '[]',
+                        demo_data: args.demo_data || '{}',
+                        has_preview: true,
+                        category: args.category || 'custom',
+                    });
+                    deploymentMethod = 'direct_api';
+                    deploymentSuccess = true;
+                    this.logger.info('✅ Direct deployment successful');
+                }
+                catch (error) {
+                    directError = error;
+                    this.logger.warn('⚠️ Direct widget deployment failed, trying fallback', directError);
+                }
             }
-            catch (directError) {
-                this.logger.warn('Direct widget deployment failed, trying fallback strategy', directError);
-                // Fallback strategy 1: Create record directly in sp_widget table
+            // Strategy 2: Direct table record creation (fallback)
+            if (!deploymentSuccess) {
                 try {
-                    this.logger.info('Attempting fallback: Direct table record creation');
+                    this.logger.info('🔄 Attempting fallback: Direct table record creation');
                     result = await this.client.createRecord('sp_widget', {
                         name: args.name,
                         id: args.name,
@@ -771,7 +763,8 @@ class ServiceNowDeploymentMCP {
                     });
                     deploymentMethod = 'table_record';
                 }
-                catch (tableError) {
+                catch (error) {
+                    tableError = error;
                     this.logger.warn('Table record creation failed, trying manual step guidance', tableError);
                     // Fallback strategy 2: Provide manual creation steps
                     // Enhanced error _analysis for OAuth permissions
@@ -3711,10 +3704,76 @@ Use \`snow_widget_test\` to run automated tests with different scenarios.`,
                 };
             }
             this.logger.info('Testing widget', { sys_id: args.sys_id });
-            // Fetch the widget
-            const widget = await this.client.getRecord('sp_widget', args.sys_id);
-            if (!widget) {
-                throw new Error(`Widget not found: ${args.sys_id}`);
+            // IMPROVED: Fetch the widget with better error handling
+            let widget;
+            try {
+                widget = await this.client.getRecord('sp_widget', args.sys_id);
+                if (!widget) {
+                    throw new Error(`Widget not found: ${args.sys_id}`);
+                }
+            }
+            catch (error) {
+                // Handle 404 and permission errors gracefully
+                if (error?.response?.status === 404 || error?.message?.includes('404')) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `❌ **Widget Not Found**
+
+**Issue:** Widget with sys_id "${args.sys_id}" does not exist in ServiceNow.
+
+**Possible Solutions:**
+1. **Verify the sys_id:**
+   - Check that the sys_id is correct
+   - Use: \`snow-flow swarm "Find widgets by name"\` to search
+
+2. **Check widget exists:**
+   - Navigate to Service Portal > Widgets in ServiceNow
+   - Search for the widget manually
+
+3. **Create the widget first:**
+   - Use: \`snow_deploy\` to create the widget
+   - Then test it with this tool
+
+**Error Details:** ${error?.message || 'Widget not found'}`
+                            }
+                        ]
+                    };
+                }
+                else if (error?.response?.status === 403 || error?.message?.includes('403')) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `🚫 **Service Portal Access Denied**
+
+**Issue:** Insufficient permissions to access widget "${args.sys_id}".
+
+**Solutions:**
+1. **Check ServiceNow roles:**
+   - admin
+   - service_portal_admin
+   - sp_admin
+
+2. **Re-authenticate with proper scopes:**
+   \`\`\`bash
+   snow-flow auth login
+   \`\`\`
+
+3. **Verify OAuth Application permissions:**
+   - Navigate to: System OAuth > Application Registry
+   - Check "Accessible from" setting
+
+**Error Details:** ${error?.message || 'Permission denied'}`
+                            }
+                        ]
+                    };
+                }
+                else {
+                    // Other errors - rethrow
+                    throw error;
+                }
             }
             const testResults = [];
             // Check dependencies if requested