Formhaus

本地服务

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

关于 Formhaus

@formhaus/mcp 是一个 MCP 服务，可使用 @formhaus/core 引擎检查 Formhaus 表单定义。它面向构建或运营表单的 Agent 和开发者，提供离线验证与路径模拟，也可选用 Formhaus Cloud 管理工具。

主要功能

01验证表单定义
02应用已知的安全修复
03模拟多步骤表单路径
04生成翻译模板
05发布表单并管理提交

适用场景

01使用前检查表单定义
02修复定义中的已知安全问题
03用示例答案测试路径和验证
04发布表单并查看提交

MCP 相关

该服务向 MCP 客户端提供离线定义检查、模拟、翻译和能力查询工具，以及用于发布和管理表单的 Formhaus Cloud 工具。云端操作调用 Formhaus API，除发布外的大多数工具需要 API 密钥。

配置

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

mcp.json · 通用配置

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

启动命令npx -y @formhaus/mcp

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

安装包

npm@formhaus/mcp0.6.3stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
definition	any	是	作为 JSON 对象或 JSON 字符串提供的 Formhaus 表单定义。

详细介绍

@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。