formchime

formchime

formchime 是一个小型本地桥接程序，可连接 Formgong 托管的 MCP 服务，用于管理网站的联系表单： 创建表单、将现成的嵌入代码片段粘贴到 页面中、查看收到的提交，并设置 Webhook，以便每次有新提交时，也会以带签名的 JSON 形式发送到你自己的端点。

该桥接程序不维护自己的工作区。它会在本地提供上游 服务的工具列表，内容与从实时端点捕获的完全一致， 并将每次工具调用转发到上游，再原样返回结果。表单和 Webhook 的变更会作用于调用者自己的 Formgong 工作区；列表和提交工具仅用于读取。

工具

• list_forms — 账号拥有的所有表单：id、 名称、公共访问密钥（fk_…）以及本月的提交数。访问密钥需放在表单的隐藏 access_key 字段中。不需要参数。
• create_form — 创建新表单。必填：name （显示在控制面板和邮件主题中，1-80 个字符）。可选：notify_email（默认为 true）。 返回表单 id 和公共访问密钥。
• get_form_snippet — 某个表单可直接粘贴使用的代码， 包含其访问密钥、隐藏的 _lang 字段、 botcheck 蜜罐，以及启用时显示的 Turnstile 小组件。 必填：form_id。可选：framework（html、 react 或 next，默认为 html）和 lang。
• list_recent_submissions — 某个表单的最新提交： 仅包含 id、时间和提交的字段，不含 IP 或浏览器数据。必填： form_id。可选：limit（1-50，默认为 10）和 include_spam（默认为 false）。
• list_webhooks — 某个表单的 Webhook URL：id、 URL 和创建时间。必填：form_id。
• create_webhook — 为某个表单添加公开的 HTTPS URL；此后每次有新提交，都会以 JSON 形式 POST 到该 URL，并附带 X-Signature 标头（使用表单的签名密钥对原始正文进行 HMAC-SHA256 计算）。 必填：form_id 和 url。返回 Webhook id 和签名密钥。
• delete_webhook — 从表单中移除一个 Webhook； 不再向其 URL 发送提交内容。必填： form_id 和 webhook_id。
• list_website_templates — Formgong 免费、 采用 MIT 许可的网站模板，每个模板都已配置好联系表单或 报价表单，并连接到 Formgong。可选： topic（trades、consulting、portfolio、 construction、health、food 或 shops）。

配置

• FORMGONG_MCP_URL（可选）— 覆盖上游 端点。默认为 https://formgong.com/mcp。 （此覆盖钩子是本次重建中自行标注的 重构内容。）
• FORMGONG_API_KEY（可选）— 设置后，每个 上游请求都会携带 Authorization: Bearer <key> 标头，供使用个人 API 令牌而非 OAuth 的客户端使用。若未设置， 则不发送认证标头；捕获的原始接口不需要密钥。 （此转发功能也是本次重建中自行标注的重构内容。）

转发机制

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

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

CLI

每个工具也都是一个子命令，接收一个 JSON 参数 字符串（不需要参数的工具可省略）：

npx @reneturcios/formchime list_forms
npx @reneturcios/formchime create_form '{"name":"Contact – acme.com"}'
npx @reneturcios/formchime get_form_snippet '{"form_id":"f_123","framework":"react"}'
npx @reneturcios/formchime list_recent_submissions '{"form_id":"f_123","limit":5}'
npx @reneturcios/formchime create_webhook '{"form_id":"f_123","url":"https://example.com/hook"}'
npx @reneturcios/formchime --version

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

MCP 服务

npx -y @reneturcios/formchime mcp

MCP 客户端配置：

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

Docker

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

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

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对存根 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。