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% 以上
• 可靠性：可靠部署确保系统稳定性

如需详细的部署说明，请查看可靠部署脚本中的注释。