mcpField
I
instance-management

instance-management

github.com/happy-technologies-llcAgent 工作流4142 次安装2 天前更新
代码仓库

关于 instance-management

用于通过 Happy Platform MCP v5.1 安全路由不同 ServiceNow 实例的技能。它将本地注册表和凭据管理与会话级及单次调用的目标选择分开。

主要功能

  1. 01检查已注册实例
  2. 02查看当前会话目标
  3. 03设置顺序操作的会话目标
  4. 04将调用路由至指定实例
  5. 05写入前验证目标

适用场景

  1. 01为顺序操作选择实例
  2. 02避免并发调用受到会话状态冲突影响
  3. 03生产变更前核对环境
  4. 04排查实例缺失或连接问题

MCP 相关

说明 MCP 工具如何列出和选择实例、报告当前目标，并通过单次调用的 `instance` 参数路由受支持的操作。持久化注册和凭据变更由本地命令行处理。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/happy-technologies-llc/happy-platform-skills --skill instance-management

安装后在 Claude Code 中输入/instance-management确认已加载。

详细介绍

实例管理

概述

Happy Platform MCP v5.1 将持久化注册与运行时路由分开。通过本地 CLI 命令管理仅包含元数据的用户注册表和由密钥链支持的凭据。MCP 工具可为当前会话或某次明确的调用选择目标。这种分离可防止某个工作流意外重定向其他工作流。

前提条件

  • 已通过 development/mcp-server-installation 配置 Happy Platform MCP v5.1
  • 已通过本地交互式 CLI 添加一个或多个实例
  • 拥有执行预期读取或写入操作所需的 ServiceNow 角色

操作步骤

步骤 1：检查已注册的实例

如需检查本地配置，建议使用：

happy-platform-mcp instance list
happy-platform-mcp instance test dev

在 MCP 中，不带参数调用 SN-Set-Instance，即可列出已配置的选项，而不更改目标：

Tool: SN-Set-Instance
Parameters: none

v5.1 没有单独的 MCP 列表工具；不带参数的 SN-Set-Instance 是受支持的列出操作。

步骤 2：确认会话目标
Tool: SN-Get-Current-Instance
Parameters: none

此操作会报告当前会话的隐式目标。在按顺序执行写入工作流前，应立即检查该目标。

步骤 3：为顺序操作选择目标
Tool: SN-Set-Instance
Parameters:
  instance_name: dev

SN-Set-Instance 只会更改当前会话在内存中的隐式目标。它不会编辑注册表、影响其他 MCP 会话，也不会更改已配置的启动默认值。新会话会从已配置的默认值开始。

步骤 4：为并发或关键调用显式指定路由

除 SN-Register-Instance、SN-Set-Instance、SN-Get-Current-Instance 和文档工具（SN-Docs-Families、SN-Docs-Status、SN-Docs-Sync、SN-Docs-Search 和 SN-Docs-Get）外，每个实时 ServiceNow 操作都接受可选的 instance 参数。注册操作不接受 instance 字段。受支持操作中显式指定的单次调用值不会改变会话目标。

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

对于并发工作、关键操作、生产环境变更，或可能与 SN-Set-Instance 发生竞争的调用，请使用显式 instance 路由。针对同一个稳定的隐式目标进行并发调用时，可以省略该参数；不过，显式路由更便于审计。

步骤 5：写入前验证

使用显式目标查询实例专属属性，将响应与预期环境进行比较，然后再执行写入：

Tool: SN-Query-Table
Parameters:
  instance: dev
  table_name: sys_properties
  query: name=instance_name^ORname=glide.installation.name
  fields: name,value
  limit: 5

随后，在变更操作中沿用相同的显式目标：

Tool: SN-Update-Record
Parameters:
  instance: dev
  table_name: incident
  sys_id: <verified-record-sys-id>
  data:
    work_notes: Verified dev routing before update

工具用法

工具用途
SN-Set-Instance不带参数时列出选项；带 instance_name 时更改顺序操作的会话目标
SN-Get-Current-Instance报告当前会话目标
SN-Query-Table从显式指定的实例读取或进行验证
SN-Create-Record在已明确验证的目标上创建记录
SN-Update-Record在已明确验证的目标上更新记录

持久化添加、移除、元数据更新、测试、迁移和凭据轮换都应由本地 CLI 处理。MCP 调用不得收集凭据材料或修改密钥链条目。

最佳实践

  • 对所有生产环境写入，优先使用显式的单次调用路由。
  • 每次关键变更都应配合同一目标的只读验证。
  • 仅将 SN-Set-Instance 用于顺序操作的便利切换，切勿将其用作并行隔离机制。
  • 如果操作策略允许，请将开发环境保留为已配置的默认环境。
  • 连接情况发生变化时，在本地运行 happy-platform-mcp instance test <name>。
  • 将原始 REST 调用作为最后手段，并且仅依赖预先存在的本地凭据助手。

故障排除

问题原因解决方法
未列出实例实例不在用户注册表中在本地运行 happy-platform-mcp instance add
当前目标不符合预期先前的顺序切换更改了此会话的状态调用 SN-Get-Current-Instance，然后使用预期名称调用 SN-Set-Instance
并行工作访问了错误的目标调用依赖于可变的会话状态为每个重叠调用添加明确的 instance
新注册未生效服务以仅文档模式启动注册后重启 MCP 主机
连接测试失败本地注册或 ServiceNow 访问无效运行本地 instance test 流程；绝不要通过 MCP 发送凭据

相关技能

  • development/mcp-server-installation - 安全的本地注册和迁移
  • admin/generic-crud-operations - 路由后的表操作
  • admin/update-set-management - 特定环境的配置传输

评论

支持 Markdown