formio-mcp

Formio MCP サーバー

MCP サーバー（@formio/mcp）は、MCP 対応クライアントから独立して利用できます。通信には stdio を使用します。クライアントがサーバーを起動し、stdin/stdout を管理します。ポートを開く必要も、手動で起動するものもありません。

このリポジトリをクローンした場合、エントリーポイントは src/stdio.ts です。

pnpm install
pnpm --filter @formio/mcp exec tsx src/stdio.ts

この方法で実行すると、stdin 上で MCP 通信を待機します。これは正常に起動することを確認するだけのため、代わりにクライアントからこのコマンドを指定してください。ビルド済みパッケージでは、同じエントリーポイントを formio-mcp バイナリと dist/stdio.js の両方から利用できます。

トランスポート

トランスポート	コマンド	対応クライアント
stdio	npx -y @formio/[email protected]（または node dist/stdio.js）	Claude Code、Claude Desktop、Cursor、VS Code、Codex、Windsurf、Cline — stdio 経由の MCP に対応するすべてのクライアント

HTTP または SSE トランスポートはありません。サーバーが HTTP リスナーを使用するのは、認証で説明する一時的なブラウザーログインページのみで、MCP 通信は行いません。

クライアントを接続する

同じ stdio エントリーはどこでも使えますが、設定ファイルと記述するキーはクライアントによって異なります。Claude Code では mcpServers の下の .mcp.json、Cursor では mcpServers の下の .cursor/mcp.json、VS Code では servers の下の .vscode/mcp.json、Codex では TOML 形式の .codex/config.toml です。共通の .mcp.json はありません。ルート READMEにクライアントごとの完全な一覧があります。JSON の mcpServers 形式は次のとおりです。

{
  "mcpServers": {
    "formio-mcp": {
      "command": "npx",
      "args": ["-y", "@formio/[email protected]"],
      "env": {
        "FORMIO_PROJECT_URL": "https://your-project.form.io"
      }
    }
  }
}

Form.io にアクセスするすべてのツールには、プロジェクトが必要です。プロジェクトの設定元は、コミット済みの formio.json、project_set ツールが書き込むディレクトリごとのマッピング、または環境変数の FORMIO_PROJECT_URL のいずれかです。優先順位は適用範囲の狭いものから順で、マッピングは環境変数より優先され、コミット済みファイルはその両方より優先されます。FORMIO_BASE_URL は任意で、通常は不要です。ベース URL はプロジェクト URL の形式から導出されます。form.io ホスト上のプロジェクトでは https://api.form.io、サブディレクトリ経由でルーティングされるプロジェクトでは親パスが使われ、導出できない場合にのみ入力を求められます。プラグインマニフェストがこれらの値を求めることはありません。各クライアントは project_set またはコミット済みの formio.json を使ってディレクトリごとに値を記録します。例外は .mcpb デスクトップバンドルのみです。デスクトップホストには入力を促す作業ディレクトリがないためです。

どちらの値も設定されていなくてもサーバーは起動するため、クライアントは接続して、設定前にツール一覧を取得できます。プロジェクト URL が求められるのはツールが必要とする時点のみで、server_status は常に動作します。

Docker で実行する

サーバーには Dockerfile が同梱されており、linux/amd64 と linux/arm64 向けに Docker Hub の formio/mcp として公開されています。イメージは stdio を使用するため、MCP クライアントが stdin/stdout を管理し、コンテナーは -i を付けて実行する必要があります。

docker run -i --rm \
  -e FORMIO_PROJECT_URL=https://your-project.form.io \
  -e FORMIO_API_KEY=your-api-key \
  formio/mcp

クライアントに組み込む場合は、クライアントを接続すると同じエントリーを使い、command と args に Docker を指定します。設定例は次のとおりです（JSON の mcpServers 形式を示しています。前述のとおり、VS Code では servers、Codex では TOML を使用します）。

{
  "mcpServers": {
    "formio-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "FORMIO_PROJECT_URL",
        "-e", "FORMIO_API_KEY",
        "formio/mcp"
      ],
      "env": {
        "FORMIO_PROJECT_URL": "https://your-project.form.io",
        "FORMIO_API_KEY": "your-api-key"
      }
    }
  }
}

コンテナでの認証

FORMIO_API_KEY を使う方法が推奨されます。ブラウザーも、対話操作も不要です。認証ポートを公開すれば、ブラウザーでのログインも利用できます。どちらの方法についても、ヘッドレス環境をご覧ください。

