servicenow-mcp-ai

# ServiceNow MCP 服务器 | [](https://www.npmjs.com/package/servicenow-mcp-ai) | [](https://www.npmjs.com/package/servicenow-mcp-ai) | [](https://www.npmjs.com/package/servicenow-mcp-ai) | [](https://github.com/IvanBBaev/servicenow-mcp-ai#tools) | [](LICENSE) | | :--: | :--: | :--: | :--: | :--: | | [](https://github.com/IvanBBaev/servicenow-mcp-ai/actions/workflows/ci.yml) | [](https://codecov.io/gh/IvanBBaev/servicenow-mcp-ai) | [](https://github.com/IvanBBaev/servicenow-mcp-ai/commits/main) | [](https://modelcontextprotocol.io) | [](https://snyk.io/test/npm/servicenow-mcp-ai) | 📖 **[文档站点 →](https://ivanbbaev.github.io/servicenow-mcp-ai/)** 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，允许 MCP 客户端（VS Code、Claude Desktop 等）通过 REST API 在 **ServiceNow** 实例上运行命令 — 表格、聚合、附件、导入集、批处理和 CMDB，以及服务目录、变更管理和知识插件 API。凭证存储在本地环境文件中，可以通过工具在运行时更新。 > **从 1.x 升级？** v2.0 默认情况下使写入 **计划默认**：`create`/`update`/`delete` 和其他记录写入工具返回非变异预览，除非您传递 `apply: true`（或设置 `SN_WRITE_MODE=apply` 以恢复 v1 的“立即执行”行为）。请参阅 [CHANGELOG](CHANGELOG.md) → 2.0.0 以获取完整的迁移说明。 **内容：** [快速演示](#quick-demo) · [功能](#features) · [要求](#requirements) · [设置](#setup) · [配置凭证](#configure-credentials) · [运行/调试](#run--debug) · [开发](#develop) · [工具](#tools) · [资源](#resources) · [提示](#prompts) · [项目结构](#project-structure) · [安全说明](#security-notes) · [项目文档](#project-documentation) ## 快速演示 平台使三个功能变得简单，每个功能只需一个调用。将您的 MCP 客户端指向实例（[设置](#setup)）并询问： **1. “这个字段实际上在哪里使用？”** — 查找使用它的每个脚本、业务规则、客户端脚本、UI 策略/操作和 ACL，作为 JSON 或 Mermaid 图。ServiceNow 没有按钮的 IDE 级 _查找用法_： ```jsonc // servicenow_where_used { "kind": "field", // "table" | "field" | "script" "name": "u_cost_center", "mermaid": true, // 还会渲染引用图 } ``` **2. “当我保存这个记录时会发生什么？”** — 执行顺序的完整自动化链（显示 → 之前 → 之后 → 异步业务规则，然后是流程、 工作流和通知），每个都有其条件 — 一个逻辑测试，运行 **无**： ```jsonc // servicenow_trace_table_event { "table": "incident", "operation": "update", // insert | update | delete | query } ``` **3. “dev 和 prod 之间有什么差异？”** — 两个配置配置文件之间表格、列、脚本（按 SHA-256）和插件的 Markdown 差异，具有 CI 友好的退出代码，以便管道可以阻止高风险部署： ```bash servicenow-mcp-ai drift dev prod # 在 stdout 上报告；如果有差异则退出 1，如果干净则退出 0 ``` 所有这三个都是 **只读** 的，并且适用于任何实例 — 包括免费的 PDI — 使用您选择的模型和客户端。 ## 功能 - 完整的 **表格 API**：查询、读取、创建、更新和删除 **任何** 表格中的记录，具有编码查询、字段选择和分页。 - 额外的 ServiceNow API：**聚合**（统计）、**附件**（列表/上传/下载/删除）、**导入集**、**批处理**（单个请求中的多个 REST 调用），以及表格/列 **元数据**（`sys_db_object`、`sys_dictionary`）。 - 流程和插件 API：**CMDB**（类感知 CI CRUD + 通过 IRE 的元数据）、**服务目录**（浏览/订购项目）、**变更管理**（类型创建 + 冲突检测）和 **知识**（文章搜索）。插件范围内的 API 在实例上不活动时报告清楚。 - **脚本智能**：读取和搜索实例自己的代码（业务规则、脚本包含、客户端脚本、UI 策略/操作、计划作业、转换/REST 脚本、ACL），并获取表格的完整自动化图片 — 所有这些都通过表格 API 只读。 - **流程跟踪和代码检查**（第 8 阶段）：确定性地跟踪表格操作运行的内容（`flows` 包 — 业务规则、流程、工作流和通知，按顺序，并带有 Mermaid 流程图），读取 Flow Designer 流程和运行历史，并使用聚合代码健康报告检查脚本是否符合本地规则集（`codecheck`）。通过 CI/CD API 运行 ATF 测试（`atf`，可选，非默认 — 运行工具在实例上执行）。 - **自我文档**：本地 Markdown 知识库（读/写/搜索）加上确定性 Mermaid 生成器（从引用生成 ER 图，从业务规则生成记录生命周期流程图），因此服务器构建持久、可重用的上下文。 - **提示**：预制工作流（事件分类、变更影响分析、记录表格）协调工具。 - **工具包**：通过 `SN_TOOL_PACKAGES` 加载您需要的工具组（默认配置文件 `core`；`all` 启用所有功能）。 - **基本** 或 **OAuth 2.0** 身份验证通过 HTTPS；密码/令牌永远不会回显。 - 特权最小化控制：表格允许/拒绝列表和全局只读模式。 - 弹性：每个请求的超时、重试和回退、`Retry-After`、SSRF 防护和结果大小防护。 - MCP **工具注释** 和 **资源**、结构化错误有效载荷和 stderr 上的结构化日志记录。 - 环境文件中的凭证（项目、`~/.config` 或 `SN_ENV_FILE`），可在运行时通过 `servicenow_set_credentials` 更新。 ## 要求 - Node.js 20+（强制执行：`engines` + 带有清晰消息的运行时保护；项目以 `.nvmrc` 中的版本为目标）。 ## 设置 从源代码（用于开发）： ```bash npm install npm run build ``` 或直接运行已发布的软件包，无需克隆： ```bash npx servicenow-mcp-ai ``` 使用 MCP 客户端（Claude Desktop、VS Code Chat、Inspector …）注册它，指向 `npx`： ```json { "mcpServers": { "servicenow": { "command": "npx", "args": ["-y", "servicenow-mcp-ai"] } } } ``` **Claude Code 插件**（零配置 — 安装已连接的服务器）： ```bash /plugin marketplace add IvanBBaev/servicenow-mcp-ai /plugin install servicenow-mcp-ai ``` **VS Code** — 从市场安装 **ServiceNow MCP** 扩展（`code --install-extension ivanbbaev.servicenow-mcp-ai`）；它在 Copilot Chat（代理模式）中自动注册服务器，无需手动 `mcp.json`。源代码：[extension/](extension/)。 凭证从 `~/.config/servicenow-mcp-ai/.env`（或实际环境变量）读取 — 参见下文。 ## 配置凭证 凭证存储在根目录的 `.env` 文件中（git-ignored）： ```dotenv SN_INSTANCE=your-instance.service-now.com SN_USER=your.username@example.com SN_PASSWORD=your-password ``` `SN_INSTANCE` 接受 `dev12345`、`dev12345.service-now.com` 或完整的 `https://` URL。 您也可以通过调用 `servicenow_set_credentials` 工具在运行时设置或更改它们 — 新值直接写入环境文件。 环境文件按以下顺序解析：`SN_ENV_FILE`，然后如果存在 `~/.config/servicenow-mcp-ai/.env`（XDG），然后是项目根目录 `.env`。因此，全局/`npx` 安装写入用户配置而不是 `node_modules`。实际环境变量始终优先于文件。 ### OAuth 2.1（授权代码 + PKCE）— 推荐 在 ServiceNow 中注册一个 **授权代码** OAuth API 端点，带有循环回调 URL（例如 `http://localhost:53682/callback`），设置 `SN_OAUTH_CLIENT_ID`（和 `SN_OAUTH_CLIENT_SECRET` 用于机密客户端），然后运行一次性交互式登录： ```bash npx servicenow-mcp-ai login ``` 它打开浏览器，您批准后，获得的 **刷新令牌** 存储在您的环境文件中。然后服务器非交互式运行（刷新令牌授权）— 永远不会存储密码。始终使用 PKCE（S256）。 > OAuth 2.0 **密码授权（ROPC）已弃用** 在 OAuth 2.1 中，并已在许多实例上禁用；请优先使用 `login`。`client_credentials` 和 `refresh_token` 授权仍然支持服务帐户。请参阅 [.env.example](.env.example)。 ### 支持的身份验证方法 ServiceNow 提供的每个入站 REST 身份验证方法都涵盖了： | 方法 | `SN_AUTH` | 设置 | 注意 | | ------ | --------- | --- | ----- | | 基本 | `basic` | `SN_USER` / `SN_PASSWORD` | 默认。 | | OAuth 2.1 — 授权代码 + PKCE | `oauth` | `npx servicenow-mcp-ai login` | **推荐。** 交互式，存储刷新令牌。 | | OAuth — 客户端凭证 | `oauth` | `SN_OAUTH_GRANT=client_credentials` | 服务到服务。 | | OAuth — 刷新令牌 | `oauth` | `SN_OAUTH_GRANT=refresh_token` + `SN_OAUTH_REFRESH_TOKEN` | 由 `login` 设置。 | | OAuth — JWT 承载者 | `oauth` | `SN_OAUTH_GRANT=jwt_bearer` + `SN_OAUTH_JWT_KEY` | RS256 断言；无密码。 | | OAuth — 密码（ROPC） | `oauth` | `SN_OAUTH_GRANT=password` | **已弃用。** | | API 密钥 | `apikey` | `SN_API_KEY` | `x-sn-apikey` 头。 | | 承载令牌 | `token` | `SN_BEARER_TOKEN` | 预先获取的令牌，原样使用。 | | 互惠 TLS（客户端证书） | `none`（或分层） | `SN_TLS_CLIENT_CERT` / `_KEY` | 证书映射到用户；需要可选的 `undici`。 | ### 环境变量 所有设置都从 `.env` 文件（或实际的进程环境，后者优先）中读取。只有前三个是必需的；其余的是可选的微调旋钮。请参阅 [.env.example](.env.example) 获取模板。 | 变量 | 是否必需 | 默认值 | 描述 | | --- | --- | --- | --- | | `SN_INSTANCE` | 是 | — | 实例名称、主机或 `https://` URL（`dev12345`、`dev12345.service-now.com`）。 | | `SN_USER` | 是 | — | 用于基本身份验证的 ServiceNow 用户名。 | | `SN_PASSWORD` | 是 | — | ServiceNow 密码。永不记录或由任何工具返回。 | | `SN_TIMEOUT_MS` | 否 | `30000` | 每个请求的超时时间（毫秒）。 | | `SN_MAX_RETRIES` | 否 | `2` | 暂时性故障（429/5xx，网络错误）的重试次数。非幂等写入仅在连接错误时重试。 | | `SN_MAX_RECORDS` | 否 | `10000` | `fetchAll` 查询返回的记录硬上限。 | | `SN_MAX_RESULT_CHARS` | 否 | `100000` | 查询结果的字符预算，在发送给客户端之前进行截断。 | | `SN_ALLOWED_HOSTS` | 否 | — | 允许的主机逗号分隔列表（用于自定义或主权云域）。设置后，仅允许匹配的主机被联系。未设置时，仅允许 `*.service-now.com` 实例，内部/环回主机被阻止（SSRF 防护）。 | | `SN_AUTH` | 否 | `auto` | 身份验证方法：`basic`、`oauth`、`apikey`、`token` 或 `none`（仅限 mTLS 证书）。根据存在的密钥自动检测（API 密钥 → bearer → OAuth → 基本身份验证）。 | | `SN_API_KEY` | 否 | — | ServiceNow Inbound API 密钥，通过 `x-sn-apikey` 头发送（启用 `apikey` 模式）。 | | `SN_BEARER_TOKEN` | 否 | — | 预先获取的 bearer 令牌，原样发送为 `Authorization: Bearer …`（启用 `token` 模式）。 | | `SN_OAUTH_CLIENT_ID` | 否 | — | OAuth 客户端 ID（其存在启用 OAuth）。 | | `SN_OAUTH_CLIENT_SECRET` | 否 | — | OAuth 客户端密钥。 | | `SN_OAUTH_GRANT` | 否 | `password` | OAuth 授权：`password`（**弃用** — ROPC）、`client_credentials`、`refresh_token` 或 `jwt_bearer`。`login` 命令为你设置此值为 `refresh_token`。 | | `SN_OAUTH_JWT_KEY` | 否 | — | `jwt_bearer` 授权的 PEM 私钥（或 `SN_OAUTH_JWT_KEY_FILE`）。可选声明：`SN_OAUTH_JWT_ISS`（默认客户端 ID）、`SN_OAUTH_JWT_SUB`（默认 `SN_USER`）、`SN_OAUTH_JWT_AUD`、`SN_OAUTH_JWT_KID`、`SN_OAUTH_JWT_EXP_SEC`（默认 300）。 | | `SN_OAUTH_REFRESH_TOKEN` | 否 | — | `refresh_token` 授权的刷新令牌。通过 `npx servicenow-mcp-ai login`（授权码 + PKCE）自动获取。 | | `SN_OAUTH_REDIRECT_URI` | 否 | `http://localhost:53682/callback` | PKCE `login` 流的环回重定向 URL。必须与 OAuth 端点上注册的重定向 URL 匹配。 | | `SN_OAUTH_SCOPE` | 否 | — | `login` 期间请求的 OAuth 作用域。 | | `SN_TLS_CLIENT_CERT` | 否 | — | **相互 TLS** 的客户端证书（PEM）（或 `SN_TLS_CLIENT_CERT_FILE`）。使用 `SN_TLS_CLIENT_KEY` 它会呈现客户端证书；ServiceNow 的相互身份验证配置文件将其映射到用户。需要可选的 `undici` 包（`npm i undici`）。 | | `SN_TLS_CLIENT_KEY` | 否 | — | 客户端证书的私钥（PEM）（或 `SN_TLS_CLIENT_KEY_FILE`）。 | | `SN_TLS_CA` | 否 | — | 可选的 CA 捆绑包（PEM）以信任（或 `SN_TLS_CA_FILE`）。`SN_TLS_REJECT_UNAUTHORIZED=false` 禁用验证（不推荐）。 | | `SN_TABLES_ALLOW` | 否 | — | 逗号分隔的表允许列表；设置后，仅允许这些表可访问。 | | `SN_TABLES_DENY` | 否 | — | 逗号分隔的表拒绝列表；始终优先于允许列表。 | | `SN_READONLY` | 否 | `false` | 为真时，拒绝所有创建/更新/删除操作。 | | `SN_WRITE_MODE` | 否 | `plan` | `plan`（默认）以 before/after 差异预览写入；`apply` 执行；传递 `apply:true` 强制单个调用。 | | `SN_REDACT_FIELDS` | 否 | — | DF-5：在记录到达模型之前屏蔽这些字段值（逗号/空格分隔）。 | | `SN_REDACT_PII` | 否 | `false` | DF-5：还在字符串值中屏蔽 email/phone/national-id 模式。 | | `SN_TRANSPORT` | 否 | `stdio` | DF-6：`stdio`（默认）或 `http`（用于远程/代理客户端的可流式 HTTP）。 | | `SN_PORT` | 否 | `3000` | DF-6：HTTP 传输的 TCP 端口。 | | `SN_HTTP_HOST` | 否 | `127.0.0.1` | DF-6：HTTP 传输的绑定地址（默认环回）。 | | `SN_HTTP_TOKEN` | 否 | — | DF-6：设置后，HTTP 请求必须发送 `Authorization: Bearer <token>`。 | | `SN_LOG_LEVEL` | 否 | `info` | stderr 上的日志详细程度：`error`、`warn`、`info`、`debug`。 | | `SN_ENV_FILE` | 否 | — | 要读取/写入的环境文件的显式路径。 | | `SN_TOOL_PACKAGES` | 否 | `core` | 逗号/空格分隔的工具包或配置文件以启用。配置文件：`core`（默认）和 `all`。软件包：`table`、`schema`、`aggregate`、`attachment`、`importset`、`batch`、`catalog`、`change`、`knowledge`、`cmdb`、`scripts`、`flows`、`codecheck`、`docs`、`instance`、`email`、`atf`。管理员工具始终开启。`atf` 在实例上运行测试 - 仅在非生产实例上启用。 | | `SN_PACKAGES_DENY` | 否 | — | 逗号/空格分隔的软件包列表，即使 `SN_TOOL_PACKAGES` 启用也排除。阻止插件 API 的唯一方法（目录、更改、知识...），表策略看不到它们。 | | `SN_PACKAGES_READONLY` | 否 | — | 逗号/空格分隔的软件包列表，其写入工具未注册；其读取工具保留。每个软件包的全局 `SN_READONLY` 补充。 | | `SN_SCHEMA_CACHE_TTL_SEC` | 否 | `300` | 近静态模式读取缓存的 TTL（`list_tables`、`describe_table`、`get_cmdb_meta`）。`0` 禁用缓存。 | | `SN_MAX_CONCURRENT` | 否 | `4` | 实例的最大并行 HTTP 请求数（简单的进程内信号量）。 | | `SN_INCLUDE_REF_LINKS` | 否 | `false` | 默认情况下，引用字段不带其 `link` URL 返回（节省令牌）。设置 `true` 以包含它们。 | | `SN_RESULT_PRETTY` | 否 | `false` | 默认情况下，工具结果为紧凑的 JSON（美化打印约双倍令牌）。设置 `true` 以使用缩进输出。 | | `SN_DOCS_DIR` | 否 | `docs/instance` | `docs` 包读取/写入 Markdown 的目录。相对路径相对于工作目录解析。 | | `SN_CODESEARCH` | 否 | `false` | 选择加入 Code Search API (`sn_codesearch`) 用于 `servicenow_search_code`（FT-7）。当 `true` 且插件激活时，它替换 LIKE 迭代；如果失败，则回退到 LIKE。 | | `SN_PROFILE_<NAME>_*` | 否 | — | 命名连接配置文件：`SN_PROFILE_DEV_INSTANCE` / `_USER` / `_PASSWORD` 定义配置文件 `dev`。裸 `SN_INSTANCE`/`SN_USER`/`SN_PASSWORD` 键是 `default` 配置文件。 | | `SN_ACTIVE_PROFILE` | 否 | `default` | 工具使用的配置文件。运行时使用 `servicenow_use_instance` 切换（持久化到 env 文件）。 | ## 运行/调试 - **VS Code**：打开命令面板并启动 [.vscode/mcp.json](.vscode/mcp.json) 中定义的服务器，然后从 Chat 使用它。 - **MCP Inspector**：`npm run inspector` - **直接运行**：`npm start` ### 命令行界面 已发布的 `servicenow-mcp-ai` 二进制文件（直接运行或通过 `npx servicenow-mcp-ai`）有三个调用。所有连接设置均来自环境变量/环境文件（请参见 [环境变量](#环境变量)）；只有 `drift` 需要位置参数。 | 命令 | 位置参数 | 功能描述 | | --- | --- | --- | | `servicenow-mcp-ai` | _（无）_ | 启动 MCP 服务器。传输（默认 `stdio` 或 `http`）由 `SN_TRANSPORT` 选择；运行直到 `SIGINT`/`SIGTERM`。 | | `servicenow-mcp-ai login` | _（无 - 操作活动配置文件）_ | 一次性 OAuth 2.1 授权码 + PKCE 登录：打开浏览器，捕获环回重定向，存储刷新令牌。 | | `servicenow-mcp-ai drift <profileA> <profileB>` | `<profileA>`，`<profileB>` - 两个配置的配置文件名称 | DF-3 CI 漂移门：比较两个实例并写入 Markdown 差异报告。 | **`login`** 操作活动配置文件（`SN_ACTIVE_PROFILE`，默认为 `default`）并为该配置文件读取： - `SN_INSTANCE` - **必需**；目标实例。 - `SN_OAUTH_CLIENT_ID` - **必需**；授权码 OAuth API 端点的客户端 ID。 - `SN_OAUTH_CLIENT_SECRET` - 可选；用于机密客户端。 - `SN_OAUTH_REDIRECT_URI` - 可选；环回 URL，默认为 `http://localhost:53682/callback`。必须与端点上注册的重定向 URL 匹配。 - `SN_OAUTH_SCOPE` - 可选；请求的 OAuth 作用域。 成功时，它将 `SN_AUTH=oauth`、`SN_OAUTH_GRANT=refresh_token` 和 `SN_OAUTH_REFRESH_TOKEN` 写回环境文件（配置文件名前缀为配置文件非 `default`）。授权 URL 打印到 stderr，以防浏览器无法自动打开。 **`drift`** 需要两个位置配置文件名称；每个名称必须解析为已配置的配置文件（`SN_PROFILE_<NAME>_*` 或裸 `SN_INSTANCE` / `SN_USER` / `SN_PASSWORD` 键用于 `default`）。Markdown 报告写入 **stdout**（将其捕获为 CI 工件）；单行漂移摘要输出到 stderr。 ### CI 漂移门（DF-3） 比较两个已配置的配置文件并 **在配置漂移时失败管道**: ```bash servicenow-mcp-ai drift dev prod # 报告到 stdout；exit 1 on drift, 0 if clean, 2 on error ``` ## 开发 ```bash npm run check # 完整检查：构建、lint、格式检查、覆盖率测试、生产审计 npm test # 仅单元测试（node:test; 需要先运行 npm run build） npm run lint # ESLint（flat config + typescript-eslint） npm run format # 使用 Prettier 格式化 ``` 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取约定（每个任务一个提交，测试随更改一起发布，生成的文档）。 ## 工具列表 <!-- GENERATED:TOOLS:BEGIN (npm run docs:readme) --> _此表格由工具注册生成 — 编辑 `src/tools/` 中的工具定义，然后运行 `npm run docs:readme`._ | 包 | 工具 | 只读 | 描述 | | ------- | ---- | :-------: | ----------- | | `table` | `servicenow_query_table` | 是 | 通过 Table API 从任意 ServiceNow 表中读取记录 | | `table` | `servicenow_get_record` | 是 | 通过 sys_id 从表中读取单个记录 | | `table` | `servicenow_create_record` | 否 | 在给定字段值的表中创建新记录 | | `table` | `servicenow_update_record` | 否 | 更新具有 sys_id 的现有记录的字段 | | `table` | `servicenow_delete_record` | 否 | 通过 sys_id 从表中删除记录 | | `schema` | `servicenow_list_tables` | 是 | 从 sys_db_object 列出表，可选地按名称或标签片段过滤 | | `schema` | `servicenow_describe_table` | 是 | 从 sys_dictionary 列出表的列（名称，标签，类型，必填，引用） | | `aggregate` | `servicenow_aggregate` | 是 | 通过 Stats API 在表上计算服务器端聚合（计数，平均值，最小值，最大值，总和），可选地... | | `attachment` | `servicenow_list_attachments` | 是 | 列出附件元数据，可选地限定为特定记录（表 + sys_id） | | `attachment` | `servicenow_get_attachment` | 是 | 通过 sys_id 读取单个附件的元数据 | | `attachment` | `servicenow_download_attachment` | 是 | 下载附件的字节，返回为 base64 | | `attachment` | `servicenow_upload_attachment` | 否 | 将文件（以 base64 提供）附加到通过表 + sys_id 标识的记录 | | `attachment` | `servicenow_delete_attachment` | 否 | 通过 sys_id 删除附件 | | `importset` | `servicenow_insert_import_set_row` | 否 | 将单行插入到暂存表中并运行其转换映射 | | `importset` | `servicenow_get_import_set_row` | 是 | 读取通过 sys_id 插入的暂存行的转换结果 | | `batch` | `servicenow_batch` | 否 | 通过 Batch API 在单个 HTTP 往返中执行多个 ServiceNow REST 子请求 | | `catalog` | `servicenow_list_catalogs` | 是 | 列出实例上可用的服务目录（服务目录 API） | | `catalog` | `servicenow_list_catalog_categories` | 是 | 列出服务目录中的类别 | | `catalog` | `servicenow_list_catalog_items` | 是 | 搜索/列出可订购的目录项，可选按文本或类别 | | `catalog` | `servicenow_get_catalog_item` | 是 | 通过 sys_id 获取目录项，包括其订单变量 | | `catalog` | `servicenow_order_catalog_item` | 否 | 直接订购目录项（'立即订购'） | | `change` | `servicenow_list_changes` | 是 | 通过变更管理 API 列出变更请求 | | `change` | `servicenow_get_change` | 是 | 通过 sys_id 获取单个变更请求 | | `change` | `servicenow_create_change` | 否 | 创建正常，标准或紧急变更 | | `change` | `servicenow_update_change` | 否 | 更新变更请求的字段，依据 sys_id | | `change` | `servicenow_change_conflicts` | 否 | 读取变更的调度冲突，或重新计算它们（calculate=true） | | `knowledge` | `servicenow_search_knowledge` | 是 | 知识文章的全文本搜索（知识 API），可选编码查询和分页 | | `knowledge` | `servicenow_get_knowledge_article` | 是 | 通过 sys_id 获取知识文章（内容和元数据） | | `knowledge` | `servicenow_knowledge_highlights` | 是 | 为当前用户列出精选或最受欢迎的知识文章 | | `cmdb` | `servicenow_list_cis` | 是 | 通过类感知 CMDB 实例 API 列出 CMDB 类的配置项 | | `cmdb` | `servicenow_get_ci` | 是 | 通过类和 sys_id 获取具有属性和入/出关系的 CI | | `cmdb` | `servicenow_create_ci` | 否 | 通过 CMDB 实例 API（通过标识和协调路由）创建 CI | | `cmdb` | `servicenow_update_ci` | 否 | 通过 CMDB 实例 API（IRE）更新 CI 的属性 | | `cmdb` | `servicenow_get_cmdb_meta` | 是 | 从 CMDB 元数据 API 获取 CMDB 类的架构/元数据（属性，关系规则） | | `scripts` | `servicenow_list_scripts$` | 是 | 列出一种类型的脚本工件作为紧凑元数据（无源代码） | | `scripts` | `servicenow_get_script` | 是 | 读取一个脚本工件，包括其源代码和执行上下文 | | `scripts` | `servicenow_search_code` | 是 | 在一个或所有脚本类型中搜索脚本源代码的 literal 子字符串 | | `scripts` | `servicenow_table_logic$` | 是 | 汇总在表上运行的自动化：业务规则（按时间+顺序排序），客户端脚本，UI... | | `scripts` | `servicenow_where_used` | 是 | 在实例代码中找到表，字段或脚本被引用的位置：每个 s... 中的文本引用... | `flows` | `servicenow_trace_table_event` | 是 | 确定性地跟踪 ServiceNow 将为表操作运行的内容，按执行顺序：显示/之前... | | `flows` | `servicenow_list_flows` | 是 | 列出 Flow Designer 流（sys_hub_flow）或传统工作流（类型：'workflow'）作为紧凑元数据 | | `flows` | `servicenow_get_flow` | 是 | 获取流或工作流的结构化视图：其触发器（表/条件/何时）和有序步骤 | | `flows` | `servicenow_get_flow_runs` | 是 | 从 sys_flow_context 读取流执行证据 - 按流 sys_id 或记录（文档）它运行... | | `codecheck` | `servicenow_lint_script` | 是 | 对一个脚本工件运行确定性代码质量规则（硬编码 sys_ids/URLs，无边界或在循环中... | | `codecheck` | `servicenow_lint_table` | 是 | 检查表的每个活动业务规则，客户端脚本和 UI 策略（通过 table_logic），返回每个... | | `codecheck` | `servicenow_code_health` | 否 | 聚合代码健康状况：按类型计算脚本，访问控制层的扫描（ACL 脚本... | | `docs` | `servicenow_docs_list` | 是 | 列出本地实例文档文件夹（SN_DOCS_DIR）中的 Markdown 文档 | | `docs` | `servicenow_docs_read` | 是 | 从本地实例文档文件夹中读取 Markdown 文档 | | `docs` | `servicenow_docs_search` | 是 | 在本地实例文档中搜索子字符串；返回每个匹配项的片段 | | `docs` | `servicenow_docs_write` | 否 | 在本地文档文件夹中创建或覆盖 Markdown 文档并刷新 index.md | | `docs` | `servicenow_generate_er_diagram` | 是 | 从 sys_dictionary 构建 Mermaid erDiagram：每个表的实体和每个引用的关系... | | `docs` | `servicenow_generate_table_flow` | 是 | 构建表的记录生命周期的 Mermaid 流程图，按阶段（显示...）分组活动业务规则 | | `instance` | `servicenow_snapshot_instance` | 否 | 将实例的结构元数据下载到本地文档文件夹（SN_DOCS_DIR/&lt;profile&gt;/）：tables.md+... | | `instance` | `servicenow_compare_instances` | 否 | 两个连接配置文件之间的差异：仅存在于一个，公共列中的类型/必填/引用差异... | | `email` | `servicenow_send_email` | 否 | 通过实例的电子邮件 API 发送电子邮件，可选地与记录（表 + sys_id）关联 | | `email` | `servicenow_get_email` | 是 | 通过 sys_id 读取已发送/接收的电子邮件记录（电子邮件 API） | | `atf` | `servicenow_list_atf_tests` | 是 | 列出自动化测试框架测试（sys_atf_test）作为元数据：名称，活动标志，描述 | | `atf` | `servicenow_list_atf_suites` | 是 | 列出自动化测试框架测试套件（sys_atf_test_suite）作为元数据 | | `atf` | `servicenow_run_atf_test` | 否 | 通过 CI/CD API 运行单个 ATF 测试 | | `atf` | `servicenow_run_atf_suite` | 否 | 通过 CI/CD API 运行 ATF 测试套件 | | `atf` | `servicenow_get_atf_result` | 是 | 通过执行 ID 轮询 ATF 运行：状态，完成百分比和消息（CI/CD 进度 API） | | `admin` | `servicenow_set_credentials` | 否 | 保存或更新 ServiceNow 连接凭证 | | `admin` | `servicenow_list_instances` | 是 | 列出配置的 ServiceNow 连接配置文件（实例）：名称，主机，用户，只读标志和是否... | | `admin` | `servicenow_use_instance` | 否 | 切换活动的 ServiceNow 连接配置文件（持久保存到 env 文件） | | `admin` | `servicenow_get_status` | 是 | 显示配置的实例，用户，身份验证模式和访问策略，以及凭证是否完整 | | `admin` | `servicenow_test_connection` | 是 | 验证配置的凭证是否有效：读取一个 sys_user 记录并报告 ok/状态/延迟 | | `admin` | `servicenow_check_capabilities` | 是 | 预检连接用户可以实际读取的 sys_* 表，并报告更高... | <!-- GENERATED:TOOLS:END --> 所有工具都带有 MCP 注释（`readOnlyHint`，`destructiveHint`，`idempotentHint`），以便客户端应用正确的确认 UI。 ### 工具包 工具被分组到包中，以便您可以仅公开给定客户端需要的内容（较少的工具保持模型聚焦）。将 `SN_TOOL_PACKAGES` 设置为逗号/空格分隔的配置文件或包名称列表： - `core`（默认）— `table`，`schema`，`aggregate`，`attachment`。 - `all` — 以下所有包。 - 单个包：`table`，`schema`，`aggregate`，`attachment`，`importset`，`batch`，`catalog`，`change`，`knowledge`，`cmdb`，`scripts`，`flows`，`codecheck`，`docs`，`instance`，`email`，`atf`。 `admin` 工具（`servicenow_set_credentials`，`servicenow_get_status`）始终注册，无论活动包如何。未知名称将被忽略。`servicenow_get_status` 报告已解析的 `enabledPackages`。 ```dotenv # 仅限 table + batch 工具（以及始终开启的 admin 工具） SN_TOOL_PACKAGES=table,batch ``` ### 示例 查询 5 个最近的活跃事件： ```jsonc // servicenow_query_table { "table": "incident", "query": "active=true^ORDERBYDESCsys_created_on", "fields": ["number", "short_description", "priority", "state"], "limit": 5, } ``` 创建事件： ```jsonc // servicenow_create_record { "table": "incident", "fields": { "short_description": "3楼的打印机坏了", "urgency": "2", "impact": "2", }, } ``` 在运行时更新凭证： ```jsonc // servicenow_set_credentials { "instance": "dev98765.service-now.com", "user": "admin", "password": "••••••", } ``` ## 资源 只读元数据也作为 MCP 资源公开，以便客户端可以声明性地附加它，而不是调用工具： | URI | 描述 | | ----------------------------- | ---------------------------------------------- | | `servicenow://status` | 连接状态，身份验证模式，访问策略。 | | `servicenow://tables` | `sys_db_object` 的表列表。 | | `servicenow://schema/{table}` | 表的列来自 `sys_dictionary`。 | | `servicenow://docs/{path}` | 来自本地文档存储的 Markdown 文档。 | ## 提示 已准备好工作流作为 MCP 提示；它们协调工具并坚持从实例中读取真实值： | 提示 | 参数 | 目的 | | ----------------------------------- | ---------- | ---------------------------------------------------------------- | | `servicenow_incident_triage` | `incident` | 总结，评估优先级，分类和建议下一步骤。 | | `servicenow_change_impact_analysis` | `change` | 受影响的 CI，调度冲突和 go/no-go 调用。 | | `servicenow_document_table` | `table` | 架构 + 自动化 + 图表 → 保存的 Markdown 文档。 | ## 项目结构 ``` . ├── .env # 凭证（git-ignored；或 ~/.config/servicenow-mcp-ai/.env） ├── .env.example # 模板 ├── .github/workflows/ # CI：构建 + 校验 + 测试 ├── .vscode/mcp.json # VS Code MCP 服务器注册 ├── eslint.config.js # ESLint 扁平配置 ├── .prettierrc.json # Prettier 配置 ├── src/ │ ├── index.ts # 引导：加载 env，注册，连接 stdio │ ├── registry.ts # 注册所有工具组 │ ├── resources.ts # MCP 资源（状态，表，架构，文档） │ ├── prompts.ts # MCP 提示（分类，变更影响，文档表） │ ├── http.ts # 共享 REST 客户端（身份验证，重试，SSRF） │ ├── auth.ts # 基本 + OAuth 2.0 提供程序 │ ├── host.ts # 主机解析 + SSRF 守卫 │ ├── policy.ts # 表允许/拒绝 + 只读守卫 │ ├── settings.ts # 数值环境设置 │ ├── logging.ts # 结构化 stderr 日志记录 │ ├── result.ts # 工具结果 + 结构化错误 │ ├── servicenow.ts # 表 API 客户端 │ ├── config.ts # 环境文件读取/写入 + 位置 │ ├── api/ # 聚合，附件，导入集，批次，目录，变更，知识，CMDB，脚本，图表，文档，元数据 │ └── tools/ # 每个 API 组的工具注册 ├── test/ # node:test 单元测试 + 模拟-fetch 测试 └── build/ # 编译输出（构建后） ``` > **名称说明：** npm 包和 GitHub 仓库都是 [`servicenow-mcp-ai`](https://github.com/IvanBBaev/servicenow-mcp-ai) （无作用域的 `servicenow-mcp` 已在 npm 上被占用）；本地工作文件夹是 `servicenow-mcp`。差异是纯粹的，不会影响构建 或运行时。 ## 安全说明 - 环境文件被 git 忽略 — 不要提交真实凭证。 - 环境文件以 **所有者专用（`0600`）** 写入 — 它保存纯文本密码。 - 服务器使用 stdio 传输，仅记录到 `stderr`；绝不记录机密和原始编码查询。 - 密码/令牌从不被任何工具返回。 - 主机受到限制：没有 `SN_ALLOWED_HOSTS`，仅 `*.service-now.com` 实例被联系（内部/环回始终被阻止），因此重定向或输入错误的主机不能静默接收凭证。设置 `SN_ALLOWED_HOSTS` 以选择自定义或主权云域。 - 在可能的情况下，优先使用 **OAuth 2.0** 而不是基本身份验证（`SN_OAUTH_CLIENT_ID`）。 - 使用 `SN_TABLES_ALLOW` / `SN_TABLES_DENY` 和 `SN_READONLY=true` 应用最小特权，适用于只读部署。 - **表策略不涵盖插件 API。** `SN_TABLES_DENY=change_request` 阻止表 API 路径，但变更管理 API（`sn_chg_rest`）仍然可以读写变更。要限制插件支持的表面，请使用 `SN_PACKAGES_DENY`（删除整个包）或 `SN_PACKAGES_READONLY`（仅注册其只读工具）。批处理 API 服从两个轴：拒绝包路径的子请求被拒绝，写入只读包被阻止 — 批处理不能用于绕过包策略。 ## 项目文档 | 文档 | 内容 | | -------- | -------- | | [ARCHITECTURE.md](ARCHITECTURE.md) | 分层架构，Mermaid 图表（模块，请求生命周期，安全模型，身份验证，包），浓缩的 ADRs | | [PRODUCT-STATE.md](PRODUCT-STATE.md) | 当前产品状态：API 覆盖范围图，质量状态，历史时间线，路线图 | | [ROADMAP.md](ROADMAP.md) | 前瞻计划：发布 1.0.0，阶段 8（流程测试 + 代码分析），阶段 9（竞争性差异化优势），可选和延迟项 | | [COMPETITIVE-ANALYSIS.md](COMPETITIVE-ANALYSIS.md) | 与官方 ServiceNow MCP Server Console 的定位：比较，结构性滞后，第 9 阶段提升计划和平台风险 | | [IMPLEMENTATION-PLAN.md](IMPLEMENTATION-PLAN.md) | 即将到来的阶段的详细规格（harness 2.0，多实例，流程测试） | | [DONE.md](DONE.md) / [TODO.md](TODO.md) | 完成的带有提交引用的工作 / 剩余的决策 | | [WORKLOG.md](WORKLOG.md) / [CHANGELOG.md](CHANGELOG.md) | 详细的工作日志 / 面向用户的变更日志 | | [CONTRIBUTING.md](CONTRIBUTING.md) / [SECURITY.md](SECURITY.md) | 开发设置，门控和约定 / 安全模型和报告 | ## 商标 `servicenow-mcp-ai` 是一个独立的，社区建设的项目。它 **不隶属于**，**不受** 或 **不受 ServiceNow, Inc. 的赞助**。 "ServiceNow"，ServiceNow 徽标，“Now”和相关标记是 ServiceNow, Inc. 在美国和其他国家的商标或注册商标。它们仅在此项目中使用 **命名性** — 以标识此软件与其交互的平台 — 并且不暗示任何关联或认可。所有其他产品名称和标记是其各自所有者的财产。 本项目根据 [MIT License](LICENSE) 获得许可；该许可涵盖源代码，不授予使用 ServiceNow 商标的任何权利。