snow-flow 10.0.9 → 10.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "10.0.9",
+  "version": "10.0.11",
   "name": "snow-flow",
   "description": "Snow-Flow - ServiceNow Multi-Agent Development Framework powered by AI",
   "license": "Elastic-2.0",

package/src/cli/cmd/tui/component/dialog-auth.tsx

@@ -604,8 +604,23 @@ function DialogAuthServiceNowOAuth() {
             <text fg={theme.primary} attributes={TextAttributes.BOLD}>
               Remote Environment Detected
             </text>
-            <text fg={theme.text}>Open this URL in your browser to authenticate (copied to clipboard):</text>
+            <text fg={theme.text}>Open this URL in your browser to authenticate:</text>
             <text fg={theme.primary}>{headlessAuthUrl()}</text>
+            <box flexDirection="row" gap={2} paddingTop={1}>
+              <box
+                paddingLeft={2}
+                paddingRight={2}
+                backgroundColor={theme.primary}
+                onMouseUp={() => {
+                  Clipboard.copy(headlessAuthUrl()).then(
+                    () => toast.show({ variant: "success", message: "URL copied to clipboard!", duration: 3000 }),
+                    () => toast.show({ variant: "error", message: "Failed to copy URL", duration: 3000 }),
+                  )
+                }}
+              >
+                <text fg={theme.selectedListItemText} attributes={TextAttributes.BOLD}>[ Copy URL ]</text>
+              </box>
+            </box>
             <box paddingTop={1}>
               <text fg={theme.textMuted}>After clicking "Allow" in ServiceNow:</text>
               <text fg={theme.textMuted}>  1. Your browser will redirect to a localhost URL</text>

package/src/servicenow/enterprise-proxy/index.ts

@@ -12,8 +12,11 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { proxyToolCall, listEnterpriseTools } from './proxy.js';
 import { mcpDebug } from '../shared/mcp-debug.js';
+import { fetchAndCacheTools, buildEnterpriseToolIndex, ToolSearch, getCurrentSessionId } from './tool-cache.js';
+import { ENTERPRISE_META_TOOLS, executeToolSearch, executeToolExecute } from './meta-tools.js';
 
 const VERSION = process.env.SNOW_FLOW_VERSION || '8.30.31';
+const LAZY_TOOLS_ENABLED = process.env.SNOW_ENTERPRISE_LAZY_TOOLS !== 'false';
 
 /**
  * Create MCP Server
@@ -33,6 +36,7 @@ const server = new Server(
 /**
  * Handle tools/list request
  * Returns list of available enterprise tools from license server
+ * In lazy mode: returns only meta-tools + session-enabled tools
  */
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   mcpDebug('[Enterprise Proxy] Received tools/list request from MCP client');
@@ -40,8 +44,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   try {
     const tools = await listEnterpriseTools();
 
-    mcpDebug(`[Enterprise Proxy] Returning ${tools.length} tools to MCP client`);
+    mcpDebug(`[Enterprise Proxy] Fetched ${tools.length} tools from license server`);
+
+    if (LAZY_TOOLS_ENABLED) {
+      // Build search index from fetched tools
+      buildEnterpriseToolIndex(tools);
+
+      // Collect session-enabled tools to include alongside meta-tools
+      const sessionId = getCurrentSessionId();
+      const enabledTools: { name: string; description: string; inputSchema: any }[] = [];
+      if (sessionId) {
+        const enabledSet = await ToolSearch.getEnabledTools(sessionId);
+        for (const toolId of enabledSet) {
+          const found = tools.find((t) => t.name === toolId);
+          if (found) {
+            enabledTools.push({
+              name: found.name,
+              description: found.description || `Enterprise tool: ${found.name}`,
+              inputSchema: found.inputSchema,
+            });
+          }
+        }
+      }
+
+      mcpDebug(`[Enterprise Proxy] Lazy mode: returning ${ENTERPRISE_META_TOOLS.length} meta-tools + ${enabledTools.length} enabled tools`);
+      return {
+        tools: [...ENTERPRISE_META_TOOLS, ...enabledTools],
+      };
+    }
 
+    mcpDebug(`[Enterprise Proxy] Returning ${tools.length} tools to MCP client`);
     return {
       tools: tools.map((tool) => ({
         name: tool.name,
@@ -50,13 +82,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       })),
     };
   } catch (error) {
-    // Return empty list on error (allows MCP server to start even if enterprise server is down)
-    mcpDebug('[Enterprise Proxy] Failed to list tools - returning empty list', {
+    mcpDebug('[Enterprise Proxy] Failed to list tools', {
       error: error instanceof Error ? error.message : String(error)
     });
-    mcpDebug(
-      `[Enterprise Proxy] Failed to list tools: ${error instanceof Error ? error.message : String(error)}`
-    );
+
+    if (LAZY_TOOLS_ENABLED) {
+      // In lazy mode, always return meta-tools so search remains available
+      mcpDebug('[Enterprise Proxy] Returning meta-tools only due to backend error');
+      return { tools: [...ENTERPRISE_META_TOOLS] };
+    }
+
+    mcpDebug('[Enterprise Proxy] Returning empty tools list due to backend error');
     return { tools: [] };
   }
 });
@@ -64,6 +100,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 /**
  * Handle tools/call request
  * Proxies tool call to enterprise license server via HTTPS
+ * In lazy mode: routes meta-tool calls and enforces tool enabling
  */
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
@@ -72,6 +109,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     arguments: args
   });
 
