snow-flow 4.6.9 → 5.0.1

package/dist/mcp/servicenow-mcp-unified/shared/tool-registry.js

@@ -0,0 +1,352 @@
+"use strict";
+/**
+ * Tool Registry with Auto-Discovery
+ *
+ * Automatically discovers and registers tools from the tools/ directory.
+ * Supports dynamic loading, validation, and hot-reload during development.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolRegistry = exports.ToolRegistry = void 0;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+class ToolRegistry {
+    constructor(config = {}) {
+        this.tools = new Map();
+        this.discoveryInProgress = false;
+        this.config = {
+            toolsDirectory: path.join(__dirname, '../tools'),
+            autoDiscovery: true,
+            enableCaching: true,
+            cacheMaxAge: 60000, // 1 minute
+            validateOnRegister: true,
+            ...config
+        };
+    }
+    /**
+     * Initialize tool registry with auto-discovery
+     */
+    async initialize() {
+        console.log('[ToolRegistry] Initializing with auto-discovery...');
+        const startTime = Date.now();
+        const result = {
+            toolsFound: 0,
+            toolsRegistered: 0,
+            toolsFailed: 0,
+            domains: [],
+            errors: [],
+            duration: 0
+        };
+        try {
+            // Discover all domains (subdirectories in tools/)
+            const domains = await this.discoverDomains();
+            result.domains = domains;
+            console.log(`[ToolRegistry] Found ${domains.length} domains: ${domains.join(', ')}`);
+            // Discover and register tools from each domain
+            for (const domain of domains) {
+                const domainPath = path.join(this.config.toolsDirectory, domain);
+                const domainResult = await this.discoverDomainTools(domain, domainPath);
+                result.toolsFound += domainResult.toolsFound;
+                result.toolsRegistered += domainResult.toolsRegistered;
+                result.toolsFailed += domainResult.toolsFailed;
+                result.errors.push(...domainResult.errors);
+            }
+            result.duration = Date.now() - startTime;
+            console.log('[ToolRegistry] Discovery complete:');
+            console.log(`  - Tools found: ${result.toolsFound}`);
+            console.log(`  - Tools registered: ${result.toolsRegistered}`);
+            console.log(`  - Tools failed: ${result.toolsFailed}`);
+            console.log(`  - Duration: ${result.duration}ms`);
+            // Export tool definitions to JSON
+            if (result.toolsRegistered > 0) {
+                await this.exportToolDefinitions();
+            }
+        }
+        catch (error) {
+            console.error('[ToolRegistry] Discovery failed:', error.message);
+            throw error;
+        }
+        return result;
+    }
+    /**
+     * Discover all domain directories
+     */
+    async discoverDomains() {
+        try {
+            const entries = await fs.readdir(this.config.toolsDirectory, { withFileTypes: true });
+            return entries
+                .filter(entry => entry.isDirectory())
+                .map(entry => entry.name)
+                .filter(name => !name.startsWith('.') && !name.startsWith('_'));
+        }
+        catch (error) {
+            console.error('[ToolRegistry] Failed to discover domains:', error.message);
+            return [];
+        }
+    }
+    /**
+     * Discover tools in a specific domain
+     */
+    async discoverDomainTools(domain, domainPath) {
+        const result = {
+            toolsFound: 0,
+            toolsRegistered: 0,
+            toolsFailed: 0,
+            domains: [domain],
+            errors: [],
+            duration: 0
+        };
+        try {
+            // Read all .js files in domain directory (except index.js)
+            // In compiled output, we want .js files, not .ts or .d.ts
+            const entries = await fs.readdir(domainPath, { withFileTypes: true });
+            const toolFiles = entries
+                .filter(entry => entry.isFile() &&
+                entry.name.endsWith('.js') &&
+                entry.name !== 'index.js' &&
+                !entry.name.endsWith('.d.ts') && // Exclude TypeScript declaration files
+                !entry.name.endsWith('.js.map') // Exclude source maps
+            )
+                .map(entry => entry.name);
+            result.toolsFound = toolFiles.length;
+            // Load each tool file
+            for (const toolFile of toolFiles) {
+                const toolPath = path.join(domainPath, toolFile);
+                try {
+                    await this.loadAndRegisterTool(domain, toolPath);
+                    result.toolsRegistered++;
+                }
+                catch (error) {
+                    result.toolsFailed++;
+                    result.errors.push({
+                        filePath: toolPath,
+                        error: error.message
+                    });
+                    console.error(`[ToolRegistry] Failed to load ${toolPath}:`, error.message);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[ToolRegistry] Failed to discover tools in ${domain}:`, error.message);
+        }
+        return result;
+    }
+    /**
+     * Load and register a tool from a file
+     */
+    async loadAndRegisterTool(domain, filePath) {
+        try {
+            // Dynamic import of tool module
+            const toolModule = await Promise.resolve(`${filePath}`).then(s => __importStar(require(s)));
+            // Validate tool module exports
+            if (!toolModule.toolDefinition) {
+                throw new Error('Tool module must export "toolDefinition"');
+            }
+            if (!toolModule.execute) {
+                throw new Error('Tool module must export "execute" function');
+            }
+            const definition = toolModule.toolDefinition;
+            const executor = toolModule.execute;
+            // Validate tool definition
+            if (this.config.validateOnRegister) {
+                const validation = this.validateToolDefinition(definition);
+                if (!validation.valid) {
+                    throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
+                }
+            }
+            // Register tool
+            const registeredTool = {
+                definition,
+                executor,
+                domain,
+                filePath,
+                metadata: {
+                    addedAt: new Date(),
+                    version: toolModule.version || '1.0.0',
+                    author: toolModule.author
+                }
+            };
+            this.tools.set(definition.name, registeredTool);
+            console.log(`[ToolRegistry] Registered: ${definition.name} (${domain})`);
+        }
+        catch (error) {
+            throw new Error(`Failed to load tool from ${filePath}: ${error.message}`);
+        }
+    }
+    /**
+     * Validate tool definition structure
+     */
+    validateToolDefinition(definition) {
+        const errors = [];
+        const warnings = [];
+        // Required fields
+        if (!definition.name) {
+            errors.push('Tool name is required');
+        }
+        else if (!/^[a-z_][a-z0-9_]*$/.test(definition.name)) {
+            errors.push('Tool name must match pattern: ^[a-z_][a-z0-9_]*$ (snake_case)');
+        }
+        if (!definition.description) {
+            errors.push('Tool description is required');
+        }
+        else if (definition.description.length < 10) {
+            warnings.push('Tool description should be more descriptive (at least 10 characters)');
+        }
+        if (!definition.inputSchema) {
+            errors.push('Tool inputSchema is required');
+        }
+        else {
+            if (definition.inputSchema.type !== 'object') {
+                errors.push('Tool inputSchema.type must be "object"');
+            }
+            if (!definition.inputSchema.properties) {
+                warnings.push('Tool should define input properties');
+            }
+        }
+        // Check for duplicate names
+        if (this.tools.has(definition.name)) {
+            errors.push(`Tool name "${definition.name}" is already registered`);
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Get all registered tool definitions (for MCP server)
+     */
+    getToolDefinitions() {
+        return Array.from(this.tools.values()).map(tool => tool.definition);
+    }
+    /**
+     * Get registered tool by name
+     */
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Execute a tool by name
+     */
+    async executeTool(name, args, context) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new Error(`Tool not found: ${name}`);
+        }
+        try {
+            console.log(`[ToolRegistry] Executing: ${name}`);
+            const result = await tool.executor(args, context);
+            console.log(`[ToolRegistry] Success: ${name}`);
+            return result;
+        }
+        catch (error) {
+            console.error(`[ToolRegistry] Failed: ${name}`, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Get tools by domain
+     */
+    getToolsByDomain(domain) {
+        return Array.from(this.tools.values()).filter(tool => tool.domain === domain);
+    }
+    /**
+     * Get all domains
+     */
+    getDomains() {
+        const domains = new Set();
+        this.tools.forEach(tool => domains.add(tool.domain));
+        return Array.from(domains).sort();
+    }
+    /**
+     * Get registry statistics
+     */
+    getStatistics() {
+        const domains = this.getDomains();
+        const stats = {
+            totalTools: this.tools.size,
+            totalDomains: domains.length,
+            toolsByDomain: {}
+        };
+        domains.forEach(domain => {
+            stats.toolsByDomain[domain] = this.getToolsByDomain(domain).length;
+        });
+        return stats;
+    }
+    /**
+     * Export tool definitions to JSON file
+     */
+    async exportToolDefinitions() {
+        const configPath = path.join(__dirname, '../config/tool-definitions.json');
+        const metadata = [];
+        this.tools.forEach((tool, name) => {
+            metadata.push({
+                name,
+                domain: tool.domain,
+                description: tool.definition.description,
+                version: tool.metadata.version,
+                author: tool.metadata.author,
+                tags: [tool.domain]
+            });
+        });
+        try {
+            await fs.mkdir(path.dirname(configPath), { recursive: true });
+            await fs.writeFile(configPath, JSON.stringify(metadata, null, 2), 'utf-8');
+            console.log(`[ToolRegistry] Exported ${metadata.length} tool definitions to ${configPath}`);
+        }
+        catch (error) {
+            console.error('[ToolRegistry] Failed to export tool definitions:', error.message);
+        }
+    }
+    /**
+     * Reload tools from disk (for development hot-reload)
+     */
+    async reload() {
+        console.log('[ToolRegistry] Reloading tools...');
+        this.tools.clear();
+        return await this.initialize();
+    }
+    /**
+     * Clear all registered tools
+     */
+    clear() {
+        this.tools.clear();
+        console.log('[ToolRegistry] Cleared all registered tools');
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+// Export singleton instance
+exports.toolRegistry = new ToolRegistry();
+//# sourceMappingURL=tool-registry.js.map

package/dist/mcp/servicenow-mcp-unified/shared/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Shared TypeScript types for Unified MCP Server
+ */
+/**
+ * ServiceNow instance authentication context
+ */
+export interface ServiceNowContext {
+    instanceUrl: string;
+    clientId: string;
+    clientSecret: string;
+    refreshToken?: string;
+    accessToken?: string;
+    tokenExpiry?: number;
+}
+/**
+ * MCP Tool Definition (compliant with Model Context Protocol)
+ */
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+}
+/**
+ * Tool execution function signature
+ */
+export type ToolExecutor = (args: Record<string, any>, context: ServiceNowContext) => Promise<ToolResult>;
+/**
+ * Tool result structure
+ */
+export interface ToolResult {
+    success: boolean;
+    data?: any;
+    error?: string;
+    metadata?: {
+        executionTime?: number;
+        apiCalls?: number;
+        updateSetId?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Registered tool (definition + executor)
+ */
+export interface RegisteredTool {
+    definition: MCPToolDefinition;
+    executor: ToolExecutor;
+    domain: string;
+    filePath: string;
+    metadata: {
+        addedAt: Date;
+        version: string;
+        author?: string;
+    };
+}
+/**
+ * Tool registry configuration
+ */
+export interface ToolRegistryConfig {
+    toolsDirectory: string;
+    autoDiscovery: boolean;
+    enableCaching: boolean;
+    cacheMaxAge: number;
+    validateOnRegister: boolean;
+}
+/**
+ * Error handling configuration
+ */
+export interface RetryConfig {
+    maxAttempts: number;
+    backoff: 'linear' | 'exponential';
+    initialDelay: number;
+    maxDelay: number;
+    retryableErrors: string[];
+}
+/**
+ * OAuth token response from ServiceNow
+ */
+export interface OAuthTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    scope: string;
+}
+/**
+ * ServiceNow API error structure
+ */
+export interface ServiceNowError {
+    error: {
+        message: string;
+        detail: string;
+    };
+    status: string;
+}
+/**
+ * Tool discovery result
+ */
+export interface ToolDiscoveryResult {
+    toolsFound: number;
+    toolsRegistered: number;
+    toolsFailed: number;
+    domains: string[];
+    errors: Array<{
+        filePath: string;
+        error: string;
+    }>;
+    duration: number;
+}
+/**
+ * Validation result for tool definitions
+ */
+export interface ToolValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Tool metadata (for tool-definitions.json)
+ */
+export interface ToolMetadata {
+    name: string;
+    domain: string;
+    description: string;
+    version: string;
+    author?: string;
+    tags?: string[];
+    examples?: Array<{
+        description: string;
+        input: Record<string, any>;
+        expectedOutput?: any;
+    }>;
+}
+/**
+ * Server statistics
+ */
+export interface ServerStats {
+    uptime: number;
+    totalToolCalls: number;
+    successfulCalls: number;
+    failedCalls: number;
+    averageExecutionTime: number;
+    toolUsage: Record<string, number>;
+    errorsByType: Record<string, number>;
+}
+/**
+ * Widget coherence validation result (Snow-Flow specific)
+ */
+export interface WidgetCoherenceResult {
+    coherent: boolean;
+    issues: Array<{
+        type: 'missing_data' | 'orphaned_method' | 'action_mismatch' | 'invalid_reference';
+        severity: 'critical' | 'warning';
+        description: string;
+        location?: string;
+        fix?: string;
+    }>;
+    analysis: {
+        serverInitializedData: string[];
+        clientMethods: string[];
+        htmlReferences: string[];
+        inputActions: string[];
+    };
+}
+/**
+ * ES5 validation result (Snow-Flow specific)
+ */
+export interface ES5ValidationResult {
+    valid: boolean;
+    violations: Array<{
+        type: 'const' | 'let' | 'arrow_function' | 'template_literal' | 'destructuring' | 'for_of' | 'default_param' | 'class';
+        line: number;
+        column: number;
+        code: string;
+        fix: string;
+    }>;
+}
+/**
+ * Update Set context (Snow-Flow specific)
+ */
+export interface UpdateSetContext {
+    sys_id: string;
+    name: string;
+    state: 'in progress' | 'complete' | 'committed';
+    description?: string;
+    isCurrent: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/servicenow-mcp-unified/shared/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Shared TypeScript types for Unified MCP Server
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/mcp/servicenow-mcp-unified/tools/access-control/index.d.ts

@@ -0,0 +1,5 @@
+export { toolDefinition as snow_create_acl_def, execute as snow_create_acl_exec } from './snow_create_acl.js';
+export { toolDefinition as snow_create_acl_role_def, execute as snow_create_acl_role_exec } from './snow_create_acl_role.js';
+export { toolDefinition as snow_test_acl_def, execute as snow_test_acl_exec } from './snow_test_acl.js';
+export { toolDefinition as snow_get_user_roles_def, execute as snow_get_user_roles_exec } from './snow_get_user_roles.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/servicenow-mcp-unified/tools/access-control/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snow_get_user_roles_exec = exports.snow_get_user_roles_def = exports.snow_test_acl_exec = exports.snow_test_acl_def = exports.snow_create_acl_role_exec = exports.snow_create_acl_role_def = exports.snow_create_acl_exec = exports.snow_create_acl_def = void 0;
+var snow_create_acl_js_1 = require("./snow_create_acl.js");
+Object.defineProperty(exports, "snow_create_acl_def", { enumerable: true, get: function () { return snow_create_acl_js_1.toolDefinition; } });
+Object.defineProperty(exports, "snow_create_acl_exec", { enumerable: true, get: function () { return snow_create_acl_js_1.execute; } });
+var snow_create_acl_role_js_1 = require("./snow_create_acl_role.js");
+Object.defineProperty(exports, "snow_create_acl_role_def", { enumerable: true, get: function () { return snow_create_acl_role_js_1.toolDefinition; } });
+Object.defineProperty(exports, "snow_create_acl_role_exec", { enumerable: true, get: function () { return snow_create_acl_role_js_1.execute; } });
+var snow_test_acl_js_1 = require("./snow_test_acl.js");
+Object.defineProperty(exports, "snow_test_acl_def", { enumerable: true, get: function () { return snow_test_acl_js_1.toolDefinition; } });
+Object.defineProperty(exports, "snow_test_acl_exec", { enumerable: true, get: function () { return snow_test_acl_js_1.execute; } });
+var snow_get_user_roles_js_1 = require("./snow_get_user_roles.js");
+Object.defineProperty(exports, "snow_get_user_roles_def", { enumerable: true, get: function () { return snow_get_user_roles_js_1.toolDefinition; } });
+Object.defineProperty(exports, "snow_get_user_roles_exec", { enumerable: true, get: function () { return snow_get_user_roles_js_1.execute; } });
+//# sourceMappingURL=index.js.map

package/dist/mcp/servicenow-mcp-unified/tools/access-control/snow_create_acl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * snow_create_acl
+ */
+import { MCPToolDefinition, ServiceNowContext, ToolResult } from '../../shared/types.js';
+export declare const toolDefinition: MCPToolDefinition;
+export declare function execute(args: any, context: ServiceNowContext): Promise<ToolResult>;
+export declare const version = "1.0.0";
+export declare const author = "Snow-Flow SDK Migration";
+//# sourceMappingURL=snow_create_acl.d.ts.map

package/dist/mcp/servicenow-mcp-unified/tools/access-control/snow_create_acl.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * snow_create_acl
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.author = exports.version = exports.toolDefinition = void 0;
+exports.execute = execute;
+const auth_js_1 = require("../../shared/auth.js");
+const error_handler_js_1 = require("../../shared/error-handler.js");
+exports.toolDefinition = {
+    name: 'snow_create_acl',
+    description: 'Create Access Control List rule',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'ACL name' },
+            operation: { type: 'string', enum: ['read', 'write', 'create', 'delete'], description: 'Operation type' },
+            type: { type: 'string', description: 'ACL type (record/field)' },
+            admin_overrides: { type: 'boolean', default: true },
+            active: { type: 'boolean', default: true }
+        },
+        required: ['name', 'operation']
+    }
+};
+async function execute(args, context) {
+    const { name, operation, type, admin_overrides = true, active = true } = args;
+    try {
+        const client = await (0, auth_js_1.getAuthenticatedClient)(context);
+        const aclData = { name, operation, admin_overrides, active };
+        if (type)
+            aclData.type = type;
+        const response = await client.post('/api/now/table/sys_security_acl', aclData);
+        return (0, error_handler_js_1.createSuccessResult)({ created: true, acl: response.data.result });
+    }
+    catch (error) {
+        return (0, error_handler_js_1.createErrorResult)(error.message);
+    }
+}
+exports.version = '1.0.0';
+exports.author = 'Snow-Flow SDK Migration';
+//# sourceMappingURL=snow_create_acl.js.map

package/dist/mcp/servicenow-mcp-unified/tools/access-control/snow_create_acl_role.d.ts

@@ -0,0 +1,9 @@
+/**
+ * snow_create_acl_role
+ */
+import { MCPToolDefinition, ServiceNowContext, ToolResult } from '../../shared/types.js';
+export declare const toolDefinition: MCPToolDefinition;
+export declare function execute(args: any, context: ServiceNowContext): Promise<ToolResult>;
+export declare const version = "1.0.0";
+export declare const author = "Snow-Flow SDK Migration";
+//# sourceMappingURL=snow_create_acl_role.d.ts.map

package/dist/mcp/servicenow-mcp-unified/tools/access-control/snow_create_acl_role.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * snow_create_acl_role
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.author = exports.version = exports.toolDefinition = void 0;
+exports.execute = execute;
+const auth_js_1 = require("../../shared/auth.js");
+const error_handler_js_1 = require("../../shared/error-handler.js");
+exports.toolDefinition = {
+    name: 'snow_create_acl_role',
+    description: 'Create ACL role association',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            acl: { type: 'string', description: 'ACL sys_id' },
+            role: { type: 'string', description: 'Role sys_id' }
+        },
+        required: ['acl', 'role']
+    }
+};
+async function execute(args, context) {
+    const { acl, role } = args;
+    try {
+        const client = await (0, auth_js_1.getAuthenticatedClient)(context);
+        const aclRoleData = { sys_security_acl: acl, sys_user_role: role };
+        const response = await client.post('/api/now/table/sys_security_acl_role', aclRoleData);
+        return (0, error_handler_js_1.createSuccessResult)({ created: true, acl_role: response.data.result });
+    }
+    catch (error) {
+        return (0, error_handler_js_1.createErrorResult)(error.message);
+    }
+}
+exports.version = '1.0.0';
+exports.author = 'Snow-Flow SDK Migration';
+//# sourceMappingURL=snow_create_acl_role.js.map

package/dist/mcp/servicenow-mcp-unified/tools/access-control/snow_get_user_roles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * snow_get_user_roles
+ */
+import { MCPToolDefinition, ServiceNowContext, ToolResult } from '../../shared/types.js';
+export declare const toolDefinition: MCPToolDefinition;
+export declare function execute(args: any, context: ServiceNowContext): Promise<ToolResult>;
+export declare const version = "1.0.0";
+export declare const author = "Snow-Flow SDK Migration";
+//# sourceMappingURL=snow_get_user_roles.d.ts.map