platform-metadata-grounding-get

Salesforce Metadata Grounding

メタデータグラウンディングは、組織のメタデータを名前、ラベル、説明、設定プロパティとともにインデックス化した、組織の Salesforce Catalog を検索します。意味に基づいてメタデータを検索するため、「顧客の特典ステータス」と入力すると、「ロイヤルティティア」というラベルの項目が見つかる場合があります。読み取り専用の操作は、検索、クエリ、説明の3つです。

結果は順位付けされ、件数が制限されます。完全な一覧が返されることはなく、グラウンディングからソースが返されることもありません。

グラウンディングを使用しない場合

• この組織に依存しない、Salesforce の標準機能や製品の動作に関する質問。
• すでに名前がわかっている場合。その名前は、範囲を指定した SOQL で確認してください。正確でリアルタイムな結果が得られます。
• 完全な一覧、件数、または存在しないことの証明が必要な場合。範囲を指定した SOQL または sf org list metadata を使用してください。
• 編集またはデプロイするソースが必要な場合。platform-metadata-retrieve で取得してください。
• どこで使用されているか、または変更した場合に何が壊れるかを知りたい場合。グラウンディングには参照データがありません。
• この会話ですでに返されており、その後変更されていないメタデータ。

platform-metadata-discovery-get は、これらのケースそれぞれに適したツールを選びます。

サーバーを選ぶ

2つのサーバーは同じカタログにアクセスし、同じ結果を返します。リクエストごとに1つのサーバーを使用し、同じ検索で両方を使わないでください。

Salesforce MCP は現在、Setup では Headless360（H360）MCP Server として表示されます。このサーバーでは、searchMetadata、queryMetadata、describeMetadata は describe と dispatch に渡す操作 ID です。ツール名ではありません。search_metadata、query_metadata、describe_metadata ツールが存在するのは Metadata Grounding MCP のみです。

順序	サーバー	呼び出し方法
1	Metadata Grounding MCP	以下の入力を指定して、search_metadata、query_metadata、または describe_metadata を呼び出します。
2	Metadata Grounding MCP に接続されていない場合、または繰り返し失敗する場合の Salesforce MCP	操作 ID searchMetadata、queryMetadata、または describeMetadata に対して describe を呼び出します。discover は使用しないでください。また、大きすぎて読み取れないグラウンディングレシピの説明も求めないでください。次に、describe が返すパスを同じ入力で呼び出します。searchMetadata には dispatch_readonly を使用し、入力をクエリパラメーターとして渡します。読み取り専用の POST 呼び出しである queryMetadata と describeMetadata には dispatch を使用し、入力を JSON 本文として渡します。他のメタデータ検索操作は使用しないでください。
どちらにも接続されていない		グラウンディングは利用できません。platform-metadata-discovery-get の名前とラベルの代替手段を使用してください。

呼び出しが失敗した場合

発生したこと	対応
エラーに Salesforce Catalog が有効になっていないと表示される場合、またはユーザーに Customize Application 権限がない場合	セッションの残りの間、両方のサーバーでグラウンディングを使用するのをやめてください。代替手段を使用し、その理由をユーザーに一度伝えてください。
その他のエラーまたはタイムアウト	1回だけ再試行してください。再度失敗した場合は、このリクエストで次のサーバーを使用してください。2つのリクエストで失敗した後は、セッションの残りの間、次のサーバーを使用してください。
ツールまたはサーバーが存在しない	次のサーバーから開始してください。

ツールが見つからないこと、アクセスエラー、または404は、メタデータが存在しない証拠にはなりません。

レスポンスの形式

呼び出し	Metadata Grounding MCP	Salesforce MCP
検索	{results, totalCount}	レスポンス本文に同じペイロード
説明とクエリ	{defaultExc: "<json string>", responseCode} としてラップされます。defaultExc 文字列を解析して、types、typeDetails、または records を読み取ります。	ラップされずにレスポンス本文にペイロードが含まれます
エラー	{errorCode, message} の配列	レスポンス本文に同じ配列

両方の形式に対応してください。レスポンスに defaultExc 文字列がある場合は、解析してください。それ以外の場合は、ペイロードを直接読み取ってください。

カタログの型名

型名は大文字と小文字を区別し、一部は Metadata API の名前と異なります。

Metadata API 名	カタログの型
CustomObject	SObject（サブタイプは CustomObject、StandardData）
CustomField	SObjectField（サブタイプは CustomField、StandardField、CustomPersonAccountField）
GlobalValueSet, StandardValueSet	PicklistValueSet（サブタイプは Global、Standard、Local）
FlexiPage	Flexipage
CustomTab	Tab
CustomApplication	TabSet
QuickAction	QuickActionDefinition
Queue	サブタイプ Queue の Group
Role	UserRole

その他のほとんどの型では、たとえば ApexClass、ApexTrigger、Flow、PermissionSet、PermissionSetGroup、Profile、ValidationRule、RecordType、SharingRule、FieldPermissions、PicklistValue、CustomPermission のように、Metadata API の名前を使用します。

必要な型がどちらのリストにもない場合に限り、requests を指定せずに describe を呼び出し、型名だけを確認してください。レスポンス全体は約 29K 文字です。型のプロパティが必要な場合に限り、metadataType を指定して describe を呼び出してください。

検索

入力：

