ZynoHosting

ZynoHosting CLI と MCP サーバー

@zyno-io/zynohosting は、ZynoHosting 用の公開コマンドラインおよびローカル MCP クライアントです。次の操作ができます。

• 現在のテナント認証情報で許可されているサイトを一覧表示する；
• 個別のファイルを確認、ダウンロード、アップロード、削除する；
• マニフェストに基づくデプロイ全体をプレビューし、適用する；
• デプロイ可能なスナップショット全体、または追加の権限がある場合はすべてのユーザーコンテンツをダウンロードする；
• 公開済みの ZynoForms を検出、作成、確認、編集、埋め込み、設定する；
• ローカルの stdio MCP サーバーを介して、同じ操作をエージェントに公開する。

このパッケージには Node.js 24 が必要です。

CLI と MCP の詳細なドキュメントは、zyno-io.github.io/zynohosting-cli をご覧ください。

インストール

npm install --global @zyno-io/zynohosting
zynohosting --help

次の 2 つの実行ファイルがインストールされます。

• zynohosting — ユーザーおよび CI 向けのコマンドラインインターフェイス；
• zynohosting-mcp — ローカルの stdio MCP サーバー。

グローバルにインストールせずにコマンドを実行することもできます。

npx -y @zyno-io/zynohosting sites list

認証

対話型ユーザーの場合：

zynohosting login --permission hosting.sitesRead
zynohosting login \
  --name "Claude MCP — work laptop" \
  --permission hosting.sitesRead \
  --permission hosting.deploy \
  --permission forms.create \
  --permission forms.edit \
  --renewable

ブラウザーログインでは、テナントに紐づいたスコープ付き CLI トークンが作成されます。--permission を指定しない場合は hosting.sitesRead が要求されます。ワークフローに必要な権限一式のうち、最も限定的なものを要求するには、このオプションを繰り返し指定してください。アクセストークンは常に 60 分後に期限切れになります。--renewable を指定すると、ローテーションする更新用認証情報がオペレーティングシステムの認証情報ストアに保存され、長時間実行する CLI／MCP プロセスで自動更新できるようになります。MCP が起動している間は、ツールが呼び出されていない場合もバックグラウンドで更新されます。また、各リクエストでも安全策として有効期限を確認します。更新シークレットが JSON 設定ファイルに書き込まれることはありません。

保存済みのスコープ付き許可を取り消し、ローカル認証情報を削除するには、zynohosting logout を実行してください。

CI などの非対話型環境では、テナント API キーを指定します。

export ZYNOHOSTING_API_KEY='...'

CLI では --environment production|alpha|dev と --api-url も使用できます。認証情報は次の順序で解決されます。

1. コマンドオプション；
2. 環境変数；
3. 保存済みのログインファイル。

関連する環境変数は次のとおりです。

• ZYNOHOSTING_API_KEY
• ZYNOHOSTING_ACCESS_TOKEN
• ZYNOHOSTING_TENANT_ID
• ZYNOHOSTING_TOKEN_EXPIRES_AT
• ZYNOHOSTING_API_URL
• ZYNO_SUITE_API_URL
• ZYNO_AUTH_API_URL
• ZYNOHOSTING_ENVIRONMENT
• ZYNOHOSTING_CONFIG
• ZYNOHOSTING_LOGIN_URL

サイト

zynohosting sites list
zynohosting sites get example.com
zynohosting sites get 11111111-1111-4111-8111-111111111111 --json

サイトは、UUID、プライマリホスト名、バニティホスト名、または許可されているエイリアスで指定できます。

個別ファイル

リモートパスは、サイトのドキュメントルートからの相対パスです。絶対パス、..、制御文字、バックスラッシュ、シンボリックリンクを経由したパスは拒否されます。

zynohosting files list example.com
zynohosting files list example.com wp-content/themes --recursive

zynohosting files get example.com index.html --output ./index.html
zynohosting files put example.com ./index.html index.html
zynohosting files rm example.com obsolete.html --yes

確認後にファイルが変更された場合に上書きしないよう、ETag を使用してください。

