servicenow-nodejs

Happy MCP 服务

面向 ServiceNow® 平台的 Model Context Protocol 服务

由元数据驱动的 MCP 服务，可自动生成 480 多个工具，覆盖 160 多个表，并支持多实例、自然语言搜索和本地脚本开发。

网站 | GitHub | npm | 工具 | 贡献 | 支持

---

从 servicenow-mcp-server 迁移？ npm 包已更名为 happy-platform-mcp，Docker 镜像已更名为 nczitzer/happy-platform-mcp。旧名称已弃用，但暂时仍可使用。请更新依赖：

# npm
npm uninstall servicenow-mcp-server && npm install happy-platform-mcp

# Docker
docker pull nczitzer/happy-platform-mcp:latest

支持

如果您觉得这个项目有用，可以考虑支持其开发。您的贡献将用于支持 Happy Technologies LLC。

• GitHub 赞助
• 请我喝杯咖啡

功能

• 多实例支持 — 可同时连接多个 ServiceNow® 实例，并按请求进行路由
• OAuth 2.0 和基本身份验证 — 支持每个实例使用客户端凭据、资源所有者密码凭据，以及每位用户使用带 PKCE 的授权码
• 智能架构发现 — 在运行时自动发现表结构和关系
• 160 多个表 — 全面覆盖 ITSM、CMDB、服务目录、平台开发和 Flow Designer
• 55 个 MCP 工具 — 可用于任意表的通用 CRUD 操作，以及专用便捷工具
• 批量操作 — 已成功测试 43 项以上并行操作
• 本地脚本开发 — 使用 Git 同步脚本，并通过监视模式持续开发
• 自然语言搜索 — 使用通俗易懂的语言查询，而非编码查询
• MCP 资源 — 提供 8 个只读资源 URI，便于快速查询和查阅文档
• 后台脚本执行 — 通过 sys_trigger 自动执行服务器端脚本
• 服务目录 AI 提交 — 以编程方式浏览、检查并提交服务目录表单
• ServiceNow 文档搜索 — 可选的 GitHub 文档检索，以及基于本地 SQLite FTS 对官方 ServiceNowDocs Markdown 文档进行搜索

快速开始

前置条件

• Node.js 20+
• 一个或多个可访问 REST API 的 ServiceNow® 实例
• 每个实例的有效凭据

从 npm 安装

npx happy-platform-mcp

或全局安装：

npm install -g happy-platform-mcp

从源代码安装

git clone https://github.com/Happy-Technologies-LLC/happy-platform-mcp.git
cd happy-platform-mcp
npm install
# Source checkout: use node src/cli.js <command>, or npm link first.
node src/cli.js instance list

启动 stdio 服务

全局安装后，不带参数运行 happy-platform-mcp 即可启动 stdio MCP 服务：

npm install -g happy-platform-mcp
SERVICENOW_INSTANCE=dev happy-platform-mcp

MCP 宿主可以使用全局命令：

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "happy-platform-mcp",
      "env": { "SERVICENOW_INSTANCE": "dev" }
    }
  }
}

也可以使用 npx，设置 command: "npx" 和 args: ["-y", "happy-platform-mcp"]。 从源码检出目录运行时，使用 node src/stdio-server.js；源码 CLI 命令 使用 node src/cli.js instance ...。

配置实例

推荐：使用本地 CLI 注册元数据

CLI 会继承启动它的进程环境。CLI 不会自动加载 .env；.env 加载仅适用于服务/stdio 进程。使用 CLI 时，请在 shell 中导出 HAPPY_CONFIG_PATH（或在 MCP 宿主启动 CLI 时，在宿主环境中设置该变量）。所有操作系统上的实际默认注册表路径均为 <homedir>/.config/happy-platform-mcp/instances.json，并使用相应操作系统的原生路径分隔符。

