formwire

formwire

formwire 是一个小型本地桥接工具，用于连接 Formpaste 托管的 MCP 服务，为网站接入联系表单： 创建表单、获取已填入表单访问密钥的框架专用复制粘贴代码片段、 检查表单的配置，以及读取收到的 提交内容。

桥接工具本身不存储任何内容。它会在本地提供 上游服务工具列表，内容与从实时端点捕获的内容完全一致， 并将每次工具调用转发到上游，原样返回结果。 表单属于调用者自己的 Formpaste 账户： 表单的收件地址是所有者自己的通知地址，在创建表单时设置一次； 测试提交工具只会在调用者自己的表单上存储一条标记为测试的记录，不会发送电子邮件。

工具

• create_form - 创建表单，并返回其 访问密钥和已接入的代码片段。必填：name （人类可读的标签）和 destinationEmail （提交内容的邮件接收地址；新地址必须先在控制面板中验证， 才会开始发送邮件）。 可选：framework（html、react、nextjs、 astro、vue 或 svelte；默认为 html）， 用于选择代码片段的格式。
• get_snippet - 获取框架专用的表单复制粘贴代码片段。 必填：framework。可选：formId 用于填入真实访问密钥；不提供时会使用占位符。
• list_submissions - 列出某个表单的提交内容， 包括计数和每条提交的元数据。 必填：formId。可选：folder（inbox 或 spam）、limit，以及用于包含完整消息正文的 includeContent。
• list_forms - 列出账户中的所有表单，以及每个表单的 ID、名称、访问密钥和收件箱／垃圾邮件计数。 无需参数。用于查找表单 ID。
• get_form - 读取单个表单，以检查其 接入配置：访问密钥、收件地址及该地址是否已验证、 允许的域名，以及通知、自动回复和 Webhook 设置。 必填：formId。绝不会返回 Webhook 签名密钥。
• send_test_submission - 在你自己的表单上存储一条测试提交， 以验证表单是否正常运行。必填： formId。可选：fields，一个由示例值组成的扁平字符串映射；省略时会使用默认负载。测试 记录会在收件箱中显示 Test 徽标，不会发送电子邮件， 也不会计入配额。

配置

• FORMPASTE_MCP_URL（可选）- 覆盖 上游端点。默认值为 https://api.formpaste.com/mcp。 （此覆盖钩子是本次重建中自行添加并标注的内容。）
• FORMPASTE_API_KEY（可选）- 设置后，每个 上游请求都会携带 Authorization: Bearer <key> 标头，其中的令牌 在 Formpaste 控制面板中生成。未设置时， 不会发送身份验证标头。（此转发功能 也是本次重建中自行添加并标注的内容；原始 接口是在无密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26， clientInfo name formwire），再发送 notifications/initialized 通知，随后发送携带调用者参数的 tools/call 请求，参数保持不变。上游在响应 initialize 时若返回 Mcp-Session-Id 标头，该值会随之后的 每个会话请求一同发送；该会话会在进程运行期间复用。 响应可能是普通 JSON，也可能是服务器发送事件；两种格式均会读取。

成功的上游结果会原样传递，包括上游设置的任何 isError 标记。 失败情况 - JSON-RPC 错误、非 2xx 状态码、无法读取的响应，或 无法完成的请求 - 会作为 isError 结果返回， 其文本以 formwire error: 开头（此错误呈现方式 是本次重建中自行添加并标注的内容）。

CLI

每个工具也可作为子命令调用，并接受一个 JSON 参数字符串（不需要参数的工具可省略）：

npx @reneturcios/formwire create_form '{"name":"Contact form","destinationEmail":"[email protected]"}'
npx @reneturcios/formwire get_snippet '{"framework":"react","formId":"frm_123"}'
npx @reneturcios/formwire list_forms
npx @reneturcios/formwire get_form '{"formId":"frm_123"}'
npx @reneturcios/formwire list_submissions '{"formId":"frm_123","folder":"inbox"}'
npx @reneturcios/formwire --version

退出代码：成功时为 0，结果为 isError 时为 1， 用法错误时为 2。

MCP 服务

npx -y @reneturcios/formwire mcp

MCP 客户端配置：

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

Docker

docker run -i ghcr.io/cloudcorprecords/formwire
docker run --rm ghcr.io/cloudcorprecords/formwire --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数会照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对桩接的 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT - 详见 LICENSE。