zynohosting files put example.com ./index.html index.html --etag '"etag-from-list"'
zynohosting files rm example.com obsolete.html --etag '"etag-from-list"' --yes

アップロード先のパスがすでに存在しないことを必須にするには、--create を使用します。

デプロイ全体

zynohosting deploy example.com ./dist
zynohosting deploy example.com ./dist --dry-run
zynohosting deploy example.com ./dist --yes

デプロイは、必ず計画を立ててから適用されます。クライアントとノードエージェントは、次の処理を行います。

1. プロトコルの制限と必須の除外対象について合意する；
2. ローカルおよびリモートのコンテンツを一覧化する；
3. サイズが同じ候補のみをハッシュ化する；
4. 作成、置換、削除の正確な計画を返す；
5. 変更されたファイルのみをアップロードする；
6. 変更を適用する前にリモートのスナップショットを再検証する；
7. 適用が成功した後にサイトキャッシュを無効化する。

必須のデプロイ対象範囲からは、プラットフォーム管理の設定、アップロード、キャッシュ、ログ、VCS データ、依存関係が除外されます。プロジェクト固有の除外対象は、.zynohostingignore または --ignore で追加してください。

空のローカルデプロイでリモートのデプロイ対象範囲を削除するには、事前に --allow-empty が必要です。

完全ダウンロード

デフォルトのスナップショットは、デプロイ対象範囲を反映します。

zynohosting download example.com ./site-copy

保護された設定やユーザー生成コンテンツをダウンロードするには、別途 hosting.downloadSensitive 権限が必要です。

zynohosting download example.com ./complete-copy --sensitive

保存先は新規または空である必要があります。アーカイブのバイト列は、ホスティングノードが生成した形式のまま展開されます。CLI は転送の完了、gzip ストリーム、tar エントリーを検証してから、ステージングされたツリーをアトミックにインストールします。絶対パス、パストラバーサル、リンク、デバイス、その他の未対応エントリーは拒否されます。

ローカル MCP サーバー

MCP サーバーはローカルの stdio 専用です。ポートを開いたり、ホスト型／クラウド型の MCP エンドポイントを提供したりすることはありません。

技術に詳しくないユーザーは、これを Codex または Claude Code に貼り付けてください。

このプロジェクトで ZynoHosting MCP がまだ設定されていない場合は、設定してください。詳細は https://raw.githubusercontent.com/zyno-io/zynohosting-cli/main/docs/mcp/agent.md を参照してください。

エージェントが設定するのは、Claude Code の場合は .mcp.json、Codex の場合は .codex/config.toml という自身のプロジェクトファイルのみで、認証情報は保存しません。設定が完了したらエージェントを再起動してください。実行中のセッションには MCP ツールが追加されません。このプロンプトはエージェント向けに書かれたインストール手順を参照しています。対応するユーザー向けのプロンプトでは、サインイン、公開、フォームについて説明しています。

ZYNOHOSTING_MCP_ROOTS は、MCP プロセスに対する任意のローカルコンピューター許可リストです。設定されていない場合、ローカルファイル用ツールは、MCP プロセスのユーザーがアクセスできる任意の絶対パスを使用できます。ルートが設定されている場合、ローカルファイルの読み取り、書き込み、デプロイ元、無視ファイル、ダウンロード先は、正規パスの解決後にその範囲内に制限されます。

直接呼び出す場合：

zynohosting-mcp --root /absolute/path/to/project

パッケージのメインバイナリでは、レジストリーに適した形式も利用できます。

npx -y @zyno-io/zynohosting mcp --root /absolute/path/to/project

クライアント設定の例：

{
    "mcpServers": {
        "zynohosting": {
            "command": "npx",
            "args": ["-y", "@zyno-io/zynohosting", "mcp"],
            "env": {
                "ZYNOHOSTING_MCP_ROOTS": "/absolute/path/to/project"
            }
        }
    }
}

macOS と Linux では、複数の ZYNOHOSTING_MCP_ROOTS の区切り文字に : を使用します。Windows では ; を使用します。--root 引数を複数回指定する方法もサポートされています。

