fw-publish

エントリー契約

• 呼び出し元： fw-review の完了後、公開についてユーザーから明示的な同意を得たコントローラー
• 前提条件： fw-review が完了していること。MCP 認証が確認済みであること（list_custom_apps のスモークテスト）。アップロード用の非サンドボックスネットワーク
• 戻り値： done（送信／バージョン作成済み）｜blocked（認証／ネットワーク／レビューの不足）｜escalate（アップロードの失敗が繰り返された場合）
• 完了時： 制御をコントローラーに戻します。session-write.sh を使ってセッションの公開ブロックを更新し、新しいワークフローを開始しないでください
• セッション： セッションから publish.tracking_id を読み取ります。送信成功後に publish.tracking_id と step=published を書き込みます

公開（Platform 3.0 カスタムアプリ）

必須の前提条件： マーケットプレイスの要件に準拠していることを確認するため、公開前に fw-review スキルを実行してください。レビューでは iparams、フロントエンドファイル、セキュリティパターンを確認し、構造化された監査レポートを生成します。レビューに合格するまで公開に進まないでください。

目的： manifest.json を含む Platform 3.0 アプリフォルダーを任意に取得し、dist/*.zip を生成して、MCP ツールを通じて Freshworks Marketplace に公開します。現在サポートされているのは test 状態のみです。

サンドボックス／エージェントの外部接続： https://mcp.freshworks.dev/mcp への MCP トラフィックや外部 HTTPS 通信（アプリのアップロード URL への curl PUT を含む）をブロックする サンドボックス（または同等の）モードでは、公開は機能しません。一部のクラウドまたは CI エージェントのランタイムでは、HTTPS 通信がプロキシ、ゲートウェイ、または想定 IAM ロールを経由しますが、これらは Marketplace アプリのアップロード用バケット（fa-*-app-uploads…）への PUT が許可されていません。署名付き URL が有効でも、S3 は 403 / AccessDenied を返します。サンドボックス化されたエージェントや制限付きシェルでは、このプレイブックを実行しないでください。ユーザーのクライアントでサンドボックスとフルネットワークアクセスを選べる場合は、公開には非サンドボックスを選択するか、ネットワークを許可してください。手順 8 を正確に実行した後も 403 PUT が発生する場合は、同じスクリプトコマンドをユーザーのローカルマシンで実行するよう依頼してください（手順 8 を参照）。

エージェントのプレイブック（MCP ツール）

ツール名とパラメーターは Freshworks の openai-server に準拠しています（references/openai-server-mcp-tools.md）。ホスト型 MCP：https://mcp.freshworks.dev/mcp。

1. 認証トークンの事前確認（必ず最初のステップとして実施）

MCP ツールを呼び出す前に、MCP の公開ツールが利用可能で、認証済みであることを確認してください。

• list_custom_apps（必要に応じて {} または { "page": 1, "perPage": 10 }）の呼び出しを試してください。これは認証／接続のスモークテストとしてのみ扱ってください。この呼び出しだけで appId を選んではいけません。公開時（ステップ 6）に、新規か既存かをもう一度確認し、既存の場合は開発者に選択してもらうために list_custom_apps を呼び出します。
• 呼び出しが成功した場合は、認証が確認できています。ステップ 2 に進んでください。
• ツールを利用できない場合、または呼び出しで認証エラーが返された場合は、該当するケースを確認してください。

ケース A — MCP サーバーはすでに設定済みだが、トークンがない、または期限切れの場合：

MCP サーバーはセットアップ済みですが、API キーの更新が必要か、まだ設定されていません。

1. https://developers.freshworks.com/developer/ にアクセスします。
2. "API key for Freddy AI Copilot VS Code plugin & Freshworks Agentic Developer Toolkit" の下にある "View API Key" をクリックします。
3. "Connect to Freddy AI Copilot MCP server" の下にある IDE タブを選択し、Copy をクリックします。
4. IDE の MCP 設定でトークンを更新し、MCP 接続を再起動／再読み込みします。
5. 公開コマンドを再実行します。

ケース B — MCP サーバーがまだ設定されていない場合：

1. https://developers.freshworks.com/developer/ にアクセスします。

2. "Connect to Freddy AI Copilot MCP server" の下にある IDE タブ（Cursor または VS Code）を選択します。

3. Cursor： "Install in Cursor" を直接クリックするか、references/templates/cursor-mcp-setup.json を ~/.cursor/mcp.json にマージします（<your-api-key> を置き換え、Cursor を再起動します）。

   Claude Code（プラグイン経由）： freshworks プラグインのインストール時に API キーの入力を求められます。スキップした場合は、/config を実行してプラグイン設定を更新します。キーはシステムのキーチェーンに安全に保存されます。

   Claude Code（プラグインを使わないスタンドアロンのスキル）： claude mcp add --scope user を使って references/templates/claude-mcp-setup.json をプロジェクトの .mcp.json または ~/.claude.json に追加します（<your-api-key> を置き換え、Claude Code を再起動します）。

4. 公開コマンドを再実行します。

認証が確認されるまで、公開に関する手順を進めてはいけません。

2. アプリのディレクトリを特定する

fw-app-dev の /fdk-fix ステップ 1 と同じ手順を使用します。詳細は ../fw-app-dev/commands/fdk-fix.md（アプリのディレクトリを特定する）を参照してください。

1. ワークスペース内で manifest.json ファイルを検索します。
2. manifest.json を含むフォルダーが複数ある場合：どのアプリを公開するか、ユーザーに尋ねます。
3. 1 つのフォルダーの場合：そのディレクトリを使用します。
4. 該当するフォルダーがない場合：ユーザーに伝えて停止します。

2.5 公開前：API キーが正しい製品用であることを確認する

Developer API キーは製品ごとに異なります。設定済みの API キーが、このアプリを公開する製品に対応しているか、ユーザーに確認してください。ユーザーが確信を持てない場合は、停止してください。続行する前に、キーを確認または更新する必要があります。

3. Node.js と FDK のバージョンを確認する（パッケージ化の前）

• アプリディレクトリの manifest.json から engines.node と engines.fdk を読み取ります
• 有効なバージョンを確認します：node --version と fdk --version
• fdk が見つからない場合（fdk --version が失敗する／コマンドが見つからない）：停止します。確認を求めずに自動インストールしたり、「最新の FDK」を想定したりしないでください。fdk validate／fdk pack には Freshworks CLI が必要であることをユーザーに伝えます。fw-setup：/fw-setup-install（デフォルトは Node 24.11 上の FDK 10.x）を案内します。任意のワンショット： 「今すぐ /fw-setup-install を実行しますか？（y/n）」 — yes の場合のみ、skills/fw-setup/SKILL.md に従います。no の場合は、ユーザーが手動でインストールするまで終了します。fdk が利用可能になるまで、手順 4 に進まないでください（ユーザーがリスクを理解したうえで明示的に上書きする場合を除きます）。
• バージョンが一致しない場合（ただし fdk が存在する場合）：停止し、references/templates/engines-mismatch-prompt.txt を表示します（manifest のバージョンと現在のバージョンを差し替えます）。
• バージョンが一致するか、ユーザーが明示的に上書きしない限り、fdk pack を実行しないでください

4. fdk validate（公開前）

cd <app-directory> && fdk validate を実行し、その結果をアップロードの有効性ゲートとして扱います。

• アップロード／提出には必須です： プラットフォームエラーが 0 件、かつ lint エラーが 0 件（fw-app-dev と同じ基準）。いずれかが失敗した場合は停止し、メトリクスを記録して（下記の Validate failure metrics を参照）、fw-app-dev スキルを使って修正します。create_app_upload_url を呼び出さず、fdk pack を実行せず、zip をアップロードしないでください。
• fdk pack --skip-coverage --skip-lint（手順 5）でスキップされるのは、パッケージ化時のカバレッジ／lint 処理のみです。この手順が免除されるわけではありません。パックだけから「アプリは有効」と判断しないでください。

検証失敗メトリクス（手順 4 で停止する前）： 開発者に .meta.json について言及しないでください。

スクリプトのみ — JSON を手書きしないでください。 Write、Edit、StrReplace、またはシェルリダイレクトを使って <app-directory>/.meta.json を作成または変更しないでください。~/.fw-dev-tools/scripts/ にある meta-init.sh、meta-update.sh、meta-feedback.sh、meta-delete.sh のみを使用してください。skill_version は、このファイルの YAML フロントマターにある version: キーのセムバーのみを設定します（例：version: "1.1.5" → skill_version=1.1.5。引用符は付けません）。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-publish \
  invoked=1 skill_version=<version> publish_outcome=failed_validate

.meta.json はディスク上に保持してください。meta-delete.sh は実行しないでください。

meta-init.sh は環境変数から IDE クライアントを自動検出するため、手動で指定する必要はありません。

マーケットプレイスのバックエンド： 無効な zip でも受け入れられることがあります。API はパッケージを拒否せずに Draft バージョンを作成できます。submit_custom_app／add_app_version が成功しても、アプリをインストールできる証拠とはみなさないでください。手順 7 の前に、必ず fdk validate がエラーなしで完了するようにしてください。

4.5 必須 — 開発者エクスペリエンスに関するフィードバック（質問は必須、回答は任意）

fdk pack に進む前に、必ずこの質問をしてください。この手順を省略しないでください。

開発者に一度だけ質問します — references/templates/developer-feedback-rating-prompt.txt をそのまま表示します。

👍 または 👎 と回答した場合は、一度だけ追加で質問します — references/templates/developer-feedback-comment-prompt.txt をそのまま表示します。

その後、手順 5 に進む前に meta-feedback.sh を使ってフィードバックを記録します（JSON を手書きしないでください）。開発者がスキップした場合、または回答しなかった場合は、meta-feedback.sh を呼び出さず、"developer_feedback" キー全体を省略します。開発者に .meta.json について言及しないでください。

# Developer chose 👍 or 👎 and provided a comment:
bash ~/.fw-dev-tools/scripts/meta-feedback.sh <app-directory> liked "Setup was smooth, fw-review caught issues I missed"

# Developer chose 👍 or 👎 and skipped the follow-up comment:
bash ~/.fw-dev-tools/scripts/meta-feedback.sh <app-directory> disliked

# Developer chose Skip or did not answer — do NOT run meta-feedback.sh

.meta.json の結果の形式：

"developer_feedback": {
  "rating": "liked",
  "comment": "Setup was smooth, fw-review caught issues I missed"
}

• rating — "liked" または "disliked"
• comment — 自由記述。開発者がスキップした場合はキー全体を省略します

4.6 必須 — fdk pack の前に .meta.json のメトリクスを書き込む（省略禁止）

プラットフォームは、アップロードされたアプリの zip からスキルのメトリクスを取り込みます。 パッケージのビルド時に <app-directory>/.meta.json に fw-publish ブロックが含まれるよう、この手順は手順 4.5 の後、手順 5（fdk pack）の前に完了してください。開発者に .meta.json については決して言及しないでください。

スクリプトのみ — JSON を手書きしないでください。

meta-init.sh が IDE クライアントを自動検出するため、引数を手動で指定する必要はありません。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-publish \
  invoked=1 skill_version=<version>

publish_outcome は空（""）のままにしてください — アップロード／送信はまだ完了していません。手順 5 でビルドする zip に、このファイルを含めてプラットフォームに渡す必要があります。

5. fdk pack

アプリディレクトリから実行します（非対話型。パッケージ作成時のカバレッジ／lint をスキップするため、自動処理がカバレッジでブロックされません）。

cd <app-directory> && printf 'Y\n' | fdk pack --skip-coverage --skip-lint

dist/*.zip が生成されます。--force-pack が不要な場合に限り、既存の zip を再利用できます（エージェントが判断してください）。

無効なアプリ： 無効なビルドをパイプラインに通さないでください。手順 4 がプラットフォームエラーも lint エラーもゼロで合格しなかった場合は、停止してください — この公開フローでは fdk pack を実行せず、手順 6〜14 にも進まないでください。pack の --skip-coverage／--skip-lint は pack 内の追加作業を避けるだけであり、クリーンな validate の代わりにはなりません。

zip レイアウトのゲート（手順 7 の前に必須）： fdk pack の後、アップロードする zip を選択します（この pack で生成された dist/*.zip。複数ある場合は、更新日時が最も新しいものか、fdk pack が出力したパスを使用します）。次を実行します。

unzip -l 'dist/<app>.zip'

各ファイル行の最後の列である Name 列を確認します。

• 合格 — マニフェスト： zip のルートに、名前が正確に manifest.json であるアーカイブメンバーが少なくとも 1 つあること（サブフォルダー内だけでは不可）。
• 合格 — メトリクス： .meta.json が zip のルートに記載されていること（手順 4.6 で書き込まれます）。fdk pack がこれを含めなかった場合は、停止して、以下の修正手順に従って再パッケージしてください — .meta.json を明示的に含めてください。
• 不合格 — 停止。create_app_upload_url を呼び出さないでください： manifest.json がない、./manifest.json のみが表示される（先頭に ./ が付いている）、またはルートの manifest.json がなく、ネストされたパス（例：some-folder/manifest.json）にのみマニフェストがある場合。Marketplace のパイプラインは保存された正確なパス名と照合することが多く、これらのチェックでは ./manifest.json は manifest.json と同じものとして扱われません。

ゲートに失敗した場合 — 修正手順：

1. <app-directory> から、上記と同じように fdk pack を再度実行します。
2. 一覧が引き続きゲートに失敗する場合は、クリーンなディレクトリに展開し、明示的にトップレベルのメンバーを指定して再度 zip 化します（一般に ./ プレフィックスが記録される zip -r … . は避けてください）。例（展開後のツリーに合わせてフォルダー名を調整してください）：

rm -rf /tmp/fw-repack && mkdir -p /tmp/fw-repack && unzip -q -o 'dist/<app>.zip' -d /tmp/fw-repack
cp '<app-directory>/.meta.json' /tmp/fw-repack/.meta.json
cd /tmp/fw-repack && zip -r '<app-directory>/dist/<app>-resubmit.zip' manifest.json .meta.json app config server README.md

解凍後に存在するパスのみを記載してください（存在しない場合は server、README.md などを省略します）。<app-directory> に存在する場合は、必ず .meta.json を含めてください。アプリに必要なその他のトップレベルのファイルやディレクトリも追加します。両方のゲートに合格するまで unzip -l を再実行し、その zip を手順 8 でアップロードします。

5.5 カスタムアプリの上限に関する警告（必須 — 省略禁止）

先に進む前に references/templates/custom-app-limit-warning.txt をそのまま表示してください。 セルフチェック：上記の警告を回答に出力しましたか？ まだの場合は、手順 6 に進む前に今すぐ出力してください。

6. 公開時のルーティング：新規リスティングか既存アプリか（MCP の引き継ぎ）

公開時に、有効な zip があり、zip レイアウトのゲートを通過した後（手順 4～5）、create_app_upload_url（手順 7）の前に行ってください。ここで分岐し、アップロード後にどの MCP ツールへ uploadId を渡すかを決定します。

ルーティングや MCP 呼び出しに .fdk/app-info.json の appId を使用しないでください。

1. 停止してユーザーに確認してください。決めつけてはいけません：

   Is this a new Marketplace listing or an update to an existing app?
   1. New listing
   2. Update existing app
   

   ユーザーが回答するまで手順 7 に進まないでください。 現在のセッションでユーザーがすでに明示している場合に限り、この確認を省略できます。

2. 新規リスティング： まだ appId がありません。手順 7～9 の後、手順 10 で submit_custom_app を呼び出し、uploadId とマニフェストのメタデータを渡します。MCP の引き継ぎ： 新規アプリのペイロードと、署名付きの uploadId のみです。

3. 既存アプリ（更新）：

   a. list_custom_apps を呼び出します（必要に応じてページネーションします）。開発者に apps を表示します。最低限、id、name、type、products、latestVersion を表示し、更新対象のリスティングを選択してもらいます。選択された appId を記録します。

   b. 最新バージョンが停止していないか確認します： 選択された appId を指定して list_app_versions を呼び出します。確認するのは最新バージョン（updatedAt が最も新しいもの）のみです。

   • 最新バージョンの state: "development" の場合は、停止して references/templates/stuck-version-warning.txt を表示します（バージョンのフィールドを入力してください）。
   • 最新バージョンがそれ以外の状態であれば、手順 7 に進みます。

   c. MCP の引き継ぎ（バージョン確認に合格した後）： 手順 7～9 の後、手順 10 で、開発者が選択した appId、uploadId、マニフェストのフィールドを指定して add_app_version を呼び出します。

4. 更新を選択したものの、リストが空の場合、リスティングは存在しません。新規リスティングまたはキャンセルを提案します。

任意：アプリが 1 つだけで、すでに更新を選択している場合は、その行を表示し、appId を使用する前に一文で確認を求めます。それでも、.fdk/app-info.json の appId を決めつけて使用してはいけません。

6.5 サポートメール：MCP アップロードの一連の処理（手順 7）より前に必須

ゲート： 該当する公開手順でこのステップを完了するまで、create_app_upload_url（手順 7）や submit_custom_app を呼び出したり、署名付き zip のアップロードを開始したりしないでください。

supportEmail がない場合、PUT アップロード時に必ず失敗するわけではありません。uploadId が使用され、zip がすでにストレージにアップロードされた後、submit_custom_app（手順 10）の呼び出し時に失敗します。ユーザーはこれを「アプリのアップロード」や公開の失敗と表現することがよくあります。MCP の送信ペイロードを uploadId の発行前に完成させるため、supportEmail を早めに確認してください。

公開手順（手順 6）	要件
新規リスティング	submit_custom_app には supportEmail が必須です。手順 7 の前に、Marketplace のサポート用として有効で、メールを確認できるアドレスをユーザーにはっきり確認してください。git config user.email から推測しないでください（設定されていない、個人用、または誤ったアドレスの可能性があります）。マニフェストやドキュメントに連絡先が記載されている場合は、ユーザーに確認してください。確認済みの値を手順 10 で使用できるように保存します。ユーザーが supportEmail を提示できない場合は、停止してください。create_app_upload_url に進んではいけません。
既存アプリ（更新）	add_app_version で使用するのは appId、platformVersion、modules、uploadId です。通常、add_app_version のペイロードに supportEmail は含まれません。製品や API のルールが変更されない限り、この手順ではメールアドレスの確認は必須ではありません。

7. アプリのアップロード URL を作成する

前提条件： 新規リスティングの場合は、手順 6.5 を満たしていること（この呼び出しの前に supportEmail が確認済みであること）。

create_app_upload_url を呼び出します。uploadId、uploadUrl、expiresInSeconds が返されます。

• 手順 10（submit_custom_app／add_app_version）で使うため、uploadId を保持します。
• 直ちに、返された JSON レスポンス全体を一時ファイルに書き込みます。使用できるのは echo … > file または cat > file のみです。処理や再出力に jq、Python、Node、その他のツールを使用しないでください。

  echo ‘<full-json-response>’ > /tmp/fw-upload-response.json
  

  uploadUrl を自分で抽出しないでください。アップロードスクリプトが内部で jq を使って読み取ります。レスポンスは不透明なデータとして扱い、ファイルパスをそのままスクリプトに渡してください。

✅ ゲート — 手順 8 に進む前に、次の点を確認してください：

Response file written using only echo or cat (not jq / Python / Node)? [yes/no]

答えが「はい」でない限り、手順 8 に進まないでください。

8. アプリをアップロードする（zip バイナリを PUT）

手順 7 のレスポンスファイルを使い、同梱のアップロードスクリプトを実行します。スクリプトが内部で jq を使って uploadUrl を抽出するため、LLM が URL を扱うことはありません。有効な URL であっても、管理対象／クラウドの実行環境では 403 が発生しやすいため、Python（urllib.request、requests、…）、Node（fetch／node -e）、その他の HTTP クライアントに置き換えないでください。

0. 手順 5 の zip レイアウトゲートに合格したものと同じ dist/*.zip ファイルを使います。そこで再ビルドした場合は …-resubmit.zip も含みます。
1. 手順 7 のレスポンスファイルを渡します。内容を読み取ったり、解析したり、エコーしたりしないでください。
2. ユーザーのマシン上で実行してください（ローカルの Terminal／ネットワーク制限のない IDE ターミナルを使用し、制限されたリモートワーカーは避けてください）。
3. スクリプトは自動的に最大 3 回再試行します。最終的に失敗した場合は、改めて create_app_upload_url を呼び出して新しいレスポンスを取得し、スクリプトを再実行してください。

bash <skill-root>/scripts/upload-app.sh dist/<app>.zip /tmp/fw-upload-response.json

• <skill-root> — fw-publish スキルがインストールされているディレクトリ（例：リポジトリ内の skills/fw-publish）
• /tmp/fw-upload-response.json — 手順 7 で書き込んだレスポンスファイル。スクリプトは jq を使って uploadUrl を抽出します。
• スクリプトは Content-Type: application/zip を送信し、成功すると Upload successful (HTTP 200) と出力します。

自動実行／サンドボックス： 制限されたサンドボックスではアップロード時に 403 やネットワークエラーが発生しやすいため、この手順ではサンドボックスを使わず、ネットワーク制限のない環境を使用してください（冒頭の Sandbox を参照）。

zip を base64 エンコードしないでください。

9. manifest.json を読み取り、AI Actions アプリかどうかを判定する

アプリのディレクトリにある manifest.json を読み取ります。次の項目を抽出します。

• platform-version（例："3.0"）
• modules のキー（例：["common", "support_ticket"]）
• appName に使う name（存在する場合）

AI Actions の判定： アプリのディレクトリに actions.json が存在するか確認します。

• 見つかった場合は、処理を停止してユーザーに尋ねます。推測しないでください：

  Detected actions.json — this looks like an AI Actions app.
  Should I include worksWith: ["ai_actions"] when publishing? (yes/no)
  

ユーザーが回答するまで、手順 10 に進まないでください。

• ユーザーが「はい」と確認した場合は、手順 10 で worksWith: ["ai_actions"] を設定します。
• 「いいえ」の場合、または actions.json が存在しない場合は、worksWith を省略します。

ダウングレードの警告（既存アプリの更新の場合のみ）： 既存アプリを更新する場合に actions.json が存在しない（またはユーザーが worksWith に対していいえと回答した）場合は、続行する前に references/templates/downgrade-warning.txt の内容をそのまま表示します。 ユーザーが確認するまで、手順 10 に進まないでください。

10. 適切な MCP ツールを呼び出す（デプロイ／バージョン引き継ぎ）

手順 6 の公開時の選択を使用します。新規 → submit_custom_app、既存 → 開発者が選択した appId を指定して add_app_version を呼び出します。

新規アプリ — submit_custom_app：

パラメーター	ソース
appName	マニフェストの name またはディレクトリ名
appDescription	ユーザーに確認するか、デフォルトを使用
appOverview	ユーザーに確認するか、説明から作成（最大 150 文字）
supportEmail	新規アプリでは必須 — 手順 6.5 で、create_app_upload_url を呼び出す前に必ず収集してください。git config user.email やその他の Git メタデータは絶対に使用しないでください。未設定、個人用、またはマーケットプレイスのサポート用として誤っている可能性があります。
alternateEmail	任意
platformVersion	マニフェストの platform-version
modules	マニフェストの modules キー（openai-server ツールのスキーマを参照してください。少なくとも 1 つの common 以外のモジュールが必要な場合があります）
uploadId	手順 7 の値
targetState	"test"（サポートされている状態はこれだけです。ユーザーに確認しないでください）
zipFileName	任意（例：my-app.zip）
worksWith	手順 9 の AI Actions 検出結果。確認できた場合は ["ai_actions"]、それ以外の場合は省略

既存アプリ — add_app_version（MCP で利用可能な場合）：

パラメーター	ソース
appId	手順 6 の list_custom_apps から取得した、開発者が選択した appId。.fdk/app-info.json の値ではありません
platformVersion	マニフェストの platform-version
modules	マニフェストの modules キー
uploadId	手順 7 の値
targetState	"test"（サポートされている状態はこれだけです。ユーザーに確認しないでください）
zipFileName	任意
worksWith	手順 9 の AI Actions 検出結果。確認できた場合は ["ai_actions"]、それ以外の場合は省略

11. アプリ ID を保存する（任意、ローカルのみ）

応答から取得した id と version をローカル記録として、アプリディレクトリ内の .fdk/app-info.json に書き込むか、更新してもかまいません。ただし、次回の公開でも手順 6 に従います。更新時は list_custom_apps を呼び出し、開発者に選択してもらいます。このファイルを根拠に一覧表示を省略したり、appId を決定したりしないでください。

12. 状態を確認する

送信／更新で返された appId（または選択した一覧の ID）を指定して get_app_status を呼び出し、アプリレベルの状態を確認します。

任意で、appId を指定して list_app_versions を呼び出し、新しいバージョンが test 状態になったことを確認し、バージョンごとの内訳を確認できます。これにより、デプロイの成功を確認し、新しいバージョンが development で止まっていないかを検出できます（その場合、デプロイに失敗しています。ユーザーは Developer Portal で失敗の詳細を確認してください）。

13. 公開後のローカルクリーンアップ（成功時は必ず実施してください。手順 14 の前に完了すること）

成功時の処理では、ユーザーに何かを伝える前に必ずこの手順を完了してください。手順 13 を完了せずに手順 14 の報告を出してはいけません。開発者に .meta.json について言及しないでください。

公開成功（手順 12 で test 状態を確認）：

bash ~/.fw-dev-tools/scripts/meta-delete.sh <app-directory>

メトリクスは手順 5 で zip にすでに含められています（手順 4.6 で書き込み済みです）。ここで publish_outcome=success を指定して meta-update.sh を呼び出さないでください。プラットフォームはアップロード後のメトリクス更新を受け付けません。

手順 5 の後に失敗（アップロードまたは送信）— 診断用にローカルの .meta.json のみ更新します（アップロード済みの zip では publish_outcome が空のままです）。

bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-publish publish_outcome=failed_upload
# or: publish_outcome=failed_submit

meta-delete.sh を呼び出さないでください。.meta.json はそのまま残してください。

publish_outcome の参照：

値	書き込み時点	アップロードされた zip 内か
failed_validate	手順 4 の STOP（パッケージ化前）	いいえ — zip は作成されていません
""（空）	手順 4.6（パッケージ化前）	はい — 通常の公開手順
failed_upload	手順 8 の失敗後、手順 13	ローカルのみ（zip はすでにアップロード済み）
failed_submit	手順 10 の失敗後、手順 13	ローカルのみ（zip はすでにアップロード済み）

14. ユーザーに報告する

ユーザーに、アプリ ID、バージョンの状態、および製品内でカスタムアプリをインストールする場所（Admin -> Apps または同等の場所）を伝えます。

MCP ツールリファレンス（fw-dev-mcp）

サポートされるアプリの状態： test 状態のみがサポートされます。targetState には必ず "test" を使用してください。ユーザーに状態を選ばせないでください。

ツール	目的	使用するタイミング
list_custom_apps	開発者アカウントにあるすべてのカスタムアプリを一覧表示します。count と apps（各アプリの id、name、type、subType、subscriptionType、state、products、latestVersion）を返します。省略可能な引数は page、perPage です。結果は最終更新日時の新しい順に並びます。	ステップ 1（認証の事前確認）、ステップ 6.3a（既存アプリの選択）
list_app_versions	1 つのアプリの全バージョンを一覧表示します。各バージョンの id、version、platformVersion、state、updatedAt を含む配列を返します。	ステップ 6.3b（add_app_version の前に development 状態の最新バージョンを確認）、ステップ 12（任意の検証）
create_app_upload_url	署名付き S3 アップロード URL を生成します。uploadId、uploadUrl、httpMethod（"PUT"）、expiresInSeconds を返します。	ステップ 7（zip のアップロード前）
submit_custom_app	新しいカスタムアプリと最初のバージョンを作成します。appName、appDescription、appOverview、supportEmail、platformVersion、modules、uploadId が必要です。create_app_upload_url の前に（ステップ 6.5）、supportEmail を収集してください。省略可能な引数：alternateEmail、zipFileName、worksWith（例：["ai_actions"]）。送信に成功すると、アプリは test 状態に移行します。	ステップ 10（新規アプリのフロー）
add_app_version	既存のアプリに新しいバージョンを追加します。appId（list_custom_apps とユーザーの選択から取得）、platformVersion、modules、uploadId が必要です。省略可能な引数：zipFileName、worksWith。最新バージョンが development 状態の場合は続行できません（事前に list_app_versions で確認してください。ユーザーは Developer Portal から停止中のバージョンを削除する必要があります）。	ステップ 10（既存アプリのフロー。バージョン状態の確認を通過した後）
get_app_status	アプリ全体のステータスを取得します。id、name、type、subType、subscriptionType、state（すべてのバージョンの状態を反映）、products を返します。デプロイに失敗すると、state はしばしば development に戻るか、その状態を含みます。	ステップ 12（公開後の検証）

fw-dev-mcp サーバーのその他のツール：

• get_developer_docs：開発者向けドキュメントを取得します。プラットフォームに関する質問では、最優先のドキュメントソースとして最初に使用してください。MCP を利用できない場合は、ハードコードされたスキルの参照情報を使用してください。アプリ構築作業（実装、検証、レビュー）には、引き続き fw-app-dev を使用します。
• 非推奨のビルドツール： implement_app、get_implementation_plan、idea_to_app、fix_app_errors — サーバーは非推奨を示す契約を返します。そのリダイレクト先である fw-app-dev に従ってください。references/deprecated-mcp-build-tools.md を参照してください。

エラー処理

• いずれかの MCP ツールから 401/403 が返された場合： 直ちに停止し、手順 1 の認証設定手順を表示してください。トークンの期限切れ、設定ミス、または未設定の可能性があります。再試行せず、トークンを修正して再実行するようユーザーに促してください。
• 検証エラー（400）： マニフェストの修正を提案するか、fw-app-dev スキルを使用してください。よくある原因：products と modules の不一致。
• 3 回再試行してもアップロードに失敗する場合（手順 8 のスクリプト）： アップロードスクリプトを再度実行しないでください。ユーザーに以下を確認するよう依頼してください。（1）ローカルマシン（サンドボックス化／制限された環境ではない）で実行していること、（2）S3 へのネットワークアクセスがブロックされていないこと（プロキシや IAM ポリシーがないこと）。両方を確認できた場合は、手順 7 から再開し、create_app_upload_url を呼び出して新しいレスポンスファイルを取得し、アップロードスクリプトを再実行してください。再び失敗した場合は停止してください。継続的な失敗は、環境またはインフラストラクチャの問題を示しています。
• fdk validate / fdk pack の失敗： fw-app-dev スキルを使用して修正し、Node/FDK のバージョンが一致しているか確認してください。validate が通らなかった場合（手順 4）は、アップロードしないでください。不正な zip からでも下書きのリスティングを作成できてしまいます。
• アップロード後または送信後のマニフェスト／パッケージレイアウトのエラー： 「Zip レイアウトゲート」（手順 5 の最後）を再実行してください。ルートの manifest.json がない状態で ./manifest.json が見つかった場合は、create_app_upload_url の前に、手順 5 の修正方法に従って再パッケージしてください。

前提条件

要件	備考
アップロードホスト	スクリプトから署名付きバケットの S3 にアクセスできる必要があります。クラウド環境／制限された環境では常に 403 が返される可能性があります。ローカル端末または制限のないネットワークを使用してください（手順 8）。
サンドボックス外での実行	MCP とスクリプトによるアップロードには、外向きの HTTPS 接続が必要です。サンドボックス化されたエージェント／シェルでは通常、公開が失敗します。このフローでは、フルネットワークを使用するか、サンドボックスを無効にしてください。
manifest.json	アプリのルートに配置し、modules を含む Platform 3.0 である必要があります。
Zip のメンバー名	fdk pack の実行後、アップロード zip のアーカイブのルートに manifest.json が含まれている必要があります（./manifest.json のみでは不可）。手順 5 の最後にある Zip レイアウトゲートを参照してください。
fdk が PATH 上にあること	fdk validate と fdk pack。
MCP ツールの設定	Claude Code：マーケットプレイスプラグインがインストールされている場合、ルートの .mcp.json を使用します（インストール時に userConfig で入力を求められます）。Cursor：そのファイルのサーバーブロックを ~/.cursor/mcp.json に統合します。
サポート用メールアドレス	create（新規アプリ）では必須です。ユーザーに確認してください。git config から取得してはいけません。更新時は既存のマーケットプレイスアプリの公開者メタデータを再利用します。
更新時のアプリ識別情報	公開時（手順 6）：開発者は update を選択した後、list_custom_apps から appId を選択します。ルーティングに .fdk/app-info.json を使用しないでください。

オプション：アプリの一覧表示

更新の場合、公開時（開発者が create_app_upload_url の前に appId を選択する）に list_custom_apps が手順 6の一部として実行されます。公開せずにアカウント上のアプリを確認するため、いつでも呼び出すこともできます。この閲覧目的の呼び出しは、公開時の選択および add_app_version への appId の引き渡しとは別です。

リンク

• references/openai-server-mcp-tools.md — mp-openai の openai-server に実装されている MCP ツール

• Developer Portal / MCP — developers.freshworks.com/developer/ から取得する API キー。Freddy AI Copilot for VS Code プラグインおよび Agentic Developer Toolkit 用の API キーです。または Developer MCP サーバーに接続してください（MCP の設定用）。