凭据会在本地通过提示输入，输入内容会被遮蔽，并存储在操作系统密钥链中。CLI 写入的新版本 1 注册表仅包含实例元数据和规范的 credentialRef 值，不包含明文凭据。旧版明文注册表文件仅作为只读兼容性输入使用；单数形式的 SERVICENOW_* 环境变量回退仅为向后兼容而保留。

happy-platform-mcp instance add
happy-platform-mcp instance list
happy-platform-mcp instance test dev
happy-platform-mcp instance update dev
happy-platform-mcp instance remove dev
happy-platform-mcp instance migrate

instance add 会根据所选身份验证模式提示输入所需凭据，并在注册元数据前存储这些凭据。instance credential set 仅用于轮换现有凭据，或完成仅包含元数据的 MCP 注册。instance update 仅更改元数据。更改身份验证方式需要先执行 instance remove，再执行 instance add。密钥提示绝不会将值放入命令参数、日志或 MCP 消息中。这些提示需要交互式本地 TTY。在非 TTY 自动化环境中，请使用预先配置的操作系统密钥链条目并运行仅涉及元数据的命令；CLI 不会从 stdin 读取密钥，也不会静默回退到明文方式。

要为 CLI 选择其他元数据注册表，请在调用 CLI 前导出 HAPPY_CONFIG_PATH：

export HAPPY_CONFIG_PATH="$HOME/.config/happy-platform-mcp/instances.json"
happy-platform-mcp instance list

对于 MCP 服务/stdio 宿主，请在宿主环境中设置相同的变量：

{
  "env": {
    "HAPPY_CONFIG_PATH": "~/.config/happy-platform-mcp/instances.json"
  }
}

HAPPY_CONFIG_PATH 支持 ~ 和相对路径。迁移时，只有在解析器将包相对路径 config/servicenow-instances.json 选为 readPath，并将不同的默认用户注册表选为 writePath 时，才会自动执行从旧版包注册表到用户注册表的迁移。HAPPY_CONFIG_PATH 通常会同时指定 readPath 和 writePath，且必须指向仅包含元数据的版本 1 注册表。如果它指向明文源文件（即同一个文件），CLI 会在写入密钥链前拒绝操作；源文件字节内容和密钥链条目均保持不变。请选择不同的 HAPPY_CONFIG_PATH 目标，或取消设置该变量以使用自动工作流。切勿将密钥复制到命令参数中。对于非包内的旧版源文件，请使用受控的不同源/目标工作流，或手动使用 instance add 和会遮蔽输入内容的 instance credential set 提示。

SN-Register-Instance 通常会应用实时注册表重新加载，无需重启。只有在文档专用模式下，或重新加载失败时，才需要重启 MCP 服务。

旧版兼容性： config/servicenow-instances.json 是只读的旧版迁移输入。仅当没有可用注册表时，单数形式的 SERVICENOW_* 环境变量才作为向后兼容的单实例回退。包相对路径下的文件不是 CLI 的可写入位置。

选项 B：单实例（旧版环境变量回退）

cp .env.example .env
# Server/stdio only: set legacy SERVICENOW_* variables in .env.

启动服务

# Stdio transport (for Claude Desktop); no HTTP token involved
npm run stdio

# HTTP/SSE transport; refuses to start without a valid bearer token
export HAPPY_MCP_API_TOKEN="$(openssl rand -hex 32)"
npm run dev

HTTP 传输安全

HTTP/SSE 传输面向一名受信任的操作员，即单个主体。任何持有 HAPPY_MCP_API_TOKEN 的人都可以使用服务器上配置的所有 ServiceNow 凭据，因此这些账户的 ServiceNow ACL 仍决定他们能做什么。HTTP 身份验证不会取代它们。不支持共享式多用户托管：多人或多个租户共用一个服务器或令牌时，不会获得按用户区分的身份、隔离或授权。每名操作员运行一个服务器。