MCP ツールは以下のとおりです。

• login
• list_sites
• get_site
• list_forms
• get_form_integration
• describe_form
• create_basic_form
• update_form
• update_form_bot_protection
• update_form_origins
• list_files
• get_file
• put_file
• delete_file
• plan_deploy
• apply_deploy
• plan_download
• apply_download

完全なデプロイとダウンロードでは、意図的にプランの作成と適用を別々に呼び出します。プランはローカルの MCP プロセス内にのみ保持され、公開されるベアラートークンを含まず、短期間のアクセスセッションが終了すると期限切れになり、サーバーの再起動後には適用できません。

MCP はログイン情報が保存されていなくても起動できます。エージェントは login を呼び出して ZynoSuite のブラウザーサインインフローを開き、ツールの結果で一度限りの URL を受け取ります。ブラウザーのコールバック後、action: "status" を指定して login を呼び出し、ログインを確認します。エージェントはプロジェクトからデプロイドメインを推測したり、類似する認証済みサイトを選んだりしてはなりません。プロジェクトに対象ドメインが記載されていない場合は、ユーザーに確認します。指定されたドメインが現在のログインコンテキストで利用できない場合、別のドメインで代用してはならず、コンテキストを切り替えるために再度 login を実行するよう案内してください。

権限

テナントの認証情報には、Hosting と Forms の明示的な権限が設定されています。

権限	機能
hosting.sitesRead	サイトの一覧表示と詳細確認
hosting.filesRead	ファイルの一覧表示と個別ファイルのダウンロード
hosting.filesWrite	個別ファイルの作成と置換
hosting.filesDelete	個別ファイルの削除
hosting.deploy	デプロイ全体の計画と適用
hosting.download	デプロイ可能なスナップショットのダウンロード
hosting.downloadSensitive	保護されたコンテンツとユーザー生成コンテンツを含める
hosting.analyticsRead	ホスティングの分析データの読み取り
hosting.analyticsManage	分析設定の変更
forms.create	基本フォームを作成してすぐに公開
forms.edit	フォーム、その Cap 保護、および許可された CORS オリジンの編集

フォームの検出ツールと統合ツールは、同じテナント認証情報を使用して ZynoSuite API にアクセスします。ホスティングサイトの参照からオリジンを追加するには、hosting.sitesRead も必要です。

テナント管理者には、通常の管理者向けデフォルト権限が付与されます。管理者以外の認証情報には、明示的に許可された操作のみが付与されます。

権限はこの表に記載されているものがすべてです。zynohosting login --help で一覧が表示され、MCP の login ツールもスキーマ内に一覧を示すため、hosting.sitesWrite のような存在しないキーは、最も近い有効なキーが提示されたうえで、ブラウザーを開く前にローカルで拒否されます。CLI トークンのリクエストには、msp.login、msp.impersonate、core.changePassword、core.manageFingerprints を含めることはできません。ブラウザーも、不明な権限や現在のユーザーが持っていない権限を拒否し、リクエストの一部だけを許可することはありません。

MCP のブラウザーフローは一度に 1 つだけ実行されます。同じリクエストで login を繰り返すと、同じ 1 回限りの URL が返されます（"reused": true）。異なる権限をリクエストすると、進行中のフローはキャンセルされ、以前のスコープを返すのではなく、新しい URL が発行されます。action: "cancel" はフローを中止し、ループバックリスナーを閉じます。

JSON 出力

ほとんどの CLI コマンドは --json を受け付けます。Deploy は進捗、計画、結果のイベントを改行区切りで出力し、list コマンドと file コマンドは単一の JSON ドキュメントを出力します。

公開 API とリリースプロセス

公開ドキュメントサイトでは、CLI コマンド、MCP ツール、設定、権限、安全性について説明しています。マネージャーと node-agent の契約については、BACKEND_PLAN.md に記載されています。メンテナー向けのリリース設定とタグのみを使用するミラー設計については、RELEASING.md に記載されています。