service-itsm-incident-mgmt-configure

ITSM Incident Management の設定（マスター切り替え）

Salesforce ITSM 組織の Incident Management のマスター設定を読み取り、切り替えます。これは、組織レベルで Incident Management のオン／オフを切り替える設定です。有効にすると、サーバー側でそのサブ機能も有効になるため、完全に有効化する操作はマスター設定だけで完了します。

書き込みは 冪等 であり、現在の状態が要求された状態と一致している場合はスキップされます。また、このスキルは常に 書き込み前に読み取り を行い、変更前に明示的な 書き込み確認 が必要です。

このスキルで制御する項目

設定（設定 UI のラベル）	対象範囲
Incident Management の有効化（マスター）	はい — 読み取りと切り替え
Incidents のデフォルト項目検証、子 Incident の自動クローズ、Email-to-Incident のサブ設定、Incident Priority Matrix、Problem／Change／Case Management、ITSM External Client App の設定	いいえ

マスター設定の読み取りと書き込みに使用する正確な URL、ワイヤー形式、実行例については、references/mcp-invocation.md を参照してください。

対象範囲

• 対象範囲内：Incident Management のマスター設定の読み取りと切り替え。
• 対象範囲外：Incidents のデフォルト項目検証（IncidentValidationsEnabled）、Incident Priority Matrix の設定、子 Incident の自動クローズと Email-to-Incident のサブ設定、Problem Management、Change Management、Case Management、ITSM External Client App の設定、その他の ITSM 設定（IncidentTriageAgentEnabled、IncAssignWithAgentEnabled、AssignedGroupValidationEnabled）、ブロードキャストチャネルの設定、Incident、Problem、ChangeRequest レコードの作成や設定。

---

前提条件

このスキルが headless-360 に対して何らかの操作を実行する前に、対象組織と MCP クライアントを設定する必要があります。以下のいずれかを満たしていない場合、最初の呼び出しでツールから 401、403、または 404 が返されます。状態を捏造せず、生のエラーをそのまま提示して停止してください。

1. 組織でサーバーを有効化：設定 → MCP Servers → headless-360 → 有効化。有効化には最大約 2 分かかる場合があります。
2. External Client App を接続：組織内に、OAuth スコープ mcp_api と refresh_token を持ち、JWT ベースのアクセストークンが有効で、PKCE が必須の ECA を設定します。ECA の反映には最大 30 分かかる場合があります。
3. API v67.0 以降：このスキルが使用する読み取りおよび書き込みルートに必要です。
4. MCP クライアントの登録：クライアント（adk-eval／Claude Code）に、正しい環境 URL を指す additionalServers.headless-360 エントリがあること（references/mcp-invocation.md を参照）。

いずれかの前提条件が満たされていない場合、ツールは次のいずれかを返します。

• 401 Unauthorized → ECA が反映されていない、スコープが誤っている、またはトークンの期限が切れている。
• 403 Forbidden → ユーザーに必要な権限がない、または組織に IncidentMgmt.orgHasITSMOrgPermission がない。
• 404 Not Found → 組織でサーバーが有効化されていない。

どの前提条件が満たされていなかったかを推測せず、生のレスポンスをそのまま報告してください。

---

アーキテクチャ — 設定の仕組み

ステップ	内容	ツール
事前確認	対象のルートにアクセスできることを確認します	describe、dispatch_readonly
スキーマを読み取る	読み取りと書き込みのリクエスト／レスポンスの仕様を取得します	describe
現在の状態を読み取る	マスター設定の現在の状態を取得します	dispatch_readonly
操作を決定する	表示／有効化／無効化 — プロンプトから判断します	—
書き込み前の確認	(status: current → requested) を提示し、明示的な「はい」を求めます	—
変更を適用する	書き込みルートを介してマスターを有効化または無効化します	dispatch
検証	再読み込みし、リクエストされた状態と比較します	dispatch_readonly

冪等性：Phase-3 の読み取り後、現在の状態がすでにリクエストされた状態と一致している場合は、Phase 5 をスキップし、操作を何もしないものとして扱います。正確なステータスフィールドと一致ルールについては、references/mcp-invocation.md を参照してください。

読み取り専用ツールの選択：読み取りには dispatch_readonly を使用します。書き込みには dispatch を使用します。サーバーは dispatch_readonly による変更操作を拒否します。

ワイヤー形式：dispatch と dispatch_readonly は、どちらも {"url": "/services/data/...", "method": "GET|POST|PATCH|...", "body"?: {...}, "query_params"?: {...}} を受け取ります。正確なリクエスト／レスポンス形式については、references/mcp-invocation.md を参照してください。実行時に describe を呼び出して確認してください。

---

確認の質問

会話のコンテキストですでに明らかになっていることは尋ねないでください。

フィールド	説明	デフォルト
リクエストされた方向	明示的な enable／disable（または on／off）	必須 — デフォルトはありません。ユーザーが方向を指定せずに「toggle」とだけ言った場合は尋ねてください
書き込みの確認	dispatch による変更の前に、明示的な「はい」を求めます	必須 — Phase 4 を参照

