Formhaus

Name: Formhaus
Author: formhaus-dev

本地服务

formhaus.dev开发工具8今天更新

代码仓库访问官网

关于 Formhaus

@formhaus/mcp 让 AI Agent 使用实际的 @formhaus/core 引擎校验 Formhaus 表单定义，并模拟多步骤表单路径。离线检查无需账户或密钥；另有工具用于发布和管理 Formhaus Cloud 表单。

主要功能

01校验并修复表单定义
02模拟多步骤表单路径
03生成翻译模板
04查看字段与验证能力
05发布表单并管理提交
06管理表单设置和 Webhook

适用场景

01在上线前检查表单定义
02测试回答如何经过多步骤表单
03为表单生成翻译文件模板
04通过 Formhaus Cloud 发布及管理表单

MCP 相关

该 MCP 服务通过 stdio 向客户端提供表单校验、模拟等工具，并以 formhaus://capabilities 资源公开能力信息。云端发布和管理工具连接 Formhaus Cloud。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y @formhaus/mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@formhaus/mcp0.12.7stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@formhaus/mcp

MCP 服务可让 AI Agent 使用真实的 @formhaus/core 引擎检查 Formhaus 表单定义。通过 stdio 运行。需要 Node 22.12 或更高版本。检查无需账号或密钥。

validate_definition、fix_definition、simulate_path、translation_template、capabilities 和 example_definitions 可离线运行。其他工具则会在 Formhaus Cloud 中发布表单、读取提交内容并管理设置。如果应用有自己的后端，请将数据保留在那里，未经用户同意不要发布表单。

设置

Claude Code 插件，包含 Formhaus 技能：

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 }`。每个问题包含 `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`	内置示例列表，或单个定义
`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_...）可访问所有表单和全部六种工具。Agent 密钥（fh_agent_...，由首次不带密钥调用 publish_form 时返回）只能访问其创建的表单；update_form_settings、get_webhook 和 reveal_webhook_secret 则需要账户密钥。服务端会从自身环境中读取 FORMHAUS_API_KEY，而不是从项目的 .env 中读取。将其添加到 MCP 客户端配置中 formhaus 服务的 env 项（例如使用 ${FORMHAUS_API_KEY}，并在 shell 中设置变量，或放入客户端会加载的、已加入 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 可在你的机器上的编码 Agent 中设置服务；请参阅 formhaus。