MCP ツール

MCP ツールリファレンス

すべての Showly MCP ツール — スコープ、パラメーター、戻り値の形状、監査動作。

Showly MCP サーバーが公開するすべてのツール。各エントリには、必要なスコープ、短い形式の入力スキーマ、戻り値の形式、および監査ログに書き込まれる内容がリストされます。

すべてのツールには認証された MCP クライアントが必要です。トークンは ワークスペース設定 → MCP クライアント から発行されます。

呼び出しがブロックされたとき

Showly が返す失敗はすべて同じエンベロープです。ツール自身が判定したものも、ツールを実行する前に MCP レイヤーが判定したもの（トークンに無いスコープ、大きすぎる引数や結果）も同じ形です。ok は false、error は分岐に使える string のコードで、オブジェクトになることはありません。MCP レイヤーによる拒否は MCP の isError フラグも立てるため、そのフラグで分岐しているクライアントには従来どおり失敗として見えます。フラグとともに返るテキストは同じ JSON です。

このエンベロープにならない失敗が 3 つあります。いずれも Showly のコードが動く前に MCP SDK が応答するもので、isError: true とプレーンテキストのメッセージで返ります。

  • 引数の欠落、または型の誤り — MCP error -32602: Input validation error: Invalid arguments for tool <name>: …。連携側がもっとも多く起こす失敗なので、パースは防御的に行ってください。
  • このサーバーが公開していないツール名 — MCP error -32602: Tool <name> not found。
  • 想定外のクラッシュ — トランスポート障害や不具合。

ツールが宣言していない引数はこの一覧に含まれず、そもそも失敗になりません。SDK が呼び出し前に未知のキーを取り除くため、ツールは宣言した引数だけを受け取ります。

解析できない本文はコードを推測せず、不明なエラーとして扱ってください。

{
  ok: false,
  error: "insufficient_credits",
  message: "A production deployment costs 5 credits and this workspace has 2 left.",
  status?: 402,

  resolvedBy: "agent" | "human",
  actionUrl?: "https://showly.ai/app/billing#upgrade",
  humanAction?: "Open Plan & Billing and add credits, then tell the agent to retry.",
  agentNext: {
    kind: "retry" | "retry_with" | "call_tool" | "poll" | "wait_for_human" | "stop",
    tool?: "publish_site",
    afterSeconds?: 10,
    note: "After the balance changes, start the publish over from step 1."
  }
}

まず resolvedBy を読みます。"agent" は、いま持っているツールだけで解決できることを意味します — 別の previewSlug を選ぶ、足りなかった id を取得する、agentNext.tool が指すツールを呼ぶ、など。"human" は、どうツールを呼んでも解決しないことを意味します。humanAction と actionUrl をユーザーに伝えたうえで agentNext に従ってください。

actionUrl は絶対 URL で、Showly ウェブアプリのページを指します。管理者専用の領域を指すことはありません。actionUrl がある場合はリンクとして伝え、humanAction は毎回伝えてください。そのリンクを誰が使えるのかを決めるのはこの一文です。重要なのはプランと請求のページで、ワークスペースのオーナー、管理者、請求ロールに限定され、決済にはさらに billing:write が必要です。一般のメンバーがリンクを開いてもダッシュボードへ戻されます。どちらの立場の人が読んでいるかを Showly は判定できません。ページが見るのは本人のウェブセッションであり、MCP トークンが表すのはエージェントだからです。したがってリンクは常に返し、条件は humanAction が伝えます。オーナーはそのまま操作でき、それ以外の人は転送してください。プランやクレジットの失敗に付く従来の webUpgradeUrl も、同じ URL で条件も同じです。

人の対応が必要な唯一の成功レスポンスにも同じ 4 つのフィールドが付きます。request_publish は resolvedBy、actionUrl、humanAction、agentNext を、失敗レスポンスとまったく同じトップレベルに返すため、if (result.actionUrl) はどちらでも機能します。これらは data の中にも従来の webApprovalUrl と並べて重複して入るので、data.actionUrl を読む既存の連携もそのまま動きます。

既存の連携を壊さないため、従来の 2 つのフィールドも actionUrl と同じ値のまま残ります。email_verification_required の webVerificationUrl と、成功した request_publish の webApprovalUrl です。

list_projects

範囲: project:read

トークンが参照できるプロジェクト (ワークスペース) をリストします。