• 每个监听器都必须设置令牌。 HTTP 启动时，如果 HAPPY_MCP_API_TOKEN 不是由 32 个随机字节编码而成的 64 位十六进制字符（openssl rand -hex 32），或不是 43 个 base64url 字符，启动就会失败。环回地址和嵌入式 createHttpApp 用法也不例外。服务器会检查编码格式，但无法衡量随机性，因此务必生成该值。将其保存在密钥存储中或未跟踪的 .env 文件中，绝不要提交或记录，并通过使用新值重启来轮换令牌。Stdio 不使用此令牌。
• 所有路由都需要身份验证。 /health、/instances、GET /mcp 和 POST /mcp 都要求且只接受一个 Authorization: Bearer <token> 标头。令牌比较采用恒定时间算法。请求会在解析请求正文或建立会话之前被拒绝。
• 失败尝试会受到限流。 如果一分钟内来自同一对端地址的失败尝试达到 10 次，该对端会收到 429 和 Retry-After，直到限流窗口结束。令牌验证之前会先检查限流，因此即使令牌正确，被阻止的对端也会遭到拒绝。限流额度保存在进程内存中：重启后会重置，不会在进程之间共享，并且只跟踪数量有限的对端。使用反向代理，或通过 Docker 端口发布（主机客户端可能共用一个网关地址）时，所有客户端共用同一限流额度，因此任何能访问端点的未经过身份验证的客户端，每分钟发送 10 个错误请求就能让操作员无法访问。请限制能访问代理的对象，并在代理处进行限流。
• 会检查 Host 和 Origin（防止 DNS 重绑定）。 Host 必须指明监听器（环回地址上的 127.0.0.1:<port>、localhost:<port> 或 [::1]:<port>；其他情况下则为绑定地址和端口），或与 HAPPY_MCP_ALLOWED_HOSTS 中的某个条目完全一致。不带 Origin 的请求（原生 MCP 客户端会这样发送）会被允许。若请求包含 Origin，则必须与 HAPPY_MCP_ALLOWED_ORIGINS 中的某个条目完全一致；null、通配符、格式错误和重复值都会被拒绝。绝不信任 X-Forwarded-* 和 Forwarded 标头。
• 资源限制。 最多允许 16 个待处理和 32 个活动 SSE 会话（超出时返回 429）；HEAD /mcp 返回 405。会话的建立超时为 30 秒，空闲超时为 30 分钟，最长生命周期为 12 小时。JSON 请求正文上限为 8 MiB。每个会话一次处理一个 POST，最多排队 8 个；所有会话总计最多同时处理 8 个 POST。每个会话最多允许 16 个未响应的 JSON-RPC 请求，每个进程最多允许 64 个。已取消的请求会一直占用名额，直到其处理程序实际结束；由于工具处理程序不会在取消时提前停止，其迟到的结果会被丢弃。未知或已关闭的会话 ID 会被拒绝。

变量	默认值	用途
HAPPY_MCP_API_TOKEN	无（HTTP 必填）	Bearer 令牌：64 位十六进制字符或 43 个 base64url 字符
HAPPY_MCP_BIND_HOST	127.0.0.1	监听地址
HAPPY_MCP_ALLOWED_HOSTS	空	以逗号分隔的额外 host[:port] 权限主体，例如反向代理名称。不允许包含 scheme、路径或通配符
HAPPY_MCP_ALLOWED_ORIGINS	空（拒绝任何 Origin）	以逗号分隔的浏览器来源精确值，例如 https://console.example.com

反向代理

在代理处终止 TLS，并将请求转发到环回监听器。如果代理将 Host 重写为上游地址（nginx 的默认值 $proxy_host，即 127.0.0.1:3000），则无需额外设置。如果代理转发的是公网名称，请批准该确切权限：

location / {
  proxy_pass http://127.0.0.1:3000;
  proxy_set_header Host $host;   # forwards "mcp.example.com"
  proxy_http_version 1.1;
  proxy_buffering off;           # required for SSE
  proxy_read_timeout 1h;
}

