snow-flow 8.5.7 → 8.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/.mcp.json.template +8 -0
  2. package/CLAUDE.md +52 -4
  3. package/README.md +99 -30
  4. package/{OPENCODE-SETUP.md → SNOWCODE-SETUP.md} +47 -21
  5. package/{OPENCODE-TROUBLESHOOTING.md → SNOWCODE-TROUBLESHOOTING.md} +18 -18
  6. package/dist/cli/auth.d.ts.map +1 -1
  7. package/dist/cli/auth.js +526 -280
  8. package/dist/cli/auth.js.map +1 -1
  9. package/dist/cli/enterprise.d.ts +36 -0
  10. package/dist/cli/enterprise.d.ts.map +1 -0
  11. package/dist/cli/enterprise.js +231 -0
  12. package/dist/cli/enterprise.js.map +1 -0
  13. package/dist/cli.d.ts +1 -1
  14. package/dist/cli.d.ts.map +1 -1
  15. package/dist/cli.js +544 -250
  16. package/dist/cli.js.map +1 -1
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.js +1 -1
  19. package/dist/mcp/clients/enterprise-remote-client.d.ts +78 -0
  20. package/dist/mcp/clients/enterprise-remote-client.d.ts.map +1 -0
  21. package/dist/mcp/clients/enterprise-remote-client.js +221 -0
  22. package/dist/mcp/clients/enterprise-remote-client.js.map +1 -0
  23. package/dist/mcp/servicenow-mcp-unified/tools/adapters/index.d.ts +0 -5
  24. package/dist/mcp/servicenow-mcp-unified/tools/adapters/index.d.ts.map +1 -1
  25. package/dist/mcp/servicenow-mcp-unified/tools/adapters/index.js +2 -18
  26. package/dist/mcp/servicenow-mcp-unified/tools/adapters/index.js.map +1 -1
  27. package/dist/templates/claude-md-template.d.ts +1 -1
  28. package/dist/templates/claude-md-template.js +1 -1
  29. package/dist/templates/readme-template.d.ts +1 -1
  30. package/dist/templates/readme-template.js +18 -18
  31. package/dist/utils/artifact-local-sync.d.ts +1 -1
  32. package/dist/utils/artifact-local-sync.js +4 -4
  33. package/dist/utils/snow-oauth.d.ts +11 -5
  34. package/dist/utils/snow-oauth.d.ts.map +1 -1
  35. package/dist/utils/snow-oauth.js +337 -90
  36. package/dist/utils/snow-oauth.js.map +1 -1
  37. package/dist/utils/{opencode-output-interceptor.d.ts → snowcode-output-interceptor.d.ts} +7 -7
  38. package/dist/utils/{opencode-output-interceptor.d.ts.map → snowcode-output-interceptor.d.ts.map} +1 -1
  39. package/dist/utils/{opencode-output-interceptor.js → snowcode-output-interceptor.js} +10 -10
  40. package/dist/utils/{opencode-output-interceptor.js.map → snowcode-output-interceptor.js.map} +1 -1
  41. package/package.json +20 -9
  42. package/scripts/{start-opencode.sh → start-snowcode.sh} +28 -28
  43. package/scripts/verify-snowcode-fork.sh +141 -0
  44. package/templates/snowcode-package.json +5 -0
  45. package/THEMES.md +0 -223
  46. package/bin/opencode +0 -17
  47. package/dist/mcp/servicenow-mcp-unified/config/tool-definitions.json +0 -3935
  48. package/dist/mcp/servicenow-mcp-unified/tools/automation/snow_automation_discover.js +0 -164
  49. package/dist/mcp/servicenow-mcp-unified/tools/deployment/snow_artifact_transfer.js +0 -282
  50. package/dist/mcp/servicenow-mcp-unified/tools/filters/snow_build_filter.js +0 -171
  51. package/dist/mcp/servicenow-mcp-unified/tools/formatters/snow_format_value.js +0 -164
  52. package/dist/mcp/servicenow-mcp-unified/tools/knowledge/index.js.bak +0 -45
  53. package/dist/mcp/servicenow-mcp-unified/tools/local-sync/snow_artifact_sync.js +0 -172
  54. package/dist/mcp/servicenow-mcp-unified/tools/system-properties/index.js +0 -36
  55. package/dist/mcp/servicenow-mcp-unified/tools/ui-builder/snow_discover_uib.js +0 -296
  56. package/dist/mcp/servicenow-mcp-unified/tools/workspace/snow_create_ux_component.js +0 -292
  57. package/dist/memory/session-memory.d.ts +0 -80
  58. package/dist/memory/session-memory.d.ts.map +0 -1
  59. package/dist/memory/session-memory.js +0 -468
  60. package/dist/memory/session-memory.js.map +0 -1
  61. package/dist/templates/opencode-agents-template.d.ts +0 -2
  62. package/dist/templates/opencode-agents-template.d.ts.map +0 -1
  63. package/dist/templates/opencode-agents-template.js +0 -469
  64. package/dist/templates/opencode-agents-template.js.map +0 -1
  65. package/scripts/bulk-optimize-tools.js +0 -486
  66. package/scripts/optimize-mcp-tools.ts +0 -410
  67. package/themes/README.md +0 -83
  68. package/themes/servicenow.json +0 -117
  69. /package/{opencode-config.example.json → snowcode-config.example.json} +0 -0
