toolify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/toolify — Wire up an integration or MCP server

/toolify — 集成外部工具或MCP服务器

Interactive wizard for adding an external tool / API / MCP into a project. Ends with working code + env vars set + a verification path.

用于将外部工具/API/MCP集成到项目中的交互式向导。最终会生成可用代码、配置环境变量并提供验证路径。

Scope

适用范围

Primary stacks: Next.js (App Router + TypeScript) and Rails. Reason: those are the two stacks the user actually ships in; supporting every stack bloats the wizard.
What toolify handles: auth pattern (API key, OAuth, JWT, session cookie), env var setup, official SDK vs raw fetch, client wrapper location, example usage, webhook handling (if applicable), MCP
```
.mcp.json
```
wiring (if MCP server).
What toolify does NOT handle: writing business logic on top of the integration (that's for the human). It scaffolds the plumbing, not the feature.

主要技术栈：Next.js（App Router + TypeScript）和Rails。原因：这是用户实际使用的两大技术栈；支持所有技术栈会导致向导过于臃肿。
toolify负责的内容：认证模式（API密钥、OAuth、JWT、会话Cookie）、环境变量配置、官方SDK与原生fetch的选择、客户端包装器位置、示例用法、Webhook处理（如适用）、MCP的.mcp.json配置（如为MCP服务器）。
toolify不负责的内容：在集成之上编写业务逻辑（这需要人工完成）。它仅搭建基础架构，而非实现具体功能。

Step 0 — Get the tool name

步骤0 — 获取工具名称

Ask if not provided: "Which tool are we integrating?"

Detect category from name:

Category	Examples	Extra steps
Payments	Stripe, LemonSqueezy, Paddle	Webhook signature verification, customer model, event handlers
Auth	NextAuth/Auth.js, Clerk, Supabase Auth, Devise	Session management, protected routes, callbacks
Email	Resend, Postmark, SendGrid, Kit	From address, template setup, unsubscribe handling
CMS/DB	Sanity, Prisma, Drizzle, Neon, Supabase	Schema location, migration path, client singleton pattern
AI/LLM	Anthropic, OpenAI, Gemini, Vercel AI SDK	Model choice, streaming vs non-streaming, rate limits
Analytics	Fathom, PostHog, Plausible	Script placement, event tracking API
Scheduling/Comms	SavvyCal, Cal.com, Twilio, Riverside	Webhook events, embed patterns
Scraping	ScrapeCreators, Apify, Playwright	Rate limits, response caching, retry policy
Affiliate/Referral	Rewardful, PartnerStack	Cookie handling, webhook events, dashboard access
Storage	Vercel Blob, S3, R2	Bucket setup, signed URL pattern, presigned upload
MCP server	Any MCP — Sanity, Stripe, GitHub, Kit, etc.	`.mcp.json` entry + env vars, no client wrapper
Custom / other	Internal API, unknown tool	Ask more questions

If category detection fails, ask 2 questions to place it: "Is it an API you call, a webhook receiver, or both?" / "Does it have an official SDK?"

若未提供则询问："我们要集成哪个工具？"

根据名称检测类别：

类别	示例	额外步骤
支付类	Stripe, LemonSqueezy, Paddle	Webhook签名验证、客户模型、事件处理器
认证类	NextAuth/Auth.js, Clerk, Supabase Auth, Devise	会话管理、受保护路由、回调函数
邮件类	Resend, Postmark, SendGrid, Kit	发件人地址、模板配置、退订处理
CMS/数据库	Sanity, Prisma, Drizzle, Neon, Supabase	Schema位置、迁移路径、客户端单例模式
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、未知工具	询问更多问题

若类别检测失败，通过两个问题进行归类："它是需要调用的API、Webhook接收器，还是两者兼具？" / "它有官方SDK吗？"

Step 1 — Structural interview

步骤1 — 结构化访谈

Ask the following in order (skip questions that don't apply based on category):

Which project? (path — infer from cwd; ask if ambiguous)
Which stack? (Next.js / Rails — infer from
```
package.json
```
vs
```
Gemfile
```
; ask if both)
Auth pattern? (API key / OAuth / JWT / session cookie / signed webhooks — usually knowable from official docs)
Official SDK exists? (check the docs; prefer SDK when good; fall back to raw fetch when SDK is bloated/abandoned)
Env var name convention? (default:
```
SCREAMING_SNAKE_CASE
```
matching official convention — e.g.,
```
STRIPE_SECRET_KEY
```
,
```
RESEND_API_KEY
```
)
Environments? (dev / preview / prod — different keys?)
Webhook receiver needed? (YES for Stripe/Rewardful/most payment+auth+CMS; NO for pure client-side or read-only APIs)
Rate limits to respect? (grep official docs)
Where does the client wrapper live? (default:
```
src/lib/<tool>.ts
```
for Next.js;
```
app/services/<tool>_client.rb
```
for Rails)

Show the user the answers as a summary before scaffolding — one chance to correct before writing files.

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

哪个项目？（路径——从当前工作目录推断；若有歧义则询问）
哪个技术栈？（Next.js / Rails——从
```
package.json
```
或
```
Gemfile
```
推断；若两者都存在则询问）
认证模式？（API密钥 / OAuth / JWT / 会话Cookie / 签名Webhook——通常可从官方文档得知）
是否存在官方SDK？（查阅文档；优先使用优质SDK；若SDK臃肿或已废弃则使用原生fetch）
环境变量命名规范？（默认：与官方规范一致的大写蛇形命名——例如
```
STRIPE_SECRET_KEY
```
、
```
RESEND_API_KEY
```
）
环境类型？（开发/预览/生产——是否需要不同密钥？）
是否需要Webhook接收器？（Stripe/Rewardful等多数支付、认证、CMS工具需要；纯客户端或只读API不需要）
是否需要遵守速率限制？（查阅官方文档）
客户端包装器存放位置？（默认：Next.js存于
```
src/lib/<tool>.ts
```
；Rails存于
```
app/services/<tool>_client.rb
```
）

在生成文件前向用户展示答案摘要——提供一次修正机会。

Step 2 — Fetch official setup docs

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

Use

WebFetch

context7:query-docs

to pull the current official quickstart:

bash

undefined

使用

WebFetch

或

context7:query-docs

获取最新的官方快速入门文档：

bash

undefined

Prefer context7 if available (fresher docs than training data)

优先使用context7（文档比训练数据更新）

Skill({skill: "compound-engineering:context7", ...})

Fallback to WebFetch

备用方案：WebFetch

WebFetch <official-quickstart-url>


Read *once*, then work from cached content. Don't re-fetch mid-scaffold. Note the SDK version cited so `package.json` gets the right pin.

WebFetch <official-quickstart-url>


仅读取一次，之后使用缓存内容。生成过程中不再重新获取。记录文档中引用的SDK版本，确保`package.json`中使用正确的版本号。

Step 3 — Scaffold files

步骤3 — 生成文件模板

For a standard Next.js integration, generate:

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

For 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

For an MCP server, only:

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

Every scaffolded file should have a comment at the top like:

typescript

// 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.

对于标准Next.js集成，生成以下文件：

src/lib/<tool>.ts                    # 客户端单例+类型化包装器
src/app/api/webhooks/<tool>/route.ts # Webhook处理器（如适用）
src/app/api/<tool>/example/route.ts  # 一个可用的示例路由
.env.local.example                    # 带占位符的环境变量模板

对于Rails项目：

config/initializers/<tool>.rb        # SDK配置
app/services/<tool>_client.rb        # 客户端包装器
app/controllers/webhooks/<tool>_controller.rb  # Webhook处理器（如适用）
config/routes.rb                      # Webhook路由
.env.example                          # 环境变量模板

对于MCP服务器，仅生成：

.mcp.json                             # 添加或更新新的服务器条目
.env.local                            # 添加MCP所需的环境变量

每个生成的文件顶部需添加如下注释：

typescript

// 由/toolify于2026-06-30生成。官方文档：<url>。SDK版本：<version>。
// 客户端包装器仅负责基础架构——业务逻辑需另行编写。

Step 4 — Auth pattern implementation

步骤4 — 实现认证模式

Apply the right auth pattern per tool category. Never invent — use the pattern the official docs specify. Common patterns:

API key in header:
```
Authorization: Bearer <key>
```
or
```
X-<Vendor>-Key: <key>
```
— check vendor's exact spelling
Webhook signature: use the vendor's crypto method (Stripe uses HMAC-SHA256; Rewardful uses similar). NEVER skip signature verification on webhooks — it's the #1 security bug in scaffolded integrations.
OAuth: redirect URL setup, token storage, refresh handling. Prefer Auth.js/NextAuth for Next.js; Devise + omniauth for Rails.
Signed URL / presigned: for uploads / temp access — set expiration explicitly, never use unbounded.

根据工具类别应用正确的认证模式。切勿自行发明——严格遵循官方文档指定的模式。常见模式：

请求头中的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/预签名：用于上传/临时访问——需明确设置过期时间，绝不使用无期限的签名。

Step 5 — Env var setup

步骤5 — 环境变量配置

Add to the appropriate file:

Local dev:
```
.env.local
```
(Next.js) /
```
.env
```
(Rails) — NEVER committed
Vercel: sensitivity depends on the var. Two rules — apply the right one:
- Public / bundle-baked vars (
  NEXT_PUBLIC_*
  ) — these get inlined into the client bundle at build time and are ALREADY public. Use
```
--no-sensitive
```
  so you can audit them later:
  bash
```
vercel env add NEXT_PUBLIC_APP_URL production --value "<url>" --no-sensitive --yes
```
- Server-side secrets (API keys, webhook secrets, DB URLs) — never enter the client bundle. Use Vercel's default
```
--sensitive
```
  behavior so the value is write-only via the CLI (can't be read back via
```
vercel env pull
```
  ):
  bash
```
vercel env add STRIPE_SECRET_KEY production --value "<key>" --sensitive --yes
vercel env add STRIPE_WEBHOOK_SECRET production --value "<secret>" --sensitive --yes
```
- The rule: only
```
NEXT_PUBLIC_*
```
  uses
```
--no-sensitive
```
  . Everything else uses
```
--sensitive
```
  . Getting this wrong means server secrets are readable via
```
vercel env pull
```
  in someone's local terminal — same class of leak as committing them.
- See
```
references/vercel-env-vars.md
```
  for the full policy + verification via
```
vercel env pull
```
  + brackets-check.

Heroku:

heroku config:set <VAR>=<value> -a <app-name>

Also update

.env.example

.env.local.example

with the placeholder so teammates know the var is needed.

添加至对应文件：

本地开发：
```
.env.local
```
（Next.js）/
```
.env
```
（Rails）——绝不能提交到版本控制
Vercel：根据变量敏感性选择规则，应用以下其中一条：
- 公开/打包内置变量（
  NEXT_PUBLIC_*
  ）——这些变量会在构建时内联到客户端包中，本身已是公开的。使用
```
--no-sensitive
```
  以便后续审计：
  bash
```
vercel env add NEXT_PUBLIC_APP_URL production --value "<url>" --no-sensitive --yes
```
- 服务端密钥（API密钥、Webhook密钥、数据库URL）——绝不能进入客户端包。使用Vercel默认的
```
--sensitive
```
  模式，确保值仅能通过CLI写入（无法通过
```
vercel env pull
```
  读取）：
  bash
```
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

，添加占位符以便团队成员了解所需变量。

Step 6 — Smoke test

步骤6 — 冒烟测试

Generate a one-line verification the user can run:

bash

undefined

生成一条用户可执行的验证命令：

bash

undefined

Example for a REST API:

REST API示例：

curl -H "Authorization: Bearer $STRIPE_SECRET_KEY" https://api.stripe.com/v1/customers?limit=1

Example for an SDK:

SDK示例：

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

For MCP: restart Claude Code, run any command that touches the MCP server

MCP示例：重启Claude Code，运行任何涉及该MCP服务器的命令


Show the expected output shape. If the call fails, the wizard should be first to catch it, not the user in prod.


展示预期的输出格式。若调用失败，向导应首先发现问题，而非等到用户在生产环境中遇到。

Step 7 — Report + follow-ups

步骤7 — 报告与后续操作

Report:

Files created (paths)
Env vars added (names only — never values in the report)
SDK/dependency added to
```
package.json
```
/
```
Gemfile
```
Smoke-test command run + result
Any TODOs the user needs to complete manually (e.g., "add webhook URL to <vendor> dashboard")

Offer:

"Set up a
loopify
cron to check the webhook is still receiving events daily?"
"Save this integration recipe as a skill via
skillify from-chat
?"
"Commit these changes now?"

报告内容：

创建的文件（路径）
添加的环境变量（仅名称——报告中绝不包含值）
添加到
```
package.json
```
/
```
Gemfile
```
的SDK/依赖
冒烟测试命令执行结果
用户需手动完成的待办事项（例如："将Webhook URL添加到<厂商>仪表盘"）

提供后续选项：

"是否设置
loopify
定时任务，每日检查Webhook是否仍在接收事件？"
"是否通过
skillify from-chat
将此集成流程保存为skill？"
"是否立即提交这些更改？"

Reference — integration recipes

参考——集成流程模板

Full recipes for common tools live in

references/

(populate as they're used):

```
references/stripe-nextjs.md
```
— payment integration + webhook + customer portal
```
references/kit-nextjs.md
```
— Kit (ConvertKit) MCP + subscriber API
```
references/sanity-nextjs.md
```
— Sanity CMS + MCP + Studio embed
```
references/anthropic-nextjs.md
```
— Claude API + streaming + rate limits
```
references/scrapecreators-nextjs.md
```
— social scraping API + retry policy
```
references/rewardful-nextjs.md
```
— referral tracking + webhook events

If a recipe doesn't exist yet, the wizard fetches the official docs, scaffolds fresh, and offers to save the recipe as

${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/toolify/recipes/<tool>-<stack>.md

for reuse (never inside the skill folder — upgrades wipe it). When looking up recipes, check both

references/

(shipped) and the config recipes dir (yours).

常见工具的完整流程模板存于

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

以便复用（绝不能存于skill文件夹——升级会覆盖）。查找模板时，需同时检查

references/

（内置）和配置模板目录（自定义）。

Composes with

可组合功能

skillify
— sibling in
```
-ify
```
trifecta. Use
```
skillify
```
when the goal is a new SKILL.md, not an integration.
loopify
— sibling. Use
```
loopify
```
for setting up cron/agent-loop patterns on top of the toolified integration (e.g., poll a webhook, sync data daily).
compound-engineering:context7
— fetch current SDK docs (fresher than training data).
makerskills:watch-video
— if the user has a Loom of an integration walkthrough, feed it in to synthesize the recipe.

skillify
— -ify三部曲的姊妹功能。若目标是创建新的SKILL.md文件，请使用
```
skillify
```
，而非本功能。
loopify
— 姊妹功能。若要在已集成的工具之上设置定时任务/代理循环（例如：轮询Webhook、每日同步数据），请使用
```
loopify
```
。
compound-engineering:context7
— 获取最新的SDK文档（比训练数据更新）。
makerskills:watch-video
— 若用户有集成流程的Loom视频，可传入视频以生成对应模板。

Notes on quality

质量注意事项

Never skip webhook signature verification. Even for internal-only endpoints. The vendor provides the crypto pattern for a reason.
Never commit secrets.
```
.env.local
```
and
```
.env
```
are gitignored — verify before finishing.
Never invent auth patterns. Use the vendor's official pattern verbatim. If docs are unclear, fetch again.
SDK version matters. Pin the SDK version in
```
package.json
```
/
```
Gemfile.lock
```
. Note the version in the file header comment.
One tool per invocation. Don't scaffold Stripe + Kit + Sanity in one run. Wizard is designed for depth per tool, not breadth.
Prefer official SDKs unless they're bloated/abandoned. Raw fetch is fine when the SDK adds no value.
Recipe-first for repeat tools. If integrating a tool the user has done before, load the recipe from
```
references/
```
or
```
$MAKERSKILLS_CONFIG/toolify/recipes/
```
and adapt, don't re-derive.

绝不能跳过Webhook签名验证。即使是仅内部使用的端点也需验证。厂商提供加密模式是有原因的。
绝不能提交密钥。
```
.env.local
```
和
```
.env
```
已被Git忽略——完成前请确认。
绝不能自行发明认证模式。严格遵循厂商的官方模式。若文档不清晰，重新获取文档。
SDK版本很重要。在
```
package.json
```
/
```
Gemfile.lock
```
中固定SDK版本。在文件顶部注释中记录版本号。
每次仅集成一个工具。不要在一次运行中同时生成Stripe+Kit+Sanity的集成代码。向导设计为针对单个工具进行深度集成，而非批量处理。
优先使用官方SDK，除非SDK臃肿或已废弃。若SDK无附加价值，使用原生fetch即可。
重复工具优先使用模板。若用户之前集成过某工具，从
```
references/
```
或
```
$MAKERSKILLS_CONFIG/toolify/recipes/
```
加载模板并调整，而非重新生成。