SN-MCP-Server

📘 SN-MCP-Server

适用于 ServiceNow 的只读 Model Context Protocol（MCP）服务，专为开发者、AI 工作流以及需要深入了解多个 ServiceNow 实例（Prod、Dev、Test、PDI）的工具打造。

---

✨ 功能特性

• 🔗 多实例 — 在一个服务中支持 Prod、Dev、Test、PDI
• 🔍 强大的查询能力 — 表、聚合、代码搜索 API
• 🧠 智能记录解析 — INC、CHG、RITM、sys_id
• 🔄 Flow Designer + 旧版工作流
• 🧩 架构检查与发现
• 👥 身份与访问数据
• 🔑 多种身份验证方式 — Basic Auth 和 OAuth 2.0（Client Credentials、Password、Auth Code、JWT）
• 🧰 支持 ServiceNow SDK — 全局安装 now-sdk 后会注册可选的 sn_sdk_explain 工具（npm install -g now-sdk）
• 默认只读 — 可安全用于生产实例
• 📄 每次运行生成日志文件 — 每次启动服务生成一个文件，存储在操作系统临时文件夹中
• 🔬 详细的工具日志 — 当 SN_MCP_VERBOSE=true 时，每次调用都会记录调用/接收调试信息（实例、参数、结果摘要）
• 📚 搜索 ServiceNow 文档 — sn_read_docs 搜索 ServiceNowDocs 仓库，返回 file_path/raw_url 以便直接读取，并可在请求非默认版本时解析所选分支

---

🚀 快速开始

选项 A — npx（无需安装）

npx @imjaineel-dev/sn-mcp-server --config ./sn-instance.json

选项 B — 本地克隆

git clone https://github.com/ImJaineel/SN-MCP-Server.git
cd SN-MCP-Server
npm install
npm start   # auto-detects sn-instance.json in repo root

---

⚙️ 配置

1. 创建 sn-instance.json

{
  "default": "dev",
  "instances": [
    {
      "alias": "prod",
      "label": "Production",
      "instance": "mycompany-prod",
      "auth": "oauth2",
      "grant_type": "client_credentials",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret"
    },
    {
      "alias": "dev",
      "label": "Development",
      "instance": "mycompany-dev",
      "auth": "basic",
      "username": "svc_mcp_readonly",
      "password": "your-password-here"
    }
  ]
}

📄 完整示例：sn-instance.example.json

常用字段

字段	必填	说明
alias	✅	工具调用中使用的简称（"prod"、"dev-2"）
instance	✅	子域名（"mycompany-dev"）或完整 URL（"https://..."）
auth	可选	"basic"（默认）或 "oauth2"
label	可选	方便识别的显示名称
default	可选	可使用顶层 "default" 别名，或在条目中设置 "default": true 来选择默认实例

Basic Auth（auth: "basic"）

字段	必填	说明
username	✅	服务账户用户名
password	✅	密码或 API 令牌

OAuth 2.0（auth: "oauth2"）

字段	必填	说明
grant_type	✅	"client_credentials"、"password"、"authorization_code" 或 "jwt_bearer"
client_id / client_secret	✅	OAuth 应用凭据
username / password	有条件	password 授权类型必填
refresh_token	有条件	authorization_code 授权类型必填
jwt_private_key / jwt_subject	有条件	jwt_bearer 授权类型必填（PEM 密钥字符串和主题用户）
jwt_issuer	可选	jwt_bearer 授权类型的可选颁发者值
token_url	可选	覆盖默认令牌端点（默认值：/oauth_token.do）

默认实例按以下顺序确定：

1. 配置对象中明确指定的顶层 "default" 别名
2. 设置了 "default": true 的条目
3. 列表中的第一项

---

2. 环境变量（可选）

所有变量均为可选项——可在 shell、MCP 客户端的 "env" 块或项目根目录的 .env 文件中设置。shell 中的值优先于 .env 中的值。

**注意：**如果从本地克隆运行服务，启动时会自动加载根目录下的 .env 文件。

变量	说明	默认值
SN_INSTANCE_CONFIG	sn-instance.json 的路径	自动解析
SN_MCP_VERBOSE	设置为 "true" 以启用调试日志	false
LOGS_TIMEZONE	日志时间戳使用的 IANA 时区（CURRENT、GLOBAL 或指定时区）	CURRENT
SN_LOG_DIR	覆盖日志文件目录	操作系统临时文件夹
GITHUB_TOKEN	用于 sn_read_docs（分支查询和 GitHub 搜索）的 GitHub 个人访问令牌	无

也支持使用 CLI 标志作为环境变量的替代方案：