HAPPY_MCP_ALLOWED_HOSTS=mcp.example.com

代理必须原样转发 Authorization 标头。不要让代理用自己的凭据替代客户端令牌。

迁移现有 HTTP 客户端

此版本要求所有 HTTP 请求都携带 bearer token，包括环回请求。

• curl 和脚本： 为每个请求添加 -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN"，包括 /health。
• MCP SSE 客户端： 配置客户端，使其在 SSE GET 和消息 POST 请求中都发送该标头。使用 TypeScript SDK 时，可以这样写：new SSEClientTransport(url, { requestInit: { headers: { Authorization: 'Bearer ' + token } } })。
• 发送 Origin 的客户端（例如网页视图或会转发该标头的代理）：将该确切来源添加到 HAPPY_MCP_ALLOWED_ORIGINS。服务器不会发送 CORS 标头，因此跨源网页仍无法读取其响应。
• Docker： 在运行时提供 HAPPY_MCP_API_TOKEN，并将 HAPPY_MCP_ALLOWED_HOSTS 设置为客户端使用的权限，例如 localhost:3000,127.0.0.1:3000。健康检查必须进行身份验证；镜像的 HEALTHCHECK 和 docker-compose.yml 已完成此设置。请参阅 docs/DOCKER_DEPLOYMENT.md。

验证

curl -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" http://localhost:3000/health
curl -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" http://localhost:3000/instances

# Without the token the server answers 401
curl -i http://localhost:3000/health

多实例路由

除 SN-Set-Instance、SN-Get-Current-Instance 和 SN-Docs-* 外，每个实时 ServiceNow 操作都接受可选的 instance 参数。省略该参数时，将使用当前会话客户端的隐式目标。当并行工作可能针对不同实例，或与 SN-Set-Instance 发生竞争时，必须显式指定路由；针对同一稳定隐式目标的并发调用则无需显式指定。显式调用会按实例名称缓存，因此对同一命名实例的调用会共享该客户端。

在 stdio 启动时，如果设置了 SERVICENOW_INSTANCE，则会选择对应的命名 JSON 条目；否则，启动时会使用标记为 "default": true 的条目，如果没有标记，则使用第一个已配置条目。HTTP 会话使用已配置的默认条目或第一个条目。如果 JSON 文件缺失，可使用 ServiceNow 环境凭据提供唯一的备用实例。"default": true 标志属于启动配置。SN-Set-Instance 仅会在内存中更改当前会话客户端，不会修改配置；新的 MCP 会话或服务器会重新使用启动时的选择。

// Uses this session client's current implicit target
await client.callTool({
  name: 'SN-Query-Table',
  arguments: { table_name: 'incident', limit: 10 }
});

// Safely query dev and prod concurrently
await Promise.all([
  client.callTool({
    name: 'SN-Query-Table',
    arguments: { table_name: 'incident', instance: 'dev', limit: 10 }
  }),
  client.callTool({
    name: 'SN-Query-Table',
    arguments: { table_name: 'incident', instance: 'prod', limit: 10 }
  })
]);

工具概览

类别	工具数	描述
通用 CRUD	7	查询、创建、获取和更新任意表
专用 ITSM	8	Incident、Change、Problem 便捷封装
便捷工具	10	添加评论、添加工作备注、分配、解决、关闭
自然语言	1	使用日常语言进行查询
更新集	6	设置、列出、移动、克隆和检查更新集
脚本	2	执行后台脚本、创建修复脚本
ATF 测试	5	通过 CI/CD REST API 运行 ATF 测试和测试套件、轮询进度、读取结果和日志
脚本同步	3	与本地文件同步脚本、监视模式
工作流	4	创建工作流、活动和转换
批处理	2	跨表批量创建/更新
架构	3	表架构、字段信息、关系
服务目录	4	浏览、检查并提交目录表单
ServiceNow 文档	5	发现、同步、搜索和获取官方 ServiceNowDocs Markdown
资源	8	用于读取表列表和字段信息的只读 URI