認証モードにかかわらず、コンテナに関する注意点が2つあります。project_set ツールではなく、FORMIO_PROJECT_URL 環境変数を優先してください。project_set はディレクトリごとのマッピングを ~/.formio/projects.json に保存しますが、このファイルはコンテナ内にあり、コンテナの終了時に破棄されます。また、すべてのツールが受け取る cwd 引数は、ホストではなく コンテナ内 のパスを指します。一方、クライアントが報告するワークスペースのルートはホスト上のパスなので、cwd を明示的に指定してください。

コンテナの実行をまたいでトークンを再利用するには、キャッシュディレクトリをマウントしてください。トークンの更新時や消去時にサーバーがファイルを書き換えるため、書き込み可能である必要があります。

-v "$HOME/.formio:/root/.formio"

セルフホスト環境へのデプロイ

公開されていないデプロイ環境で、よく問題になる点が2つあります。

ホスト名の名前解決。 プライベートなホスト名はコンテナ内で名前解決できません。明示的にマッピングしてください。

docker run -i --rm --add-host forms.internal:10.0.0.5 \
  -e FORMIO_BASE_URL=https://forms.internal \
  -e FORMIO_PROJECT_URL=https://forms.internal/my-project \
  -e FORMIO_API_KEY=your-api-key \
  formio/mcp

プライベート証明書または自己署名証明書。 イメージが信頼するのは標準の CA バンドルのみです。たとえば macOS のキーチェーンを通じてホストが信頼する証明書でも、コンテナ内では失敗し、ツールから単に fetch failed と表示されます。ケースは2つあり、それぞれ挙動が異なります。

プライベート CA によって発行された証明書。 CA 証明書をマウントし、Node に指定してください。

-v /path/to/rootCA.pem:/certs/rootCA.pem:ro -e NODE_EXTRA_CA_CERTS=/certs/rootCA.pem

完全な自己署名サーバー証明書（subject と issuer が同一で、CA:TRUE の基本制約がないもの）。サーバー自身の証明書をマウントしても、NODE_EXTRA_CA_CERTS では修正できません。Node は信頼アンカーが CA であることを要求し、チェーンを DEPTH_ZERO_SELF_SIGNED_CERT で拒否します。どちらのケースか、次のコマンドで確認してください。

echo | openssl s_client -connect your-host:443 -servername your-host 2>/dev/null \
  | openssl x509 -noout -subject -issuer

subject と issuer が一致する場合、唯一の選択肢は FORMIO_INSECURE_TLS=1 です。これを設定すると検証が完全にスキップされます。ローカル開発でのみ使用してください。本番環境のデプロイに対しては、決して使用しないでください。

イメージをローカルでビルドする

ビルドコンテキストはリポジトリのルートではなく、このディレクトリです。このパッケージは、tsconfig がこのディレクトリより上の設定を継承せず、依存関係にもワークスペースパッケージがないため、単独でコンパイルできます。

docker build -t formio-mcp packages/mcp-server

MCP Inspector で確認する

MCP Inspector はサーバーに接続し、ツールを手動で閲覧して呼び出せます。エージェントに組み込む前に、設定が正しく動作するか確認するのに便利です。Web ポータルを起動します。

npx @modelcontextprotocol/inspector

認証トークン付きの URL が表示され、ブラウザーが開きます。デフォルトのポートは 6274 です。すでに使用されている場合は、CLIENT_PORT=6284 SERVER_PORT=6285 で両方を変更してください。

inspector-config.example.json を inspector-config.json にコピーし、プロジェクトの URL と API キーを入力すると、次の手順で使用するファイルが用意できます。このファイル名は gitignore に登録されているため、入力済みのコピーを誤ってコミットすることはありません。

同じ実行手順を順に説明します。

1. Add Servers → Import from client config を選択します。

2. 「From file…」をクリックします。 ダイアログで選択できるのはクライアント設定ファイルか、このマシンにインストールされたクライアントです。JSON を貼り付ける場所はありません。

3. inspector-config.json を選択します。 定義したサーバーが新規サーバーとして一覧表示されます。「Import 1 server」で確定します。

4. カードのトグルでサーバーを有効にします。 緑色に変わり、コンテナーの起動後にネゴシエートされたプロトコルのバージョンが表示されます。初回の接続には Docker の起動が必要なため、時間がかかります。

5. Tools タブを開き、 このサーバーが公開するツールを確認します。すべてのサーバーに 23 個すべてのツールが表示されます。各クライアント向けに登録されている project_set と project_get も含まれます。

6. ツールを選び、引数を入力して「Execute Tool」を押します。 結果は中央のペインに、JSON-RPC のやり取りは右側の Protocol パネルに表示されます。server_status は認証情報に触れず、Form.io へのリクエストも行わないため、トランスポートの問題と認証の問題を切り分けられます。以下の form_list は、プロジェクトに対する実際の呼び出しです。

