instance-management

インスタンス管理

概要

Happy Platform MCP v5.1 では、永続的な登録と実行時のルーティングが分離されています。ローカル CLI コマンドでは、メタデータのみを保持するユーザーレジストリと、キーチェーンで管理される認証情報を管理します。MCP ツールでは、現在のセッションまたは明示した単一の呼び出しに対するターゲットを選択します。この分離により、あるワークフローが誤って別のワークフローのルーティング先を変更することを防ぎます。

前提条件

• development/mcp-server-installation を通じて Happy Platform MCP v5.1 が設定されていること
• ローカルの対話型 CLI を使って、1 つ以上のインスタンスが追加されていること
• 想定する読み取りまたは書き込みに適した 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 - 環境固有の構成の移送