SkyeNet-MCP-ACE

ServiceNow Background Script Execution for AI Agents - A Model Context Protocol (MCP) server that enables AI agents to execute server-side JavaScript directly on ServiceNow instances with context bloat reduction features.

🚀 Quick Start

Prerequisites

• Node.js 20+ (system-wide installation recommended for Linux, nvm works on macOS)
• ServiceNow instance with API access
• Root/sudo access for system-wide installation (Linux only)

Installation

For Local Development (macOS/Linux)

# Clone the repository
git clone https://github.com/skyenet/skyenet-mcp-ace.git
cd skyenet-mcp-ace

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

For System-Wide Installation (Linux)

# Clone the repository
git clone https://github.com/skyenet/skyenet-mcp-ace.git
cd skyenet-mcp-ace

# Bulletproof deployment (handles all edge cases)
sudo ./bulletproof-deploy.sh

# Verify installation
./bulletproof-verify.sh

Note: The deployment scripts are Linux-specific. For macOS, use local development mode or configure manually.

Configuration

The MCP server supports multiple ways to provide credentials, checked in priority order:

1. Environment variables in MCP config (highest priority) - Recommended for project-specific configs
2. Project directory .servicenow-ace.env file - In the SkyeNet-MCP-ACE repository root
3. Home directory ~/.servicenow-ace.env file - Global/shared credentials
4. System directory /etc/csadmin/servicenow-ace.env - Linux system-wide fallback

Option 1: Environment Variables in MCP Config (Recommended)

When configuring the MCP server in Cursor (.cursor/mcp.json), you can pass credentials directly:

{
  "mcpServers": {
    "skyenet-ace": {
      "command": "node",
      "args": ["/absolute/path/to/SkyeNet-MCP-ACE/build/index.js"],
      "env": {
        "SERVICENOW_ACE_INSTANCE": "your-instance.service-now.com",
        "SERVICENOW_ACE_USERNAME": "your-username",
        "SERVICENOW_ACE_PASSWORD": "your-password"
      }
    }
  }
}

Advantages: Project-specific credentials, no separate .env files needed, works from any project folder.

Option 2: Environment File

Create your ServiceNow credentials file:

# Copy the example file
cp servicenow-ace.env.example ~/.servicenow-ace.env

# Edit with your ServiceNow details
nano ~/.servicenow-ace.env

Required environment variables:

SERVICENOW_ACE_INSTANCE=your-instance.service-now.com
SERVICENOW_ACE_USERNAME=your-username
SERVICENOW_ACE_PASSWORD=your-password

Note: You can also place .servicenow-ace.env in the project root directory for project-specific credentials.

Cursor IDE Integration

For Cursor IDE (Project-Level Configuration)

Create .cursor/mcp.json in your project folder:

{
  "mcpServers": {
    "skyenet-ace": {
      "command": "node",
      "args": ["/absolute/path/to/SkyeNet-MCP-ACE/build/index.js"],
      "env": {
        "SERVICENOW_ACE_INSTANCE": "your-instance.service-now.com",
        "SERVICENOW_ACE_USERNAME": "your-username",
        "SERVICENOW_ACE_PASSWORD": "your-password"
      }
    }
  }
}

Replace /absolute/path/to/SkyeNet-MCP-ACE with the actual path to this repository. See .cursor/mcp.json.example for a template.

Note: If credentials are provided via the env field, they take highest priority over any .env files.

For Codex (System-Wide Configuration)

Add to your Codex configuration (/etc/codex/config.toml):

[[mcp.servers.skyenet-ace]]
command = "/usr/local/sbin/skyenet-mcp-ace-server"
args = []

🛠️ Available Tools

1. execute_background_script

Execute server-side JavaScript directly on ServiceNow instances.

Parameters:

• script (string): The JavaScript code to execute
• quiet (boolean, optional): Ultra-minimal response mode

Example:

// Get user information
var user = new GlideRecord('sys_user');
user.get('admin');
gs.print(user.getDisplayValue());

2. execute_table_operation

Perform CRUD operations on ServiceNow tables with context bloat reduction.

Parameters:

