toolify

/toolify — 接入集成服务或 MCP 服务

用于将外部工具、API 或 MCP 接入项目的交互式向导。完成后会生成可用代码、设置好环境变量，并提供验证方式。

范围

• 主要技术栈：Next.js（App Router + TypeScript）和 Rails。原因：用户实际交付的项目只用这两种技术栈；支持所有技术栈会让向导臃肿。
• toolify 处理的内容：身份验证模式（API 密钥、OAuth、JWT、会话 Cookie）、环境变量设置、官方 SDK 与原始 fetch 的选择、客户端封装代码的位置、使用示例、Webhook 处理（如适用）、MCP .mcp.json 配置（如果是 MCP 服务）。
• toolify 不处理的内容：在集成服务之上编写业务逻辑（这应该由人来完成）。它搭建的是基础设施，而不是功能。

步骤 0 — 获取工具名称

如果用户未提供，则询问：“我们要集成哪个工具？”

根据名称判断类别：

类别	示例	额外步骤
支付	Stripe、LemonSqueezy、Paddle	Webhook 签名验证、客户模型、事件处理器
身份验证	NextAuth/Auth.js、Clerk、Supabase Auth、Devise	会话管理、受保护路由、回调
电子邮件	Resend、Postmark、SendGrid、Kit	发件人地址、模板设置、退订处理
CMS/数据库	Sanity、Prisma、Drizzle、Neon、Supabase	架构位置、迁移路径、客户端单例模式
AI/大模型	Anthropic、OpenAI、Gemini、Vercel AI SDK	模型选择、流式与非流式处理、速率限制
分析	Fathom、PostHog、Plausible	脚本放置位置、事件跟踪 API
日程安排/通信	SavvyCal、Cal.com、Twilio、Riverside	Webhook 事件、嵌入模式
数据抓取	ScrapeCreators、Apify、Playwright	速率限制、响应缓存、重试策略
联盟营销/推荐	Rewardful、PartnerStack	Cookie 处理、Webhook 事件、控制面板访问
存储	Vercel Blob、S3、R2	存储桶设置、签名 URL 模式、预签名上传
MCP 服务	任意 MCP 服务 — Sanity、Stripe、GitHub、Kit 等	添加 .mcp.json 条目和环境变量，不需要客户端封装
自定义/其他	内部 API、未知工具	进一步提问

如果无法判断类别，则问 2 个问题来确定：“这是你要调用的 API、Webhook 接收器，还是两者都有？” / “它有官方 SDK 吗？”

步骤 1 — 结构性访谈

按以下顺序提问（根据类别跳过不适用的问题）：

1. 哪个项目？（路径 — 根据 cwd 推断；如果不明确则询问）
2. 使用哪种技术栈？（Next.js / Rails — 根据 package.json 和 Gemfile 推断；如果两者都有则询问）
3. 身份验证模式？（API 密钥 / OAuth / JWT / 会话 Cookie / 签名 Webhook — 通常可从官方文档中获知）
4. 是否有官方 SDK？（查看文档；优先使用质量良好的 SDK；如果 SDK 臃肿或已弃用，则改用原始 fetch）
5. 环境变量命名约定？（默认：采用与官方约定一致的 SCREAMING_SNAKE_CASE — 例如 STRIPE_SECRET_KEY、RESEND_API_KEY）
6. 使用哪些环境？（开发 / 预览 / 生产 — 是否使用不同的密钥？）
7. 是否需要 Webhook 接收器？（Stripe/Rewardful/大多数支付、身份验证和 CMS 集成需要；纯客户端或只读 API 不需要）
8. 需要遵守哪些速率限制？（检索官方文档）
9. 客户端封装代码放在哪里？（默认：Next.js 使用 src/lib/<tool>.ts；Rails 使用 app/services/<tool>_client.rb）

在搭建代码前，先向用户展示答案摘要，让用户有一次机会在写入文件前进行更正。

步骤 2 — 获取官方设置文档

获取当前版本的官方快速入门文档。如果你的 Agent 支持 context7，优先使用它（文档比训练数据更新）；否则，使用 Agent 的 URL 获取工具（Claude Code 中的 WebFetch）或 curl 获取官方快速入门 URL。

只读取一次，之后使用缓存内容进行操作。搭建过程中不要重新获取文档。记下文档中注明的 SDK 版本，以便在 package.json 中指定正确的版本。

步骤 3 — 搭建脚手架文件

对于标准 Next.js 集成，生成：

src/lib/<tool>.ts                    # client singleton + typed wrappers
src/app/api/webhooks/<tool>/route.ts # webhook handler (if applicable)
src/app/api/<tool>/example/route.ts  # one working example route
.env.local.example                    # env var template with placeholder values

对于 Rails：

config/initializers/<tool>.rb        # SDK config
app/services/<tool>_client.rb        # client wrapper
app/controllers/webhooks/<tool>_controller.rb  # webhook handler if applicable
config/routes.rb                      # webhook route
.env.example                          # env vars

对于 MCP 服务，仅生成：

.mcp.json                             # add or update with the new server entry
.env.local                            # add the env vars the MCP needs

每个搭建脚手架的文件顶部都应有类似这样的注释：

// Scaffolded by /toolify on 2026-06-30. Official docs: <url>. SDK version: <version>.
// The client wrapper is scoped to plumbing only — business logic lives elsewhere.

步骤 4 — 实现身份验证模式

根据工具类别应用正确的身份验证模式。切勿自行臆造——应使用官方文档指定的模式。常见模式：