+  // Route meta-tool calls in lazy mode
+  if (LAZY_TOOLS_ENABLED) {
+    if (name === 'enterprise_tool_search') {
+      return executeToolSearch((args || {}) as Record<string, unknown>);
+    }
+    if (name === 'enterprise_tool_execute') {
+      return executeToolExecute((args || {}) as Record<string, unknown>);
+    }
+
+    // For direct tool calls in lazy mode, check if tool is enabled
+    const sessionId = getCurrentSessionId();
+    if (sessionId) {
+      const canExecute = await ToolSearch.canExecuteTool(sessionId, name);
+      if (!canExecute) {
+        mcpDebug(`[Enterprise Proxy] Tool ${name} not enabled for session ${sessionId}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Tool "${name}" is not enabled. Use enterprise_tool_search to find and enable it first.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  }
+
   try {
     const result = await proxyToolCall(name, args || {});
 
@@ -100,7 +165,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [
         {
           type: 'text',
-          text: `❌ Enterprise tool error: ${errorMessage}`,
+          text: `Enterprise tool error: ${errorMessage}`,
         },
       ],
       isError: true,

package/src/servicenow/enterprise-proxy/meta-tools.ts

@@ -0,0 +1,211 @@
+/**
+ * Enterprise Meta-Tools for Lazy Loading
+ *
+ * Two meta-tools that replace the full 76+ enterprise tool list:
+ * - enterprise_tool_search: Search and enable enterprise tools
+ * - enterprise_tool_execute: Execute an enabled enterprise tool
+ *
+ * Prefix `enterprise_` prevents collision with the unified server's
+ * `tool_search` / `tool_execute` (both MCP servers run simultaneously).
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+import { ToolSearch, getCurrentSessionId, fetchAndCacheTools, buildEnterpriseToolIndex, getCachedTool } from './tool-cache.js'
+import { proxyToolCall } from './proxy.js'
+import { mcpDebug } from '../shared/mcp-debug.js'
+
+/**
+ * The two meta-tools exposed in ListTools when lazy loading is active
+ */
+export const ENTERPRISE_META_TOOLS: Tool[] = [
+  {
+    name: 'enterprise_tool_search',
+    description:
+      'Search through 76+ enterprise integration tools (Jira, Azure DevOps, Confluence, GitHub, GitLab, Process Mining). ' +
+      'Returns matching tools with their full schemas. Found tools are automatically enabled for the session so you can call them directly. ' +
+      'Always search before using an enterprise tool for the first time.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description:
+            'Search query — use tool names (e.g. "jira_create_issue"), domains (e.g. "confluence"), ' +
+            'or actions (e.g. "create sprint", "search issues", "get page").',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results to return (default: 10, max: 30).',
+        },
+        enable: {
+          type: 'boolean',
+          description: 'Whether to automatically enable found tools for direct calling (default: true).',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'enterprise_tool_execute',
+    description:
+      'Execute an enterprise tool by name. Use enterprise_tool_search first to discover available tools. ' +
+      'After searching, tools are enabled and can also be called directly by name without this wrapper.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tool: {
+          type: 'string',
+          description: 'The exact tool name to execute (e.g. "jira_get_issue", "confluence_search_pages").',
+        },
+        args: {
+          type: 'object',
+          description: 'Arguments to pass to the tool. See the tool schema from enterprise_tool_search results.',
+          additionalProperties: true,
+        },
+      },
+      required: ['tool'],
+    },
+  },
+]
+
+/**
+ * Handle enterprise_tool_search calls
+ */
+export async function executeToolSearch(args: Record<string, unknown>): Promise<{
+  content: { type: string; text: string }[]
+  isError?: boolean
+}> {
+  const query = args.query as string
+  const limit = Math.min((args.limit as number) || 10, 30)
+  const enable = args.enable !== false // default true
+
+  if (!query) {
+    return {
+      content: [{ type: 'text', text: 'Error: "query" parameter is required.' }],
+      isError: true,
+    }
+  }
+
+  try {
+    // Ensure tools are cached and indexed
+    const tools = await fetchAndCacheTools()
+    buildEnterpriseToolIndex(tools)
+
+    // Search the index
+    const results = ToolSearch.search(query, limit)
+    mcpDebug(`[Enterprise MetaTools] Search "${query}" returned ${results.length} results`)
+
+    if (results.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `No enterprise tools found for "${query}". Try broader terms like "jira", "confluence", "azure", "sprint", "issue", "page".`,
+          },
+        ],
+      }
+    }
+
+    // Enable found tools for the session
+    const sessionId = getCurrentSessionId()
+    if (enable && sessionId) {
+      const toolIds = results.map((r) => r.id)
+      await ToolSearch.enableTools(sessionId, toolIds)
+      mcpDebug(`[Enterprise MetaTools] Enabled ${toolIds.length} tools for session ${sessionId}`)
+    }
+
+    // Build response with full tool schemas from cache
+    const formatted = results.map((entry) => {
+      const cached = getCachedTool(entry.id)
+      const schema = cached?.inputSchema
+        ? JSON.stringify(cached.inputSchema, null, 2)
+        : '(schema unavailable — tool will still work)'
+      return [
+        `### ${entry.id}`,
+        `**Category:** ${entry.category}`,
+        `**Description:** ${entry.description}`,
+        `**Input Schema:**`,
+        '```json',
+        schema,
+        '```',
+      ].join('\n')
+    })
+
+    const header = enable && sessionId
+      ? `Found ${results.length} enterprise tools (enabled for this session — you can now call them directly):\n`
+      : `Found ${results.length} enterprise tools:\n`
+
+    return {
+      content: [{ type: 'text', text: header + '\n' + formatted.join('\n\n') }],
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    mcpDebug(`[Enterprise MetaTools] Search failed: ${msg}`)
+    return {
+      content: [{ type: 'text', text: `Enterprise tool search failed: ${msg}` }],
+      isError: true,
+    }
+  }
+}
+
+/**
+ * Handle enterprise_tool_execute calls
+ */
+export async function executeToolExecute(args: Record<string, unknown>): Promise<{
+  content: { type: string; text: string }[]
+  isError?: boolean
+}> {
+  const toolName = args.tool as string
+  const toolArgs = (args.args as Record<string, unknown>) || {}
+
+  if (!toolName) {
+    return {
+      content: [{ type: 'text', text: 'Error: "tool" parameter is required.' }],
+      isError: true,
+    }
+  }
+
+  // Check if tool is enabled for the session
+  const sessionId = getCurrentSessionId()
+  if (sessionId) {
+    const canExecute = await ToolSearch.canExecuteTool(sessionId, toolName)
+    if (!canExecute) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `Tool "${toolName}" is not enabled for this session. ` +
+              `Use enterprise_tool_search first to find and enable it.`,
+          },
+        ],
+        isError: true,
+      }
+    }
+  }
+
+  // Proxy the call to the license server
+  try {
+    mcpDebug(`[Enterprise MetaTools] Executing tool: ${toolName}`)
+    const startTime = Date.now()
+    const result = await proxyToolCall(toolName, toolArgs as Record<string, any>)
+    const duration = Date.now() - startTime
+    mcpDebug(`[Enterprise MetaTools] Tool ${toolName} completed in ${duration}ms`)
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+        },
+      ],
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    mcpDebug(`[Enterprise MetaTools] Tool ${toolName} failed: ${msg}`)
+    return {
+      content: [{ type: 'text', text: `Enterprise tool error (${toolName}): ${msg}` }],
+      isError: true,
+    }
+  }
+}

