mcpField
P
platform-metadata-retrieve

platform-metadata-retrieve

github.com/forcedotcom開発1.1k6.7k 回インストール1 日前に更新
リポジトリ

platform-metadata-retrieve について

platform-metadata-retrieveは、`sf` CLIでSalesforce組織のメタデータをローカルプロジェクトへ取得するエージェントスキルです。変更、ディレクトリ、型、マニフェスト、パッケージ別の取得と、JSON出力や操作上の制約を扱います。

主な機能

  1. 01追跡対象の変更をすべて取得
  2. 02ソースディレクトリを指定して取得
  3. 03メタデータ型やワイルドカードで取得
  4. 04マニフェストやパッケージ名で取得
  5. 05ソース形式またはメタデータ形式を選択
  6. 06構造化JSON結果を出力

活用シーン

  1. 01Salesforce組織のメタデータをプロジェクトへ取得
  2. 02開発用に指定したメタデータ型を取得
  3. 03取得したメタデータをプロジェクト内に保存

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/forcedotcom/sf-skills --skill platform-metadata-retrieve

インストール後、Claude Code で/platform-metadata-retrieveを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

examples/
error_output.json
success_output.json
references/
cli_flags.md
retrieval_modes.md

詳細

platform-metadata-retrieve

sf project retrieve start を使用して、Salesforce 組織からローカルプロジェクトにメタデータを取得します。すべての変更、ソースディレクトリ、メタデータタイプ（ワイルドカード対応）、マニフェスト、パッケージ名など、複数の取得モードに対応しています。

ツールの制限事項

sf project retrieve start の実行には Bash ツールのみを使用してください。 MCP ツールは使用せず、完全に無視してください。

対象範囲

  • 対象：すべての対応モード（すべての変更、source-dir、メタデータタイプ、マニフェスト、パッケージ名）での sf project retrieve start によるメタデータの取得、ソース形式およびメタデータ形式での出力
  • 対象外：メタデータのデプロイ（platform-metadata-deploy を使用）、メタデータタイプの一覧表示、package.xml ファイルの生成、ソーストラッキングコマンド（sf project retrieve preview）

必須入力

ユーザーのリクエストから以下を推定します。

  • 取得モード：すべての変更｜ソースディレクトリ｜メタデータタイプ｜マニフェスト｜パッケージ名
  • 対象組織：組織エイリアス／ユーザー名（指定がない場合はデフォルトを使用）
  • 出力形式：ソース形式（デフォルト）｜メタデータ形式（ZIP）
  • 追加オプション：競合の無視、出力ディレクトリ、待機時間、API バージョン

ワークフロー

  1. ユーザーのリクエストを以下のコマンドパターンに対応付けます。
  2. Bash ツールで、適切なフラグと --json フラグを指定して sf project retrieve start を実行します。
  3. 取得したコンポーネント数とファイルパスを含めて結果を返します。
コマンドパターン
ユーザーの意図Bash ツールで実行
リモートのすべての変更を取得sf project retrieve start --json
ソースディレクトリを指定して取得sf project retrieve start --source-dir <path> --target-org <alias> --json
メタデータタイプを指定して取得sf project retrieve start --metadata <MetadataType:Name> --target-org <alias> --json
ワイルドカードを使用してメタデータタイプを取得sf project retrieve start --metadata '<MetadataType:Pattern*>' --target-org <alias> --json
複数のメタデータタイプを取得sf project retrieve start --metadata <Type1> --metadata <Type2> --target-org <alias> --json
マニフェストを指定して取得sf project retrieve start --manifest <path/to/package.xml> --target-org <alias> --json
パッケージ名を指定して取得sf project retrieve start --package-name <PackageName> --target-org <alias> --json
メタデータ形式（ZIP）で取得sf project retrieve start --source-dir <path> --target-metadata-dir <output> --unzip --target-org <alias> --json
競合を無視sf project retrieve start --source-dir <path> --ignore-conflicts --target-org <alias> --json

