GetFacade

@getfacade/mcp

适用于 GetFacade.ai 的 MCP 服务：Agent 创建一栋建筑，上传建筑照片，即可获得外立面设计、报价和文档，无需有人坐在屏幕前操作。

每项设计都会根据建筑所在的国家量身定制：采用当地适用的材料、当地实际有售的制造商产品，以及表面后面的技术构造。渲染效果会呈现在房屋照片上。

报价和图册来自同一份设计：

• 报价按行列出材料和人工的价格，采用这些材料在所在国家的价格。
• 图册为施工团队提供文档：外立面的构造、安全说明及其依据的规范。

此服务只是对 GetFacade 公共 API 的薄封装。它不存储任何内容、不缓存任何内容，也不做任何决策：所有规则（定价、准入、颜色语法以及每条消息）都由服务端负责，封装层只传递调用和响应。

通过 URL 连接

大多数客户端无需安装任何内容即可连接。添加自定义连接器，使用以下 URL，并在提示时登录你的 GetFacade 账户：

https://app.getfacade.ai/mcp

• Claude（claude.ai 和桌面应用）：设置 → 连接器 → 添加自定义连接器。
• Claude Code：claude mcp add --transport http getfacade https://app.getfacade.ai/mcp
• ChatGPT、Cursor、VS Code 及其他 MCP 客户端：使用相同的 URL 添加远程（HTTP）服务。

在登录界面中，你可以为此连接设置消费上限。费用从账户的 Agent 钱包中扣除，连接器不会自行购买代币。此连接会显示在应用中的 Agent 密钥列表里，你可以随时撤销。

附加到聊天中的照片无法通过连接器读取链接。create_building 会返回 photos_page，即应用中的建筑照片页面：在那里添加照片，list_photos 就能找到它。upload_photo 也支持直接使用图片的公开链接。

在本地运行

下面的软件包可让你使用 Agent 密钥，在自己的计算机上运行相同的工具。可用于自动化，也适用于照片存储在该计算机上的情况。

要求

• Node.js 20+
• Agent API 密钥。前往 app.getfacade.ai → Account → Settings → API，为自己签发密钥。 密钥值只会显示一次，无法找回；每个密钥都有严格的消费上限。
• Agent 访问权限需付费，且不提供试用额度：密钥从 Agent 钱包扣费，余额不足时，首次付费调用会被拒绝并附带说明。有效的 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	删除一个渲染结果。主渲染结果对应的设计会恢复为草稿状态。
delete_design	删除一项设计及其下的渲染结果。
delete_building	删除一栋建筑及其下的所有内容。
list_token_packages	获取此账户可购买的代币套餐。
buy_tokens	为此密钥的钱包充值。仅限本地套餐。见下文。
get_balance	获取 Agent 钱包、密钥限额，以及下一次付费调用是否会被接受。
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 都需要付费，费用会随创建的任务扣除。如果其中一个调用超时，真正需要确认的是任务是否已创建，而 Agent 无法仅凭当前状态回答这个问题。

因此，本服务会代为确认。每个付费调用都会使用专属名称（Idempotency-Key）发送；连接失败或 API 表示首次尝试仍在运行时，由本服务使用相同名称重试，而不是由 Agent 重试。API 会识别重复请求并返回原始任务，因此超时只会产生一个设计，而不是两个。

这不会影响工具参数：仍然可以有意对同一设计下单两次，因为两次调用会使用两个不同的名称。消除的只是意外的重复下单。

API 要求每次使用 API 密钥进行付费调用时都提供此名称，因此，如果不使用此封装程序，就必须自行发送该请求头。参考文档见 getfacade.ai/agents。

密钥可访问的内容

密钥是一种保存在 Agent 配置中的持有者秘密，其访问范围仅限已发布的 Agent 可访问内容：建筑、照片、设计、渲染结果、估算、相册、任务列表和 API 钱包。其他任何内容都会返回 403 AGENT_SURFACE_FORBIDDEN，包括账户本身的登录设置、订阅和付款历史记录。修改这些内容，以及签发或撤销密钥，都必须由已登录应用的用户完成。

参考文档见 getfacade.ai/agents。

结果是永久公开链接

已完成的渲染（result_url、main_render_url）和已完成的相册（result_url）都通过稳定 URL 提供：没有签名，也不会过期。助手可以直接把链接发给用户，作为“给我看看结果”这一请求的答复，无需刷新，也无需再次调用。

需要如实说明的是：由于链接未签名，任何人都无需获得许可，因此转发给谁都能继续使用，而且之后无法撤回。分享时请像对待其他永久公开的链接一样谨慎。GET /renders/{render}/download 则是另一回事——它会返回一个带文件名的短期签名 URL，用于保存文件，而不是分享文件。

服务器上的删除是软删除：用户可以在应用中撤销删除，但本服务无法撤销。

只有在密钥签发时启用了允许购买（签发页面上的开关），且尚未超出该密钥可用的消费额度时，buy_tokens 才能生效——购买不会提高密钥自身的消费上限。如果支付服务商通过已保存的付款方式扣款，返回的状态为 charged；如果需要用户操作，则返回 requires_human 和 checkout_url，供用户打开。无论哪种情况，付款确认后都会为账户充入代币，因此请轮询 get_balance。

有意不提供签发密钥和购买订阅的功能：允许密钥自行签发新密钥就没有上限，而订阅需要用户在应用中购买。

许可证

MIT（参见 LICENSE）——此封装仅传递调用和答复，不包含其他内容，因此没有需要闭源的部分。它所调用的 GetFacade 服务则另当别论：使用该服务受 getfacade.ai/terms 中条款的约束，密钥是签发给账户的，而不是签发给此软件包的。

开发

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

test/live-journey.mjs 使用真实 MCP 客户端、真实 API 和真实密钥，完整跑通整个流程。它不属于 npm test，因为会消耗实际额度；文件头部说明了如何运行。

发布：参见 RELEASING.md。