Snow-Flow Documentation

Installation

Requirements

• Node.js 18+ - Required runtime
• npm 8.0+ - Package manager
• ServiceNow instance - With OAuth configured
• LLM provider - API key or local Ollama

Install via npm

# Global installation (recommended)
npm install -g snow-flow

# Verify installation
snow-flow --version

Quick Start

1. Initialize Project

# Initialize Snow-Flow in your project
snow-flow init

# This creates:
# - .mcp.json (MCP server configuration)
# - CLAUDE.md (AI agent instructions)

2. Authenticate

# Login to ServiceNow and configure LLM provider
snow-flow auth login

# Check authentication status
snow-flow auth status

3. Start Building

# Run an autonomous task
snow-flow agent "Create a widget showing high-priority incidents"

# Query data
snow-flow agent "Show me all incidents from last week"

# Create automation
snow-flow agent "Create a business rule for auto-assignment"

Authentication Overview

Snow-Flow uses OAuth 2.0 for secure ServiceNow authentication. Credentials are stored securely and automatically refreshed.

Authentication Priority

Snow-Flow checks credentials in this order:

1. Environment variables - Highest priority
2. auth.json - Auto-loaded from snow-code
3. .mcp.json credentials - Project-specific
4. Interactive login - Prompts if none found

ServiceNow OAuth Setup

Create an OAuth application in your ServiceNow instance:

1. Navigate to System OAuth → Application Registry
2. Click New → Create an OAuth API endpoint for external clients
3. Configure:
   • Name: Snow-Flow
   • Redirect URL: http://localhost:3005/callback
   • Refresh Token Lifespan: 0 (unlimited)
4. Copy the Client ID and Client Secret

Credential Storage

Snow-Flow stores credentials securely at:

~/.local/share/snow-code/auth.json

This file is:

• Created automatically by snow-flow auth login
• Contains encrypted OAuth tokens
• Tokens are automatically refreshed
• Never synced to cloud or version control

Environment Variables (Alternative)

# ServiceNow credentials
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret

# Optional: Pre-configured refresh token
SERVICENOW_REFRESH_TOKEN=your-refresh-token

LLM Providers

Snow-Flow supports 75+ AI providers via Models.dev. Configure via environment variables:

Using Ollama (Free, Local)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.3

# Configure Snow-Flow
DEFAULT_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
DEFAULT_OLLAMA_MODEL=llama3.3

CLI Commands

Auth Commands

# Full interactive login
snow-flow auth login

# Check current authentication
snow-flow auth status

# Logout and clear credentials
snow-flow auth logout

# Refresh OAuth token manually
snow-flow auth refresh

Agent Mode

Agent mode enables autonomous, multi-agent task execution:

# Create a widget
snow-flow agent "Create a dashboard widget for incident metrics"

# Automate a process
snow-flow agent "Create business rule to auto-assign incidents by category"

# Query and analyze
snow-flow agent "Analyze incident trends from the past month"

# Complex task with multiple agents
snow-flow agent "Build a complete workspace for IT support"

MCP Tools Overview

Snow-Flow provides 385+ MCP tools across 80 functional domains, all accessible through natural language commands via the unified MCP architecture.

Complete Tool Reference

All tools follow the snow_* naming convention. Below is the complete list organized by domain.

Operations (24 tools)

Core CRUD operations and data management.

Security & Compliance (18 tools)

Security policies, vulnerability scanning, and compliance management.

Automation (18 tools)

Script execution, scheduling, and workflow automation.

Integration (14 tools)

REST/SOAP integrations, data mapping, and external connections.

CMDB (13 tools)

Configuration Management Database operations.

UI Builder (12 tools)

Next Experience UI Builder pages and components.

Deployment (11 tools)

Artifact deployment and management.

Workspace (10 tools)

Agent Workspace and UX configuration.

Development Assistant (10 tools)

Intelligent development helpers.

Platform Development (12 tools)

Business rules, client scripts, UI policies.

Update Sets (8 tools)

Change management and deployment.

Service Portal (10 tools)

Widgets, pages, and portal configuration.

Virtual Agent (7 tools)

Virtual Agent NLU and conversations.

Mobile (7 tools)

Mobile app configuration.

AI & Machine Learning (8 tools)

Predictive intelligence and ML features.

Asset Management (8 tools)

Asset lifecycle and license management.

Change Management (8 tools)

Change requests and CAB management.

Knowledge Management (7 tools)

Knowledge base articles and management.

Flow Designer (8 tools)