ルール／制約

制約理由
常に --json フラグを使用する信頼性の高い解析とエラー処理のために、構造化された出力を提供します
Salesforce プロジェクト内で実行する必要があるコマンドの実行には、リポジトリのルートに sfdx-project.json が必要です
ワイルドカードパターンは引用符で囲む必要がある引用符で囲まれていない ApexClass:My* などのワイルドカードは、シェルによって展開されます
--manifest は --metadata または --source-dir と併用できない相互排他的なフラグのため、コマンドでエラーが発生します
すべての変更を取得するにはソーストラッキングが必要本番組織ではソーストラッキングに対応していないため、他の取得モードを使用する必要があります
--ignore-conflicts はトラッキング可能な組織でのみ機能する本番組織では効果がなく、スクラッチ組織／Sandbox にのみ適用されます
--output-dir はプロジェクトディレクトリ内に指定する必要があるコマンドは出力パスがプロジェクトの範囲内にあることを検証します
--output-dir をパッケージディレクトリと同じ場所に指定できないターゲットが sfdx-project.json の packageDirectories に一致すると、コマンドは失敗します
デフォルトの待機時間は 33 分大規模な取得では --wait フラグを使用して上書きします
パッケージの取得は参照用取得したパッケージメタデータは、開発用のソース管理に追加しないでください
CustomField の取得時には CustomObject も自動的に含まれるCustomField を取得すると、完全なコンテキストを得るために CLI が CustomObject を自動的に追加します

トラブルシューティング

問題解決方法
"This command is required to run from within an SFDX project"Salesforce プロジェクトのディレクトリにいません。sfdx-project.json があるプロジェクトのルートに移動してください
"No org found for " error組織エイリアスが存在しないか、認証されていません。sf org list で確認してください
"This org does not support source tracking"本番組織では「すべての変更を取得」モードを使用できません。代わりに --source-dir、--metadata、または --manifest を使用してください
"ERROR running project retrieve start: Cannot mix --manifest with --metadata or --source-dir"競合するフラグを削除してください。取得モードは 1 つだけ使用してください
ワイルドカードパターンで何も取得されないパターンが引用符で囲まれていません。シングルクォートで囲んでください：'ApexClass:My*'
"The package directory path in sfdx-project.json does not exist"出力ディレクトリがパッケージディレクトリと競合しています。別のパスを使用してください
"Output directory must be inside the project"--output-dir のパスがプロジェクトの範囲外です。プロジェクト内の相対パスを使用してください
取得がタイムアウトする大量のメタデータを取得する場合は、--wait 60 で待機時間を延長してください
取得したファイルによってローカルの変更が上書きされる--output-dir を使用して別の場所に取得するか、先にローカルの変更をコミットしてください
競合テーブルを含む SourceConflictError追跡可能な組織（スクラッチ組織／サンドボックス）で、ローカルとリモートの間に競合が検出されました。競合を手動で解決するか、--ignore-conflicts を使用して強制的に上書きしてください

出力の概要

このコマンドは、取得したコンポーネントの詳細を含む JSON 出力を返します。

応答の構造については、examples/success_output.json と examples/error_output.json を参照してください。

スキル間の連携

必要な作業委任先
組織にメタデータをデプロイするplatform-metadata-deploy スキル
実行せずに取得内容をプレビューするsf project retrieve preview --target-org <alias> --json を実行
利用可能なメタデータ型を一覧表示するsf org list metadata-types --target-org <alias> --json を実行

参考ファイル一覧

ファイル参照するタイミング
examples/success_output.json取得成功時の応答構造を把握する
examples/error_output.jsonよくあるエラー状況に対処する
references/retrieval_modes.mdすべての取得モードと、それぞれを使用するタイミングについて詳しく確認する
references/cli_flags.md使用パターンを含むフラグの完全なリファレンスを確認する

コメント

Markdown 対応