Input:  {}
Output: { ok, data: Array<{ id, name, slug, createdAt }> }
Audit:  mcp.list_projects

list_sites

範囲: site:read

現在のワークスペース内のサイトを一覧表示します。 projectId を渡してリストの範囲を指定します。プロジェクト スコープの MCP トークンは、パラメーターに関係なくこのフィルターを強制します。

Input:  { projectId?: string }
Output: { ok, data: Array<Site>, view: ListSitesView }
Audit:  mcp.list_sites

2 つのテキスト ブロックを返すのはこのツールだけです。1 つ目はサーバー側で組み立てた要約で、サイト名、公開済みかどうか、推奨される次の操作を 1 つ含みます。そのため呼び出しごとに表記が変わりません。2 つ目は上記の JSON エンベロープで、内容は従来どおりです。content[0] ではなく content[content.length - 1] から読み取ってください。同じエンベロープは structuredContent としても返され、view は要約と後述の対話的表示が共有する射影です。

クライアントが initialize のケーパビリティで MCP Apps 拡張 io.modelcontextprotocol/ui を宣言した場合、このツールには _meta.ui.resourceUri も付きます。これはホストがサンドボックス iframe で描画する ui:// HTML リソースを指します。宣言しないクライアントにこのメタデータは渡らず、結果の他の部分も変わりません。

get_site_context

範囲: site:read