インポートすると、サーバーは Inspector 独自のカタログ ~/.mcp-inspector/mcp.json に保存されるため、次回も表示されます。使い終わったらカードから削除してください。ツールが単に fetch failed というエラーで失敗する場合、通常はサーバーではなくデプロイの問題です。コンテナー内でのホスト名解決と証明書の信頼については、セルフホスト可能なデプロイを参照してください。

---

MCP サーバーのツール

バンドルされている @formio/mcp サーバーは、次の 23 個のツールを公開します。操作に対応するツールがある場合、スキルは生の HTTP よりもこれらを優先します。

フォーム

ツール	目的
form_create	新しいフォームを作成します。JSON 定義を作成する前に、まず formio-schema スキルを使用してください。リビジョンライセンスが有効なデプロイでは、revisions のデフォルトは "original" です。
form_get	_id またはパス（formIdOrPath）で単一のフォーム定義を取得します。draft: true を指定すると、代わりにその下書きを取得します。
form_list	type と tags（指定したすべてのタグを持つフォーム）で絞り込み、フォームを1ページずつ一覧表示します。select で別のフィールドを指定しない限り、概要フィールドを返します。
form_update	編集済みの JSON でフォームを更新します。まず form_get を呼び出してから、formio-schema で編集し、更新してください。draft: true を指定すると、公開中のフォームではなく下書きを保存します。
form_publish	フォームの下書きを公開バージョンとして公開します（formId、note）。フォームに下書きがない場合は NO_DRAFT で失敗します。リビジョンライセンス（Security Module）が必要です。
form_revert	過去のリビジョンのコンポーネント、タグ、プロパティ、表示設定を公開中のフォームに復元します（formId、version、note）。リビジョンライセンス（Security Module）が必要です。
form_revision_list	フォームのリビジョン概要（_id、_vid、_vnote、_vuser、created、modified）を新しい順に一覧表示します。フォームのリビジョンが有効になっている必要があります。
form_revision_get	_vid またはリビジョンドキュメントの _id で、変更不可能な単一のフォームリビジョンを取得します。

ロール

ツール	目的
role_create	新しいプロジェクトロールを作成します。role: { title, description?, default?, admin? } として渡します。
role_list	プロジェクトのロールを1ページずつ一覧表示します。
role_update	ロールを更新します（roleId、role）。省略したフィールドは保存済みの値が維持されます。

アクション

ツール	目的
action_type_list	サーバーで利用可能なすべてのアクションタイプを一覧表示します。Form.io がページ分割しないカタログ全体を返します。
action_type_get	アクションタイプの設定スキーマを取得します。カタログにないタイプの場合は UNKNOWN_ACTION_TYPE で失敗します。
action_create	新しいアクションをフォームに追加します。
action_list	フォームのアクションを1ページずつ一覧表示します。
action_get	ID で単一のアクションを取得します。
action_update	アクションを更新します。省略したフィールドは保存済みの値が維持されます。
action_delete	フォームからアクションを取り外します。

プロジェクト

ツール	目的
project_export	プロジェクトの完全なテンプレート（ロール、リソース、フォーム、アクション）をポータブルな JSON ドキュメントとしてエクスポートします。スナップショットを作成するため、project_import の前に使用してください。
project_import	テンプレート JSON をインポートし、ロール、リソース、フォーム、アクションを1回の呼び出しで追加的にマージします。同じマシン名の項目は上書きされ、それ以外はすべて保持されます。
project_get	ディレクトリがどのプロジェクトに解決されるか、どのデプロイがそれをホストしているか、各設定がどのレイヤーから取得されたかを報告します。読み取りまたは書き込みを行う最初の呼び出しの前に実行するプリフライトです。ほかのすべてのツールと同じリゾルバーを使い、サーバー内部から回答するため、確認にシェルコマンドは必要ありません。ok、not-configured、base-url-unresolved のいずれかの status を返します。
project_set	ディレクトリの Project URL を ~/.formio/projects.json に保存します。コードとともに対象を記録するには、アプリケーションのフォルダー内にコミット済みの formio.json を記述してください。サーバーはこのファイルを読み取りますが、書き込みは行いません。1つのサーバーで複数のワークスペースを提供できます。すべてのクライアントに登録されます。ここに記述したマッピングは、最も優先度の低い設定元であるサーバー環境の FORMIO_PROJECT_URL を上書きします。

project_setがこのように動作する理由

ツールの説明には、呼び出し側が従うルールだけが記載されています。その理由は次のとおりです。

