snow-flow 3.2.2 → 3.3.0

package/README.md

@@ -10,6 +10,31 @@
 
 Snow-Flow is an AI-powered development platform for ServiceNow that provides 180+ MCP tools and multi-agent coordination. It enables developers and administrators to interact with ServiceNow through natural language commands and automated workflows.
 
+## Quick Start - One Command to Rule Them All
+
+### 🚀 The Swarm Command
+The simplest way to use Snow-Flow is with the swarm command. Just describe what you want in natural language:
+
+```bash
+# Basic usage - no flags needed!
+snow-flow swarm "Create an incident dashboard with real-time updates"
+```
+
+This single command automatically:
+- Spawns multiple specialized AI agents
+- Discovers existing ServiceNow artifacts
+- Creates complete working solutions
+- Deploys directly to your instance
+- Handles all technical complexity
+
+More examples:
+```bash
+snow-flow swarm "Build employee onboarding workflow"
+snow-flow swarm "Create knowledge base for IT support"
+snow-flow swarm "Set up change management process"
+snow-flow swarm "Analyze last month's incident patterns"
+```
+
 ## Core Functionality
 
 Snow-Flow connects directly to ServiceNow instances through OAuth 2.0 authentication and provides:
@@ -19,6 +44,20 @@ Snow-Flow connects directly to ServiceNow instances through OAuth 2.0 authentica
 - Natural language interface for ServiceNow operations
 - Machine learning capabilities using TensorFlow.js
 - Process automation and workflow optimization
+- Real-time logging and token tracking for API operations
+
+### API Operation Visibility
+
+Snow-Flow displays detailed information during API calls:
+
+```
+⏳ Operation in progress... (2s elapsed, 150 tokens used)
+🔄 API Call: GET /api/now/table/incident (10 records)
+📊 Tokens used: 450 (in: 100, out: 350)
+✅ Operation complete in 3 seconds
+```
+
+MCP operations run in separate processes and their logs are sent to stderr for visibility in the console.
 
 ## ServiceNow API Integration
 
@@ -369,8 +408,43 @@ snow-flow auth login
 snow-flow auth test
 ```
 
+### Troubleshooting: Claude Code stdio Error
+
+If you encounter a stdio/permissions error when using Snow-Flow with Claude Code:
+
+```bash
+# 1. Fix Claude permissions
+claude --dangerously-skip-permissions
+
+# 2. Activate Claude Code
+# Open Claude Code and ensure it's activated with your account
+
+# 3. Login to Claude
+# Sign in with your Claude account in the Claude Code interface
+
+# 4. Close Claude Code completely
+# Make sure Claude Code is fully closed before proceeding
+
+# 5. Now run Snow-Flow swarm
+snow-flow swarm "Your ServiceNow task here"
+```
+
+This resolves the common "stdio" error that occurs when Claude Code doesn't have proper permissions to communicate with MCP servers.
+
 ## Usage Examples
 
+### Swarm Command (Recommended)
+```bash
+# The simplest way - just describe what you want!
+snow-flow swarm "Create incident management dashboard"
+
+# No flags needed for basic usage
+snow-flow swarm "Build service catalog for laptop requests"
+
+# Advanced usage with optional flags
+snow-flow swarm "Optimize incident resolution process" --monitor --parallel
+```
+
 ### Natural Language Commands
 ```bash
 # Create an incident dashboard
@@ -395,19 +469,24 @@ snow-flow deploy widget --name "SLA Dashboard" --template dashboard
 snow-flow generate docs --scope "incident_management"
 ```
 
-### Swarm Coordination
+### Advanced Swarm Options
 ```bash
-# Multi-agent development
+# With specific strategy
 snow-flow swarm "Build complete HR service portal" \
   --strategy development \
   --mode hierarchical \
   --max-agents 8
 
-# Analysis swarm
+# Parallel analysis
 snow-flow swarm "Analyze system performance bottlenecks" \
   --strategy analysis \
   --mode mesh \
   --parallel