ユーザーが方向を指定せずに「toggle」と言った場合は、Phase 4 の前に方向を尋ねてください。現在の状態から推測しないでください。

---

ワークフロー

すべてのステップは headless-360 MCP サーバーに対して実行します。ツールの名前空間は mcp__headless-360__<tool-name> です。

フェーズ 0 — セッションがすでに知っている情報を再利用する

以下の各プリフライト読み取りには、すでに判明している場合はスキップするという条件が付いています。読み取りエンドポイントを呼び出す前に、このセッションの以前のターンで、現在の組織に紐づく成功したツール応答から同じ事実がすでに得られていないか確認してください（このスキルの以前の呼び出し、親オーケストレーターによるライブ読み取り、または今回の実行における以前の dispatch_readonly）。ユーザーによる明示的な発言は、マスター設定のライブ読み取りの代わりにはなりません — ユーザーの主張は古くなっていたり誤っていたりする可能性があり、このスキルは、確認ペイロードとフェーズ 6 の冪等性検証において、読み取りが信頼できる情報源であることに依存しています。唯一の情報源がユーザーの発言である場合は、再読み取りしてください。

• マスター読み取り/書き込みルートの describe — 現在の組織に対してリクエスト/レスポンススキーマがこのセッションですでに取得済みであれば、フェーズ 1 とフェーズ 2 をスキップし、キャッシュされたスキーマを再利用してください。describe の出力はセッション内では安定しています。
• 現在のマスター設定の状態 — 現在の組織のマスター IncidentMgmtEnabled の値が、このセッションですでに成功した dispatch_readonly レスポンス経由で読み取られている場合（このスキルの以前の実行によるフェーズ 3 の結果、またはすでに確認を依頼してきた親オーケストレーター）、フェーズ 3 をスキップし、記録された「変更前」の値を再利用してください。ユーザーが口頭でスイッチがオンまたはオフであると主張しても、キャッシュの対象にはなりません。

疑わしい場合は再確認してください。 以前の事実がコンテキスト内で明確であり、かつ組織を切り替えていない場合にのみスキップしてください — headless-360 MCP セッションは JWT を介して 1 つの組織にバインドされるため、組織の変更は、会話の途中でセッションが再認証された場合にのみ発生し得ます。ユーザーが別の組織を示唆している場合、または以前の事実がどの組織から来たものか判別できない場合は、読み取りを再実行してください。注: セッション内の他の場所でマスターを反転させた可能性のある dispatch 書き込み（このスキルのフェーズ 5、または別のツールによる管理者変更）もキャッシュを無効化します — 再読み取りしてください。ライブ組織への書き込みで誤ってスキップするほうが、読み取りを重複させるよりも有害です。

フェーズ 1 — プリフライト（discover / describe）

1. (このセッションで操作スキーマがすでに検証済みの場合はスキップしてください — フェーズ 0 を参照。) 読み取り/書き込みルートに対して describe を呼び出します（または、操作 ID が不明な場合は "ITSM incident management setup discovery" のようなクエリで discover を呼び出します）。操作が存在し、その引数スキーマが references/mcp-invocation.md と一致することを確認してください。
2. いずれかのツール呼び出しが 401 / 403 / 404 を返した場合は、中断して生のエラーを提示してください — 組織またはクライアントが正しく構成されていません（前提条件を参照）。

フェーズ 2 — スキーマの読み込み（describe）

3. (各操作のスキーマがこのセッションですでにキャッシュされている場合はスキップしてください — フェーズ 0 を参照。) 呼び出しが使用する各操作について、describe を呼び出し、返されたリクエスト/レスポンススキーマをキャッシュしてください。参照ドキュメントから引数の形をハードコードしないでください — describe から読み取ってください。ドキュメントは作業上の想定であり、実行時の契約は describe が返すものです。

フェーズ 3 — 現在の状態の読み取り（dispatch_readonly）

4. (この組織の現在のマスター状態がこのセッションですでに読み取られており、かつそれ以降にそれを反転させた書き込みがない場合はスキップしてください — フェーズ 0 を参照。) references/mcp-invocation.md に記載された読み取りルートを使用して、マスター設定の現在の状態を読み取ってください。フェーズ 4 の確認とフェーズ 6 の検証のために、その値を「変更前」の状態として記録してください。

   閲覧のみのリクエストの場合は、フェーズ 3 の後で停止し、フェーズ 7 に進んで報告してください。

フェーズ 4 — 操作の決定 + 書き込みの確認（書き込みには必須）

5. ユーザーのプロンプトから操作（閲覧 / 有効化 / 無効化）を決定してください。ユーザーが方向を指定せずに「トグル」と言った場合は、まず方向を尋ねてください。

6. 対象ペイロードを提示してください — AskUserQuestion を介して (Master Incident Management: <current> → <requested>) の形式で提示します。続行する前に明示的な「はい」を要求してください。フェーズ 5 に進むのは明示的な「はい」があった場合のみです。「いいえ」の場合は、書き込みを行わずに停止し、現在の状態を報告してください。