サイト、検出されたフレームワーク、ルート、参照された環境変数名、最新のプレビュー URL、および指定した siteId の最新本番デプロイ ID を返します。Site の構造は[共通型](#common-types)を参照してください。

Input:  { siteId }
Output: { ok, data: { site, framework, routes, envReferences, latestPreviewUrl, lastProductionDeploymentId } }
Audit:  mcp.get_site_context  (records siteId)

create_change_plan

範囲: site:read

変更計画の提案を作成します。ファイルを変更しません_。通常、エージェントは返された計画を読み、ユーザーに確認を求めてから、apply_site_patch に電話します。

Input:  { siteId, request: string }
Output: { ok, data: { siteId, request, plan, nextStep } }
Audit:  mcp.create_change_plan

apply_site_patch

範囲: site:write

サイトのファイル編集をステージングします。ステージングされた変更セットは一時的なものであり、create_preview までに具体化する必要があります。

Input:  { siteId, files: Array<{ path, content }>, message: string }
Output: { ok, data: { changesetId, siteId, fileCount, ttlSeconds, nextStep } }
Audit:  mcp.apply_site_patch  (records siteId + changesetId + file count)

create_preview

範囲: preview:create

パッチ適用されたワークスペースを構築し、プレビュー URL を生成します。ユーザーが所有するのは、 プライベートアクセスの決定: サーバー生成の短い XXX-XXX の場合は access を省略します。 パスワード、6 ～ 128 文字のカスタム パスワードを渡すか、organization を選択します (Pro+) または organization_or_password。生成された平文は一旦返却され、 後で取り出すことはできません。プレビューを公開することはできません。ライブ配信時に公開する 誰にでも見えるはずです。previewSlug を指定すると、別の 1 階層アドレス <previewSlug>.showly.site を選択できます。

Input:  { changesetId?, siteId?, files?, previewSlug?, access?: { mode, password? } }
Output: { deploymentId, previewUrl, framework?, fileCount?, access: { mode, passwordConfigured, password? } }
Audit:  mcp.create_preview

create_github_preview

範囲: preview:create

サイトに接続されている GitHub 上の最新のコミットからプライベート プレビューを構築します 枝。インストール資格情報は Showly 内に残ります。 access を省略すると、 サーバー生成の短い XXX-XXX パスワードが 1 回返され、カスタム 6 ～ 128 を渡します 文字パスワードを使用するか、Pro+ で組織メンバーのアクセスを選択します。このツール Liveは決して公開しません。返されたもので get_preview_status を投票します deploymentId。

サイトにアクティブな GitHub アプリ リポジトリがない場合は、まず Showly Web に接続します。 リポジトリの自動ビルドは現在、静的なデプロイメント ターゲットをサポートしています。ダイナミックな コンテナターゲットは何よりも前に repository_build_target_unsupported を返します 列に並んでいます。 未検証の Showly メールは、Web URL を含む email_verification_required を返します 検証を完了します。

set_preview_access

範囲: preview:create

URL を変更せずに、既存の Preview または公開済み Live デプロイのアクセス ポリシーを変更します。 公開サイトを保護するには、list_deployments が返す ready 状態の production ID を使います。 既存クライアントとの互換性のため、ツール名は従来のままです。パスワード モードではパスワードがローテーションされます。6 ～ 128 文字の値を渡すか省略します password はサーバー側で短い XXX-XXX 共有コードを生成します。応答 新しい平文パスワードを previewUrl と並べて 1 回表示します。あらゆる政策 変更すると、以前に発行されたプレビュー アクセス Cookie が無効になります。

組織モードは、訪問者のアクティブな Showly 組織メンバーシップを確認します。 そのため、チームメイトはパスワードを共有する代わりにサインインします。 organization_or_password 内部フローを維持しながら、外部レビュー担当者がパスワードを使用できるようにします。

Input:  { deploymentId, access: { mode: "password" | "organization" | "organization_or_password", password? } }
Output: { deploymentId, target, previewUrl, access: { mode, passwordConfigured, password? }, policyVersion, advancedDeploymentControls }
Audit:  mcp.set_preview_access

カスタム パスワードのローテーションの例:

{
  "deploymentId": "00000000-0000-4000-8000-000000000000",
  "access": { "mode": "password", "password": "ABC-123" }
}

retry_deployment

範囲: preview:create

失敗したまたはキャンセルされたプレビュー展開を再構築します。 create_preview に指定したものと同じ files を再供給します。ソースはサーバー側で保持されないため、files は 必須です。 status: "building" で 新しい deploymentId (失敗したものは履歴として残ります) を作成し、ポーリングのために返します。各再試行は 毎月のデプロイ クォータにカウントされます。これは新しいビルドです。デプロイメントがまだ構築中またはすでに準備ができている場合は 409 not_retryable を返し、トークンに表示されない場合は 404 を返し、クォータを超えている場合は 402 を返します。

Input:  { deploymentId, files: [{ path, content }] }
Output: { ok, data: { deploymentId, status: "building", pollUrl, retriedFrom } }
Audit:  mcp.retry_deployment

run_checks

範囲: checks:run

ワークスペースのチェック マトリックス (lint、タイプ、カスタム CI フック) をプレビューに対して実行します。 checks は { id, status } 行 (lint / typecheck / build / audit-gate) のリストです。 summary は、"3 passed / 1 pending" などの 1 行の文字列です。

Input:  { deploymentId }
Output: { ok, data: { deploymentId, checks: [{ id, status }], summary } }
Audit:  mcp.run_checks

request_publish

範囲: publish:request

準備ができたプレビュー展開の承認リクエストを開きます。応答には以下が含まれます webApprovalUrl ディープリンク;ユーザーが正確な内容を確認できるようにリンクを表示します。 プランに必要な 2 人目の承認をプレビューして完了します。出版は行う OTP/MFA 登録は必要ありません。 MCP トークンにバインドされているユーザーは、 Showly アカウントのメールアドレスを確認しました。ツールが戻ってきた場合 email_verification_required、ユーザーを webVerificationUrl に送信して再送信します 再試行する前に検証を完了してください。

Input:  { deploymentId, message: string }
Output: { approvalId, deploymentId, state: "pending", expiresAt, reused, webApprovalUrl }
Audit:  mcp.request_publish

publish_site

範囲: publish:confirm

承認ワークフローを必要としないソロ ワークスペースおよび計画向けに、会話から直接、運用環境へのすぐに使えるプレビュー デプロイメントを公開します。 MCP トークンにバインドされているユーザーは、検証済みの Showly アカウント電子メールを持っている必要があります。ツールが email_verification_required を返した場合は、ユーザーを webVerificationUrl に送り、検証が完了するまで待ってから、2 段階のフローを再開します。サイトはまだ公開されていません。 2 ステップ 人間による確認済み: siteId + deploymentId (confirmationToken は不可) を使用して呼び出し、概要 + 短期間の confirmationToken を取得します。これからライブになる内容をユーザーに示してから、トークンを使用して再度呼び出します。ステップ 2 は 202 publishing を返します。承認ワークフローが有効になっているプラ​​ンでは、代わりに request_publish を使用してください。このツールがそこに誘導します。

Step 1: { siteId, deploymentId }                        → { confirmationToken, summary }
Step 2: { siteId, deploymentId, confirmationToken }      → { siteId, deploymentId, status: "publishing" }
Audit:  mcp.publish_site

MCP Apps を描画するホストでは、ステップ 1 の往復を省略できます。Preview が完成したカードには Publish live ボタンがあり、クリックするとユーザーの確認がメッセージとして会話に送られます。そのメッセージを確認と見なし、事前チェックとトークン付きの発行を続けて実行し、結果を一度だけ返してください。それ以外は変わりません。同じ 2 回の呼び出し、同じサーバー発行のトークン、同じ阻害要因、そして通常の本番デプロイと同じクレジット消費です。

get_preview_status

範囲: preview:read

プレビュー展開の現在のステータスを返します。オプションで、ステータスが既知の値から移行するまでロングポーリング (デフォルトは 30 秒、最大 60 秒)。request_publish 以降のレビュー担当者の待機中に役立ちます。 status が failed または canceled の場合、結果には errorCode、errorMessage、stage、およびビルドが失敗した 理由 を説明する短い logTail も含ま​​れます。 retry_deployment とペアにして再構築します。

Input:  { deploymentId, waitForChange?: boolean, currentStatus?: string, timeoutMs?: number }
Output: { ok, data: Deployment & { productionUrl?, errorCode?, errorMessage?, stage?, logTail? }, changed?, timedOut? }
Audit:  mcp.get_preview_status

get_deployment_logs

範囲: logs:read

デプロイメントのビルド ログの末尾 (キャプチャされたビルド出力の最後の lineCount 行、デフォルトは 200) を返します。 source は、db (実際のログ行)、pending (デプロイメントは存在するがログがまだキャプチャされていない - まだ構築中か末尾がない)、または not-found (このトークンにはそのようなデプロイメントが存在しない) を識別します。

Input:  { deploymentId, lineCount?: number }
Output: { ok, data: { deploymentId, lineCount, source, lines } }
Audit:  mcp.get_deployment_logs

diagnose_deployment

範囲: logs:read

独自の展開の 1 つを自己診断します。単一の構造化された AI 利用可能な 診断バンドルを返すため、エージェントは個別の get_preview_status / get_deployment_logs 読み取りをつなぎ合わせるのではなく、1 回の呼び出しでビルドが失敗した 理由 を推論し、ソースと retry_deployment を修正できます。バンドルには次のものが集約されます: ビルド 失敗 (stage、errorCode、errorMessage、logTail)、Sentry からの関連ランタイム エラー (コミット SHA + 環境 + デプロイ前後のウィンドウ、フェールソフトによって相関)、デプロイの ops-job ステータス、組織の クォータ ステータス、エージェントによってプッシュされたすべてclientLogs (編集 + 上限付き)、および決定論的 hypotheses - 高品質の開始点として (AI ではなく) ルールによって導出される、信頼性の高い根本原因 (例: quota_exceeded / build_install_failed)。

テナント分離: 診断できるのは、独自の組織内のデプロイのみです。トークンに表示されないデプロイメント ID は 404 を返します (存在しない ID と区別できません - 組織間の存在リークはありません)。これは、スタッフ診断センター バンドルのエージェント側のツインです。どちらも 1 つのバックエンド アグリゲータを共有します。 GET /deployments/:deploymentId/diagnostics に電話します。

Input:  { deploymentId }
Output: { ok, data: { deployment, failure, jobRun, quota, sentry, clientLogs, hypotheses } }
Audit:  mcp.diagnose_deployment

list_templates

範囲: template:read

現在のトークンで利用可能な Showly サイト テンプレートをリストします。 create_site_from_template と組み合わせて、Git リポジトリなしで新しいサイトをオンボードします。

Input:  { framework?: string }
Output: { ok, data: Array<{ slug, displayName, description, framework, screenshots }> }
Audit:  mcp.list_templates

create_site_from_template

範囲: template:create、site:write

新しい Showly が管理するサイトをテンプレートから実体化し、最初のサイトを構築します プライベートプレビュー。省略された access は返されるサーバー所有のパスワードを生成します initialPreviewUrl でちょうど 1 回;編成モードには Pro が必要です。siteSlug は最初のプレビューと Live の両方で使う安定した <siteSlug>.showly.site アドレスです。

Input:  { projectId, templateSlug, name, siteSlug, variables?: Record<string, unknown>, access?: { mode, password? } }
Output: { ok, data: { siteId, projectId, initialVersionId, initialPreviewDeploymentId, initialPreviewUrl, access, templateSlug, createdAt } }
Audit:  mcp.create_site_from_template

create_site_from_html

範囲: site:write、preview:create

テンプレート、フレームワーク、Git リポジトリを使用せず、プレーンな HTML/CSS/JS ファイルから新しい Showly 管理のサイトを直接作成します。ファイルをインラインで (index.html 必須、バイナリ アセットの場合は encoding: "base64")、または request_upload_url 経由でアウトオブバンドでアップロードした大規模なソースの場合は sourceBundleId (正確には files / sourceBundleId の 1 つ) を渡します。サイトが作成され、最初のプレビューが 1 回の呼び出しで構築されます。返された deploymentId を get_preview_status でポーリングします。siteSlug はプレビュー/Live で共有する <siteSlug>.showly.site アドレスになります。制作は公開フローのままです。

Input:  { projectId, name, siteSlug, files?: Array<{ path, content, encoding?: "utf8" | "base64" }>, sourceBundleId?, framework?, access?: { mode, password? } }
Output: { ok, data: { siteId, deploymentId, status | previewUrl, access, ... } }
Audit:  mcp.create_site_from_html

request_upload_url

範囲: site:write、preview:create

モデル経由で渡すのに適さない 大きな サイトソース向けに、短時間だけ有効な使い捨てアップロード URL を発行します。Content-Type: application/x-tar を指定して tar アーカイブを返された uploadUrl に PUT し、files の代わりに返された sourceBundleId を使って create_site_from_html を呼び出します。

Input:  {}
Output: { ok, data: { uploadUrl, sourceBundleId, contentType, expiresInSeconds } }
Audit:  mcp.request_upload_url

request_download_url

範囲: site:read

request_upload_url に対応する読み取りツールです。アクセスできる deploymentId を渡すと、保持されたソースアーカイブ用の短時間だけ有効な使い捨て downloadUrl が返ります。アーカイブをローカルで編集し、request_upload_url で新しいソースをアップロードして、その sourceBundleId を create_preview に渡します。ソースアーカイブがない場合は source_not_retained (422) を返します。小さなサイトには get_site_files を使用してください。

Input:  { deploymentId }
Output: { ok, data: { downloadUrl, expiresInSeconds } }
Audit:  mcp.request_download_url

claim_trial_site

範囲: site:write

Showly の公開試用フローで作成したサイトを 現在の認証済みアカウント に取り込み、有効期限のない永続サイトにします。サーバーが提供した trialId + guestToken を渡します。試用期限が切れている場合、またはワークスペースに有効なサイト数の明示的な制限がある場合は失敗します。不要なサイトを削除するか Showly サポートに連絡してから再試行してください。Free と Pro は既定でプレビュー数と公開サイト数が無制限で、プラン変更によってサイト枠は増えません。

Input:  { trialId: string, guestToken: string }
Output: { ok, data: { trialId, siteId, claimed: true } }
Audit:  mcp.claim_trial_site

delete_preview

範囲: preview:create

ID を使用してプレビュー展開を論理的に削除します。 deletedAt を返します。 冪等 — すでに削除されたプレビューを削除すると、404 preview_not_found が返されます。ここではプレビューのみを削除できます。生産には影響ありません。

Input:  { deploymentId }
Output: { ok, data: { deploymentId, deletedAt } }
Audit:  mcp.delete_preview

delete_site

範囲: site:delete

サイトを論理的に削除し、その展開、バージョン、カスタム ドメインにカスケードします。 2 段階 人間による確認: siteId (confirmationToken は不可) で呼び出して、概要 (スラッグ + カスケード展開の数) と短期間の confirmationToken を取得します。ユーザーを表示し、削除するトークンを使用して再度呼び出します。バックアップからのみ回復可能。

Step 1: { siteId }                          → { confirmationToken, summary: { siteSlug, cascade: { deployments } } }
Step 2: { siteId, confirmationToken }        → { siteId, deletedAt }
Audit:  mcp.delete_site

list_site_domains

範囲: site:read

サイトに関連付けられているカスタムドメインについて、現在のガイド手順、DNS レコード、証明書の状態、復旧 CTA、管理ページ、公開 URL を一覧表示します。結果は既定で 50 件、最大 100 件です。pagination.nextCursor が null でない場合は、その値を変更せず cursor として渡してください。カーソルは不透明で、1 つのサイトにのみ紐づきます。

結果が空でない場合は、対象行ごとの domains[].journey に従ってください。トップレベルの journey はありません。トップレベルの journey は一覧が空の場合にのみ返され、最初のドメイン接続を案内します。対象ドメインのフェーズが setting_up_https の間だけポーリングし、needs_attention になったら停止してください。

Input:  { siteId, limit?, cursor? }
Output: { ok,
          journeyGuide: { steps, whatShowlyGivesYou },
          domains: [{ id, hostname, status, isLive, certStatus, liveUrl,
                      manageUrl, dnsRecords, proxyNote, apexNote?,
                      journey: { phase, currentStep, stepStatuses,
                                 whereYouAre, userAction, agentAction,
                                 actionUrl }, recovery? }],
          pagination: { count, total, nextCursor },
          journey? }
Audit:  mcp.list_site_domains

add_custom_domain

範囲: site:write · すべてのプランで利用可能

顧客独自のドメインをサイトにアタッチし、ユーザーがドメイン プロバイダーで公開する必要がある DNS レコードを返します。

これらのユーザーのためにこの手順を完了することはできません。 この要求では保留中のレコードが作成され、トラフィックはルーティングされません。ドメインは、購入者が誰から購入したかにかかわらず、顧客が DNS を編集した場合にのみ本物になります。記録を渡し、記録を追加するまで何も起こらないとはっきり言って待ちます。ルート ドメインでは、応答には apexNote が含まれます。プレーンな CNAME はゾーン 頂点では無効であるため、これを表面化します。 すべての応答には proxyNote も含まれます。CNAME はプロキシを経由せずに公開する必要があり（Cloudflare ではグレーの雲。新規レコードはオレンジです）、そうでなければ証明書は発行できません。TXT レコードはどちらでも検証されるため、このフローの他のどこでも検出されません。必ず利用者に伝えてください。

返された verificationToken は保管しておいてください。 verify_custom_domain にはそれが必要ですが、一度だけ表示されます。

Input:  { siteId, hostname }
Output: { ok, domain: { id, hostname, status, dnsRecords, proxyNote, apexNote?, verificationToken }, nextStep }
Audit:  mcp.add_custom_domain

verify_custom_domain

範囲: site:write · すべてのプランで利用可能

保留中のドメインについて DNS を再チェックします。ユーザーがレコードを追加したと言ったら、これを呼び出します。レコードが実際に公開および伝播された場合にのみ成功します。失敗は通常、「壊れている」ではなく「まだ」を意味するため、エラーを報告するのではなく、数分待ってから再試行してください。

成功すると、TLS 証明書が自動的に要求され、ドメインは 1 時間以内に稼働します。 list_site_domains に isLive を投票します。

Input:  { siteId, domainId, token }
Output: { ok, domain: { id, hostname, status, isLive, ... } }
Audit:  mcp.verify_custom_domain

エージェントはドメインの削除を意図的に利用できません。 ライブ ドメインをアーカイブすると、顧客のサイトが宣伝されたアドレスで即座にオフラインになり、外部に同意する必要はありません。そのため、ユーザーのアクションはダッシュボードに残ります。 ADR 0015を参照してください。

list_site_versions

範囲: site:read

サイトのバージョン履歴をリストします (新しい順): id、source、changeSummary、作成者、createdAt。 get_site_files とペアにして (versionId を渡す)、そのバージョンのコンテンツを読み取ります。

キーセット方式でページ分割されます。limit の上限は 1 ページあたり 100 です。古いバージョンを取得するには、前の応答の pagination.nextCursor を cursor として渡します。nextCursor が null の場合は、履歴の末尾に到達しています。カーソルは不透明で 1 つのサイトに紐づき、最初のページを取得した時点の一覧を固定するため、ページング中に作成されたバージョンが既読ページへずれ込むことはありません。

hasMore は 非推奨 であり、pagination.nextCursor !== null をミラーします。 pagination を好みます。

Input:  { siteId, limit?, cursor? }
Output: { ok, data: {
          versions: [{ id, source, changeSummary, authorUserId, createdAt }],
          hasMore,
          pagination: { limit, nextCursor: string | null }
        } }
Audit:  mcp.list_site_versions

list_deployments

範囲: site:read

サイトのデプロイメントをリストします (新しい順): id、target (preview / staging / production)、status、url、createdAt。これが deploymentId の由来です。返された id を retry_deployment、delete_preview、request_publish、または publish_site とともに使用します。

Input:  { siteId }
Output: { ok, data: [{ id, siteId, target, status, url, createdAt }] }
Audit:  mcp.list_deployments

get_site_files

範囲: site:read

サイト バージョンのファイル ツリー (path → content) を読み取るため、編集前に現在のコンテンツを確認できます。 siteId + versionId (list_site_versions から) を通過します。大規模/マニフェストベースのバージョンは、files: null に加えて note を返します。

Input:  { siteId, versionId }
Output: { ok, data: { versionId, source, changeSummary, files: Record<string,string> | null, note? } }
Audit:  mcp.get_site_files

diff_site_versions

範囲: site:read

2 つのバージョンを比較し、変更内容を正確に返します: ファイルごとのステータス (added / removed / changed) と行レベルの add / remove / context。 list_site_versions から、siteId + versionA (古い「前」) + versionB (新しい「後」) を通過します。 「昨日と今日で何が変わったのか」などの質問に答えます。大規模なバージョン/マニフェストベースのバージョンは比較できず、エラーが返されます。

Input:  { siteId, versionA, versionB }
Output: { ok, data: {
          versionA: { id, source, changeSummary, createdAt },
          versionB: { id, source, changeSummary, createdAt },
          summary: { filesChanged, filesAdded, filesRemoved, linesChanged },
          files: Array<{ path, status, lines: Array<{ type, text }> }>
        } }
Audit:  mcp.diff_site_versions

rollback_to_version

範囲: rollback:confirm

本番を古いバージョンにロールバックし、プレビューなしで公開します。これは、ここで最も重要なツールです。 2 ステップ 人間による確認済み: siteId + versionId (confirmationToken は不可) で呼び出し、warning + サマリー + confirmationToken を取得します。ユーザーに警告を表示してから、トークンを使用して再度呼び出します。ステップ 2 は 202 building を返します — Showly はそのバージョンのプレビューをビルドし、それを運用環境に自動昇格させます。新しいバージョンにロールフォワードすることで回復可能です。

Step 1: { siteId, versionId }                       → { confirmationToken, warning, summary: { changeSummary, versionCreatedAt, previewed: false } }
Step 2: { siteId, versionId, confirmationToken }     → { siteId, versionId, deploymentId, status: "building" }
Audit:  mcp.rollback_to_version

制作ツール (MCP 公開されていない)

MCP に公開されていない — Web/API 承認フローが必要です。

従来の rollback_deployment 操作は MCP では利用できません。tools/list には表示されず、MCP トークンでも呼び出せません。該当する Showly Web の承認画面を使用してください。

本番環境の公開は **MCP 呼び出し可能です: publish_site (上記の 2 ステップの確認) は直接公開し、rollback_to_version は本番環境をロールバックします。どちらも、最初の呼び出しでは決して動作しない kind: "confirm-publish" スタイルのツールです。

一般的なタイプ

リファレンスでは、上記の名前付きシェイプをいくつか使用します。具体的なフィールド セットは エンドツーエンド フロー に示されており、実際の JSON で完全なセッションを実行します。簡単な要約:

タイプ主要なフィールド
Siteid、name、slug、projectId、framework (自動検出)、repositoryUrl
Deploymentid、siteId、target (preview / staging / production)、status、previewUrl?、createdAt
plancreate_change_plan 提案: 意図されたファイル編集のリストと人間が判読できる概要。 apply_site_patchまで適用されません
checksワークスペース チェック マトリックスからのチェックごとの結果 (lint、タイプ、カスタム CI フック)
summaryrun_checks によって返された checks (合格/不合格のカウント) のロールアップ

status は、queued、building、ready、failed、canceled のいずれかです。 ready は、プレビュー展開と運用展開の両方の最終的な成功状態です。 framework はビルド時に自動検出され、astro、vite、next-export、static-html、custom、unknown のいずれかです。マニフェストで設定するものではありません。

バージョン管理

ツール スキーマは、MCP version フィールドを介して semver に従います。重大な変更により、新しいツール名 (apply_site_patch_v2) が同梱されます。古い名前は少なくとも 1 つのリリース サイクルの間は引き続き機能しますが、notes に非推奨の注記が記載されています。