Flow Designer automation.

Reporting & Analytics (8 tools)

Reports, dashboards, and analytics.

Automated Test Framework (6 tools)

Test automation and validation.

Notifications (7 tools)

Notification management and delivery.

Agent Orchestration (12 tools)

Multi-agent coordination via snow-flow-mcp.

MCP Configuration

The .mcp.json file configures MCP servers:

{
  "mcp": {
    "servicenow-unified": {
      "type": "local",
      "command": ["node", "dist/mcp/servicenow-mcp-unified/index.js"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "{{SNOW_INSTANCE}}",
        "SERVICENOW_CLIENT_ID": "{{SNOW_CLIENT_ID}}",
        "SERVICENOW_CLIENT_SECRET": "{{SNOW_CLIENT_SECRET}}"
      },
      "enabled": true
    }
  }
}

Use With Any AI IDE

Snow-Flow works with any MCP-compatible AI tool. After running snow-flow init, the configuration is generated at .mcp.json and synced to .snow-code/config.json.

Setup for Claude Desktop

Claude Desktop uses a different key (mcpServers) than other tools:

# macOS config location
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows config location
%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "servicenow-unified": {
      "command": "node",
      "args": ["/path/to/snow-flow/dist/mcp/servicenow-mcp-unified/index.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_CLIENT_ID": "your-client-id",
        "SERVICENOW_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Setup for Cursor

# After snow-flow init, copy config to Cursor
cp .mcp.json .cursor/mcp.json

# Or create .cursor directory first
mkdir -p .cursor && cp .mcp.json .cursor/mcp.json

Setup for Windsurf

# After snow-flow init, copy config to Windsurf
cp .mcp.json mcp_config.json

Setup for Continue.dev

# Continue.dev config location
~/.continue/config.json

Add the MCP servers to your Continue.dev config:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/snow-flow/dist/mcp/servicenow-mcp-unified/index.js"]
        }
      }
    ]
  }
}

# Global npm installation
npm root -g
# Output: /usr/local/lib/node_modules
# Full path: /usr/local/lib/node_modules/snow-flow/dist/mcp/...

# Or use which to find the binary
which snow-flow

ES5 JavaScript Requirement

ES6+ Features That WILL CRASH

// ALL OF THESE BREAK SERVICENOW:
const x = 5;                    // SyntaxError
let items = [];                 // SyntaxError
const fn = () => {};            // SyntaxError
var msg = `Hello ${name}`;      // SyntaxError
for (let item of items) {}    // SyntaxError
var {name, id} = user;          // SyntaxError
array.map(x => x.id);           // SyntaxError
class MyClass {}                // SyntaxError

Correct ES5 Syntax

// THESE WORK IN SERVICENOW:
var x = 5;
var items = [];
function fn() { return 'result'; }
var msg = 'Hello ' + name;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
}
var name = user.name;
var id = user.id;

Update Set Management

Update Sets track ALL changes for deployment between instances. Always create an Update Set before making changes.

Workflow

// 1. Create Update Set FIRST
snow_update_set_manage({
  action: 'create',
  name: "Feature: Incident Dashboard",
  description: "Widget showing incident metrics"
});

// 2. Develop (changes auto-tracked)
snow_create_artifact({...});
snow_create_business_rule({...});

// 3. Complete Update Set
snow_update_set_manage({
  action: 'complete',
  update_set_id: 'sys_id_here'
});

Widget Coherence

ServiceNow widgets require perfect synchronization between Server Script, Client Script, and HTML Template.

The Three-Way Contract

// SERVER SCRIPT - Initialize data
data.message = "Hello";
data.items = [];
if (input.action === 'loadItems') {
  data.items = getItems();
}

// CLIENT SCRIPT - Handle UI interactions
c.loadItems = function() {
  c.server.get({action: 'loadItems'}).then(function() {
    console.log(c.data.items);
  });
};

// HTML TEMPLATE - Display data
<button ng-click="loadItems()">Load</button>
<div ng-repeat="item in data.items">{{item}}</div>

Coherence Checklist

• Every data.property in server is used in HTML/client
• Every ng-click="method()" in HTML has matching c.method in client
• Every c.server.get({action}) in client has matching if(input.action) in server

Enterprise Features Enterprise

Snow-Flow Enterprise adds powerful integrations for team workflows:

Integration Setup

# Login with enterprise features
snow-flow auth login

# Connect Jira
# (Follow prompts to authorize)

# Complete a Jira story autonomously
snow-flow agent "Complete JIRA-1234"