GetFacade

@getfacade/mcp

GetFacade.ai 用の MCP サーバーです。エージェントが建物を作成して写真をアップロードすると、人が画面の前にいなくても、外観のデザイン、価格算出、資料作成が行われます。

各デザインは、建物がある国に合わせて作成されます。その国で使用できる材料、実際に販売されているメーカー製品、そして表面の下にある技術的な構成が考慮されます。レンダリングでは、住宅の写真上にそれらが表示されます。

見積もりとアルバムは、同じデザインをもとに作成されます。

• 見積もりでは、その国での材料費に基づき、材料と人件費を項目ごとに価格算出します。
• アルバムでは、施工する作業員向けに、ファサードの構成、安全に関する注意事項とその根拠となる規格を記録します。

このサーバーは、公開されている GetFacade API を薄くラップしたものです。データの保存、キャッシュ、判断は行いません。価格設定、利用可否、色の文法、あらゆるメッセージを含むすべてのルールはサーバー側にあり、このラッパーは呼び出しと応答を受け渡すだけです。

URL で接続する

ほとんどのクライアントは、何もインストールせずに接続できます。この URL でカスタムコネクターを追加し、求められたら GetFacade アカウントにサインインしてください。

https://app.getfacade.ai/mcp

• Claude（claude.ai とデスクトップ）：Settings → Connectors → Add custom connector。
• Claude Code：claude mcp add --transport http getfacade https://app.getfacade.ai/mcp
• ChatGPT、Cursor、VS Code などの MCP クライアント：同じ URL を使用して、リモート（HTTP）サーバーを追加します。

サインイン画面で、接続の利用上限を設定します。アカウントのエージェントウォレットからトークンを使用し、独自にトークンを購入することはありません。アプリでは、この接続はエージェントキーの一覧に表示され、いつでも取り消すことができます。

チャットに添付された写真には、コネクターが読み取れるリンクがありません。create_building は、アプリ内にある建物の写真ページ photos_page を返します。そこで写真を追加すると、list_photos が取得します。画像への直接リンクが公開されている場合は、upload_photo でも使用できます。

ローカルで実行する

以下のパッケージを使うと、エージェントキーを使用して、同じツールを自分のマシンで実行できます。自動化する場合や、写真がそのマシン上のファイルである場合に使用してください。

必要条件

• Node.js 20+
• エージェント API キー。app.getfacade.ai → Account → Settings → API から発行してください。キーの値は一度しか表示されず、再取得できません。各キーには厳格な利用上限が設定されています。
• エージェントの利用は有料です。トライアルクレジットはありません。キーはエージェントウォレットから使用し、残高がない場合、最初の有料呼び出しは説明とともに拒否されます。有効な Pro Plan があると、請求期間ごとにウォレットへ最大 1,000 クレジットが補充されます。それを超えると、クレジットを購入する必要があります。

セットアップ

Claude Desktop／任意の MCP クライアントの mcpServers セクション：

{
  "mcpServers": {
    "getfacade": {
      "command": "npx",
      "args": ["-y", "@getfacade/mcp"],
      "env": { "GETFACADE_API_KEY": "your-key" }
    }
  }
}

公開パッケージの代わりにチェックアウトしたコードを実行するには、クライアントの参照先を変更してください： "command": "node", "args": ["/path/to/mcp/src/index.js"]。

変数	必須	デフォルト
GETFACADE_API_KEY	はい	—
GETFACADE_API_BASE_URL	いいえ	https://api.getfacade.ai/api/v1
GETFACADE_LANG	いいえ	en

拒否のメッセージも含め、メッセージは GETFACADE_LANG で指定した言語でサービスから返されます。回答を読みたい言語に設定してください。

ツール

ツール	機能
create_building	建物を作成します。名前はアカウント内で一意です。建物の場所を指定してください。指定しない場合は、呼び出しが届いた接続元から場所が推測されます。
upload_photo	ローカルのファイルパス、または画像リンク（URL 接続）を受け取ります。ファイルを登録してバイトデータをアップロードし、確認後、結果を待ちます。結果は、デザイン用のビュー、建物に保存される図面や参考資料、または理由を添えた拒否のいずれかです。
list_photos	アプリで追加された写真を含む、建物のビューを一覧表示します。view_id は start_design で使用します。
start_design	デザインを作成し、レンダリングをキューに登録します。ジョブ ID を返します。
refine_design	完成したデザインを言葉で変更します。最初のステップ以降で使用します。
get_job	レンダリング、見積もり、またはアルバムのジョブを確認します。
list_jobs	アカウント全体の最近のジョブを、未完了のものから順に一覧表示します。
list_designs	建物のデザインを、レンダリングと完成画像とともに一覧表示します。
order_estimate	選択したレンダリングの費用見積もりを依頼します。
order_album	選択したレンダリングの PDF アルバムを依頼します。
upscale_render	完成したレンダリングを拡大します。トークンを消費し、非同期で処理されます。
get_estimate	見積もりの内容を取得します。合計、前提条件、すべての明細が含まれます。
add_estimate_line	見積もりに明細を追加します。
update_estimate_line	見積もりの明細を編集します。
delete_estimate_line	見積もりの明細を削除します。
delete_render	レンダリングを 1 つ削除します。メインのレンダリングを削除すると、そのデザインはドラフトに戻ります。
delete_design	デザインを 1 つ、その配下のレンダリングとともに削除します。
delete_building	建物を、その配下にあるすべてのものとともに削除します。
list_token_packages	このアカウントで購入できるパッケージを一覧表示します。
buy_tokens	このキーのウォレットにトークンをチャージします。ローカルのパッケージのみです。以下を参照してください。
get_balance	エージェントのウォレット、キーの上限、次の有料呼び出しが受け付けられるかどうかを確認します。
report_problem	この API の不具合を報告します。無料で、ウォレットが空でも利用できます。

