Skyenet MCP Ace

🚀 SkyeNet-MCP-ACE

供AI智能體使用的ServiceNow後臺腳本執行工具 - 這是一個模型上下文協議（MCP）服務器，支持AI智能體直接在ServiceNow實例上執行服務器端JavaScript代碼，同時具備減少上下文冗餘的功能。

🚀 快速開始

前提條件

• Node.js 20 及以上版本（建議進行系統級安裝）
• 具備 API 訪問權限的 ServiceNow 實例
• 擁有系統級安裝所需的 root/sudo 權限

安裝

# 克隆倉庫
git clone https://github.com/skyenet/skyenet-mcp-ace.git
cd skyenet-mcp-ace

# 進行可靠部署（處理所有邊緣情況）
sudo ./bulletproof-deploy.sh

# 驗證安裝
./bulletproof-verify.sh

配置

創建你的 ServiceNow 憑證文件：

# 複製示例文件
cp servicenow-ace.env.example ~/.servicenow-ace.env

# 使用你的 ServiceNow 詳細信息進行編輯
nano ~/.servicenow-ace.env

所需的環境變量：

SNOW_INSTANCE=https://your-instance.service-now.com
SNOW_USERNAME=your-username
SNOW_PASSWORD=your-password

Codex 集成

將以下內容添加到你的 Codex 配置文件（/etc/codex/config.toml）中：

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

✨ 主要特性

• 減少上下文冗餘：為 AI 智能體提供精簡模式和靜默模式。
• 可靠部署：自動處理所有邊緣情況。
• 多用戶兼容性：適用於系統內的所有用戶。
• 全面驗證：對所有場景進行測試。
• ServiceNow 集成：具備錯誤處理功能的直接 API 訪問。
• 更新集管理：支持完整的生命週期。
• 表操作：具備字段驗證的 CRUD 操作。

📦 安裝指南

安裝步驟

# 克隆倉庫
git clone https://github.com/skyenet/skyenet-mcp-ace.git
cd skyenet-mcp-ace

# 進行可靠部署（處理所有邊緣情況）
sudo ./bulletproof-deploy.sh

# 驗證安裝
./bulletproof-verify.sh

配置步驟

創建 ServiceNow 憑證文件：

# 複製示例文件
cp servicenow-ace.env.example ~/.servicenow-ace.env

# 使用你的 ServiceNow 詳細信息進行編輯
nano ~/.servicenow-ace.env

所需環境變量：

SNOW_INSTANCE=https://your-instance.service-now.com
SNOW_USERNAME=your-username
SNOW_PASSWORD=your-password

Codex 集成步驟

將以下內容添加到 /etc/codex/config.toml：

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

💻 使用示例

基礎用法

1. execute_background_script

直接在 ServiceNow 實例上執行服務器端 JavaScript 代碼。

參數：

• script（字符串）：要執行的 JavaScript 代碼
• quiet（布爾值，可選）：超精簡響應模式

示例：

// 獲取用戶信息
var user = new GlideRecord('sys_user');
user.get('admin');
gs.print(user.getDisplayValue());

2. execute_table_operation

在 ServiceNow 表上執行 CRUD 操作，同時減少上下文冗餘。

參數：

• operation（字符串）：GET、POST、PUT、DELETE
• table（字符串）：表名（例如，'sys_user'、'incident'）
• sys_id（字符串，可選）：特定操作所需的記錄 sys_id
• sys_ids（數組，可選）：批量操作所需的多個 sys_id
• fields（數組，可選）：要檢索的特定字段
• query（字符串，可選）：編碼後的查詢字符串
• limit（數字，可選）：返回的最大記錄數
• strict_fields（布爾值，可選）：啟用嚴格的字段驗證
• response_mode（字符串，可選）：'minimal' 用於減少響應大小

示例：

// 獲取用戶記錄
{
  "operation": "GET",
  "table": "sys_user",
  "fields": ["sys_id", "user_name", "email"],
  "limit": 10,
  "response_mode": "minimal"
}

// 創建事件
{
  "operation": "POST",
  "table": "incident",
  "data": {
    "short_description": "New incident",
    "priority": "3"
  }
}

3. execute_updateset_operation

管理 ServiceNow 更新集，同時減少上下文冗餘。

參數：

• operation（字符串）：recent、contents、set_working、get_working
• update_set_sys_id（字符串，可選）：更新集的 sys_id
• response_mode（字符串，可選）：'minimal' 用於減少響應大小
• quiet（布爾值，可選）：超精簡響應模式

示例：

// 獲取最近的 XML 活動（精簡模式）
{
  "operation": "recent",
  "response_mode": "minimal"
}

// 設置工作更新集
{
  "operation": "set_working",
  "update_set_sys_id": "abc123def456",
  "quiet": true
}

🔧 技術細節

上下文冗餘減少特性

精簡模式

• 表 API：截斷大字段、限制記錄數量、移除冗餘數據
• 更新集：限制為 5 條記錄、採用緊湊摘要、扁平化結構
• 後臺腳本：截斷輸出、移除詳細日誌

靜默模式

• 超精簡響應：僅返回成功/失敗狀態
• 無詳細輸出：僅包含必要信息
• 減少令牌使用：響應大小減少 90% 以上

響應大小示例

• 標準表 API：約 15KB
• 精簡表 API：約 700 字節
• 靜默更新集：約 300 字節
• 精簡更新集：約 2.6KB

🔄 維護

更新安裝

# 拉取最新更改
git pull origin main

# 重新運行可靠部署腳本
sudo ./bulletproof-deploy.sh

# 驗證一切正常
./bulletproof-verify.sh

徹底重新安裝

# 清除所有內容
sudo rm -rf /usr/local/lib/node_modules/skyenet-mcp-ace
sudo rm -f /usr/local/sbin/skyenet-mcp-ace-server

# 重新運行可靠部署腳本
sudo ./bulletproof-deploy.sh

# 驗證
./bulletproof-verify.sh

🚨 故障排除

服務器無法啟動

# 檢查服務器二進制文件
ls -la /usr/local/sbin/skyenet-mcp-ace-server

# 手動測試
/usr/local/sbin/skyenet-mcp-ace-server

# 檢查 Node.js 版本
/usr/bin/node --version

Codex 超時問題

# 驗證服務器是否正常工作
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /usr/local/sbin/skyenet-mcp-ace-server

# 檢查 Codex 配置
cat /etc/codex/config.toml | grep skyenet

權限問題

# 修復權限
sudo chmod +x /usr/local/sbin/skyenet-mcp-ace-server

# 驗證所有權
sudo chown root:root /usr/local/sbin/skyenet-mcp-ace-server

📊 項目結構

SkyeNet-MCP-ACE/
├── bulletproof-deploy.sh    # 可靠部署腳本
├── bulletproof-verify.sh    # 全面驗證腳本
├── src/                     # TypeScript 源代碼
│   ├── index.ts            # 主 MCP 服務器
│   ├── servicenow/         # ServiceNow 集成
│   └── utils/               # 實用函數
├── build/                  # 編譯後的 JavaScript
└── README.md              # 本文件

🔒 安全

• 憑證管理：與 MCP-Connect 分離
• 字段驗證：防止注入攻擊
• 錯誤處理：提供安全的錯誤響應
• 系統級安裝：具備正確的權限設置

📈 性能

• 響應時間：大多數操作的響應時間小於 3 秒
• 內存使用：針對 AI 智能體交互進行了優化
• 令牌效率：上下文冗餘減少 90% 以上
• 可靠性：可靠部署確保系統穩定性

如需詳細的部署說明，請查看可靠部署腳本中的註釋。