• query：必須の自然言語による語句です。空のクエリを指定すると ILLEGAL_QUERY_PARAMETER_VALUE が返されます。
• metadataType：任意のカタログ型名です。
• metadataSubType：任意の単一値です。metadataType が必要です。
• parentIdentifier：任意の値です。1 つのオブジェクトまたは権限コンテナー内を検索する場合に指定します。
• limit：1～100、デフォルトは 50 です。10～20 を使用してください。

効果的な検索方法：

1. 可能な場合は型で絞り込んでください。 範囲の広い質問では、フィルターなしの検索を 1 回行うのではなく、SObject、SObjectField、Flow など、可能性の高い型をいくつか検索してください。
2. オブジェクト内を検索するには、返された識別子を parentIdentifier として渡してください。まず SObject を検索してオブジェクトの正確な API 名を見つけるか、フィールドの検索結果にある parentIdentifier を再利用し、その識別子を変更せずにコピーしてください。オブジェクトの API 名をそのまま渡してはいけません。これにより、トピックに関連するフィールドを検索できます。フィールドの全リストが得られるわけではありません。
3. 「組織のカタログに一致するものが見つかりませんでした」と報告する前に、同義語や可能性の高いラベルを使って別の表現でもう一度検索してください。
4. サービスの公開ポリシーを信頼してください。 API 名のサフィックスから、可視性やサポート対象であると推測してはいけません。ユーザーが求めるドメインに関連する結果を保持し、意図的に公開されている Data Cloud メタデータも、関連がある場合は利用可能な状態にしてください。
5. 検索結果が何も返さなかった場合、それ以上クエリを実行せず、検索を終了してください。

クエリ

Query は、フィールドのデータ型、必須フラグ、長さ、数式、デフォルト値、ヘルプテキスト、選択リストの値セットなど、型固有の properties を含む完全なレコードを返します。

次のいずれか 1 つだけを指定してください：

• metadataIdentifiers：レコード自体を読み取るための 1～50 個の識別子です。
• parentIdentifiers：子レコードを読み取るための 1～10 個の識別子です。

選択リストの値には parentIdentifiers を使用してください。フィールドの PicklistValueSet を検索し、その値セットの識別子を渡します。オブジェクトを渡してはいけません。オブジェクトを渡すと、そのオブジェクト上のすべてのフィールドが返され、非常に大きな結果になります（Contact の場合、約 77KB）。フィールドの全リストを取得するには、EntityParticle に対して範囲を指定した SOQL を使用してください。

識別子は :: で区切られた 3 つの要素で構成されます。18 文字の org id、名前、型です。ツールが返した識別子のみを使用してください。識別子を自分で作成、短縮、編集してはいけません。

一般的なパターン

この項目用のフィールドはすでにありますか？ ユーザーの言葉とオブジェクトの parentIdentifier を使って SObjectField を検索します。最も一致する候補を、API 名、ラベル、説明とともに提示します。

このフィールドはどのように設定されていますか？ フィールドを検索し、その識別子をクエリして properties を読み取ります。

この選択リストにはどのような値がありますか？ フィールドを対象に PicklistValueSet を検索し、parentIdentifiers を指定して値セットをクエリします。

このフィールドを読み取ったり編集したりできるのは誰ですか？ Contact.Loyalty_Tier__c など、フィールドの API 名を使って FieldPermissions を検索します。各結果の親はプロファイルまたは権限セットです。結果をクエリして、読み取りフラグと編集フラグを確認します。結果は100件で打ち切られるため、完全な一覧が必要な場合は、FieldPermissions に対して範囲を指定した SOQL を使用します。

この入力規則では何が強制されますか？ ValidationRule を検索し、数式、エラーメッセージ、有効フラグをクエリします。

制限事項

• フロー： ヘッダーのみです。つまり、プロセスタイプ、トリガータイプ、トリガーオブジェクト、有効ステータスが対象です。要素やロジックは含まれません。トリガーオブジェクトはフィルターではないため、検索しても特定のオブジェクト上のすべてのフローを一覧表示することはできません。
• Apex： シグネチャのみで、メソッド本体は含まれません。管理パッケージのクラスは空のスタブを返します。
• ページとアクション： Flexipage と QuickActionDefinition のレコードは、そのオブジェクトの子ではありません。オブジェクトを parentIdentifier に指定して検索しても見つかりません。代わりに意味で検索してください。
• カタログに含まれないもの： ページレイアウト、レポート、カスタムメタデータタイプ、カスタム設定。
• 鮮度： カタログにデプロイやその他の変更が反映されるまで、数分かかることがあります。このセッションで変更したものについては、デプロイ結果を信頼し、リアルタイムの SOQL で確認してください。

根拠に基づく回答の徹底

• ツールが返した API 名、ラベル、プロパティを引用します。どの記述が観測されたもので、どれが推論なのかを明示します。
• 「組織のカタログで一致するものは見つかりませんでした」と述べます。メタデータが存在しないとは決して言わないでください。
• 結果を完全な一覧として扱わないでください。
• クエリ結果から作成したファイルを作成したり、デプロイしたりしないでください。返されるのはプロパティであり、ソースではありません。
• すべての識別子は組織 ID で始まります。CLI や別のツールも使う場合は、結果を組み合わせる前に、両方が同じ組織を参照していることを確認してください。

操作リファレンス

このスキルで使用する操作 — ルーティングと依存関係のリファレンスです。

操作	目的	ステータス	呼び出し	依存先
describe-metadata	読み取り	—	POST /metadata-grounding/schema	—
search-metadata	読み取り	—	GET /metadata-grounding/search	—
query-metadata	読み取り	—	POST /metadata-grounding/query	—