用途：安装 Happy Platform MCP v5.1，注册一个或多个 ServiceNow 实例，并连接支持 MCP 的客户端，同时确保认证材料不暴露给模型、MCP 消息、日志、shell 历史或客户端 JSON。遵循 MCP 优先策略：本地配置完成后优先使用 SN-* 工具，仅在无对应 MCP 工具且已有本地凭据助手时使用原始 REST。
前提条件：Node.js >= 20；Happy Platform MCP 5.1.0 或兼容的 5.x 版本；本地交互式终端（用于掩码提示）；当前用户可用的操作系统钥匙串；支持 MCP 的客户端及相应 ServiceNow 访问权限。
安装：使用 npm 全局安装：npm install -g happy-platform-mcp@5.1.0，然后运行 happy-platform-mcp --version 验证。MCP 宿主也可用 npx -y happy-platform-mcp@5.1.0 启动。不要在参数或环境变量中加入认证材料。
认证模式：本地运行 happy-platform-mcp instance add，通过交互式掩码提示收集所需值，凭据存入操作系统钥匙串。可选模式包括 Basic（命名集成用户）、OAuth client_credentials（非交互式服务集成）、OAuth password（旧版资源所有者流程）以及带 PKCE 的公共 authorization_code（每用户浏览器登录，无静态密钥）。实例生命周期命令：instance add、instance list、instance test dev、instance update dev、instance remove dev、instance migrate。instance update 仅改元数据；认证变更需先 remove 再 add。instance credential set dev 仅用于轮换已注册实例或补全仅元数据的注册，不能引导新实例名。
注册表存储：默认 v1 用户注册表位于 ~/.config/happy-platform-mcp/instances.json，仅含非机密元数据和规范 credentialRef 值，凭据保留在钥匙串中。HAPPY_CONFIG_PATH 可覆盖注册表位置，支持绝对路径、相对路径和 ~，需在运行 CLI 前设置并向 MCP 宿主提供相同值。包内 config/servicenow-instances.json 是只读的旧版迁移输入，不是可写的 v5.1 注册表。
文档模式：当既无注册表/配置也无旧版环境凭据时，stdio 自动回退到仅文档模式；也可通过 HAPPY_MCP_DOCS_ONLY=true 显式强制。v5.1 的 --docs-only 标志不能可靠覆盖已有注册表。仅文档模式暴露文档和安全注册工具，不创建实时 ServiceNow 客户端。
安全注册：SN-Register-Instance 仅处理元数据并拒绝机密字段。v5.1 存在引导约束：凭据支持的注册在写入新元数据前检查凭据引用，而 instance credential set 需要已注册的名称。因此 Basic、client_credentials 和 OAuth password 应使用本地 instance add；公共 authorization_code 可直接用 SN-Register-Instance。切勿向 SN-Register-Instance 传递凭据或令牌。
验证与路由：重启 MCP 宿主后，用无参数的 SN-Set-Instance 列出实例，用 SN-Get-Current-Instance 检查会话，并执行低风险读取（如 SN-Query-Table）。SN-Set-Instance 更改当前会话的隐式目标；并发、关键或可能发生会话切换竞争的操作应显式传入每次调用的实例值。
最佳实践：从只读和非生产实例开始；保持实例名称清晰并在写入前验证当前目标；凭据仅保留在本地掩码提示和钥匙串中；破坏性、生产、并发或关键操作使用显式路由；启用写入工作流前运行 instance test <name>；不熟悉的表操作前先用 SN-Get-Table-Schema。
限制与故障排查：CLI 报告 Node 运行时过旧需安装 Node 20+；实例名缺失运行 instance list 后本地 instance add；认证模式需变更先 remove 再 add；元数据存在但认证失败运行 instance credential set <name> 后 instance test <name>；仅出现文档工具需移除强制仅文档模式并在有效注册后重启；迁移拒绝路径时使用自动旧版到默认用户路径或选择不同的仅元数据目标。