• --config <path> → 设置 SN_INSTANCE_CONFIG
• --verbose → 设置 SN_MCP_VERBOSE=true
• --github-token <token> → 设置 GITHUB_TOKEN

---

🔌 MCP 客户端设置

适用于所有人

**VS Code：**按 Ctrl+Shift+P，选择 Add MCP

**Claude Desktop：**编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

**Gemini Code Assist：**创建或编辑 ~/.gemini/mcp.json

**Amazon Q：**创建或编辑 ~/.aws/amazonq/mcp.json

使用 npx（推荐）：

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["sn-mcp-server", "--config", "/absolute/path/to/sn-instance.json"],
    }
  }
}

使用本地克隆：

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/SN-MCP-Server/src/index.js"]
    }
  }
}

⚠️ MCP 客户端配置中务必使用绝对路径。

---

▶️ 本地运行

# Standard start (auto-detects ./sn-instance.json)
npm start

# With explicit config path
node src/index.js --config /path/to/sn-instance.json

# With verbose logging
npm run dev
node src/index.js --config ./sn-instance.json --verbose

# Auto-restart on file changes (development)
npm run watch

# Open MCP Inspector UI in browser (test tools interactively)
npm run inspect
# The inspector launcher accepts localhost and 127.0.0.1 origins so the browser can connect reliably.

# Show help
npx sn-mcp-server --help

---

🪵 日志

每次运行服务都会创建一个带时间戳的新日志文件：

2026-04-09T14-32-01.123Z.log

日志存储在操作系统的临时目录中：

操作系统	默认日志位置
Windows	%TEMP%\ImJaineel_SN-MCP-Instance_logs\
macOS	$TMPDIR/ImJaineel_SN-MCP-Instance_logs/
Linux	/tmp/ImJaineel_SN-MCP-Instance_logs/

使用 SN_LOG_DIR 环境变量进行覆盖。操作系统会在重启时自动清理日志文件。

启动横幅始终会显示准确的日志文件路径：

Log file : /tmp/ImJaineel_SN-MCP-Instance_logs/2026-04-09T14-32-01.123Z.log

---

🧰 可用工具

在当前环境支持的情况下，服务运行时会公开 16 个工具：

• 14 个实例工具——需要配置 sn-instance.json
• 2 个知识工具——与实例无关，用于提供文档和 SDK 指导

14 个实例工具

工具	描述	可见性
sn_list_instances	列出所有已配置的实例及其别名、标签和 URL。	配置并加载 sn-instance.json 后可见。
sn_ping	测试与特定实例或默认实例的连接。	配置并加载 sn-instance.json 后可见。
sn_get_identity	从身份表中查询用户、群组和群组成员关系。	配置并加载 sn-instance.json 后可见。
sn_inspect_table	检查表架构，或按名称/标签搜索匹配的表。	配置并加载 sn-instance.json 后可见。
sn_aggregate_table	执行计数、求和、平均值、最小值和最大值等聚合查询。	配置并加载 sn-instance.json 后可见。
sn_query_table	从任意 ServiceNow 表中通用读取数据，支持编码查询、字段、分页和显示值。	配置并加载 sn-instance.json 后可见。
sn_get_record	按 sys_id、记录编号、任务表或 CMDB CI 类解析并获取记录。	配置并加载 sn-instance.json 后可见。
sn_get_attachment	从 Attachment API 获取附件元数据或文件内容。	配置并加载 sn-instance.json 后可见。
sn_get_update_sets	列出更新集，或深入查看特定更新集中的文件。	配置并加载 sn-instance.json 后可见。
sn_code_search	使用原生 ServiceNow Code Search API 搜索脚本工件。	配置并加载 sn-instance.json 后可见。
sn_get_scripted_artifacts	获取 Script Includes、Business Rules、Client Scripts、UI Actions、Scheduled Jobs、Fix Scripts 和 Scripted REST 工件。	配置并加载 sn-instance.json 后可见。
sn_legacy_workflow_search	搜索经典工作流活动变量值，并解析所属的工作流版本。	配置并加载 sn-instance.json 后可见。
sn_get_legacy_workflow_artifacts	从 wf_* 表中获取旧版工作流工件。	配置并加载 sn-instance.json 后可见。
sn_get_workflow_studio_artifacts	从 sys_hub_* 和相关表中获取 Workflow Studio 和 Flow Designer 工件。	配置并加载 sn-instance.json 后可见。

2 个知识工具

