mcp-server-installation

Happy Platform MCP v5.1 安装

概述

安装 Happy Platform MCP v5.1，注册一个或多个 ServiceNow 实例，并连接 MCP 主机，避免向模型、MCP 消息、日志、Shell 历史记录或客户端 JSON 暴露身份验证材料。遵循 MCP 优先策略：完成本地设置后，使用实时 SN-* 工具处理 ServiceNow 任务；仅当没有 MCP 工具能执行该操作，且调用方已有本地管理的凭据助手时，才使用原始 REST。

前提条件

• Node.js >= 20
• Happy Platform MCP 5.1.0 或兼容的更高 5.x 版本
• 可用于输入掩码提示的本地交互式终端
• 当前用户可用的操作系统密钥链
• 支持 MCP 的客户端，以及适当的 ServiceNow 访问权限

操作步骤

步骤 1：安装服务

使用 npm 进行常规安装：

npm install -g [email protected]
happy-platform-mcp --version

MCP 主机也可以通过 npx -y [email protected] 启动此软件包。不要将身份验证材料添加到参数或环境块中。

步骤 2：选择身份验证模式

在本地运行 happy-platform-mcp instance add。该命令会通过交互式掩码提示收集所需值，并将凭据材料存入操作系统密钥链。模型绝不能要求用户粘贴、回显、记录、写入文档或通过 MCP 调用发送这些材料。

模式	适用情况	本地设置行为
Basic	需要指定集成用户时	在本地提示输入用户身份和凭据
OAuth client_credentials	需要非交互式服务集成时	在本地提示输入客户端元数据和客户端凭据
OAuth password	明确要求使用旧版资源所有者流程时	在本地提示输入用户和客户端凭据；条件允许时，优先选择更安全的流程
带 PKCE 的公共 authorization_code	可进行按用户浏览器登录时	直接实现零静态密钥路径；浏览器流程会将刷新状态存入操作系统密钥链

使用本地 CLI 生命周期：

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 update 仅更改元数据。更改身份验证信息需要先移除再重新添加。仅在轮换已注册实例的凭据或完成现有的仅含元数据的注册时，才使用 happy-platform-mcp instance credential set dev；它无法引导注册新的实例名称。

步骤 3：了解注册表存储

默认的版本 1 用户注册表位于 ~/.config/happy-platform-mcp/instances.json。其中仅包含非机密元数据和规范的 credentialRef 值。凭据保留在操作系统密钥链中。不要手动向注册表添加明文值。

HAPPY_CONFIG_PATH 可覆盖注册表位置，并支持绝对路径、相对路径和 ~。请在运行 CLI 前设置该值，并向 MCP 主机提供相同的值。这是安全的主机配置，因为它指定的是元数据，而不是凭据。

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

软件包本地的 config/servicenow-instances.json 是只读的旧版迁移输入，绝不是可写的 v5.1 注册表。使用自动的“软件包旧版配置到用户注册表”路径时，happy-platform-mcp instance migrate 会将凭据移入操作系统密钥链，并保持旧版源文件不变。如果覆盖配置指向同一个明文源文件和目标文件，迁移会在写入前拒绝执行；请选择不同的目标位置，或使用 instance add 重新创建每个实例。绝不要指导用户手动编辑明文注册表。

步骤 4：正常启动或使用仅文档模式

当注册表/配置和旧版环境凭据均不存在时，stdio 会自动回退到仅文档模式。若要明确强制使用该模式，请配置：

{
  "env": {
    "HAPPY_MCP_DOCS_ONLY": "true"
  }
}

使用 HAPPY_MCP_DOCS_ONLY=true；v5.1 的 --docs-only 标志无法可靠地覆盖现有注册表。仅文档模式会公开文档和安全的注册工具，而不会创建实时 ServiceNow 客户端。

步骤 5：安全注册 MCP

SN-Register-Instance 仅处理元数据，并会拒绝包含机密信息的字段。它通常会持久化元数据并执行实时重新加载。以仅文档模式启动的服务必须重启，ServiceNow 实时工具才能使用。

v5.1 存在一项引导限制：基于凭据的注册会在写入新元数据之前检查凭据引用，而 instance credential set 要求名称已注册。因此：

• Basic、client_credentials 和 OAuth password 请使用本地 instance add。
• SN-Register-Instance 直接注册适用于公开的 authorization_code，此模式没有静态客户端凭据。
• 如果外部已预先配置确定性的钥匙串引用，也可以直接进行基于凭据的注册。
• 切勿将凭据或令牌传递给 SN-Register-Instance。

公开注册示例：

Tool: SN-Register-Instance
Parameters:
  name: public-dev
  url: https://example.service-now.com
  authType: oauth
  grantType: authorization_code
  clientId: registered-public-client-id
  makeDefault: true

步骤 6：验证和路由

重启 MCP 主机后，使用不带参数的 SN-Set-Instance 列出实例，使用 SN-Get-Current-Instance 检查会话，并执行低风险读取操作：

Tool: SN-Query-Table
Parameters:
  instance: dev
  table_name: incident
  query: active=true
  fields: number,short_description,state
  limit: 1

SN-Set-Instance 会更改当前会话中后续操作的隐式目标。对于并发工作、关键操作，或任何可能与会话切换发生竞争的操作，请传入显式的每次调用 instance 值。

最佳实践

• 从只读操作开始，并使用非生产实例。
• 使用清晰的实例名称，并在写入前确认当前目标。
• 将凭据保存在经过掩码处理的本地提示中和操作系统钥匙串中。
• 对破坏性、生产环境、并发或关键操作使用显式路由。
• 启用写入工作流之前，运行 happy-platform-mcp instance test <name>。
• 遵循 MCP 优先策略，并在操作不熟悉的表之前使用 SN-Get-Table-Schema。

故障排除

问题	解决方法
CLI 报告 Node 运行时版本过旧	安装 Node 20 或更高版本，然后重试该命令
缺少实例名称	运行 happy-platform-mcp instance list，然后在本地使用 instance add
必须更改身份验证模式	运行 instance remove <name>，然后运行 instance add 并选择新的模式
元数据存在，但身份验证失败	在本地运行 instance credential set <name>，然后运行 instance test <name>
仅显示文档工具	如果存在强制启用的仅文档模式，请移除该设置，并在存在可用注册后重启
迁移拒绝该路径	使用自动的旧版到默认用户路径迁移，或选择一个不同的仅元数据目标

相关技能

• admin/instance-management - 运行时路由和环境安全
• development/servicenow-docs-mcp - 文档搜索和仅文档模式行为
• development/mcp-server - 构建自定义的 MCP 兼容集成