snow-flow 3.2.3 → 3.3.1

package/dist/mcp/shared/enhanced-base-mcp-server.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Enhanced Base MCP Server with Logging and Token Tracking
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ServiceNowClientWithTracking } from '../../utils/servicenow-client-with-tracking.js';
+import { MCPLogger } from './mcp-logger.js';
+import { SnowOAuth } from '../../utils/snow-oauth.js';
+export interface MCPToolResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}
+export declare abstract class EnhancedBaseMCPServer {
+    protected server: Server;
+    protected client: ServiceNowClientWithTracking;
+    protected logger: MCPLogger;
+    protected oauth: SnowOAuth;
+    protected isAuthenticated: boolean;
+    constructor(name: string, version?: string);
+    /**
+     * Execute tool with enhanced tracking
+     */
+    protected executeTool(toolName: string, handler: () => Promise<MCPToolResult>): Promise<MCPToolResult>;
+    /**
+     * Validate ServiceNow connection with progress
+     */
+    protected validateConnection(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Create standardized response with tracking
+     */
+    protected createResponse(message: string, data?: any): MCPToolResult;
+    /**
+     * Query table with progress tracking
+     */
+    protected queryTable(table: string, query: string, limit?: number): Promise<any>;
+    /**
+     * Create record with tracking
+     */
+    protected createRecord(table: string, data: any): Promise<any>;
+    /**
+     * Get client for direct use
+     */
+    getClient(): ServiceNowClientWithTracking;
+    /**
+     * Get logger for direct use
+     */
+    getLogger(): MCPLogger;
+}
+//# sourceMappingURL=enhanced-base-mcp-server.d.ts.map

package/dist/mcp/shared/enhanced-base-mcp-server.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Enhanced Base MCP Server with Logging and Token Tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnhancedBaseMCPServer = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const servicenow_client_with_tracking_js_1 = require("../../utils/servicenow-client-with-tracking.js");
+const mcp_logger_js_1 = require("./mcp-logger.js");
+const snow_oauth_js_1 = require("../../utils/snow-oauth.js");
+const mcp_auth_middleware_js_1 = require("../../utils/mcp-auth-middleware.js");
+class EnhancedBaseMCPServer {
+    constructor(name, version = '1.0.0') {
+        this.isAuthenticated = false;
+        // Create enhanced logger
+        this.logger = new mcp_logger_js_1.MCPLogger(name);
+        // Log startup
+        this.logger.info(`🚀 Starting ${name} MCP Server v${version}`);
+        // Create enhanced client with tracking
+        this.client = new servicenow_client_with_tracking_js_1.ServiceNowClientWithTracking(this.logger);
+        // Initialize OAuth
+        this.oauth = new snow_oauth_js_1.SnowOAuth();
+        // Create server with capabilities
+        this.server = new index_js_1.Server({
+            name,
+            version,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        // Report initialization
+        this.logger.info(`✅ ${name} initialized and ready`);
+    }
+    /**
+     * Execute tool with enhanced tracking
+     */
+    async executeTool(toolName, handler) {
+        // Start operation tracking
+        this.logger.operationStart(toolName);
+        try {
+            // Ensure authentication
+            await mcp_auth_middleware_js_1.mcpAuth.ensureAuthenticated();
+            this.isAuthenticated = true;
+            // Execute the tool handler
+            const result = await handler();
+            // Log completion
+            this.logger.operationComplete(toolName);
+            // Send token usage summary if in Claude
+            if (process.send) {
+                const usage = this.logger.getTokenUsage();
+                process.send({
+                    type: 'token_usage',
+                    data: {
+                        tool: toolName,
+                        tokens: usage
+                    }
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`Tool execution failed: ${toolName}`, error);
+            // Return error as tool result
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ Error executing ${toolName}: ${error instanceof Error ? error.message : String(error)}`
+                    }]
+            };
+        }
+    }
+    /**
+     * Validate ServiceNow connection with progress
+     */
+    async validateConnection() {
+        this.logger.progress('Validating ServiceNow connection...');
+        try {
+            // Check credentials
+            const credentials = await this.oauth.loadCredentials();
+            if (!credentials) {
+                return {
+                    success: false,
+                    error: 'No ServiceNow credentials found. Run "snow-flow auth login"'
+                };
+            }
+            // Check token
+            if (!credentials.accessToken) {
+                return {
+                    success: false,
+                    error: 'OAuth authentication required. Run "snow-flow auth login"'
+                };
+            }
+            // Test connection
+            this.logger.progress('Testing ServiceNow API connection...');
+            const connectionTest = await this.client.testConnection();
+            if (!connectionTest.success) {
+                return {
+                    success: false,
+                    error: `ServiceNow connection failed: ${connectionTest.error}`
+                };
+            }
+            this.logger.info('✅ ServiceNow connection validated');
+            return { success: true };
+        }
+        catch (error) {
+            this.logger.error('Connection validation failed', error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    /**
+     * Create standardized response with tracking
+     */
+    createResponse(message, data) {
+        // Log the response
+        this.logger.debug('Tool response', { message, hasData: !!data });
+        // Format response
+        const response = {
+            content: [{
+                    type: 'text',
+                    text: message
+                }]
+        };
+        // Add data if provided
+        if (data) {
+            response.content[0].text += '\n\n' + JSON.stringify(data, null, 2);
+        }
+        return response;
+    }
+    /**
+     * Query table with progress tracking
+     */
+    async queryTable(table, query, limit = 10) {
+        this.logger.progress(`Querying ${table} table (limit: ${limit})...`);
+        const result = await this.client.searchRecords(table, query, limit);
+        const recordCount = result?.data?.result?.length || 0;
+        this.logger.info(`Query completed: ${recordCount} records found`);
+        return result;
+    }
+    /**
+     * Create record with tracking
+     */
+    async createRecord(table, data) {
+        this.logger.progress(`Creating ${table} record...`);
+        const result = await this.client.createRecord(table, data);
+        if (result?.success) {
+            this.logger.info(`✅ Created ${table} record: ${result.data?.result?.sys_id}`);
+        }
+        return result;
+    }
+    /**
+     * Get client for direct use
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Get logger for direct use
+     */
+    getLogger() {
+        return this.logger;
+    }
+}
+exports.EnhancedBaseMCPServer = EnhancedBaseMCPServer;
+//# sourceMappingURL=enhanced-base-mcp-server.js.map

package/dist/mcp/shared/mcp-logger.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Enhanced MCP Logger with Token Tracking and Progress Reporting
+ * Sends logs to stderr so they appear in Claude Code console
+ */
+interface TokenUsage {
+    input: number;
+    output: number;
+    total: number;
+}
+export declare class MCPLogger {
+    private name;
+    private tokenUsage;
+    private startTime;
+    private lastProgressTime;
+    private progressInterval;
+    constructor(name: string);
+    /**
+     * Log to stderr with proper formatting
+     */
+    private log;
+    /**
+     * Start progress indicator for long-running operations
+     */
+    private startProgressIndicator;
+    /**
+     * Stop progress indicator
+     */
+    stopProgress(): void;
+    /**
+     * Log info message
+     */
+    info(message: string, data?: any): void;
+    /**
+     * Log warning message
+     */
+    warn(message: string, data?: any): void;
+    /**
+     * Log error message
+     */
+    error(message: string, error?: any): void;
+    /**
+     * Log debug message
+     */
+    debug(message: string, data?: any): void;
+    /**
+     * Log progress update
+     */
+    progress(message: string): void;
+    /**
+     * Track API call
+     */
+    trackAPICall(operation: string, table?: string, recordCount?: number): void;
+    /**
+     * Add token usage
+     */
+    addTokens(input: number, output: number): void;
+    /**
+     * Log operation start
+     */
+    operationStart(operation: string, params?: any): void;
+    /**
+     * Log operation complete
+     */
+    operationComplete(operation: string, result?: any): void;
+    /**
+     * Get token usage
+     */
+    getTokenUsage(): TokenUsage;
+    /**
+     * Reset token usage
+     */
+    resetTokens(): void;
+}
+export declare function getGlobalLogger(name?: string): MCPLogger;
+/**
+ * Log formatter for consistent output
+ */
+export declare function formatLogMessage(level: string, message: string, data?: any): string;
+export {};
+//# sourceMappingURL=mcp-logger.d.ts.map

package/dist/mcp/shared/mcp-logger.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Enhanced MCP Logger with Token Tracking and Progress Reporting
+ * Sends logs to stderr so they appear in Claude Code console
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPLogger = void 0;
+exports.getGlobalLogger = getGlobalLogger;
+exports.formatLogMessage = formatLogMessage;
+class MCPLogger {
+    constructor(name) {
+        this.tokenUsage = { input: 0, output: 0, total: 0 };
+        this.startTime = Date.now();
+        this.lastProgressTime = Date.now();
+        this.progressInterval = null;
+        this.name = name;
+        // Start progress indicator
+        this.startProgressIndicator();
+    }
+    /**
+     * Log to stderr with proper formatting
+     */
+    log(level, message, data) {
+        const timestamp = new Date().toISOString();
+        const logEntry = {
+            timestamp,
+            level,
+            service: this.name,
+            message,
+            data,
+            tokens: this.tokenUsage.total,
+            duration: Math.round((Date.now() - this.startTime) / 1000)
+        };
+        // Send to stderr so it appears in console
+        console.error(`[${this.name}] ${level}: ${message}`, data ? JSON.stringify(data, null, 2) : '');
+        // Also send structured log for potential parsing
+        if (process.send) {
+            process.send({
+                type: 'log',
+                data: logEntry
+            });
+        }
+    }
+    /**
+     * Start progress indicator for long-running operations
+     */
+    startProgressIndicator() {
+        // Send progress every 2 seconds
+        this.progressInterval = setInterval(() => {
+            const duration = Math.round((Date.now() - this.startTime) / 1000);
+            if (duration > 0) {
+                this.progress(`Operation in progress... (${duration}s elapsed, ${this.tokenUsage.total} tokens used)`);
+            }
+        }, 2000);
+    }
+    /**
+     * Stop progress indicator
+     */
+    stopProgress() {
+        if (this.progressInterval) {
+            clearInterval(this.progressInterval);
+            this.progressInterval = null;
+        }
+    }
+    /**
+     * Log info message
+     */
+    info(message, data) {
+        this.log('INFO', message, data);
+    }
+    /**
+     * Log warning message
+     */
+    warn(message, data) {
+        this.log('WARN', message, data);
+    }
+    /**
+     * Log error message
+     */
+    error(message, error) {
+        const errorData = error instanceof Error ? {
+            message: error.message,
+            stack: error.stack,
+            name: error.name
+        } : error;
+        this.log('ERROR', message, errorData);
+    }
+    /**
+     * Log debug message
+     */
+    debug(message, data) {
+        if (process.env.DEBUG === 'true' || process.env.NODE_ENV === 'development') {
+            this.log('DEBUG', message, data);
+        }
+    }
+    /**
+     * Log progress update
+     */
+    progress(message) {
+        // Only log progress if enough time has passed
+        const now = Date.now();
+        if (now - this.lastProgressTime > 1000) {
+            this.lastProgressTime = now;
+            console.error(`⏳ [${this.name}] ${message}`);
+        }
+    }
+    /**
+     * Track API call
+     */
+    trackAPICall(operation, table, recordCount) {
+        const message = `🔄 API Call: ${operation}${table ? ` on ${table}` : ''}${recordCount ? ` (${recordCount} records)` : ''}`;
+        this.info(message);
+        // Estimate token usage (rough approximation)
+        const estimatedTokens = recordCount ? recordCount * 50 : 100;
+        this.addTokens(estimatedTokens, 50);
+    }
+    /**
+     * Add token usage
+     */
+    addTokens(input, output) {
+        this.tokenUsage.input += input;
+        this.tokenUsage.output += output;
+        this.tokenUsage.total = this.tokenUsage.input + this.tokenUsage.output;
+        // Report token usage
+        if (this.tokenUsage.total > 0) {
+            console.error(`📊 [${this.name}] Tokens used: ${this.tokenUsage.total} (in: ${this.tokenUsage.input}, out: ${this.tokenUsage.output})`);
+        }
+    }
+    /**
+     * Log operation start
+     */
+    operationStart(operation, params) {
+        this.startTime = Date.now();
+        this.info(`🚀 Starting: ${operation}`, params);
+    }
+    /**
+     * Log operation complete
+     */
+    operationComplete(operation, result) {
+        const duration = Math.round((Date.now() - this.startTime) / 1000);
+        this.stopProgress();
+        this.info(`✅ Completed: ${operation} (${duration}s, ${this.tokenUsage.total} tokens)`, result);
+        // Send final token report
+        if (this.tokenUsage.total > 0) {
+            console.error(`
+═══════════════════════════════════════════════════════════
+📊 ${this.name} - Operation Complete
+─────────────────────────────────────────────────────────
+⏱️  Duration: ${duration} seconds
+🔢 Tokens Used: ${this.tokenUsage.total}
+   ├─ Input: ${this.tokenUsage.input}
+   └─ Output: ${this.tokenUsage.output}
+🎯 Operation: ${operation}
+═══════════════════════════════════════════════════════════
+      `);
+        }
+    }
+    /**
+     * Get token usage
+     */
+    getTokenUsage() {
+        return { ...this.tokenUsage };
+    }
+    /**
+     * Reset token usage
+     */
+    resetTokens() {
+        this.tokenUsage = { input: 0, output: 0, total: 0 };
+    }
+}
+exports.MCPLogger = MCPLogger;
+/**
+ * Create a singleton logger instance for consistent logging
+ */
+let globalLogger = null;
+function getGlobalLogger(name) {
+    if (!globalLogger) {
+        globalLogger = new MCPLogger(name || 'MCP-Server');
+    }
+    return globalLogger;
+}
+/**
+ * Log formatter for consistent output
+ */
+function formatLogMessage(level, message, data) {
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    const dataStr = data ? ` | ${JSON.stringify(data)}` : '';
+    return `[${timestamp}] ${level.padEnd(5)} | ${message}${dataStr}`;
+}
+//# sourceMappingURL=mcp-logger.js.map

package/dist/utils/servicenow-client-with-tracking.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ServiceNow Client Wrapper with Token & Progress Tracking
+ */
+import { ServiceNowClient } from './servicenow-client.js';
+import { MCPLogger } from '../mcp/shared/mcp-logger.js';
+export declare class ServiceNowClientWithTracking extends ServiceNowClient {
+    private mcpLogger;
+    constructor(logger?: MCPLogger);
+    /**
+     * Override makeRequest to add tracking
+     */
+    makeRequest(config: any): Promise<any>;
+    /**
+     * Override searchRecords to add tracking
+     */
+    searchRecords(table: string, query: string, limit?: number): Promise<any>;
+    /**
+     * Override createRecord to add tracking
+     */
+    createRecord(table: string, data: any): Promise<any>;
+    /**
+     * Override updateRecord to add tracking
+     */
+    updateRecord(table: string, sysId: string, data: any): Promise<any>;
+    /**
+     * Override getRecord to add tracking
+     */
+    getRecord(table: string, sysId: string, fields?: string[]): Promise<any>;
+    /**
+     * Extract table name from URL
+     */
+    private extractTableFromUrl;
+    /**
+     * Get logger for external use
+     */
+    getLogger(): MCPLogger;
+}
+//# sourceMappingURL=servicenow-client-with-tracking.d.ts.map

package/dist/utils/servicenow-client-with-tracking.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * ServiceNow Client Wrapper with Token & Progress Tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceNowClientWithTracking = void 0;
+const servicenow_client_js_1 = require("./servicenow-client.js");
+const mcp_logger_js_1 = require("../mcp/shared/mcp-logger.js");
+class ServiceNowClientWithTracking extends servicenow_client_js_1.ServiceNowClient {
+    constructor(logger) {
+        super();
+        this.mcpLogger = logger || new mcp_logger_js_1.MCPLogger('ServiceNow-API');
+    }
+    /**
+     * Override makeRequest to add tracking
+     */
+    async makeRequest(config) {
+        const operation = `${config.method || 'GET'} ${config.url || config.endpoint}`;
+        const table = this.extractTableFromUrl(config.url || config.endpoint);
+        // Log API call start
+        this.mcpLogger.trackAPICall(operation, table);
+        this.mcpLogger.progress(`Calling ServiceNow API: ${operation}`);
+        try {
+            // Call parent method
+            const result = await super.makeRequest(config);
+            // Estimate tokens based on response size
+            if (result.data) {
+                const responseSize = JSON.stringify(result.data).length;
+                const estimatedTokens = Math.ceil(responseSize / 4); // Rough estimate: 4 chars per token
+                this.mcpLogger.addTokens(50, estimatedTokens); // 50 for request, response based on size
+            }
+            return result;
+        }
+        catch (error) {
+            this.mcpLogger.error(`API call failed: ${operation}`, error);
+            throw error;
+        }
+    }
+    /**
+     * Override searchRecords to add tracking
+     */
+    async searchRecords(table, query, limit = 10) {
+        this.mcpLogger.operationStart(`Search ${table}`, { query, limit });
+        try {
+            const result = await super.searchRecords(table, query, limit);
+            // Track record count
+            const recordCount = result?.data?.result?.length || 0;
+            this.mcpLogger.info(`Found ${recordCount} ${table} records`);
+            // Estimate tokens
+            if (result?.data?.result) {
+                const dataSize = JSON.stringify(result.data.result).length;
+                const estimatedTokens = Math.ceil(dataSize / 4);
+                this.mcpLogger.addTokens(100, estimatedTokens);
+            }
+            this.mcpLogger.operationComplete(`Search ${table}`, { count: recordCount });
+            return result;
+        }
+        catch (error) {
+            this.mcpLogger.error(`Search failed for ${table}`, error);
+            throw error;
+        }
+    }
+    /**
+     * Override createRecord to add tracking
+     */
+    async createRecord(table, data) {
+        this.mcpLogger.operationStart(`Create ${table} record`, { fields: Object.keys(data).length });
+        try {
+            const result = await super.createRecord(table, data);
+            // Estimate tokens
+            const requestSize = JSON.stringify(data).length;
+            const responseSize = JSON.stringify(result).length;
+            this.mcpLogger.addTokens(Math.ceil(requestSize / 4), Math.ceil(responseSize / 4));
+            this.mcpLogger.operationComplete(`Create ${table} record`, {
+                sys_id: result?.data?.result?.sys_id
+            });
+            return result;
+        }
+        catch (error) {
+            this.mcpLogger.error(`Failed to create ${table} record`, error);
+            throw error;
+        }
+    }
+    /**
+     * Override updateRecord to add tracking
+     */
+    async updateRecord(table, sysId, data) {
+        this.mcpLogger.operationStart(`Update ${table} record`, { sys_id: sysId });
+        try {
+            const result = await super.updateRecord(table, sysId, data);
+            // Estimate tokens
+            const requestSize = JSON.stringify(data).length;
+            const responseSize = JSON.stringify(result).length;
+            this.mcpLogger.addTokens(Math.ceil(requestSize / 4), Math.ceil(responseSize / 4));
+            this.mcpLogger.operationComplete(`Update ${table} record`);
+            return result;
+        }
+        catch (error) {
+            this.mcpLogger.error(`Failed to update ${table} record`, error);
+            throw error;
+        }
+    }
+    /**
+     * Override getRecord to add tracking
+     */
+    async getRecord(table, sysId, fields) {
+        this.mcpLogger.progress(`Fetching ${table} record: ${sysId}`);
+        try {
+            const result = await super.getRecord(table, sysId, fields);
+            // Estimate tokens
+            if (result?.data?.result) {
+                const responseSize = JSON.stringify(result.data.result).length;
+                this.mcpLogger.addTokens(50, Math.ceil(responseSize / 4));
+            }
+            return result;
+        }
+        catch (error) {
+            this.mcpLogger.error(`Failed to get ${table} record`, error);
+            throw error;
+        }
+    }
+    /**
+     * Extract table name from URL
+     */
+    extractTableFromUrl(url) {
+        const match = url.match(/\/table\/([^/?]+)/);
+        return match ? match[1] : undefined;
+    }
+    /**
+     * Get logger for external use
+     */
+    getLogger() {
+        return this.mcpLogger;
+    }
+}
+exports.ServiceNowClientWithTracking = ServiceNowClientWithTracking;
+//# sourceMappingURL=servicenow-client-with-tracking.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "snow-flow",
-  "version": "3.2.3",
-  "description": "Snow-Flow v3.2.3: ServiceNow development platform with 180+ MCP tools. One command to rule them all: 'snow-flow swarm'. Includes ATF Testing, Knowledge Management, Service Catalog, Change Management, Virtual Agent, Performance Analytics, Flow Designer, Agent Workspace, Mobile, CMDB/Discovery, Event Management, HR Service Delivery, Customer Service Management, and DevOps integration. All tools use official ServiceNow REST APIs across 17 specialized MCP servers.",
+  "version": "3.3.1",
+  "description": "Snow-Flow v3.3.1: ServiceNow development platform with 180+ MCP tools. Enhanced MCP servers with real-time progress indicators, detailed token tracking, and comprehensive operation logging. Supports ATF Testing, Knowledge Management, Service Catalog, Change Management, Virtual Agent, Performance Analytics, Flow Designer, Agent Workspace, Mobile, CMDB/Discovery, Event Management, HR Service Delivery, Customer Service Management, and DevOps integration. All tools use official ServiceNow REST APIs across 17 specialized MCP servers with full visibility into API operations.",
   "main": "dist/index.js",
   "type": "commonjs",
   "bin": {