@@ -17,6 +17,14 @@
17
17
  "env": {
18
18
  "SNOW_FLOW_ENV": "{{SNOW_FLOW_ENV}}"
19
19
  }
20
+ },
21
+ "snow-flow-enterprise": {
22
+ "type": "sse",
23
+ "url": "https://enterprise.snow-flow.dev/mcp/sse",
24
+ "description": "Snow-Flow Enterprise - 26 advanced integration tools (Jira, Azure DevOps, Confluence) with bidirectional sync, AI-powered planning, analytics, and automation. Requires enterprise license.",
25
+ "headers": {
26
+ "Authorization": "Bearer {{ENTERPRISE_JWT_TOKEN}}"
27
+ }
20
28
  }
21
29
  }
22
30
  }
package/CLAUDE.md CHANGED
@@ -1,5 +1,51 @@
1
1
  # Snow-Flow ServiceNow Development Framework
2
2
 
3
+ ## 🚨 CRITICAL: MCP CLIENT COMPATIBILITY
4
+
5
+ **Snow-Flow supports multiple AI clients with DIFFERENT MCP configurations:**
6
+
7
+ ### **Supported Clients:**
8
+
9
+ | Client | Config File | Config Format | MCP Tools Available As |
10
+ |--------|-------------|---------------|------------------------|
11
+ | **Claude Desktop** | `.mcp.json` | `mcpServers` + `args` + `env` | ✅ Direct functions (`snow_*`) |
12
+ | **Claude Code (CLI)** | `.mcp.json` or `.claude/settings.json` | `mcpServers` + `args` + `env` | ✅ Direct functions (`snow_*`) |
13
+ | **OpenCode** | `opencode.json` or `~/.config/opencode/opencode.json` | `mcp` + `command[]` + `environment` + `type` + `enabled` | ⚠️ Via MCP protocol (NOT direct functions!) |
14
+ | **SnowCode** | `opencode.json` or `~/.config/snowcode/snowcode.json` | `mcp` + `command[]` + `environment` + `type` + `enabled` | ⚠️ Via MCP protocol (NOT direct functions!) |
15
+
16
+ ### **⚠️ IMPORTANT: OpenCode/SnowCode Users**
17
+
18
+ If you're using **OpenCode** or **SnowCode** (fork of OpenCode):
19
+
20
+ 1. ✅ MCP servers are configured via `opencode.json` (auto-generated by `snow-flow init`)
21
+ 2. ✅ Servers start automatically when you launch the client
22
+ 3. ✅ Tools are available via MCP protocol
23
+ 4. ❌ Tools are **NOT** available as direct JavaScript functions (e.g., `snow_create_ui_page()` won't work directly)
24
+ 5. ✅ Use tools via the client's UI or MCP command interface
25
+
26
+ **To check if MCP servers are running (OpenCode/SnowCode):**
27
+ ```bash
28
+ # Check server status in your terminal
29
+ ps aux | grep -i "servicenow-mcp\|snow-flow-mcp" | grep -v grep
30
+
31
+ # Or use /mcp command in your client
32
+ # /mcp
33
+ ```
34
+
35
+ **After changing config:**
36
+ - **Restart your client** (OpenCode/SnowCode/Claude Code) for changes to take effect
37
+
38
+ ### **✅ Claude Desktop/Code Users**
39
+
40
+ If you're using **Claude Desktop** or **Claude Code CLI**:
41
+
42
+ 1. ✅ MCP servers configured via `.mcp.json` + `.claude/settings.json` (auto-generated)
43
+ 2. ✅ Servers start when you launch the client
44
+ 3. ✅ Tools available as **direct JavaScript functions** (e.g., `await snow_create_ui_page({...})`)
45
+ 4. ✅ Can call tools directly in conversations
46
+
47
+ ---
48
+
3
49
  ## ⚡ QUICK START - READ THIS FIRST!
4
50
 
5
51
  | What You Want | ❌ WRONG (will fail!) | ✅ CORRECT (works!) |
@@ -13,12 +59,14 @@
13
59
 
14
60
  ---
15
61
 
16
- ## 🚨 CRITICAL: HOW MCP TOOLS WORK IN OPENCODE
62
+ ## 🚨 IMPORTANT: MCP Tool Usage (Claude Desktop/Code Only)
63
+
64
+ **⚠️ The examples below work in Claude Desktop and Claude Code CLI ONLY!**
17
65
 
18
- **MCP tools are AUTOMATICALLY AVAILABLE - NO bash/npx/node needed!**
66
+ **For OpenCode/SnowCode users:** Tools are available via MCP protocol, not as direct functions. See compatibility section above.
19
67
 
20
68
  ```javascript
21
- // ✅ CORRECT - MCP tools are available directly:
69
+ // ✅ CORRECT in Claude Desktop/Claude Code - MCP tools as direct functions:
22
70
  await snow_create_ui_page({
23
71
  name: "incident_dashboard",
24
72
  html: "<div>...</div>"
@@ -67,7 +115,7 @@ cd /path/to/project && node -e "const { snow_query_table } = require(...);"
67
115
 
68
116
  **🚨 WHY THESE FAIL:**
69
117
  - MCP tools are **functions**, NOT CLI commands
70
- - They are loaded by OpenCode/Claude Code automatically
118
+ - They are loaded by SnowCode/Claude Code automatically
71
119
  - No `dist/` directory exists in user's project
72
120
  - No CLI wrapper exists for MCP tools
73
121
 
package/README.md CHANGED
@@ -27,11 +27,11 @@ Traditional ServiceNow development means:
27
27
  Snow-Flow provides:
28
28
  - ✅ **Conversational Development**: Build through natural language
29
29
  - ✅ **411 ServiceNow Tools**: Complete API coverage via 2 unified MCP servers
30
- - ✅ **75+ LLM Providers**: Claude, GPT-4o, Gemini, Llama, Mistral, DeepSeek, Groq, or ANY provider via OpenCode
30
+ - ✅ **75+ LLM Providers**: Claude, GPT-4o, Gemini, Llama, Mistral, DeepSeek, Groq, or ANY provider via SnowCode
31
31
  - ✅ **100% Free Option**: Ollama, LM Studio, Jan - run models locally offline
32
32
  - ✅ **Local Development**: Pull artifacts to local files, edit with native tools
33
33
  - ✅ **Local ML Training**: TensorFlow.js neural networks (runs locally, trains on ServiceNow data)
34
- - ✅ **Universal Compatibility**: Works with OpenCode, Claude Code, Cursor, Windsurf, Continue.dev, Cline
34
+ - ✅ **Universal Compatibility**: Works with SnowCode, Claude Code, Cursor, Windsurf, Continue.dev, Cline
35
35
 
36
36
  ---
37
37
 
@@ -48,8 +48,8 @@ snow-flow init
48
48
  ```
49
49
 
50
50
  Snow-Flow will automatically:
51
- - ✅ Detect and install OpenCode (recommended AI coding platform)
52
- - ✅ Generate configuration files (`.env`, `.opencode/config.json`)
51
+ - ✅ Detect and install SnowCode (recommended AI coding platform)
52
+ - ✅ Generate configuration files (`.env`, `.snowcode/config.json`)
53
53
  - ✅ Set up 2 MCP servers with 411 ServiceNow tools
54
54
  - ✅ Create documentation (`AGENTS.md`, `README.md`)
55
55
 
@@ -95,16 +95,16 @@ snow-flow auth login
95
95
  3. **ServiceNow**: Browser opens for OAuth authentication
96
96
  4. **Done**: You're ready to develop!
97
97
 
98
- ### OpenCode Setup
98
+ ### SnowCode Setup
99
99
 
100
- For detailed OpenCode configuration (MCP servers, environment variables, troubleshooting), see:
100
+ For detailed SnowCode configuration (MCP servers, environment variables, troubleshooting), see:
101
101
 
102
- 📖 **[OPENCODE-SETUP.md](OPENCODE-SETUP.md)** - Complete OpenCode configuration guide
102
+ 📖 **[SNOWCODE-SETUP.md](SNOWCODE-SETUP.md)** - Complete SnowCode configuration guide
103
103
 
104
104
  **Quick checklist:**
105
- - ✅ Use `"environment"` (not `"env"`) in `opencode-config.json`
105
+ - ✅ Use `"environment"` (not `"env"`) in `snowcode-config.json`
106
106
  - ✅ Run `npm run build` to create `dist/` directory
107
- - ✅ Verify MCP servers load when OpenCode starts
107
+ - ✅ Verify MCP servers load when SnowCode starts
108
108
  - ✅ Test tools actually execute (not just show code snippets)
109
109
 
110
110
  ### Start Developing
@@ -113,15 +113,15 @@ For detailed OpenCode configuration (MCP servers, environment variables, trouble
113
113
  # Use Snow-Flow swarm for any ServiceNow task
114
114
  snow-flow swarm "create incident dashboard widget with real-time charts"
115
115
 
116
- # Or launch OpenCode with Snow-Flow tools pre-loaded
117
- opencode
116
+ # Or launch SnowCode with Snow-Flow tools pre-loaded
117
+ snowcode
118
118
  ```
119
119
 
120
120
  ---
121
121
 
122
122
  ## 💡 LLM Provider Options
123
123
 
124
- Snow-Flow works with **75+ LLM providers** through OpenCode and Models.dev. Choose ANY model that fits your needs!
124
+ Snow-Flow works with **75+ LLM providers** through SnowCode and Models.dev. Choose ANY model that fits your needs!
125
125
 
126
126
  ### 🌟 Popular Providers
127
127
 
@@ -135,7 +135,7 @@ Snow-Flow works with **75+ LLM providers** through OpenCode and Models.dev. Choo
135
135
 
136
136
  ### 🔓 Full Provider List (75+)
137
137
 
138
- **Via OpenCode + Models.dev:**
138
+ **Via SnowCode + Models.dev:**
139
139
  - **Anthropic**: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1
140
140
  - **OpenAI**: GPT-5, GPT-4o, GPT-4o-mini
141
141
  - **Google**: Gemini 2.0 Flash, Gemini 2.5 Pro, Gemini 2.5 Flash
@@ -205,17 +205,86 @@ OPENAI_API_KEY=your-key
205
205
 
206
206
  ## 🎯 ServiceNow OAuth Setup
207
207
 
208
- Snow-Flow uses OAuth 2.0 for secure ServiceNow access:
208
+ Snow-Flow uses OAuth 2.0 with localhost callback for secure ServiceNow access:
209
209
 
210
- 1. **Navigate to:** System OAuth Application Registry
211
- 2. **Click:** New → "Create an OAuth API endpoint for external clients"
212
- 3. **Configure:**
210
+ ### Step 1: Create OAuth Application in ServiceNow
211
+
212
+ 1. **Log into ServiceNow** as administrator
213
+ 2. **Navigate to:** System OAuth → Application Registry
214
+ 3. **Click:** New → "Create an OAuth API endpoint for external clients"
215
+ 4. **Configure the following fields:**
213
216
  - **Name:** `Snow-Flow Integration`
214
- - **Redirect URL:** `http://localhost:3005/callback` ⚠️ **Must be exact!**
217
+ - **Redirect URL:** `http://localhost:3005/callback` ⚠️ **CRITICAL: Must be exactly this!**
215
218
  - **Refresh Token Lifespan:** `0` (unlimited)
216
219
  - **Access Token Lifespan:** `1800` (30 minutes)
217
- 4. **Save** Copy Client ID and Client Secret
218
- 5. **Add to `.env`** (see Configuration above)
220
+ 5. **Save** the application
221
+ 6. **Copy** the generated Client ID and Client Secret
222
+
223
+ ### Step 2: Add Credentials to Environment
224
+
225
+ Add the credentials to your `.env` file:
226
+
227
+ ```bash
228
+ SNOW_INSTANCE=your-instance.service-now.com
229
+ SNOW_CLIENT_ID=your-client-id-from-step-1
230
+ SNOW_CLIENT_SECRET=your-client-secret-from-step-1
231
+ ```
232
+
233
+ ### Step 3: Authenticate
234
+
235
+ ```bash
236
+ snow-flow auth login
237
+ ```
238
+
239
+ **What happens:**
240
+ 1. Snow-Flow starts a temporary localhost server on port 3005
241
+ 2. Your browser opens automatically to ServiceNow's OAuth page
242
+ 3. You click "Allow" to authorize Snow-Flow
243
+ 4. **Choose one option:**
244
+ - **Option A (Automatic):** Browser redirects back to localhost automatically
245
+ - **Option B (Manual):** Copy the callback URL from browser and paste it in the terminal
246
+ 5. Snow-Flow exchanges the code for access tokens
247
+ 6. Done! All MCP servers are now authenticated
248
+
249
+ **Manual URL paste option:**
250
+ If the browser doesn't redirect automatically, or you prefer manual control:
251
+ 1. After clicking "Allow" in ServiceNow, your browser redirects to a URL like:
252
+ ```
253
+ http://localhost:3005/callback?code=abc123&state=xyz789
254
+ ```
255
+ 2. Copy this ENTIRE URL from your browser address bar
256
+ 3. Paste it in the Snow-Flow terminal when prompted
257
+ 4. Snow-Flow will extract the code and complete authentication
258
+
259
+ ### ⚠️ Troubleshooting
260
+
261
+ **Error: "Invalid redirect_uri"**
262
+
263
+ This means the redirect URL in your ServiceNow OAuth application doesn't match. Fix it:
264
+
265
+ 1. Go to: System OAuth → Application Registry
266
+ 2. Find your Snow-Flow application (search for the Client ID)
267
+ 3. Edit the **Redirect URL** field
268
+ 4. Change it to: `http://localhost:3005/callback` (exactly this, no typos!)
269
+ 5. Save and try `snow-flow auth login` again
270
+
271
+ **Error: "Port 3005 is already in use"**
272
+
273
+ Another application is using port 3005. Fix it:
274
+
275
+ 1. Stop any application using port 3005
276
+ 2. Or change the port in `.env`:
277
+ ```bash
278
+ SNOW_OAUTH_REDIRECT_PORT=3006
279
+ ```
280
+ 3. Update the redirect URL in ServiceNow to match the new port
281
+
282
+ **Using in GitHub Codespaces or Remote Environments**
283
+
284
+ The localhost callback works automatically through port forwarding in:
285
+ - ✅ GitHub Codespaces (automatic port forwarding)
286
+ - ✅ VS Code Remote SSH (automatic port forwarding)
287
+ - ✅ Local development (direct localhost access)
219
288
 
220
289
  ---
221
290
 
@@ -426,7 +495,7 @@ Provide optimization recommendations"
426
495
 
427
496
  ## 🤖 Multi-Agent Coordination
428
497
 
429
- Snow-Flow uses OpenCode's native Task() system for intelligent agent teams:
498
+ Snow-Flow uses SnowCode's native Task() system for intelligent agent teams:
430
499
 
431
500
  **Available Agent Types:**
432
501
  - `widget-creator` - Service Portal widget development
@@ -448,11 +517,11 @@ Snow-Flow works with **any MCP-compatible AI coding assistant**:
448
517
 
449
518
  | AI Assistant | How to Connect |
450
519
  |-------------|----------------|
451
- | **Cursor** | Copy `.opencode/config.json` → `.cursor/mcp.json` |
452
- | **Windsurf** | Copy `.opencode/config.json` → `mcp_config.json` |
453
- | **Continue.dev** | Copy `.opencode/config.json` → `.continue/mcpServers/snow-flow.json` |
454
- | **Cline** | Copy `.opencode/config.json` → `.vscode/mcp.json` |
455
- | **GitHub Copilot** | Copy `.opencode/config.json` → `.vscode/mcp.json` |
520
+ | **Cursor** | Copy `.snowcode/config.json` → `.cursor/mcp.json` |
521
+ | **Windsurf** | Copy `.snowcode/config.json` → `mcp_config.json` |
522
+ | **Continue.dev** | Copy `.snowcode/config.json` → `.continue/mcpServers/snow-flow.json` |
523
+ | **Cline** | Copy `.snowcode/config.json` → `.vscode/mcp.json` |
524
+ | **GitHub Copilot** | Copy `.snowcode/config.json` → `.vscode/mcp.json` |
456
525
 
457
526
  **Quick setup:**
458
527
  ```bash
@@ -460,10 +529,10 @@ Snow-Flow works with **any MCP-compatible AI coding assistant**:
460
529
  snow-flow init
461
530
 
462
531
  # For Cursor
463
- cp .opencode/config.json .cursor/mcp.json
532
+ cp .snowcode/config.json .cursor/mcp.json
464
533
 
465
534
  # For Windsurf
466
- cp .opencode/config.json mcp_config.json
535
+ cp .snowcode/config.json mcp_config.json
467
536
 
468
537
  # Restart your AI assistant → 411 Snow-Flow tools available!
469
538
  ```
@@ -550,7 +619,7 @@ snow-flow auth logout
550
619
  - **Node.js**: 18.0.0 or higher
551
620
  - **ServiceNow**: Any supported version
552
621
  - **LLM Provider**: Any of the supported options above
553
- - **AI Coding Assistant**: OpenCode (auto-installed) or others
622
+ - **AI Coding Assistant**: SnowCode (auto-installed) or others
554
623
  - **Memory**: 4GB RAM recommended for ML training
555
624
  - **Storage**: 1GB free space for models and artifacts
556
625
 
@@ -584,7 +653,7 @@ The current Snow-Flow release includes:
584
653
  - ✅ **Multi-Agent Orchestration** - SPARC methodology, swarm coordination
585
654
  - ✅ **Update Set Management** - Full lifecycle, auto-sync current update set
586
655
  - ✅ **Background Script Execution** - With output capture and auto-confirm mode
587
- - ✅ **Universal Compatibility** - Works with OpenCode, Claude Code, Cursor, Windsurf, Continue.dev, Cline
656
+ - ✅ **Universal Compatibility** - Works with SnowCode, Claude Code, Cursor, Windsurf, Continue.dev, Cline
588
657
 
589
658
  **Use for:** Solo developers, small teams, learning, proof-of-concepts, community projects
590
659
 
@@ -1,24 +1,24 @@
1
- # OpenCode Setup Guide for Snow-Flow
1
+ # SnowCode Setup Guide for Snow-Flow
2
2
 
3
- This guide explains how to properly configure OpenCode to use Snow-Flow's MCP tools.
3
+ This guide explains how to properly configure SnowCode to use Snow-Flow's MCP tools.
4
4
 
5
5
  ## Quick Start
6
6
 
7
7
  ### 1. Copy Example Config
8
8
 
9
9
  ```bash
10
- cp opencode-config.example.json opencode-config.json
10
+ cp snowcode-config.example.json snowcode-config.json
11
11
  ```
12
12
 
13
13
  ### 2. Update Environment Variables
14
14
 
15
- Edit `opencode-config.json` and replace the `${VARIABLE}` placeholders with your actual values:
15
+ Edit `snowcode-config.json` and replace the `${VARIABLE}` placeholders with your actual values:
16
16
 
17
17
  ```json
18
18
  {
19
- "$schema": "https://opencode.ai/config.json",
20
- "name": "snow-flow-opencode",
21
- "description": "OpenCode configuration for Snow-Flow ServiceNow development",
19
+ "$schema": "https://snowcode.ai/config.json",
20
+ "name": "snow-flow-snowcode",
21
+ "description": "SnowCode configuration for Snow-Flow ServiceNow development",
22
22
  "model": {
23
23
  "provider": "anthropic",
24
24
  "model": "claude-sonnet-4-5-20250929",
@@ -54,7 +54,7 @@ Edit `opencode-config.json` and replace the `${VARIABLE}` placeholders with your
54
54
  "instructions": [
55
55
  "AGENTS.md",
56
56
  "CLAUDE.md",
57
- ".opencode/AGENTS.md"
57
+ ".snowcode/AGENTS.md"
58
58
  ],
59
59
  "cwd": "/path/to/your/snow-flow/installation"
60
60
  }
@@ -68,10 +68,10 @@ npm run build
68
68
 
69
69
  This creates the `dist/` directory with the MCP server files.
70
70
 
71
- ### 4. Start OpenCode
71
+ ### 4. Start SnowCode
72
72
 
73
73
  ```bash
74
- opencode
74
+ snowcode
75
75
  ```
76
76
 
77
77
  ## Critical Configuration Details
@@ -98,25 +98,51 @@ opencode
98
98
 
99
99
  3. **Forgetting to build**
100
100
  - Always run `npm run build` after pulling updates
101
- - The `dist/` directory must exist before starting OpenCode
101
+ - The `dist/` directory must exist before starting SnowCode
102
102
 
103
103
  ### Environment Variables
104
104
 
105
105
  **Required for ServiceNow MCP:**
106
106
  - `SNOW_INSTANCE` - Your ServiceNow instance URL (e.g., `dev12345.service-now.com`)
107
- - `SNOW_CLIENT_ID` - OAuth client ID
108
- - `SNOW_CLIENT_SECRET` - OAuth client secret
107
+ - `SNOW_CLIENT_ID` - OAuth client ID (from ServiceNow Application Registry)
108
+ - `SNOW_CLIENT_SECRET` - OAuth client secret (from ServiceNow Application Registry)
109
109
  - `SNOW_USERNAME` - ServiceNow username
110
110
  - `SNOW_PASSWORD` - ServiceNow password
111
111
 
112
112
  **Optional for Snow-Flow MCP:**
113
113
  - `SNOW_FLOW_ENV` - Environment (default: `production`)
114
114
 
115
+ ### OAuth Setup (CRITICAL!)
116
+
117
+ Before using Snow-Flow, you **MUST** configure OAuth in ServiceNow:
118
+
119
+ 1. **Create OAuth Application** in ServiceNow:
120
+ - Navigate to: System OAuth → Application Registry
121
+ - Click: New → "Create an OAuth API endpoint for external clients"
122
+ - **Redirect URL:** `http://localhost:3005/callback` ⚠️ **MUST be exactly this!**
123
+ - Save and copy the Client ID and Client Secret
124
+
125
+ 2. **Add credentials** to your environment:
126
+ - Either in `snowcode-config.json` under `"environment"` section
127
+ - Or in `.env` file (recommended for security)
128
+
129
+ 3. **Authenticate** using Snow-Flow CLI:
130
+ ```bash
131
+ snow-flow auth login
132
+ ```
133
+
134
+ **Common Error:** If you get `Invalid redirect_uri` error:
135
+ - The redirect URL in ServiceNow MUST be exactly: `http://localhost:3005/callback`
136
+ - Go to System OAuth → Application Registry → Your Application
137
+ - Edit the "Redirect URL" field to match exactly
138
+
139
+ 📖 **See [README.md - OAuth Setup](README.md#-servicenow-oauth-setup) for detailed instructions**
140
+
115
141
  ## Verifying MCP Tools are Loaded
116
142
 
117
143
  ### Check Tool Availability
118
144
 
119
- When OpenCode starts, you should see the MCP servers loading in the logs:
145
+ When SnowCode starts, you should see the MCP servers loading in the logs:
120
146
 
121
147
  ```
122
148
  [MCP] Loading servicenow-unified...
@@ -127,7 +153,7 @@ When OpenCode starts, you should see the MCP servers loading in the logs:
127
153
 
128
154
  ### Test Tool Execution
129
155
 
130
- In OpenCode, try a simple command:
156
+ In SnowCode, try a simple command:
131
157
 
132
158
  ```
133
159
  Create an Update Set named "Test Update Set"
@@ -139,7 +165,7 @@ The agent should:
139
165
  3. ✅ Return the Update Set sys_id
140
166
 
141
167
  **If the agent only shows code snippets instead of calling tools, check:**
142
- - Is `opencode-config.json` using `"environment"` (not `"env"`)?
168
+ - Is `snowcode-config.json` using `"environment"` (not `"env"`)?
143
169
  - Did you run `npm run build` after updating Snow-Flow?
144
170
  - Are the MCP servers enabled (`"enabled": true`)?
145
171
  - Do the `dist/` files exist?
@@ -187,17 +213,17 @@ The agent should:
187
213
  ### Problem: "Tools not available"
188
214
 
189
215
  **Solution:**
190
- 1. Check `opencode-config.json` exists
216
+ 1. Check `snowcode-config.json` exists
191
217
  2. Verify `"environment"` key (not `"env"`)
192
218
  3. Run `npm run build`
193
- 4. Restart OpenCode
219
+ 4. Restart SnowCode
194
220
 
195
221
  ### Problem: "Agent shows code instead of calling tools"
196
222
 
197
223
  This usually means the MCP servers aren't loaded correctly.
198
224
 
199
225
  **Solution:**
200
- 1. Check OpenCode logs for MCP loading errors
226
+ 1. Check SnowCode logs for MCP loading errors
201
227
  2. Verify `dist/` directory exists
202
228
  3. Check command paths in config
203
229
  4. Ensure `"enabled": true`
@@ -295,14 +321,14 @@ await snow_query_table({ table: 'sp_widget' });
295
321
 
296
322
  If you encounter issues:
297
323
 
298
- 1. **Check logs**: OpenCode shows detailed MCP loading logs
324
+ 1. **Check logs**: SnowCode shows detailed MCP loading logs
299
325
  2. **Verify config**: Use `"environment"` (not `"env"`)
300
326
  3. **Rebuild**: Always `npm run build` after updates
301
327
  4. **GitHub Issues**: https://github.com/your-repo/snow-flow/issues
302
328
 
303
329
  ## Version Info
304
330
 
305
- - **OpenCode**: Requires OpenCode v1.0+
331
+ - **SnowCode**: Requires SnowCode v1.0+
306
332
  - **Snow-Flow**: v8.3.0+
307
333
  - **Node.js**: v18+ recommended
308
334
  - **MCP Spec**: 1.0.0
@@ -1,4 +1,4 @@
1
- # OpenCode MCP Troubleshooting Guide
1
+ # SnowCode MCP Troubleshooting Guide
2
2
 
3
3
  ## Problem: "Tools not available" or Agent Shows Code Instead of Calling Tools
4
4
 
@@ -23,7 +23,7 @@ npm install -g snow-flow@latest
23
23
 
24
24
  # Use the new launcher (handles everything)
25
25
  cd your-project
26
- ./node_modules/snow-flow/scripts/start-opencode.sh
26
+ ./node_modules/snow-flow/scripts/start-snowcode.sh
27
27
  ```
28
28
 
29
29
  The launcher will:
@@ -31,7 +31,7 @@ The launcher will:
31
31
  - ✅ Build Snow-Flow if needed
32
32
  - ✅ Start MCP servers automatically
33
33
  - ✅ Run health checks
34
- - ✅ Launch OpenCode with tools pre-loaded
34
+ - ✅ Launch SnowCode with tools pre-loaded
35
35
 
36
36
  ---
37
37
 
@@ -65,9 +65,9 @@ If you prefer OAuth, ensure your ServiceNow OAuth app has:
65
65
 
66
66
  Go to: **System OAuth** → **Application Registry** → Your OAuth App
67
67
 
68
- ### Step 2: Fix OpenCode Configuration
68
+ ### Step 2: Fix SnowCode Configuration
69
69
 
70
- Ensure `opencode-config.json` uses `"environment"` (not `"env"`):
70
+ Ensure `snowcode-config.json` uses `"environment"` (not `"env"`):
71
71
 
72
72
  ```json
73
73
  {
@@ -102,14 +102,14 @@ Ensure `opencode-config.json` uses `"environment"` (not `"env"`):
102
102
  # Should show: "✓ Health check passed - 370+ tools available"
103
103
  ```
104
104
 
105
- ### Step 4: Launch OpenCode
105
+ ### Step 4: Launch SnowCode
106
106
 
107
107
  ```bash
108
108
  # Option A: Use launcher (recommended)
109
- ./scripts/start-opencode.sh
109
+ ./scripts/start-snowcode.sh
110
110
 
111
111
  # Option B: Manual launch
112
- opencode
112
+ snowcode
113
113
  ```
114
114
 
115
115
  ---
@@ -223,12 +223,12 @@ SNOW_PASSWORD=your-password
223
223
 
224
224
  ### Error: "Model tried to call unavailable tool '$functions.snow_update_set_manage'"
225
225
 
226
- **Cause:** MCP tools not loaded in OpenCode
226
+ **Cause:** MCP tools not loaded in SnowCode
227
227
 
228
228
  **Fix:**
229
- 1. Check `opencode-config.json` uses `"environment"` (not `"env"`)
229
+ 1. Check `snowcode-config.json` uses `"environment"` (not `"env"`)
230
230
  2. Verify MCP servers are running: `./scripts/mcp-server-manager.sh status`
231
- 3. Restart OpenCode: `./scripts/start-opencode.sh`
231
+ 3. Restart SnowCode: `./scripts/start-snowcode.sh`
232
232
 
233
233
  ### Error: "Connection timeout" or "ECONNREFUSED"
234
234
 
@@ -301,15 +301,15 @@ SNOW_PASSWORD=your-password
301
301
 
302
302
  ---
303
303
 
304
- ## OpenCode Launcher Benefits
304
+ ## SnowCode Launcher Benefits
305
305
 
306
- Using `./scripts/start-opencode.sh` instead of direct `opencode`:
306
+ Using `./scripts/start-snowcode.sh` instead of direct `snowcode`:
307
307
 
308
308
  - ✅ Validates .env file exists
309
309
  - ✅ Builds Snow-Flow if dist/ missing
310
310
  - ✅ Auto-starts MCP servers
311
311
  - ✅ Runs pre-flight health checks
312
- - ✅ Creates opencode-config.json if missing
312
+ - ✅ Creates snowcode-config.json if missing
313
313
  - ✅ Replaces ${VARIABLES} with actual values
314
314
  - ✅ Shows clear error messages with solutions
315
315
 
@@ -323,8 +323,8 @@ Using `./scripts/start-opencode.sh` instead of direct `opencode`:
323
323
  # MCP server logs
324
324
  ./scripts/mcp-server-manager.sh logs
325
325
 
326
- # OpenCode logs (if available)
327
- cat ~/.opencode/logs/latest.log
326
+ # SnowCode logs (if available)
327
+ cat ~/.snowcode/logs/latest.log
328
328
  ```
329
329
 
330
330
  ### 2. Test Individual Components
@@ -351,7 +351,7 @@ curl -u "$SNOW_USERNAME:$SNOW_PASSWORD" \
351
351
  npm run build
352
352
 
353
353
  # Start fresh
354
- ./scripts/start-opencode.sh
354
+ ./scripts/start-snowcode.sh
355
355
  ```
356
356
 
357
357
  ### 4. Report Issue
@@ -360,7 +360,7 @@ If none of the above works, create a GitHub issue with:
360
360
 
361
361
  - Snow-Flow version: `npm list -g snow-flow`
362
362
  - Node.js version: `node -v`
363
- - OpenCode version: `opencode --version`
363
+ - SnowCode version: `snowcode --version`
364
364
  - Output of: `./scripts/mcp-server-manager.sh health`
365
365
  - Relevant logs (without passwords!)
366
366
 
@@ -1 +1 @@
1
- {"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/cli/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAycpD"}
1
+ {"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/cli/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA4uBpD"}