Ikiform

面向 Claude Code 和其他 Agent 的 Ikiform

Ikiform 是任何表单的后端。将 HTML 表单、框架表单或服务器请求指向 https://ikiform.com/f/<formId>。Ikiform 会验证提交内容、拦截垃圾信息、存储提交内容并发送经过签名的 Webhook。

此仓库包含两部分：

• 一个 Agent Skill（ikiform），用于教会编码 Agent 将表单连接到 Ikiform、从服务器提交、验证 Ikiform Webhook 并对提交内容进行分类。它适用于 Claude Code 以及任何能读取 SKILL.md 技能的 Agent。
• 一个 Claude Code 插件，将该技能与 Ikiform MCP 服务打包在一起，让 Agent 能查找并创建表单、读取提交内容以及调试 Webhook。

在 Claude Code 中安装

在 Claude Code 会话中：

/plugin marketplace add preetsuthar17/ikiform-plugin
/plugin install ikiform@ikiform

或者在 Shell 中运行：

claude plugin marketplace add preetsuthar17/ikiform-plugin
claude plugin install ikiform@ikiform

设置 API 密钥

插件的 MCP 服务会从 IKIFORM_API_KEY 环境变量读取密钥。

1. 在 https://ikiform.com/dashboard/api-keys 创建一个密钥。

2. 为其授予你希望 Agent 拥有的权限范围：

   权限范围	Agent 可执行的操作
   forms:read	列出表单，并读取表单的端点、字段和设置步骤
   forms:write	创建表单，以及更改名称、允许的域名或重定向 URL
   submissions:read	列出并读取提交内容
   submissions:write	将提交内容标记为垃圾或非垃圾，并删除提交内容
   webhooks:read	列出 Webhook 端点和传送记录
   webhooks:write	发送测试事件并重新传送失败的记录

   forms:read 足以将表单接入你的代码。只有在希望 Agent 执行更多操作时才添加其他权限。

3. 在启动 Claude Code 的 Shell 中导出密钥，例如添加到 ~/.zshrc：

   export IKIFORM_API_KEY=ik_sk_...
   

4. 启动 Claude Code 并运行 /mcp。服务会显示为 plugin:ikiform:ikiform。

该密钥属于机密。请将其保存在 Shell 配置文件或密钥管理器中，切勿放入代码仓库或浏览器代码中。

该技能无需密钥也能使用。没有密钥时，Agent 会要求你提供控制面板中的表单 ID，而不会自行查找。

使用方法

用日常语言提出请求，例如：

• “将此项目中的联系表单连接到 Ikiform。”
• “在落地页添加一个候补名单表单，并将其提交到 Ikiform。”
• “在我们的 Express 服务器中验证 Ikiform Webhook。”
• “显示联系表单本周的垃圾提交。”
• “我的 Ikiform Webhook 为什么失败？”

或者直接使用 /ikiform:ikiform 运行该技能。

删除提交内容或重新传送 Webhook 记录前，Agent 会先征求你的确认。

在其他 Agent 中使用该技能

该技能是一个普通的 Agent Skills 文件夹：plugins/ikiform/skills/ikiform/。将它复制到你的 Agent 技能目录中。

通过 skills CLI，可用于 Claude Code、Cursor、Codex 和其他 Agent：

npx skills add preetsuthar17/ikiform-plugin

不使用插件的 Claude Code：

git clone https://github.com/preetsuthar17/ikiform-plugin ikiform-plugin
mkdir -p ~/.claude/skills
cp -R ikiform-plugin/plugins/ikiform/skills/ikiform ~/.claude/skills/ikiform

也可以在项目中使用 .claude/skills/ikiform，与团队共享该技能。对于其他 Agent，将同一文件夹复制到该 Agent 读取技能的目录中。该技能的 frontmatter 仅使用 name、description 和 license，因此可移植性良好。

不使用插件连接 MCP 服务

服务地址：https://ikiform.com/mcp，使用 Streamable HTTP，通过 Authorization: Bearer ik_sk_... 进行身份验证。

Claude Code

claude mcp add --transport http ikiform https://ikiform.com/mcp --header "Authorization: Bearer ik_sk_..."

Cursor

在 ~/.cursor/mcp.json 中，或在项目中的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "ikiform": {
      "url": "https://ikiform.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:IKIFORM_API_KEY}"
      }
    }
  }
}

VS Code

在 .vscode/mcp.json 中。VS Code 首次使用时会要求输入密钥，并安全地保存该密钥：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ikiform-api-key",
      "description": "Ikiform secret API key (ik_sk_...)",
      "password": true
    }
  ],
  "servers": {
    "ikiform": {
      "type": "http",
      "url": "https://ikiform.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ikiform-api-key}"
      }
    }
  }
}

工具

完整的工具列表及各工具所需的权限范围，请访问 https://ikiform.com/docs/mcp#tools。

该服务还提供 connect_form 提示词，可返回表单设置步骤。

目录结构

.claude-plugin/marketplace.json        the "ikiform" marketplace
plugins/ikiform/
  .claude-plugin/plugin.json           plugin manifest
  .claude-plugin/icon.png              listing icon
  .mcp.json                            the Ikiform MCP server
  skills/ikiform/SKILL.md              the skill
  skills/ikiform/references/*.md       detail the skill loads when needed
server.json                            MCP Registry listing
glama.json                             Glama listing
.github/workflows/publish-mcp.yml      publishes server.json to the MCP Registry
scripts/check.mjs                      offline checks

检查更改

已安装 Claude Code 时：

claude plugin validate --strict .
claude plugin validate --strict ./plugins/ikiform

未安装 Claude Code，或在 CI 中时，运行离线检查。这些检查需要 Node 20 或更高版本，且无需安装软件包：

node scripts/check.mjs

它们会检查每个 JSON 文件是否能解析、SKILL.md 是否具有符合 Agent Skills 限制的有效 name 和 description、其中的相对链接是否有效，以及市场条目是否与插件清单一致。

发布前尝试本地副本：

claude plugin marketplace add ./
claude plugin install ikiform@ikiform

文档

• Ikiform 文档：https://ikiform.com/docs
• 面向 Agent 的所有 Markdown 文档：https://ikiform.com/llms.txt
• 支持：[email protected]

许可证

MIT。请参阅 LICENSE。