示例

以下与传输方式无关的示例展示了 MCP 工具名称及其参数：

SN-Query-Table
{ "table_name": "incident", "query": "active=true^priority=1", "limit": 10 }

SN-Create-Incident
{ "short_description": "Email service down", "urgency": 1 }

SN-NL-Search
{ "table_name": "incident", "query": "high priority incidents assigned to me" }

SN-Execute-Background-Script
{ "script": "gs.info('Hello');" }

SN-Set-Update-Set
{ "update_set_sys_id": "abc123..." }

SN-Batch-Update
{ "updates": [{ "table": "incident", "sys_id": "id1", "data": { "state": 2 } }] }

SN-Catalog-Search-Items
{ "keyword": "VPN access" }
SN-Catalog-Get-Item
{ "sys_id": "<catalog_item_sys_id>" }
SN-Catalog-Submit
{ "sys_id": "<catalog_item_sys_id>", "variables": { "requested_for": "jsmith", "justification": "Project X" } }

SN-Run-ATF-Suite
{ "test_suite_name": "Smoke Tests", "timeout_seconds": 45 }
SN-Get-ATF-Test-Logs
{ "result_id": "<sys_atf_test_result sys_id>", "pattern": "error|fail" }

SN-Docs-Families
{}
SN-Docs-Sync
{ "family": "australia" }
SN-Docs-Search
{ "query": "create a Flow Designer action", "family": "australia" }

本地脚本开发

在本地开发脚本，并使用版本控制和自动同步：

SN-Sync-Script-To-Local
{
  "script_sys_id": "abc123...",
  "local_path": "/scripts/business_rules/validate_incident.js"
}

SN-Watch-Script
{
  "local_path": "/scripts/business_rules/validate_incident.js",
  "script_sys_id": "abc123..."
}

自然语言搜索

SN-NL-Search
{
  "table_name": "incident",
  "query": "active high priority incidents that are unassigned"
}

支持 15 种以上模式，包括字段比较、文本搜索、日期范围、逻辑运算符和排序。

ServiceNow 文档搜索

Happy MCP 可直接从 GitHub 获取官方 ServiceNowDocs Markdown，并可选择将某个文档系列本地化到 SQLite FTS5 索引中，以便快速进行本地搜索。默认禁用本地索引；在版本 1 注册表中将 docs.localIndexEnabled=true 设为启用，或设置 HAPPY_DOCS_ENABLE_LOCAL_INDEX=true。

SN-Register-Instance
{ "name": "dev", "url": "https://your-instance.service-now.com", "username": "your-username" }

SN-Docs-Families
{}
SN-Docs-Status
{}
SN-Docs-Sync
{ "family": "australia" }
SN-Docs-Search
{ "query": "update set best practices", "family": "australia", "limit": 5 }
SN-Docs-Get
{ "family": "australia", "path": "platform/example.md" }

SN-Register-Instance 仅接受元数据。它不会接受密码、客户端密钥或其他机密字段。如果缺少必需的本地凭据，其响应会给出确切的 happy-platform-mcp instance credential set ... 命令，供你在本地运行。注册会持久化元数据，但仅提供文档的服务必须重启后才能启用实时 ServiceNow 工具。

SQLite 本地索引为可选功能，默认禁用。向量搜索同样为可选功能；启用本地索引、设置 HAPPY_DOCS_ENABLE_VECTOR=true，并使用 HAPPY_DOCS_EMBEDDING_PROVIDER=local，即可通过确定性的本地嵌入构建 sqlite-vec 索引。请参阅 ServiceNow 文档搜索。

对于没有 ServiceNow 凭据的纯文档部署，请设置 HAPPY_MCP_DOCS_ONLY=true。如果没有配置文件或 ServiceNow 环境凭据，stdio 服务会自动回退到纯文档模式。