レンダリングは非同期です。start_design、refine_design、order_estimate、order_album はジョブ ID をすぐに返し、完了したかどうかは get_job で確認します。完成した見積もりのステータスは ready、レンダリングとアルバムのステータスは completed になります。完了まで待つ呼び出しは upload_photo だけで、結果が届くまでポーリングします。

有料の呼び出しが二重に注文されることはありません

start_design、refine_design、order_estimate、order_album、upscale_render は有料で、料金は作成されたジョブに対して発生します。そのいずれかがタイムアウトした場合、確認すべきことはジョブが存在するかどうかですが、エージェントは現在の状態からそれを判断できません。

そこで、このサーバーが代わりに確認します。有料の呼び出しはすべて、それぞれ固有の名前（Idempotency-Key）を付けて送信されます。接続に失敗した場合や、API が最初の試行を処理中だと返した場合は、エージェントではなくこのサーバーが同じ名前を使って再試行します。API は重複した呼び出しを認識して元のジョブを返すため、タイムアウトしてもデザインが 2 つではなく 1 つ分の料金しかかかりません。

この仕組みはツールの引数には影響しません。同じデザインを意図的に 2 回注文することは引き続き可能です。2 回の呼び出しにはそれぞれ別の名前が付くためです。防止されるのは、意図しない二重注文です。

API キーを使用する有料の呼び出しにはすべてこの名前が必要です。そのため、このラッパーを使わずに API を呼び出す場合は、自分でヘッダーを送信する必要があります。リファレンスは getfacade.ai/agents にあります。

キーでアクセスできる範囲

キーは、エージェントの設定に保存されるベアラーシークレットです。そのアクセス範囲は公開されたエージェント向けの機能に限られます。対象は、建物、写真、デザイン、レンダリング、見積もり、アルバム、ジョブ一覧、API ウォレットです。それ以外へのアクセスには 403 AGENT_SURFACE_FORBIDDEN が返されます。これには、アカウント自身のサインイン設定、サブスクリプション、支払い履歴が含まれます。それらの変更やキーの発行・失効は、アプリにサインインしたユーザーが行います。

リファレンスは getfacade.ai/agents にあります。

結果は永続的な公開リンクです

完成したレンダリング（result_url、main_render_url）と完成したアルバム（result_url）は、安定した URL で提供されます。署名も有効期限もありません。アシスタントは「結果を見せて」という依頼への回答として、そのまま人に渡せます。更新も追加の呼び出しも必要ありません。

率直に言えば、リンクに署名がないため、誰にも許可を求めず、転送された相手が誰でも引き続き利用できます。また、あとから取り消すこともできません。永久に公開されるほかのリンクと同様、共有するかどうかは慎重に判断してください。GET /renders/{render}/download は別のもので、ファイルを共有するのではなく保存するための、ファイル名付きの短期間有効な署名付き URL です。

サーバー上での削除はソフト削除です。アプリではユーザーが元に戻せますが、このサーバーでは元に戻せません。

buy_tokens は、キーの発行時に 購入を有効にする（発行画面のスイッチ）設定がされている場合のみ機能し、キーがまだ使用できる金額の範囲内に限られます。購入によってキー自体の支出上限が引き上げられることはありません。決済プロバイダーが保存済みの支払い方法から代金を引き落とす場合は charged を返し、人が開くための checkout_url とともに requires_human を返す場合もあります。いずれの場合も、支払いが確認されるとトークンが加算されるため、get_balance をポーリングしてください。

キーの発行とサブスクリプションの購入は、意図的に対象外としています。キーを発行できるキーには上限がなく、サブスクリプションはアプリで人が購入するものだからです。

ライセンス

MIT（LICENSE を参照）— このラッパーは呼び出しと応答を運ぶだけで、それ以外の機能はないため、非公開にするものはありません。呼び出し先の GetFacade サービスは別の扱いです。利用は getfacade.ai/terms の利用規約に従い、キーはこのパッケージではなくアカウントに発行されます。

開発

npm install
npm test    # smoke test against a stub of the API

test/live-journey.mjs は、実際のキーを使い、実際の API に対して実際の MCP クライアントで一連の操作を実行します。実際のクレジットを消費するため、npm test には含まれていません。実行方法はファイルの冒頭に記載されています。

リリースについては、RELEASING.md を参照してください。