• 永続化されるのはツール呼び出しです。 エージェントがテキストで「プロジェクト X に切り替えます」と回答しても、何も変更されません。マッピングを書き込むのはツール呼び出しだけです。
• マッピングのキーには、呼び出しによって解決されるディレクトリが使われます。 cwd が渡された場合はその値が使われ、渡されなければ、ほかのすべてのツールが解決するのと同じディレクトリが使われます（以下の規約の cwd を参照）。最後のフォールバックであるサーバープロセス自体の作業ディレクトリは、クライアントがサーバーを起動するときに固定され、ユーザーが作業している場所とは異なることがよくあります。そのため、その場所をキーにした書き込みではそのことが示されます。
• 再起動は不要ですが、常に有効になるとは限りません。 各ツールは呼び出しごとにプロジェクトを解決するため、新しいマッピングは次の呼び出しで読み込まれます。マッピングが優先される記録である場所でのみ有効です。コミット済みの formio.json がある場合は、そのファイルがなくなったときのフォールバックになります。そのため、結果では、記録されたばかりの値ではなく、実際に解決されたペア（projectUrl、ok）が報告されます。
• ベース URL は要求されるのではなく、導出されます。 ベース URL はポータルログイン URL の構築と、キャッシュされたトークンのキーとして使われます。そのため、誤った値を指定するとリクエスト時ではなくログイン時に失敗し、推測した値を指定すると、ユーザーが使っていないデプロイメントにログインが送られてしまいます。form.io ホストの場合（ホストされたすべてのプロジェクトで共有されるベース URL https://api.form.io）と、サブディレクトリのプロジェクトの場合（親パス）は導出できます。例外は、パスのない顧客ドメイン上のプロジェクト URL です。そのデプロイメントは兄弟サブドメインにあり、プロジェクト URL からは特定できません。
• デプロイメントはプロジェクトに紐付けられます。 ベース URL は、それと一緒に記録されたプロジェクトの隣にあるディレクトリごとに保存されます。そのため、ディレクトリごとに異なるデプロイメントを対象にでき、別のプロジェクトに対してデプロイメントが応答することはありません。したがって、ディレクトリを別のプロジェクトに向け直す呼び出しでは、ベース URL は引き継がれません。古い値は置き換えられるプロジェクトに属していたためです。
• マッピングはマシンローカルです。 絶対パスをキーにするため、クローンには引き継がれません。コミット済みの formio.json はバージョン管理され、差分で確認でき、リポジトリをクローンするすべてのユーザーと共有されます。そのため、対象がアプリケーションに属する場合はこちらが優先されます。
• 不明な引数は拒否されます。 入力スキーマは厳格です。削除済みの scope など、ツールが受け取らない引数は破棄されずに拒否されるため、古いドキュメントに基づいて記述された呼び出しが、実際には行われていない書き込みを報告することはありません。

診断

ツール	目的
server_status	サーバーの名前とバージョン、および project_get と同じ方法で cwd がプロジェクトに解決される仕組みを報告します。Form.io へのリクエストは行わず、認証情報も不要なため、トランスポートの問題と認証または設定の問題を切り分けられます。他のツールが失敗した場合は、まずこれを呼び出してください。

すべてのツールに共通する規約