package/src/servicenow/enterprise-proxy/server.ts

@@ -39,9 +39,12 @@ import path from 'path';
 import os from 'os';
 import { listEnterpriseTools, proxyToolCall } from './proxy.js';
 import { mcpDebug } from '../shared/mcp-debug.js';
+import { fetchAndCacheTools, buildEnterpriseToolIndex, ToolSearch, getCurrentSessionId } from './tool-cache.js';
+import { ENTERPRISE_META_TOOLS, executeToolSearch, executeToolExecute } from './meta-tools.js';
 
 // Configuration from environment variables
 const LICENSE_SERVER_URL = process.env.SNOW_ENTERPRISE_URL || 'https://enterprise.snow-flow.dev';
+const LAZY_TOOLS_ENABLED = process.env.SNOW_ENTERPRISE_LAZY_TOOLS !== 'false';
 
 /**
  * Check if a valid token source exists
@@ -155,12 +158,41 @@ class EnterpriseProxyServer {
 
         mcpDebug(`[Proxy] ✓ ${this.availableTools.length} tools available`);
 
+        if (LAZY_TOOLS_ENABLED) {
+          // Build search index from fetched tools
+          buildEnterpriseToolIndex(tools);
+
+          // Collect session-enabled tools to include alongside meta-tools
+          const sessionId = getCurrentSessionId();
+          const enabledTools: Tool[] = [];
+          if (sessionId) {
+            const enabledSet = await ToolSearch.getEnabledTools(sessionId);
+            for (const toolId of enabledSet) {
+              const found = this.availableTools.find(t => t.name === toolId);
+              if (found) enabledTools.push(found);
+            }
+          }
+
+          mcpDebug(`[Proxy] Lazy mode: returning ${ENTERPRISE_META_TOOLS.length} meta-tools + ${enabledTools.length} enabled tools`);
+          return {
+            tools: [...ENTERPRISE_META_TOOLS, ...enabledTools]
+          };
+        }
+
         return {
           tools: this.availableTools
         };
       } catch (error: any) {
         mcpDebug('[Proxy] ✗ Failed to fetch tools:', error.message);
 
+        if (LAZY_TOOLS_ENABLED) {
+          // In lazy mode, always return meta-tools so search remains available
+          mcpDebug('[Proxy] Returning meta-tools only due to backend error');
+          return {
+            tools: [...ENTERPRISE_META_TOOLS]
+          };
+        }
+
         // Return empty tools list instead of crashing - allows graceful degradation
         mcpDebug('[Proxy] Returning empty tools list due to backend error');
         return {
@@ -174,6 +206,34 @@ class EnterpriseProxyServer {
       var toolName = request.params.name;
       var toolArgs = request.params.arguments || {};
 
+      // Route meta-tool calls in lazy mode
+      if (LAZY_TOOLS_ENABLED) {
+        if (toolName === 'enterprise_tool_search') {
+          return executeToolSearch(toolArgs as Record<string, unknown>);
+        }
+        if (toolName === 'enterprise_tool_execute') {
+          return executeToolExecute(toolArgs as Record<string, unknown>);
+        }
+
+        // For direct tool calls in lazy mode, check if tool is enabled
+        const sessionId = getCurrentSessionId();
+        if (sessionId) {
+          const canExecute = await ToolSearch.canExecuteTool(sessionId, toolName);
+          if (!canExecute) {
+            mcpDebug(`[Proxy] Tool ${toolName} not enabled for session ${sessionId}`);
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: `Tool "${toolName}" is not enabled. Use enterprise_tool_search to find and enable it first.`
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+      }
+
       try {
         mcpDebug(`[Proxy] Executing tool: ${toolName}`);
 

package/src/servicenow/enterprise-proxy/tool-cache.ts

@@ -0,0 +1,134 @@
+/**
+ * Enterprise Tool Cache + Search Index
+ *
+ * Builds a search index from remote enterprise tool definitions fetched via HTTPS.
+ * Reuses the shared ToolSearch module for search, session management, and tool enabling.
+ *
+ * Cache is in-memory with a configurable TTL (default 5 minutes) to avoid
+ * hitting the license server on every ListTools request.
+ */
+
+import { ToolSearch, getCurrentSessionId } from '../servicenow-mcp-unified/shared/tool-search.js'
+import type { ToolIndexEntry } from '../servicenow-mcp-unified/shared/tool-search.js'
+import { listEnterpriseTools } from './proxy.js'
+import type { EnterpriseTool } from './types.js'
+import { mcpDebug } from '../shared/mcp-debug.js'
+
+export { ToolSearch, getCurrentSessionId }
+export type { ToolIndexEntry }
+
+const CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+let cachedTools: EnterpriseTool[] = []
+let cacheTimestamp = 0
+let indexBuilt = false
+
+/**
+ * Infer domain/category from a tool name prefix
+ */
+export function inferDomain(toolName: string): string {
+  if (toolName.startsWith('jira_')) return 'jira'
+  if (toolName.startsWith('azure_') || toolName.startsWith('azdo_')) return 'azure-devops'
+  if (toolName.startsWith('confluence_')) return 'confluence'
+  if (toolName.startsWith('github_') || toolName.startsWith('gh_')) return 'github'
+  if (toolName.startsWith('gitlab_') || toolName.startsWith('gl_')) return 'gitlab'
+  if (toolName.startsWith('process_mining_') || toolName.startsWith('pm_')) return 'process-mining'
+  return 'enterprise'
+}
+
+/**
+ * Extract search keywords from tool name and description
+ */
+export function extractKeywords(name: string, description: string): string[] {
+  const words = new Set<string>()
+
+  // Split tool name on underscores
+  for (const part of name.split('_')) {
+    if (part.length > 2) words.add(part.toLowerCase())
+  }
+
+  // Extract meaningful words from description
+  const descWords = description.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/)
+  const stopWords = new Set([
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+    'should', 'may', 'might', 'can', 'shall', 'to', 'of', 'in', 'for',
+    'on', 'with', 'at', 'by', 'from', 'as', 'into', 'through', 'during',
+    'before', 'after', 'above', 'below', 'between', 'out', 'off', 'over',
+    'under', 'again', 'further', 'then', 'once', 'and', 'but', 'or',
+    'nor', 'not', 'only', 'own', 'same', 'so', 'than', 'too', 'very',
+    'this', 'that', 'these', 'those', 'it', 'its',
+  ])
+  for (const w of descWords) {
+    if (w.length > 2 && !stopWords.has(w)) words.add(w)
+  }
+
+  return Array.from(words)
+}
+
+/**
+ * Fetch enterprise tools from license server with caching
+ * Returns cached tools if still fresh, otherwise fetches new ones
+ */
+export async function fetchAndCacheTools(): Promise<EnterpriseTool[]> {
+  const now = Date.now()
+  if (cachedTools.length > 0 && now - cacheTimestamp < CACHE_TTL_MS) {
+    mcpDebug(`[Enterprise ToolCache] Using cached tools (${cachedTools.length} tools, age: ${Math.round((now - cacheTimestamp) / 1000)}s)`)
+    return cachedTools
+  }
+
+  mcpDebug('[Enterprise ToolCache] Fetching tools from license server...')
+  const tools = await listEnterpriseTools()
+  cachedTools = tools
+  cacheTimestamp = Date.now()
+  mcpDebug(`[Enterprise ToolCache] Cached ${tools.length} tools`)
+  return tools
+}
+
+/**
+ * Build the ToolSearch index from enterprise tools
+ * All enterprise tools are registered as deferred (lazy-loaded)
+ */
+export function buildEnterpriseToolIndex(tools: EnterpriseTool[]): void {
+  if (indexBuilt && cachedTools.length === tools.length) return
+
+  const entries: ToolIndexEntry[] = tools.map((tool) => ({
+    id: tool.name,
+    description: tool.description || `Enterprise tool: ${tool.name}`,
+    category: inferDomain(tool.name),
+    keywords: extractKeywords(tool.name, tool.description || ''),
+    deferred: true,
+  }))
+
+  ToolSearch.clearIndex()
+  ToolSearch.registerTools(entries)
+  indexBuilt = true
+
+  const stats = ToolSearch.getStats()
+  mcpDebug(`[Enterprise ToolCache] Index built: ${stats.total} tools across ${Object.keys(stats.categories).length} categories`)
+}
+
+/**
+ * Get a single cached tool definition by name
+ */
+export function getCachedTool(name: string): EnterpriseTool | undefined {
+  return cachedTools.find((t) => t.name === name)
+}
+
+/**
+ * Get all cached tool definitions
+ */
+export function getCachedTools(): EnterpriseTool[] {
+  return cachedTools
+}
+
+/**
+ * Force refetch on next request
+ */
+export function invalidateCache(): void {
+  cachedTools = []
+  cacheTimestamp = 0
+  indexBuilt = false
+  ToolSearch.clearIndex()
+  mcpDebug('[Enterprise ToolCache] Cache invalidated')
+}

package/src/servicenow/enterprise-proxy/types.ts

@@ -58,6 +58,11 @@ export interface EnterpriseToolListResponse {
   tools: EnterpriseTool[];
 }
 
+export interface EnterpriseToolCacheConfig {
+  cacheTtlMs: number;
+  maxCacheSize: number;
+}
+
 export interface LicenseValidationResponse {
   valid: boolean;
   error?: string;