运行时实例选择

注册和运行时选择是分开的：

• 注册会在注册表中持久化一个可用的命名实例。
• SERVICENOW_INSTANCE 仅用于选择 stdio 启动默认实例。
• SN-Set-Instance 会在内存中更改顺序会话的共享隐式目标；它不会修改注册表。
• 可选的单次调用 instance 参数会选择一个隔离的请求目标，因此并发调用可以路由到不同实例，而不会与顺序目标发生冲突。

Claude Desktop 集成

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

对于全局安装，不带参数即可启动 stdio：

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "happy-platform-mcp",
      "env": { "SERVICENOW_INSTANCE": "dev" }
    }
  }
}

对于临时安装，请使用 command: "npx" 和 args: ["-y", "happy-platform-mcp"]：

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "npx",
      "args": ["-y", "happy-platform-mcp"],
      "env": {
        "HAPPY_CONFIG_PATH": "~/.config/happy-platform-mcp/instances.json"
      }
    }
  }
}

注册表设置指向元数据；凭据仍保存在本地操作系统钥匙串中。默认用户路径下，HAPPY_CONFIG_PATH 为可选项，且必须在服务启动前设置。对于源码安装，请在宿主配置中使用 node src/stdio-server.js，并使用 node src/cli.js instance <command> 执行 CLI 操作。编辑配置后，请重启 Claude Desktop。

身份验证

Happy MCP Server 支持每个实例使用三种凭据流程。交互式 instance add 会一次性收集每个必需的机密，将其存储在操作系统钥匙串中，并注册元数据。之后仅在轮换现有凭据或完成仅含元数据的 MCP 注册时，才使用 instance credential set。切勿将机密放入 JSON 或命令参数中。

全局 CLI：dev 基本身份验证

happy-platform-mcp instance add
# Select Basic authentication; set the name to dev, enter URL and username,
# then enter the masked password when prompted. The command stores it once.
happy-platform-mcp instance test dev

全局 CLI：prod OAuth 客户端凭据

happy-platform-mcp instance add
# Select OAuth -> Client credentials; set the name to prod, enter URL and
# client ID, then enter the masked client secret. The command stores it once.
happy-platform-mcp instance test prod

OAuth 密码授权

happy-platform-mcp instance add
# Select OAuth -> Password grant; enter URL, client ID, and username, then
# enter both masked prompts. The command stores both credentials once.
happy-platform-mcp instance test password-prod

密码授权的 credentialRef 必须是同时包含以下两个规范引用的对象：

"credentialRef": {
  "password": "keychain:instance/password-prod/password",
  "clientSecret": "keychain:instance/password-prod/client-secret"
}

使用 PKCE 的公共授权码

happy-platform-mcp instance add
# Select OAuth -> Authorization code and enter URL, client ID,
# authorize URL, token URL, redirect port, and callback path.
happy-platform-mcp instance test public-dev

公共授权码元数据无需 credentialRef 或客户端密钥。首次测试/API 调用会打开浏览器授权流程，并将其刷新令牌存储在操作系统密钥链中。

刷新令牌按 OAuth 身份区分，即本地操作系统用户、规范化实例 URL、客户端 ID 和生效的授权/令牌端点，而非按实例名称区分。因此，重命名实例后仍可保持登录状态；另一个名称相同但 URL、客户端或 IdP 不同的实例则绝不会获得该令牌。**升级后，请在每个授权码实例中登录一次：**旧的按名称索引的令牌不会被读取或迁移，并会在新登录成功后删除。 instance remove 以及 instance update 对 URL、客户端 ID 或授权/令牌 URL 的更改，会先从操作系统密钥链和文件令牌存储中删除该身份的刷新令牌（以及任何旧的按名称索引的条目），无论服务使用的是哪种存储，并会指出已清理的存储。如果任一存储报告错误，命令会在更改注册表之前停止。在 Windows 上，仅当文件存储目录不存在时才会跳过文件存储。手动编辑注册表文件时不会清理令牌；此类过期令牌绝不会用于其他身份。