• cwd。 プロジェクトを解決する各ツールには任意の cwd があり、呼び出しごとに次の順序で選ばれた1つのディレクトリを解決します。cwd 引数、クライアントが MCP roots 機能を宣言している場合はクライアントのワークスペースルート（ルートが1つならそのまま使用します。複数ある場合は、プロジェクトレコード（コミット済みの formio.json またはディレクトリマッピング。破損しているものも含みます）を持つルートで判定します。すべてが同じレコードを持つ場合はそのうちの最初のルートを使用し、どのルートにもレコードがない場合は次のソースに進み、異なるレコードを持つ場合はそれらを列挙して INVALID_ARGUMENT で拒否します）、絶対パスである場合の CLAUDE_PROJECT_DIR 環境変数、最後にクライアントがサーバーを起動した場所に固定されるサーバープロセス自身の作業ディレクトリです。ルートはセッションごとに1回読み取られ、notifications/roots/list_changed の後にも再度読み取られます。roots/list が失敗するか、2秒以内に応答しない場合は、最後に正常に取得したリストが使われます。読み取りに成功したことがない場合に限り、ルートなしとして扱われます。project_get と server_status は、ソースを cwdSource（argument、client-root、claude-project-dir または server）として報告します。cwdSource が server または claude-project-dir の場合（どちらもユーザーの場所を推測した値です）、あるいは別のディレクトリを対象にする場合（たとえば、アプリごとに formio.json を持つモノレポ内の1つのアプリなど）は、絶対パスとして cwd を渡してください。
• formId と formIdOrPath。 formId は常にフォームの24文字の ObjectId _id です。formIdOrPath は _id またはフォームのパスを受け取り、パスで Form.io が提供する読み取り操作でのみ使います。対象は form_get、form_revision_list、form_revision_get です。formId にパスを渡すと INVALID_ARGUMENT で拒否されます。form_get でフォームの _id を読み取ってください。
• リスト。 form_list、role_list、action_list、form_revision_list は limit（デフォルトは100）、skip、sort、select を受け取ります。それぞれの項目は、total（クエリ全体に一致する項目数）および hasMore とともに、各ツール固有のキー（forms、roles、actions、revisions）の下に返されます。hasMore が true の間は次のページがあるため、false になるまで skip を増やして再度呼び出してください。Form.io が合計数を報告しない場合、total は省略され、ページが満杯で返されたときは hasMore が true になります。action_type_list も同様に actionTypes を返しますが、hasMore: false が常に設定されます。
• 更新では送信した内容で上書きされます。 form_update、role_update、action_update は PUT を送信し、Form.io はそれを保存済みドキュメントに適用します。本文に含まれる各フィールドは保存済みの値を上書きし、含まれないトップレベルフィールドは保存済みの値を保持します。本文中の配列やオブジェクトは、保存済みのものにマージされず、全体がそのまま置き換えられます。そのため、そのフィールドに保持させたいコンポーネント、アクセスエントリー、設定はすべて送信してください。
• リビジョン履歴。 form_create または form_update によってリビジョン履歴なしで保存される場合（デプロイメントにリビジョンのライセンスがない、本文で revisions: "" が設定されている、または更新対象フォームでリビジョンが無効になっている場合）、呼び出しに acceptNoHistory: true が渡されない限り、HISTORY_NOT_ACCEPTED で拒否され、何も書き込まれません。サーバーがユーザーに直接確認することはありません。エージェントが拒否を伝え、ユーザーの回答を受けて再試行します。ドラフト、form_publish、form_revert にはリビジョンのライセンスが必要であり、ライセンスがない場合は LICENSE_REQUIRED で拒否されます。
• エラー。 呼び出しが失敗すると isError: true が返されます。テキストはエラーコードを角括弧で囲んだもの（[NOT_FOUND] …）で始まり、その後にメッセージが続きます。また、_meta["io.form/error"]: { code, status?, body? } も返されます。status は Form.io の HTTP ステータス、body は2,000文字に切り詰められた応答本文です。エラー結果に structuredContent は含まれません。エラーコードは NOT_CONFIGURED、BASE_URL_UNRESOLVED、CONFIG_UNREADABLE、INVALID_ARGUMENT、AUTH_REQUIRED、FORBIDDEN、NOT_FOUND、VALIDATION_FAILED、LICENSE_REQUIRED、HISTORY_NOT_ACCEPTED、NO_DRAFT、UNKNOWN_ACTION_TYPE、REDIRECTED、UPSTREAM_ERROR、NETWORK_ERROR、INTERNAL です。ツールの入力スキーマに適合しない引数は、コードなしのプレーンテキストとして MCP SDK から報告されます。

---

認証

MCP サーバーは、次の 2 つの認証モードをサポートしています。

• JWT モード（デフォルト）。 短時間だけ起動するローカルの Express サーバーが Form.io ポータルのログインフォームを表示します。ユーザーが一度サインインすると、JWT が /callback エンドポイント経由で返され、formioFetch が以降の各リクエストに x-jwt-token を付加します。このフローは暗黙的に実行され、キャッシュミス時に初めて認証が必要なツール呼び出しを行うと開始されます。明示的な authenticate ツールはありません。
• API キーモード。 FORMIO_PROJECT_URL と並べて FORMIO_API_KEY 環境変数を設定します。プロジェクト FORMIO_PROJECT_URL へのリクエストには x-token が付加され、ブラウザーを使ったフローは完全に省略されます。コミット済みの formio.json またはディレクトリのマッピングによって解決されるその他のプロジェクトでは、代わりにポータルログインを通じて認証され、project_get がその理由を示します。

JWT は ~/.formio/mcp-tokens.json（モード 0600）にキャッシュされ、解決済みの Base URL をキーとして保存されます。同じデプロイメント上のすべてのプロジェクトで、1 つのトークンを使用できます。トークンの有効期間はおよそ 7 日間です。キャッシュがヒットすると、サーバーはローカルで有効期限を確認した後、サーバーに対して再検証します。いずれかの確認に失敗した場合は、新たにログインします。

エージェントに付与される権限。 JWT モードでは、エージェントにログインしたユーザーの JWTが渡されるため、トークンの有効期間中、エージェントはそのユーザーの権限で動作します。管理者としてサインインすると、エージェントはそのデプロイメントへの管理者アクセス権を引き継ぎます。API キーは代わりに対象プロジェクトに限定されます。無人環境や共有環境では API キーモードを優先し、JWT モードを使用する場合は最小限の権限を持つユーザーとしてサインインしてください。

ヘッドレス環境

