# 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.**