密钥链绑定（@napi-rs/keyring 2.1+）会将密钥链锁定、访问被拒或无法访问报告为错误，而非“无条目”，因此无法完成的删除会在注册表更改之前停止命令——请解锁密钥链后重试。密钥链错误不包含用于区分“没有密钥链后端”和“已锁定”的代码，因此密钥链不可用时命令始终会停止。在没有 Secret Service 的 Linux 上，该绑定会回退到内核密钥环；如果两者都不可用（例如容器禁止使用 keyctl），服务只能使用文件存储：请手动删除 $XDG_CONFIG_HOME/happy-platform-mcp/（或 ~/.config/happy-platform-mcp/）下的 token-* 文件，以及注册表文件中的实例条目。

受信任的外部身份提供商

授权和令牌端点默认指向实例自身（/oauth_auth.do、/oauth_token.do）。实例源站上的自定义端点始终允许使用。只有当每个加载配置的进程的环境中都列出了外部 IdP 的确切源站时，才会接受该 IdP——包括 MCP 服务以及运行 happy-platform-mcp instance … 的 shell（CLI 不会读取 .env）：

export SERVICENOW_OAUTH_TRUSTED_ORIGINS=https://login.example.com,https://idp.example.net:8443

条目必须是 HTTPS 源站（本地测试允许使用环回 HTTP），且不得包含路径、查询、片段、凭据或通配符；格式错误的条目将被拒绝。无法通过实例注册表或 MCP 工具设置允许列表。系统会在注册或加载实例时检查允许列表，并在每次令牌请求前再次检查；令牌请求绝不跟随重定向。已使用外部 IdP 的注册表将无法加载——无论是在服务中，还是在包括 instance remove 在内的任何 CLI 命令中——直到添加其源站。如果服务使用具有自定义 XDG_CONFIG_HOME 的文件令牌存储，请为 CLI 导出相同的 XDG_CONFIG_HOME，以确保移除操作清理正确的目录。

可选的纯文本刷新令牌存储（仅限 POSIX）

操作系统密钥链仍是默认选项（未设置或 SERVICENOW_TOKEN_STORE=keychain）。 如需将授权码刷新令牌以纯文本形式持久化为 token-<sha256-hex> 文件，请在服务进程环境中明确设置 SERVICENOW_TOKEN_STORE=file。文件名为账户密钥的 SHA-256 哈希值，因此在不区分大小写的文件系统中，账户名仅大小写不同也不会发生别名冲突。文件存储在 $XDG_CONFIG_HOME/happy-platform-mcp 中；若未设置 XDG，则存储在 ~/.config/happy-platform-mcp 中。不会读取早期的 token-<account> 文件；请重新授权。XDG_CONFIG_HOME 必须是可信的绝对路径。这不会改变实例密码或 OAuth 客户端密钥的密钥链存储方式。

文件存储会检查当前用户所有权、权限私有的 0700 目录以及普通的 0600 令牌文件；遇到不安全的现有目录或文件、符号链接、可由不可信用户写入的上级目录，以及设置或权限错误时，都会安全失败。创建任何目录前，都会检查所有现有上级目录（解析符号链接后）；这些目录必须归当前用户或 root 所有，且不得允许组或其他用户写入，除非目录设置了 sticky 位。错误信息会指出有问题的路径以及所需的所有权和权限。如果目录中已有权限较宽松的配置，请先检查并将其权限设为私有，再启用文件存储；服务不会悄悄修复已暴露的现有存储。Windows 文件模式位无法保障 Windows ACL 隐私，因此 Windows 上会拒绝文件存储：请保留操作系统密钥链默认设置。请参阅设置详情。

