Formhaus

@formhaus/mcp

AI エージェントが Formhaus のフォーム定義を、実際の @formhaus/core エンジンで検証できる MCP サーバーです。stdio 経由で動作します。Node 22.12 以降が必要です。検証にアカウントやキーは必要ありません。

validate_definition、fix_definition、simulate_path、translation_template、capabilities、example_definitions はオフラインで実行されます。その他のツールは、Formhaus Cloud でフォームを公開し、送信内容を読み取り、設定を管理します。アプリに独自のバックエンドがある場合は、データをそのまま保持し、ユーザーの同意なしに公開しないでください。

セットアップ

Formhaus のスキルを含む Claude Code プラグイン：

claude plugin marketplace add formhaus-dev/formhaus
claude plugin install formhaus@formhaus

Claude Code のセッション内で確認プロンプトに応答した後、/plugin marketplace add formhaus-dev/formhaus と /plugin install formhaus@formhaus を実行しても同じです。

Claude Code、サーバーのみ：

claude mcp add formhaus -- npx -y @formhaus/mcp

Claude Desktop（claude_desktop_config.json）および Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "formhaus": {
      "command": "npx",
      "args": ["-y", "@formhaus/mcp"]
    }
  }
}

ツール

ツール	入力	出力
validate_definition	definition（オブジェクトまたは JSON 文字列）	{ valid, issues }。各 issue には code、severity、JSON ポインターの path、message、hint があり、修正方法がわかっている場合は fixes（RFC 6902 JSON Patch を含む { title, safe, patch }）も含まれます
fix_definition	definition（オブジェクトまたは JSON 文字列）	{ definition, applied, valid, issues }：安全な修正をすべて適用した定義、適用した修正、および残っている問題
simulate_path	definition、answers、省略可能な actions（next、back、skip）および overlay	アクティブなステップパスと表示されるフィールド、アクションのトレース、validation（{ valid, issues }）、フィールドの errors、wouldSubmit、submitValues。グループ項目のフィールドは participants.0.email のようなパスで表示されます
capabilities	なし	フィールドの種類、セクション、繰り返し可能なグループ、フィールドのプロパティ、検証ルール、条件演算子、ステップとルートのセマンティクス、翻訳カタログ、キーとオーバーレイのアドレス、アダプター
translation_template	definition、lang、省略可能な prefix	ソーステキストを含む overlay のひな形、推奨される file 名、およびアドレス、キー、プレースホルダー、ハッシュを含む slots
example_definitions	省略可能な id	バンドルされているサンプルの一覧、または1つの定義
publish_form	definition、省略可能な form_id、email、success_message、redirect_url	form_id、endpoint、hosted_url、embed_snippet、react_snippet、dashboard_url、warnings
list_forms	なし	API キーでアクセスできるフォームと、そのステータス、バージョン、送信数、エンドポイント
get_submissions	form_id、省略可能な limit、cursor	submissions と next_cursor
update_form_settings	form_id、省略可能な webhook_url、notify_mode、success_message、redirect_url、status	form_id、status、success_message、redirect_url、notify_mode、webhook_url、マスクされた webhook_secret
get_webhook	form_id	url とマスクされた secret
reveal_webhook_secret	form_id	form_id と完全な webhook_secret。読み取り専用ではない機密性の高いツールとしてマークされています。クライアントが最初に確認を求めるかどうかは、権限設定によって異なります

publish_form、list_forms、get_submissions、update_form_settings、get_webhook、reveal_webhook_secret は Formhaus Cloud の https://api.formhaus.dev を呼び出します。publish_form 以外はサーバー環境に FORMHAUS_API_KEY が必要で、publish_form は設定されている場合に使用します。アカウントキー（fh_live_...）では、すべてのフォームと6つのツールすべてにアクセスできます。エージェントキー（fh_agent_...。キーなしで最初に publish_form を実行したときに一度だけ返されます）では、そのキーを作成したフォームにのみアクセスでき、update_form_settings、get_webhook、reveal_webhook_secret にはアカウントキーが必要です。サーバーはプロジェクトの .env ではなく、自身の環境から FORMHAUS_API_KEY を読み込みます。MCP クライアントの設定にある formhaus サーバーの env に追加し（たとえば、${FORMHAUS_API_KEY} を記述した .mcp.json を使い、値はシェルまたはクライアントが読み込む Git で無視される .env に設定します）、その後サーバーを再起動してください。FORMHAUS_API_BASE で API URL を上書きできます。また、サーバーは接続時に短い使用方法の説明をクライアントに送信します。

simulate_path は、answers を初期値として適用します。グループの回答は項目オブジェクトの配列として指定し、その後、アクションを順番に実行します。アクションが指定されていない場合は、最後のステップまたは最初のブロッキングエラーまで Next を実行します。errors に含まれるのは、訪問済みのステップのみです。カスタムバリデーター、onStepValidate、ライフサイクルフックは実行されません。機能情報は formhaus://capabilities リソースからも利用できます。

MCP を使わずに利用できるよう、ツールハンドラーがエクスポートされています。

import { simulatePathTool, validateDefinitionTool } from '@formhaus/mcp';

const report = await validateDefinitionTool({ definition });
const result = await simulatePathTool({ definition, answers: { kind: 'business' } });

出力例については、MCP ガイドをご覧ください。Formhaus Cloud 用のリモート MCP サーバーも利用できます。npx formhaus を実行すると、お使いのマシン上のコーディングエージェントにサーバーがセットアップされます。詳しくは formhausをご覧ください。

ライセンス

MIT