デフォルトでは、ログインページは 127.0.0.1 にバインドされた一時ポートで提供され、サーバーは open（macOS）、xdg-open（Linux）、または url.dll プロトコルハンドラー（Windows）を使って、シェルを経由せずにデフォルトのブラウザーを直接起動します。これは、同じマシン上にデスクトップブラウザーがあることを前提としています。

コンテナー、SSH セッション、CI など、その前提が成り立たない環境では、次の 3 つの方法があります。

1. FORMIO_PROJECT_URL と並べて FORMIO_API_KEY 環境変数を設定し、ブラウザーを使わずに認証します。 無人での使用に最も簡単な方法です。

2. 手動でログインを完了します。 ログイン URL は、ブラウザーの起動を試みる前に、すべてのログイン試行で stderr に出力されます。エラーが発生した場合にのみ出力されるわけではありません。起動に失敗した場合は、その旨が追加の行として報告され、無視されることはありません。URL はタイムアウトエラーにも表示され、そのエラーはクライアントがツール出力として提示するため、サーバーのログを一度も見られなくても URL を確認できます。

   stdio トランスポートでは stdout が MCP プロトコル自体に使われるため、stderr を使用します。stdout にそれ以外の内容を書き込むと、ストリームが破損します。

3. アクセス可能な場所にバインドします。 FORMIO_AUTH_HOST=0.0.0.0 と固定の公開ポートを指定する FORMIO_AUTH_PORT を設定し、自分のマシンから URL を開きます。

   docker run -i --rm -p 43117:43117 \
     -e FORMIO_PROJECT_URL=https://your-project.form.io \
     -e FORMIO_AUTH_HOST=0.0.0.0 -e FORMIO_AUTH_PORT=43117 \
     formio/mcp
   

   FORMIO_AUTH_HOST=0.0.0.0 を設定すると、ログイン中、すべてのインターフェースでログインページが公開されます。その方法が許容される環境でのみ使用してください。

FORMIO_AUTH_TIMEOUT 秒（デフォルトは 900 秒）以内にログインが完了しない場合、クライアントが諦めるまで処理が停止するのではなく、これらの方法を示すエラーが返されます。

ログインフォームの自動解決

FORMIO_LOGIN_FORM が未設定の場合、サーバーは最初のログイン試行時に次の候補を確認し、応答した最初の候補をキャッシュします（候補ごとのタイムアウトは 1.5 秒です）。

1. {baseUrl}/formio/user/login（ポータルベース）
2. {projectUrl}/admin/login（プロジェクト管理者）
3. {projectUrl}/user/login（プロジェクトユーザー）

{baseUrl} と {projectUrl} は解決済みの値です。そのディレクトリについて project get が報告する値であり、名前の似た環境変数の値ではありません。

プローブは遅延実行され、ローカルの認証ページが実際に提供される場合にのみ実行されます。

---

環境変数