任何以同一操作系统用户身份运行的进程都能读取这些纯文本令牌。请将此目录排除在共享或同步备份之外，或将备份作为机密保护（包括访问控制和加密）。不要提交、记录或上传其中的内容。切换存储方式不会迁移令牌；请在所选存储中重新授权。每次写入都会使用唯一且独占的 0600 临时文件，并通过同目录原子重命名完成，因此并发写入者不会共用临时文件，读取者也能看到完整令牌。这不会串行化 OAuth 刷新操作、解决跨进程刷新令牌轮换问题，也不保证断电时的数据持久性；每个身份请仅使用一个负责刷新的进程。

架构

src/
├── server.js                     # Express HTTP server (SSE transport)
├── stdio-server.js               # Stdio transport (Claude Desktop)
├── mcp-server-consolidated.js    # MCP tool registration & routing
├── servicenow-client.js          # REST API client
└── config-manager.js             # Multi-instance configuration

config/
└── servicenow-instances.json     # Instance configuration

docs/
├── API_REFERENCE.md              # Complete tool reference
├── SETUP_GUIDE.md                # Detailed setup instructions
└── research/                     # Technical research & discoveries

测试

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

# MCP Inspector
npm run inspector

故障排除

连接问题

# Test configured credentials without exposing them in shell history.
happy-platform-mcp instance test <instance-name>

# Check server health (HTTP transport)
curl -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" http://localhost:3000/health

常见问题

• 多实例无法正常工作： 确认版本 1 注册表是有效的 JSON，并且在需要启动默认实例时，恰有一个实例设为 "default": true。正常情况下，实时注册无需重启即可重新加载；仅在文档专用模式或重新加载失败时才重启。
• 工具未显示： 检查 MCP Inspector 连接和服务日志。
• 身份验证失败： 运行 happy-platform-mcp instance test <instance-name>，并确认本地密钥链凭据引用和所需的 ServiceNow 角色。
• HTTP 401/403/429： 401 表示缺少、不唯一或错误的 bearer token。403 表示 Host 或 Origin 标头未经批准（请参阅 HTTP 传输安全）。429 表示你的地址有太多失败尝试，或打开的会话过多；请等待 Retry-After。
• Docker 中的 SSE 连接断开： 启用 keepalive（默认 15s）。请参阅 docs/SSE_DOCKER_SETUP.md。

调试模式

DEBUG=true npm run dev

已知限制

• 无法通过 REST API 创建 Flow Designer 逻辑块（请使用 UI）
• Flow 编译和验证必须在 UI 中完成
• UI Policy Actions 链接需要使用后台脚本变通处理

详情请参阅 docs/ 下的 API 参考和工具专属指南。

致谢

本项目的灵感来自 Echelon AI Labs ServiceNow MCP Server。感谢他们率先为 ServiceNow® 平台引入 MCP 功能。

贡献

请参阅 CONTRIBUTING.md 了解指南。所有贡献者都必须签署 CLA。

安全

如需报告漏洞，请参阅 SECURITY.md。请勿公开提交安全问题。

许可证

本项目采用 Apache License 2.0 授权。

版权所有 2025 Happy Technologies LLC

---

商标声明

ServiceNow® 是 ServiceNow, Inc. 的注册商标。“Now”是 ServiceNow, Inc. 的注册商标。所有 ServiceNow® 产品名称、徽标和品牌均归 ServiceNow, Inc. 所有。

Model Context Protocol (MCP) 是由 Anthropic, PBC 创建的开放标准。“Claude”是 Anthropic, PBC 的商标。

**Happy MCP Server 是一个独立、由社区驱动的项目。**它与 ServiceNow, Inc. 或 Anthropic, PBC 均无关联，也未获得其认可或赞助。本项目提供可通过已发布的 REST API 连接到 ServiceNow® 实例的工具，并实现开放的 MCP 规范。本项目并非任何 ServiceNow® 产品或服务的竞争者。

所有其他商标均归其各自所有者所有。完整归属信息请参阅 NOTICE。