フェーズ 5 — 変更を適用する（表示のみの場合はスキップ）

7. references/mcp-invocation.md のべき等性ルールを適用します。現在の状態がすでに要求された状態と一致している場合は、フェーズ 5 をスキップし、操作をべき等な無操作として記録します。

8. それ以外の場合は、references/mcp-invocation.md に記載されている有効化または無効化のルートを使用して、dispatch 経由で書き込みを実行します。マスターを有効にすると、サーバー側でインシデント管理のサブ機能も有効になります。個別に有効化する呼び出しは不要です。マスターを無効にしても、サブ機能は最後に設定された値のままになります。

9. エラー（4xx、5xx）が発生した場合は、未加工のレスポンスをそのまま記録し、停止します。

フェーズ 6 — 検証（dispatch_readonly）

10. フェーズ 3 の読み取りを再度実行し、references/mcp-invocation.md のルールに従って要求された状態と比較します。一致しない場合は書き込みの失敗として扱い、未加工のサーバーレスポンスをそのまま報告します。

フェーズ 7 — 報告

11. 変更前後の概要を提示します。
    • 表示：Master Incident Management: <current-status>。
    • 切り替え：Master Incident Management: <before> → <after> と判定結果 SUCCEEDED ／ ALREADY-<state> ／ FAILED。
    • フェーズ 6 で不一致があった場合：write FAILED — server state differs from request. Server response: <verbatim>。

---

ルール／制約

制約	理由
すべての操作は、ホスト型の 4 つの headless-360 ツールを通じて実行する	ホスト型 MCP が必須のトランスポートです
dispatch ／ dispatch_readonly を呼び出す前に、各操作の引数スキーマを describe 経由で読み取る	実行時の契約は describe が返す内容です。ハードコードしないでください
読み取りには dispatch_readonly を使用し、書き込みには dispatch を使用する	サーバーは dispatch_readonly 経由の変更操作を拒否します
常に API v67.0 以上を指定／想定する	読み取りルートと書き込みルートには v67 以上が必要です
書き込み前にライブ状態を読み取る	フェーズ 3 の取得結果は、確認プロンプト、べき等性の確認、フェーズ 6 の検証における信頼できる情報源です
dispatch による変更の前に、必須の書き込み確認チェックポイントを設ける	この設定の切り替えは組織の状態を変更します。ユーザーは具体的な実行計画を承認する必要があります
べき等性 — 現在の状態が要求された状態と一致する場合は、dispatch をスキップする	無操作の書き込みを避けます。正確な一致ルールについては references/mcp-invocation.md を参照してください
MCP ツールのレスポンスに含まれるエラー文を正確に報告する	サーバーは根本原因のエラーメッセージをそのまま返します
フェーズ 1 で 401 ／ 403 ／ 404 が発生した場合は、処理を停止し、未加工のエラーを提示する	失敗した前提条件は、未加工のレスポンスからのみ診断できます
dispatch の引数に orgId や Core URL を含めない	サーバーはリクエストの JWT 発行者から対象の組織を特定します

---

検証チェックリスト

変更の完了を報告する前に、以下をすべて確認してください。未確認の項目がある場合は、成功を報告せず、不足している内容を明示してください。

• フェーズ 1 の事前確認（describe / discover）で、401 / 403 / 404 を返さずに操作が返されました。いずれかが返された場合は、生のエラーを提示し、処理を停止しました。
• フェーズ 3 でマスター設定を読み取り、ステータスが返され、その値を「変更前」の状態として記録しました。
• フェーズ 4 の書き込み前確認で、AskUserQuestion を通じて (Master Incident Management: <current> → <requested>) を提示し、ユーザーから明示的な「yes」の返答がありました（沈黙、「maybe」、「looks good」などの暗黙の承認を含め、それ以外の返答では書き込みを実行していません）。
• 冪等性：現在の状態がすでに要求された状態と一致していた場合、フェーズ 5 をスキップし、冪等な変更なしとして処理を報告しました（dispatch による書き込みは発行していません）。
• フェーズ 5 の書き込みでは、references/mcp-invocation.md に記載されたワイヤー形式で dispatch（dispatch_readonly ではなく）を使用しました。4xx / 5xx が返された場合は、生のレスポンスを提示し、処理を停止しました。
• フェーズ 6 の検証では、フェーズ 3 の読み取りを再実行し、書き込み後の状態がユーザーの承認した目標と一致しました。差分がある場合は write FAILED — server state differs from request と報告しました。
• 最終報告では、マスター設定の変更前／変更後を示し、判定として SUCCEEDED / ALREADY-<state> / FAILED のいずれかを記載しました。

---

参照ファイル一覧

ファイル	読み取るタイミング
references/mcp-invocation.md	マスター設定の読み取りと書き込みに使用する正確なツール呼び出し形式、mcp-config.json での headless-360 の MCP クライアント登録手順、External Client App のセットアップチェックリスト（mcp_api スコープ、PKCE、JWT）、Headless-360 のエラー分類、ならびに有効化／無効化の実例