名前	必須	デフォルト	用途	ホスト型 SaaS の例	セルフホストの例
FORMIO_PROJECT_URL	はい*	—	Form.io プロジェクトの完全な URL です。3 つの情報源のうち優先度が最も低く、作業ディレクトリから親ディレクトリをたどって見つかったコミット済みの formio.json が優先され、次に project_set で書き込まれたディレクトリごとのマッピングが優先されます。セルフホストの場合、デプロイメントでのプロジェクトのルーティング方法に応じて、デプロイメントのサブディレクトリまたは独自ドメインのサブドメイン（https://myproject.example.com）になります。	https://myproject.form.io	https://forms.example.com/myproject
FORMIO_BASE_URL	いいえ	派生値。注を参照	Form.io デプロイメントのベース URL 全体です。通常は設定せず、プロジェクト URL から派生します。form.io ホスト上のプロジェクトでは https://api.form.io、サブディレクトリとして指定されたプロジェクトでは親パスになります。独自ドメイン上でパスを持たないプロジェクト URL で、デプロイメントから派生できない場合にのみ指定してください。3 つの情報源のうち優先度が最も低く、コミット済みの formio.json が優先され、次にディレクトリごとのマッピングが優先されます。ホスト型クラウドでは常に https://api.form.io であり、プロジェクトの *.form.io サブドメインではありません。	https://api.form.io	https://forms.example.com
FORMIO_API_KEY	いいえ	undefined	長期間有効なプロジェクト API キーです。FORMIO_PROJECT_URL が指定するプロジェクトにのみ適用されるため、隣に FORMIO_PROJECT_URL も設定してください。適用される場合、サーバーはブラウザーでのログインフローを省略します。これはブラウザーのないホストで認証する唯一の方法です。	CHANGEME	CHANGEME
FORMIO_LOGIN_FORM	いいえ	自動解決	JWT ログインフローで使用するポータルのログインフォーム URL を上書きします。	https://formio.form.io/user/login	https://forms.example.com/formio/user/login
FORMIO_AUTH_HOST	いいえ	127.0.0.1	ブラウザーログインページのバインドアドレスです。0.0.0.0 にすると、コンテナーの外部からアクセスできるようになります。
FORMIO_AUTH_PORT	いいえ	エフェメラル	コンテナーから公開できるようにするための、ブラウザーログインページの固定ポートです。	43117	43117
FORMIO_AUTH_TIMEOUT	いいえ	900	ブラウザーログインを待機してから呼び出しを失敗させるまでの秒数です。2147483 以下の正の整数を指定してください。それ以外の値は無視されます。
FORMIO_REQUEST_TIMEOUT	いいえ	60	Form.io リクエストへの応答を待機してから、URL と待機時間を示す NETWORK_ERROR で呼び出しを失敗させるまでの秒数です。2147483 以下の正の整数を指定してください。それ以外の値は無視されます。project_import と project_export の待機時間は 300 秒、またはこの値がそれより長い場合はこの値になります。
FORMIO_INSECURE_TLS	いいえ	undefined	TLS 検証をスキップするには 1 に設定します。ローカル開発でのみ使用し、本番環境では絶対に使用しないでください。
FORMIO_FORCE_BROWSER	いいえ	0	サーバーがブラウザーなしと判断する環境（CI、コンテナー、ディスプレイのない SSH）でもブラウザーログインを試みるには 1 に設定します。
* 起動時には必要ありません。サーバーは起動し、すべてのツールを一覧表示し、これがなくても server_status に応答します。Form.io データを読み書きするツールのみがエラーになり、project_set とこの変数を示します。代わりに project_set ツールを使うと、作業ディレクトリを ~/.formio/projects.json 内のプロジェクトに対応付けられます。解決はスコープの狭い順に行われます。呼び出し元の cwd から親ディレクトリをたどって見つかったコミット済みの formio.json、次にその cwd の対応付け、最も優先度の低い情報源として環境変数の FORMIO_PROJECT_URL、それでも見つからなければエラーです。クライアントが接続する前に、npx -y @formio/[email protected] project set --project-url <url> --cwd <path> でディレクトリを対応付けてください。デプロイ先は、可能な場合はプロジェクト URL から特定されるため、サーバーから特定できないと通知された場合にのみ --base-url <url> を追加します。ドメインのルールでは誤りと区別できない唯一の組み合わせは、*.form.io ドメインで提供される内部デプロイ先です。両方の URL の横に --force を追加すると、このルールで拒否される組み合わせを記録できます。この指定には同じ呼び出しで両方の URL が必要で、以降の読み取りでも有効です。また、シェル専用のフラグであり、project_set ツールにはありません。project set --reset --cwd <path> を実行すると、ディレクトリのエントリーがクリアされます。これは強制指定を解除する方法でもあります。書き込みで両方の値を変更しない場合は強制指定が維持されるため、強制指定なしで再記録しても変更はありません。project get --cwd <path> は、解決された値と、採用された情報源を表示します。解決できた場合は 0、そのディレクトリに対応付けがない場合は 1、コマンドが回答できなかった場合（使用方法の誤り、不正な URL、読み取り不能な ~/.formio/projects.json）は 2、プロジェクトは解決されたものの Base URL を特定できなかった場合は 3 で終了します。これにより、「まだ何も設定されていない」「処理に失敗した」「設定が一部だけで、不足している値がこれ」と区別できます。project set --cwd <path> は、ディレクトリから呼び出しを受け付けられる状態になった場合は 0、指定された値がまだ不足している場合は 1、コマンドが回答できなかった場合は 2、レコードは書き込まれたもののディレクトリの Base URL を依然として解決できない場合は 3 で終了します。コミット済みの formio.json が優先され、そこに値がないためです。その場合は、再度書き込むのではなく、そのファイルを編集してください。

---

CLI リファレンス：project get、project set、project logout

formio-mcp バイナリ（npx -y @formio/[email protected] project …）は、ディレクトリがどのように解決されるかを報告し、クライアントが接続する前にそのディレクトリのプロジェクトを記録します。project logout は、1 つのデプロイメントからサインアウトします。対象は、project get と同じ方法でディレクトリが解決するデプロイメント、または --base-url で指定したデプロイメントです。~/.formio/mcp-tokens.json からそのデプロイメントのキャッシュ済みトークンを削除し、ほかのすべてのエントリはそのまま残します。実行中のサーバーは次回の呼び出し時にこれを検知して再度サインインするため、サインアウトやアカウントの切り替えに再起動は不要です。これらのフラグと終了コードは 1.0 の仕様の一部です。

