SkyeNet-MCP-ACE

# 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) ```bash # 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) ```bash # 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: ```json { "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: ```bash # Copy the example file cp servicenow-ace.env.example ~/.servicenow-ace.env # Edit with your ServiceNow details nano ~/.servicenow-ace.env ``` Required environment variables: ```bash 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: ```json { "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`): ```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:** ```javascript // 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:** ```javascript // 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:** ```javascript // 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 ```bash # Pull latest changes git pull origin main # Re-run bulletproof deployment sudo ./bulletproof-deploy.sh # Verify everything works ./bulletproof-verify.sh ``` ### Clean Reinstall ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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.**