+
+# With monitoring
+snow-flow swarm "Deploy production changes" \
+  --monitor \
+  --auto-rollback
 ```
 
 ## Configuration

package/dist/dynamic-version.js

@@ -36,7 +36,7 @@ function getDynamicVersion() {
         console.warn('Warning: Could not read version from package.json:', error);
     }
     // Fallback to hardcoded version
-    return '3.2.2';
+    return '3.3.0';
 }
 // Export a constant that uses the dynamic version
 exports.VERSION = getDynamicVersion();

package/dist/mcp/servicenow-knowledge-catalog-mcp-enhanced.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * ServiceNow Knowledge Management & Service Catalog MCP Server - ENHANCED VERSION
+ * With logging, token tracking, and progress indicators
+ */
+export {};
+//# sourceMappingURL=servicenow-knowledge-catalog-mcp-enhanced.d.ts.map

package/dist/mcp/servicenow-knowledge-catalog-mcp-enhanced.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * ServiceNow Knowledge Management & Service Catalog MCP Server - ENHANCED VERSION
+ * With logging, token tracking, and progress indicators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const enhanced_base_mcp_server_js_1 = require("./shared/enhanced-base-mcp-server.js");
+const mcp_config_manager_js_1 = require("../utils/mcp-config-manager.js");
+class ServiceNowKnowledgeCatalogMCPEnhanced extends enhanced_base_mcp_server_js_1.EnhancedBaseMCPServer {
+    constructor() {
+        super('servicenow-knowledge-catalog-enhanced', '2.0.0');
+        this.config = mcp_config_manager_js_1.mcpConfig.getConfig();
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: [
+                // Knowledge Management Tools
+                {
+                    name: 'snow_create_knowledge_article',
+                    description: 'Creates a knowledge article in ServiceNow Knowledge Base using kb_knowledge table.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            short_description: { type: 'string', description: 'Article title' },
+                            text: { type: 'string', description: 'Article content (HTML supported)' },
+                            kb_knowledge_base: { type: 'string', description: 'Knowledge base sys_id or name' },
+                            kb_category: { type: 'string', description: 'Category sys_id or name' },
+                            article_type: { type: 'string', description: 'Type: text, html, wiki' },
+                            workflow_state: { type: 'string', description: 'State: draft, review, published, retired' },
+                            valid_to: { type: 'string', description: 'Expiration date (YYYY-MM-DD)' },
+                            meta_description: { type: 'string', description: 'SEO meta description' },
+                            keywords: { type: 'array', items: { type: 'string' }, description: 'Search keywords' },
+                            author: { type: 'string', description: 'Author user sys_id or username' }
+                        },
+                        required: ['short_description', 'text']
+                    }
+                },
+                {
+                    name: 'snow_search_knowledge',
+                    description: 'Searches knowledge articles in kb_knowledge table with full-text search.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: { type: 'string', description: 'Search query text' },
+                            kb_knowledge_base: { type: 'string', description: 'Filter by knowledge base' },
+                            kb_category: { type: 'string', description: 'Filter by category' },
+                            workflow_state: { type: 'string', description: 'Filter by state (published, draft, etc.)' },
+                            limit: { type: 'number', description: 'Maximum results to return', default: 10 },
+                            include_content: { type: 'boolean', description: 'Include full article content', default: false }
+                        },
+                        required: ['query']
+                    }
+                },
+                // ... other tools omitted for brevity
+            ]
+        }));
+        this.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            try {
+                const { name, arguments: args } = request.params;
+                // Execute with enhanced tracking
+                return await this.executeTool(name, async () => {
+                    switch (name) {
+                        case 'snow_create_knowledge_article':
+                            return await this.createKnowledgeArticle(args);
+                        case 'snow_search_knowledge':
+                            return await this.searchKnowledge(args);
+                        default:
+                            throw new types_js_1.McpError(types_js_1.ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                    }
+                });
+            }
+            catch (error) {
+                if (error instanceof types_js_1.McpError)
+                    throw error;
+                throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `Tool execution failed: ${error}`);
+            }
+        });
+    }
+    /**
+     * Create Knowledge Article with enhanced tracking
+     */
+    async createKnowledgeArticle(args) {
+        this.logger.info('Creating knowledge article...', {
+            title: args.short_description,
+            hasContent: !!args.text,
+            contentLength: args.text?.length
+        });
+        // Validate connection
+        const connCheck = await this.validateConnection();
+        if (!connCheck.success) {
+            return this.createResponse(`❌ Connection failed: ${connCheck.error}`);
+        }
+        // Progress indicator
+        this.logger.progress('Building knowledge article data...');
+        const articleData = {
+            short_description: args.short_description,
+            text: args.text,
+            kb_knowledge_base: args.kb_knowledge_base || '',
+            kb_category: args.kb_category || '',
+            article_type: args.article_type || 'text',
+            workflow_state: args.workflow_state || 'draft',
+            valid_to: args.valid_to || '',
+            meta_description: args.meta_description || '',
+            keywords: args.keywords?.join(',') || '',
+            author: args.author || ''
+        };
+        this.logger.progress('Creating article in ServiceNow...');
+        // Create with tracking
+        const response = await this.createRecord('kb_knowledge', articleData);
+        if (!response.success) {
+            this.logger.error('Failed to create knowledge article', response.error);
+            return this.createResponse(`❌ Failed to create article: ${response.error}`);
+        }
+        // Success with details
+        const result = response.data;
+        this.logger.info('✅ Knowledge article created successfully', {
+            sys_id: result.sys_id,
+            number: result.number,
+            title: args.short_description
+        });
+        return this.createResponse(`✅ Knowledge Article created successfully!
+
+📚 **${args.short_description}**
+🆔 sys_id: ${result.sys_id}
+📋 Number: ${result.number}
+📊 State: ${args.workflow_state || 'draft'}
+📝 Type: ${args.article_type || 'text'}
+${args.kb_knowledge_base ? `📁 Knowledge Base: ${args.kb_knowledge_base}` : ''}
+${args.kb_category ? `🏷️ Category: ${args.kb_category}` : ''}
+${args.valid_to ? `📅 Valid Until: ${args.valid_to}` : ''}
+
+✨ Article created and ready for review!`);
+    }
+    /**
+     * Search Knowledge with enhanced tracking
+     */
+    async searchKnowledge(args) {
+        this.logger.info('Searching knowledge articles...', {
+            query: args.query,
+            limit: args.limit || 10,
+            includeContent: args.include_content
+        });
+        // Build query
+        let query = `short_descriptionLIKE${args.query}^ORtextLIKE${args.query}`;
+        if (args.kb_knowledge_base) {
+            query += `^kb_knowledge_base=${args.kb_knowledge_base}`;
+        }
+        if (args.kb_category) {
+            query += `^kb_category=${args.kb_category}`;
+        }
+        if (args.workflow_state) {
+            query += `^workflow_state=${args.workflow_state}`;
+        }
+        else {
+            query += '^workflow_state=published'; // Default to published only
+        }
+        this.logger.progress(`Searching kb_knowledge table for: "${args.query}"...`);
+        // Search with tracking
+        const limit = args.limit || 10;
+        const response = await this.queryTable('kb_knowledge', query, limit);
+        if (!response.success) {
+            this.logger.error('Knowledge search failed', response.error);
+            return this.createResponse(`❌ Search failed: ${response.error}`);
+        }
+        const articles = response.data.result;
+        if (!articles.length) {
+            this.logger.info('No articles found', { query: args.query });
+            return this.createResponse(`❌ No knowledge articles found matching "${args.query}"`);
+        }
+        this.logger.info(`Found ${articles.length} knowledge articles`);
+        // Format results
+        const articleList = articles.map((article) => {
+            const snippet = args.include_content ?
+                article.text?.substring(0, 200) + '...' :
+                article.short_description;
+            return `📄 **${article.short_description}**
+🆔 ${article.sys_id}
+📊 State: ${article.workflow_state}
+📅 Updated: ${article.sys_updated_on}
+${args.include_content ? `📝 ${snippet}` : ''}`;
+        }).join('\n\n');
+        return this.createResponse(`🔍 Knowledge Search Results for "${args.query}":
+
+${articleList}
+
+✨ Found ${articles.length} article(s)`);
+    }
+    async start() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await this.server.connect(transport);
+        // Log ready state
+        this.logger.info('🚀 ServiceNow Knowledge & Catalog MCP Server (Enhanced) running');
+        this.logger.info('📊 Token tracking enabled');
+        this.logger.info('⏳ Progress indicators active');
+    }
+}
+// Start the enhanced server
+const server = new ServiceNowKnowledgeCatalogMCPEnhanced();
+server.start().catch((error) => {
+    console.error('Failed to start enhanced server:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=servicenow-knowledge-catalog-mcp-enhanced.js.map

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.2",
-  "description": "Snow-Flow v3.2.2: ServiceNow development platform with 180+ MCP tools. 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.0",
+  "description": "Snow-Flow v3.3.0: ServiceNow development platform with 180+ MCP tools. Includes API operation logging and token usage tracking. 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.",
   "main": "dist/index.js",
   "type": "commonjs",
   "bin": {