フラグ	コマンド	意味
--cwd <absolute path>	3 つすべて	報告、記録、またはサインアウトの対象となるディレクトリです。既定値は現在のディレクトリです。相対パスは受け付けません。
--project-url <url>	project set	記録する Project URL です。
--base-url <url>	project set	プロジェクトをホストするデプロイメントです。サーバーが Project URL から導出できないと示した場合にのみ指定してください。
--force	project set	ドメインのチェックを省略し、指定どおりのペアを記録します。同じ呼び出しで --project-url と --base-url の両方が必要です。project_set ツールに同等の機能はありません。
--reset	project set	このディレクトリのエントリを ~/.formio/projects.json から削除します。URL は指定しません。
--base-url <url>	project logout	--cwd によって解決されるデプロイメントの代わりに、サインアウトするデプロイメントを指定します。

終了コード	project get	project set	project logout
0	ディレクトリからプロジェクトとその Base URL が解決されました。	ディレクトリは呼び出しを処理できる状態です。	トークンが削除されたか、そのデプロイメントのキャッシュ済みトークンがありません。どちらに該当するかは出力に示されます。
1	このディレクトリには何もマッピングされていません。	名前付きの値がまだ不足しています。	このディレクトリには何もマッピングされていないため、デプロイメントを解決できません。--base-url で指定してください。または、指定した --base-url が有効な URL ではありません。再度指定してください。
2	コマンドで回答できませんでした。使用方法の誤り、不正な URL、または読み取り不能な ~/.formio/projects.json が原因です。	コマンドで回答できませんでした。	コマンドで回答できませんでした。使用方法の誤り、または読み書きできない ~/.formio/mcp-tokens.json が原因です。
3	プロジェクトは解決されましたが、Base URL を特定できませんでした。	記録は書き込まれましたが、ディレクトリから Base URL を引き続き解決できません。コミット済みの formio.json が適用されており、Base URL が指定されていないため、このファイルを編集する必要があります。	プロジェクトは解決されましたが、そのデプロイメントを特定できませんでした。--base-url で指定してください。

---

プライバシーポリシー

Form.io のプライバシーポリシーは、このサーバーが通信する Form.io サービスを対象としています：https://form.io/privacy

上記のポリシーでは説明できない、このサーバー自体によるデータの取り扱いについて説明します。

データの送信先。 設定した Form.io のデプロイ先だけです。すべてのリクエストは、作業ディレクトリで解決されるプロジェクト URL とベース URL を宛先とします。これは、ご自身の SaaS プロジェクトかセルフホストサーバーです。セルフホストの場合、サーバーから Form.io にデータが送信されることはなく、テレメトリー、分析、使用状況の報告も一切ありません。

マシンに保存されるもの。 ~/.formio/ 以下に、どちらもモード 0600 で書き込まれる 2 つのファイルがあります。

ファイル	内容	書き込まれるタイミング
mcp-tokens.json	ブラウザーでのログインで取得した JWT。解決されたベース URL をキーにして保存されます	ブラウザーからサインインしたとき
projects.json	ディレクトリごとのプロジェクト URL とベース URL の対応表	project_set の実行時

フォームデータと送信データがディスクに書き込まれることはありません。ツール呼び出しへの応答に使用するため、メモリー上で処理されます。

認証情報。 FORMIO_API_KEY 環境変数が設定されている場合、環境から読み込まれ、プロジェクトの FORMIO_PROJECT_URL が指す先へのリクエストに限って認証ヘッダーとして送信されます。ディスクに書き込まれることはありません。キャッシュされた JWT の有効期間はおよそ 7 日間で、その後、サーバーは再認証します。すぐにサインアウトするには、~/.formio/mcp-tokens.json を削除してください。

第三者サービス。 サーバーが第三者サービスに接続することはありません。ただし、1 つ例外があります。ブラウザーのサインインページはローカルで配信されますが、ページ内で表示される Form.io レンダラーとスタイルシートは cdn.jsdelivr.net から、ウェブフォントは fonts.googleapis.com から、Form.io のロゴは portal.form.io から読み込まれます。そのため、そのページを開いている間、これらのホストにはブラウザーの IP アドレスが見えます。ページ上のその他すべての要素は、ご自身のデプロイ先から取得されます。ブラウザーでの認証フローを完全に省略してこれを回避するには、FORMIO_PROJECT_URL と同じ場所に FORMIO_API_KEY 環境変数を設定してください。

保持期間。 上記のファイルは削除するまで保持されます。Form.io プロジェクトに保存されるデータは、ご自身のデプロイ先の保持ルールに従います。Form.io がホストするプロジェクトの場合は、上記のリンク先にあるポリシーにも従います。

データの取り扱いに関するお問い合わせ：[email protected]