工具	描述	可见性
sn_read_docs	按发布分支搜索、浏览和阅读 ServiceNowDocs Markdown。搜索模式会返回 file_path 和 raw_url 值，以便直接读取；get_file 接受原始 GitHub URL 或相对于仓库的路径。	始终可见。
sn_sdk_explain	通过 now-sdk 查询 ServiceNow SDK，获取有关 SDK 技能、API 和概念的说明。	仅在安装并可成功执行 now-sdk 时可见。

运行时可见性规则

• 实例工具（14 个）在服务以无配置模式（未提供 sn-instance.json）启动时会隐藏。在此模式下，仅保留可见的 2 个知识工具。
• **sn_read_docs**始终会注册，因为它不依赖 ServiceNow 实例凭据。
• **sn_sdk_explain**仅在成功探测 now-sdk 后添加；如果未安装该软件包或无法执行，则完全省略此工具。使用以下命令全局安装：npm install -g now-sdk
• 每个实例工具都接受可选的 instance 参数。如果省略，服务会使用已配置的默认实例。

---

💡 使用示例

指定目标实例

sn_get_scripted_artifacts  table="sys_script_include"  query="nameLIKEMorpheus"  instance="prod"
sn_query_table  table="incident"  query="state=1"  instance="dev"
sn_get_update_sets  instance="pdi"

查询事件

{ "tool": "sn_query_table", "table": "incident", "query": "active=true", "limit": 5 }

搜索 ServiceNow 文档

{ "tool": "sn_read_docs", "mode": "search", "search": "Install the ServiceNow SDK in an application", "version": "australia" }

使用 mode": "get_file" 和返回的 file_path 或 raw_url 读取匹配的文档。

按编号获取记录

{ "tool": "sn_get_record", "number": "INC0012345" }

搜索旧版工作流

{ "tool": "sn_legacy_workflow_search", "query": "morpheus", "instance": "prod" }

聚合

{
  "tool": "sn_aggregate_table",
  "table": "incident",
  "aggregates": [{ "field": "priority", "function": "count" }],
  "group_by": ["priority"]
}

---

📁 项目结构

SN-MCP-Server/
├── src/
│   ├── cli.js            ← npx entrypoint (--config, --verbose, --github-token, --help)
│   ├── index.js          ← server bootstrap and startup banner
│   ├── config.js         ← config path resolution and validation
│   ├── validator.js      ← sn-instance.json schema validation
│   ├── constants.js      ← shared repo/example URLs
│   ├── env-loader.js     ← .env file parser (no external deps)
│   ├── logger.js         ← structured logger, per-run log files
│   ├── multi-client.js   ← multi-instance routing and default-instance resolution
│   ├── sn-client.js      ← per-instance REST client
│   ├── handler.js        ← tool name → method router
│   ├── tools.js          ← MCP tool definitions
│   ├── docs-client.js    ← ServiceNowDocs search/browse/read implementation
│   └── sdk-client.js     ← ServiceNow SDK availability probe and explain helper
├── scripts/
│   ├── dev.js            ← development helper
│   └── inspect.js        ← MCP Inspector launcher with origin allowlist
├── sn-instance.json          ← your credentials (git-ignored)
├── sn-instance.example.json  ← template with supported auth flows
├── .env.example              ← environment variable documentation
├── README.md                 ← full project documentation
└── package.json

---

⚠️ 故障排除

凭据无效

• 检查 sn-instance.json 中的用户名和密码
• 确保 ServiceNow 中已启用该帐户的 REST API 访问权限

无法访问实例

• 检查 instance 值的格式——子域名或完整 URL
• 检查 VPN / 网络连接

sn-instance.json 验证错误

• 服务会打印具体错误消息，指出确切的字段/条目
• 查看示例：sn-instance.example.json

MCP 客户端未检测到服务

• 在 MCP 客户端配置中始终使用绝对路径
• 更改配置后，重启 MCP 客户端

---

🔐 安全说明

• sn-instance.json 位于 .gitignore 中——切勿提交该文件
• 每个实例使用专用的只读服务帐户
• PDI 实例可以安全地使用 admin 凭据，因为它们彼此隔离
• 不要在共享环境中将凭据存储在环境变量中

---

🤝 参与贡献

欢迎提交 PR！进行较大的更改前，请先创建 issue。

🐛 报告错误

如果遇到错误，请在此处创建 GitHub issue：

• https://github.com/ImJaineel/SN-MCP-Server/issues/new

请在报告中包含以下信息，以便快速修复：

• 你预期发生什么
• 实际发生了什么
• 你使用的命令或 MCP 客户端配置
• 相关日志输出或错误文本
• 来自 sn-instance.json 或 .env 的任何已脱敏片段

---

📄 许可证

详情请参阅 LICENSE。