• operation (string): GET, POST, PUT, DELETE
• table (string): Table name (e.g., 'sys_user', 'incident')
• sys_id (string, optional): Record sys_id for specific operations
• sys_ids (array, optional): Multiple sys_ids for batch operations
• fields (array, optional): Specific fields to retrieve
• query (string, optional): Encoded query string
• limit (number, optional): Maximum records to return
• strict_fields (boolean, optional): Enable strict field validation
• response_mode (string, optional): 'minimal' for reduced response size

Examples:

// Get user records
{
  "operation": "GET",
  "table": "sys_user",
  "fields": ["sys_id", "user_name", "email"],
  "limit": 10,
  "response_mode": "minimal"
}

// Create incident
{
  "operation": "POST",
  "table": "incident",
  "data": {
    "short_description": "New incident",
    "priority": "3"
  }
}

3. execute_updateset_operation

Manage ServiceNow Update Sets with context bloat reduction.

Parameters:

• operation (string): recent, contents, set_working, get_working
• update_set_sys_id (string, optional): Update Set sys_id
• response_mode (string, optional): 'minimal' for reduced response size
• quiet (boolean, optional): Ultra-minimal response mode

Examples:

// Get recent XML activity (minimal mode)
{
  "operation": "recent",
  "response_mode": "minimal"
}

// Set working update set
{
  "operation": "set_working",
  "update_set_sys_id": "abc123def456",
  "quiet": true
}

🔧 Context Bloat Reduction Features

Minimal Mode

• Table API: Truncates large fields, limits records, removes redundant data
• Update Sets: Limits to 5 records, compact summaries, flattened structure
• Background Scripts: Truncates output, removes verbose logging

Quiet Mode

• Ultra-minimal responses: Only success/failure status
• No verbose output: Essential information only
• Reduced token usage: 90%+ reduction in response size

Response Size Examples

• Standard Table API: ~15KB
• Minimal Table API: ~700 bytes
• Quiet Update Set: ~300 bytes
• Minimal Update Set: ~2.6KB

🔄 Maintenance

Update Installation

# Pull latest changes
git pull origin main

# Re-run bulletproof deployment
sudo ./bulletproof-deploy.sh

# Verify everything works
./bulletproof-verify.sh

Clean Reinstall

# Clean everything
sudo rm -rf /usr/local/lib/node_modules/skyenet-mcp-ace
sudo rm -f /usr/local/sbin/skyenet-mcp-ace-server

# Re-run bulletproof deployment
sudo ./bulletproof-deploy.sh

# Verify
./bulletproof-verify.sh

🚨 Troubleshooting

Server Won't Start

# Check server binary
ls -la /usr/local/sbin/skyenet-mcp-ace-server

# Test manually
/usr/local/sbin/skyenet-mcp-ace-server

# Check Node.js version
/usr/bin/node --version

Codex Timeout Issues

# Verify server works
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /usr/local/sbin/skyenet-mcp-ace-server

# Check Codex configuration
cat /etc/codex/config.toml | grep skyenet

Permission Issues

# Fix permissions
sudo chmod +x /usr/local/sbin/skyenet-mcp-ace-server

# Verify ownership
sudo chown root:root /usr/local/sbin/skyenet-mcp-ace-server

📊 Project Structure

SkyeNet-MCP-ACE/
├── bulletproof-deploy.sh    # Bulletproof deployment script
├── bulletproof-verify.sh    # Comprehensive verification
├── src/                     # TypeScript source code
│   ├── index.ts            # Main MCP server
│   ├── servicenow/         # ServiceNow integration
│   └── utils/               # Utility functions
├── build/                  # Compiled JavaScript
└── README.md              # This file

🎯 Key Features

• Context Bloat Reduction: Minimal and quiet modes for AI agents
• Bulletproof Deployment: Handles all edge cases automatically
• Multi-User Compatibility: Works for all users system-wide
• Comprehensive Verification: Tests all scenarios
• ServiceNow Integration: Direct API access with error handling
• Update Set Management: Full lifecycle support
• Table Operations: CRUD with field validation

🔒 Security

• Credential Management: Separate from MCP-Connect
• Field Validation: Prevents injection attacks
• Error Handling: Secure error responses
• System-wide Installation: Proper permissions

📈 Performance

• Response Times: < 3 seconds for most operations
• Memory Usage: Optimized for AI agent interactions
• Token Efficiency: 90%+ reduction in context bloat
• Reliability: Bulletproof deployment ensures stability

For detailed deployment instructions, see the bulletproof deployment script comments.