• 标头中的 API 密钥：Authorization: Bearer <key> 或 X-<Vendor>-Key: <key> — 请核对供应商规定的确切拼写
• Webhook 签名：使用供应商的加密方法（Stripe 使用 HMAC-SHA256；Rewardful 使用类似方法）。绝不能跳过 Webhook 的签名验证——这是搭建脚手架的集成中最常见的安全漏洞。
• OAuth：设置重定向 URL、存储令牌并处理令牌刷新。Next.js 优先使用 Auth.js/NextAuth；Rails 优先使用 Devise + omniauth。
• 签名 URL / 预签名 URL：用于上传 / 临时访问——明确设置过期时间，绝不要设为无限期。

步骤 5 — 设置环境变量

添加到相应文件：

• 本地开发：.env.local（Next.js）/ .env（Rails）——绝不能提交到版本库
• Vercel：是否敏感取决于变量。请遵循以下两条规则，选择正确的方式：
  • 公开变量 / 构建时内嵌变量（NEXT_PUBLIC_*）——这些变量会在构建时内嵌到客户端包中，因此本来就是公开的。使用 --no-sensitive，方便之后审计：

    vercel env add NEXT_PUBLIC_APP_URL production --value "<url>" --no-sensitive --yes
    

  • 服务器端机密（API 密钥、Webhook 机密、数据库 URL）——这些变量不会进入客户端包。使用 Vercel 默认的 --sensitive 行为，使该值只能通过 CLI 写入（无法通过 vercel env pull 读回）：

    vercel env add STRIPE_SECRET_KEY production --value "<key>" --sensitive --yes
    vercel env add STRIPE_WEBHOOK_SECRET production --value "<secret>" --sensitive --yes
    

  • 规则：只有 NEXT_PUBLIC_* 使用 --no-sensitive。其他所有变量都使用 --sensitive。设置错误会导致服务器机密可通过某人本地终端中的 vercel env pull 读取——这与将其提交到版本库属于同类泄露。
  • 完整策略以及通过 vercel env pull + 括号检查进行验证的方法，请参阅 references/vercel-env-vars.md。
• Heroku：heroku config:set <VAR>=<value> -a <app-name>

同时更新 .env.example / .env.local.example，添加占位符，让团队成员知道需要设置该变量。

步骤 6 — 冒烟测试

生成一条用户可以运行的单行验证命令：

# Example for a REST API:
curl -H "Authorization: Bearer $STRIPE_SECRET_KEY" https://api.stripe.com/v1/customers?limit=1

# Example for an SDK:
node -e "const s = require('./src/lib/stripe.ts').default; s.customers.list({limit:1}).then(console.log)"

# For MCP: restart your agent so it reloads MCP config, run any command that touches the MCP server

展示预期的输出格式。如果调用失败，应由向导先发现问题，而不是让用户在生产环境中发现。

步骤 7 — 报告与后续事项

报告：

• 创建的文件（路径）
• 添加的环境变量（仅名称——报告中绝不包含值）
• 添加到 package.json / Gemfile 的 SDK/依赖项
• 运行的冒烟测试命令及结果
• 用户需要手动完成的待办事项（例如：“将 Webhook URL 添加到 控制面板”）

提供以下选项：

• “要设置一个 loopify cron，每天检查 Webhook 是否仍在接收事件吗？”
• “要通过 skillify from-chat 将此集成方案保存为 skill 吗？”
• “现在提交这些更改吗？”

参考 — 集成方案

常见工具的完整方案位于 references/ 中（使用时填充）：

• references/stripe-nextjs.md — 支付集成 + webhook + 客户门户
• references/kit-nextjs.md — Kit (ConvertKit) MCP + 订阅者 API
• references/sanity-nextjs.md — Sanity CMS + MCP + Studio 嵌入
• references/anthropic-nextjs.md — Claude API + 流式传输 + 速率限制
• references/scrapecreators-nextjs.md — 社交媒体抓取 API + 重试策略
• references/rewardful-nextjs.md — 推荐跟踪 + webhook 事件

如果方案尚不存在，向导会获取官方文档、搭建全新方案，并提供将方案保存到 ${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/toolify/recipes/<tool>-<stack>.md 以供复用的选项（切勿保存到技能文件夹中——升级时会清除该文件夹）。查找方案时，请同时检查 references/（随附）和配置目录中的 recipes。

可组合使用

• skillify — -ify 三件套中的同伴工具。如果目标是创建新的 SKILL.md，而非集成，请使用 skillify。
• loopify — 同伴工具。使用 loopify 在工具化集成的基础上设置 cron/Agent 循环模式（例如，轮询 webhook、每天同步数据）。
• compound-engineering:context7 — 获取最新 SDK 文档（比训练数据更新）。
• makerskills:watch-video — 如果用户有集成演示的 Loom 视频，将其输入以合成方案。

质量注意事项

• 绝不跳过 webhook 签名验证。 即使是仅供内部使用的端点也不例外。供应商提供加密模式自有其理由。
• 绝不提交密钥。 .env.local 和 .env 已加入 gitignore——完成前请确认。
• 绝不臆造身份验证模式。 原样采用供应商的官方模式。如果文档不清楚，请重新获取。
• SDK 版本很重要。 在 package.json / Gemfile.lock 中固定 SDK 版本，并在文件头注释中注明版本。
• 每次调用只处理一个工具。 不要在一次运行中同时搭建 Stripe、Kit 和 Sanity。向导的设计目标是深入处理单个工具，而非广泛处理多个工具。
• 优先使用官方 SDK，除非它们臃肿或已被弃用。如果 SDK 没有带来价值，直接使用原始 fetch 也可以。
• 重复集成的工具优先使用方案。 如果用户要集成之前用过的工具，请从 references/ 或 $MAKERSKILLS_CONFIG/toolify/recipes/ 加载方案并进行调整，不要重新推导。