mockanything

Mock Anything

在你的机器上用一条命令运行 API 的可用孪生服务。无需密钥、无需注册沙盒，也无需付费。

npx @shipatmidnight/mockanything stripe
# → Stripe twin running at http://localhost:4010/v1

将你的应用或 Agent 指向该 URL，而非真实 API；对于它支持的流程，其行为就像真实 API 一样：创建客户、使用测试卡扣款、接收签名 Webhook、退款。这一切都不是真实操作，你的应用调用也永远不会到达真实服务提供商。

Mock Anything 适用于大多数公共 API，而不只是固定列表中的 API（在我们的 2026-10-29 测量中，public APIs.guru 目录里的每个 API 最初都作为孪生服务运行）：

npx @shipatmidnight/mockanything stripe                          # a hand-tuned pack
npx @shipatmidnight/mockanything ./openapi.yaml                  # your own OpenAPI / Swagger file
npx @shipatmidnight/mockanything https://example.com/openapi.json
npx @shipatmidnight/mockanything slack                           # any name in the public APIs.guru directory (2,500+ APIs)

为什么

Agent 每天都在编写调用支付、短信、电子邮件和开发者 API 的代码。如今要测试这些代码，就得使用真实密钥（Agent 可能会花钱或给真人发短信）、沙盒（每个服务提供商都要有账户和密钥，而且许多地区性服务提供商几乎没有沙盒），或者手写模拟，而模拟会在 Agent 做出你没预料到的操作时失效。

孪生服务与模拟不同：

• 它会保留状态。 POST 创建客户，然后 GET 获取该客户。退款后，剩余余额会变化。删除某项内容后，它就不复存在。
• 它的行为与服务提供商一致。 真实的 ID 格式、列表分页、错误结构、状态生命周期（requires_payment_method → succeeded、queued → sent → delivered）。
• 它会发送 Webhook，并按照服务提供商的方式签名，因此你的验证代码无需改动即可运行。
• 它能处理棘手情况： 被拒绝的卡、3-D Secure、退回的电子邮件、无法送达的短信、重复引用、速率限制。
• 混乱模式（--chaos）会添加超时、5xx 错误、429 错误、慢响应、重复和乱序的 Webhook。故障会使用固定种子，因此可以重放遇到的故障。

内置包

经过精心调校的孪生服务，并在我们的测试套件中对照各服务提供商的官方 SDK 进行验证。

包	流程	测试值
stripe	客户、PaymentIntents（确认、手动扣款、取消）、退款、Checkout Sessions、Webhook 端点、事件	pm_card_visa、pm_card_chargeDeclined、pm_card_chargeDeclinedInsufficientFunds、pm_card_threeDSecure2Required …
paystack	初始化 → 测试结账页面 → 验证、使用已保存的卡扣款、客户、退款	在本地测试页面上选择批准/拒绝
twilio	发送短信、状态回调（queued → sent → delivered）、获取、列出、删除	+15005550001（无效）、+15005550002（无法路由）、+15005550004（已退订）…
resend	发送、检索、列出、安排、取消；送达、退信和投诉事件	[email protected]、[email protected]、[email protected]
github	仓库、议题（打开、编辑、关闭、重新打开）、评论、拉取请求（打开、合并）	任意 owner/repo 均可使用，且初始为空
openai	Chat completions 和 Responses API，支持流式或非流式；embeddings；模型。回复为预设内容，并以 [mock] 开头；不会运行模型	场景 tool_call、rate_limit、insufficient_quota、context_length_exceeded、server_error
anthropic	Messages，支持流式或非流式，并支持工具调用；令牌计数；模型。回复为预设内容，并以 [mock] 开头；不会运行模型	场景 tool_use、rate_limit、overloaded、invalid_request、api_error

mockanything env <pack> 会打印用于将官方 SDK 指向孪生服务的代码片段，例如：

const stripe = new Stripe("sk_test_mockanything", { host: "localhost", port: 4010, protocol: "http" });

其他任何 API

向 Mock Anything 提供 OpenAPI 3.x 或 Swagger 2.0 描述（文件、URL，或只提供 API 名称），它就会读取规范并构建一个有状态的孪生体：

• /things + /things/{id} 会变成一个集合，你可以创建、列出、读取、更新和删除其中的对象；
• /things/{id}/cancel 这类路径会变成状态变更，并与对象的 status 值匹配；
• 嵌套路径会进行范围限定（一个仓库中的 issue 不会出现在另一个仓库中）；
• 响应封装、分页方式、错误格式、身份验证和 OAS 3.1 Webhook 都会从规范中读取；
• 规范未描述的路径仍可作为通用 REST 使用（标记为 x-mockanything-fallback）；
• 只读资源（API 中没有任何操作会创建它们）会返回按规范构造的虚构示例对象，因此查询和列表不会为空。

查看推断结果并进行修改：

npx @shipatmidnight/mockanything inspect ./openapi.yaml --out twin.yaml   # edit twin.yaml
npx @shipatmidnight/mockanything twin.yaml

有多少 API 可以使用？

数据由 scripts/coverage.ts 于 2026-10-29 测得。该脚本会根据每份规范构建孪生体、创建对象，然后调用每个操作（每个 API 最多 40 个）：

来源	API 数量	成功启动的孪生体	未出现服务器错误的调用	成功的调用
public APIs.guru 目录中的所有 API	2,528	2,528	37,770 / 37,770	90.2%
提供方当前的规范（mockanything list）	54	54	1,988 / 1,988	96.8%

未成功的调用会返回正确的错误，主要是针对从未创建过的 ID 返回“未找到”，或缺少父对象。能够启动并响应，不代表与真实 API 匹配；verify 会对此进行衡量。

提供方发布了当前规范的热门 API（Square、PayPal、Adyen、Discord、Jira、Cloudflare、Vercel、Supabase、Clerk、Hugging Face 等）会从提供方自己发布的来源获取，而不是从目录获取，因为目录往往不是最新的。运行 mockanything list 查看所有这些 API。

直接根据公开的 Stripe、Twilio、GitHub 和 Resend 规范构建的孪生体，无需手动调整，即可通过官方 SDK 的基本创建／读取／更新／列出／删除流程（scripts/conformance.ts）。

根据录制内容构建

录制你的应用与真实 API 的交互（浏览器开发者工具 → Network →“Save all as HAR”，或使用任何能写入 HAR 的代理），然后根据文件启动孪生体：

npx @shipatmidnight/mockanything ./checkout.har

Mock Anything 会重建录制内容中出现的端点、ID 格式、列表结构和状态生命周期。它只保留字段名称、类型、ID 格式以及简短的状态／类型代码：ID 会替换为格式相同的虚构 ID；录制中的标头值、Cookie、查询值、自由文本、数字和布尔值都不会复制到孪生体中。电子邮件、URL 和日期也会替换为虚构值。

完全没有规范？让你的 Agent 来编写：MCP 工具 twin_from_docs 会读取文档页面，并向 Agent 提供简短的格式指南；Agent 编写孪生体定义，再使用 twin_start 启动它。

面向 Agent

作为技能使用（无需额外设置，只需复制文件）

将 skills/mock-anything 复制到 ~/.claude/skills/（或你的 Agent 技能文件夹）。然后告诉 Agent“模拟 Stripe”“针对虚假的 Notion 进行测试”，或者让它查看规范、HAR 文件或文档页面。该技能只使用命令行：启动孪生体、将应用指向它，并驱动应用：

npx @shipatmidnight/mockanything events                  # requests and webhooks the twin saw
npx @shipatmidnight/mockanything state                   # objects it holds
npx @shipatmidnight/mockanything scenario card_declined  # force an edge case on the next call
npx @shipatmidnight/mockanything chaos 5xx,429           # failures (chaos off to stop)
npx @shipatmidnight/mockanything clock 3d                # move time forward
npx @shipatmidnight/mockanything reset

如果 API 只有文档页面，运行 npx @shipatmidnight/mockanything docs <url> 即可向 Agent 提供页面文本和孪生体格式；Agent 会编写 twin.json，使用 npx @shipatmidnight/mockanything validate twin.json 检查，然后启动它。

MCP

claude mcp add mockanything -- npx -y @shipatmidnight/mockanything mcp

Cursor、Windsurf 和其他 MCP 客户端：

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

工具：twin_start、twin_from_docs、twin_env、twin_events、twin_state、twin_scenario、twin_chaos、twin_webhook_add、twin_emit、twin_advance_clock、twin_reset、twin_stop、twin_list、packs_list。

twin_start 仅会加载位于 MCP 服务工作目录内且未隐藏的 .json、.yaml、.yml 或 .har 文件。除非在服务的环境中设置 MOCKANYTHING_ALLOW_LOCAL=1，否则 Agent 无法访问本机上的 URL。

Agent 可以说：“启动一个 Stripe twin，构建结账流程，然后强制触发一张被拒绝的卡，并检查我的代码能否妥善处理”，而无需向你索要密钥。

在重启后保留数据

npx @shipatmidnight/mockanything stripe --persist            # ~/.mockanything/state/stripe.json
npx @shipatmidnight/mockanything stripe --state ./twin.json  # or a file you choose

对象、ID 计数器、测试时钟、webhook 密钥和已注册的 webhook 端点会在每次更改后不久以及 twin 停止时保存。该文件只有你能读取。删除它（或在仪表板中按下 Reset）即可重新开始。Agent 使用 twin_start 和 persist: true 也能获得相同效果。

仪表板

每个 twin 都有一个本地仪表板（启动时会打印带访问令牌的链接）：实时请求与响应、已发送的 webhook 及其传送状态、twin 存储的状态、可强制触发的场景，以及故障注入控制。

命令行

mockanything <api>                 start a twin (pack, API name, OpenAPI file or URL)
mockanything list                  built-in packs
mockanything inspect <api>         print the inferred definition (--out file.yaml)
mockanything validate <file>       check a twin definition
mockanything env <api>             config snippets
mockanything verify <api>          how closely the twin matches the real API (your test key)
mockanything running | events | state | scenario [name] | chaos <modes|off> | clock <duration> | reset
mockanything docs <url> | guide    build a twin from a docs page
mockanything mcp                   MCP server over stdio

--port <n>  --webhook <url>  --allow-webhook-host <host>  --cors <origin>
--chaos[=timeout,5xx,slow,429,dup-webhooks,out-of-order]  --chaos-rate <0..1>  --seed <n>
--persist  --state <file>  --overrides <file>  --json

默认安全

• 仅监听 localhost。除非你允许某个主机，否则只向 localhost 传送 webhook。
• 拒绝实时密钥（sk_live_… 等）和看起来真实的卡号。请使用服务提供商文档中列出的测试值。
• 测试结账页面为纯文本页面，带有“非真实付款”横幅，且仅存在于你的机器上。
• 不进行遥测。仅在你要求时才会产生出站流量：向你配置的 URL 发送 webhook，从你指定的 URL、服务提供商发布的来源或 APIs.guru 目录下载 API 描述，使用你的测试密钥向服务提供商的沙盒发起 verify 调用，以及在安装时或通过 npx 运行时访问 npm。

Twin 的还原度如何？

Twin 的质量取决于构建它所依据的事实。Packs 覆盖了每个 API 的主要流程，而非所有端点；推断出的 twin 会做出猜测，你可以检查并覆盖这些猜测。

verify 会对其进行衡量。它使用相同的脚本化调用，分别针对 twin 和服务提供商的真实沙盒运行，并使用你自己的测试模式密钥，然后比较状态码、字段名称、字段类型、ID 格式和错误代码：

npx @shipatmidnight/mockanything verify stripe --key sk_test_...      # or set MOCKANYTHING_SANDBOX_KEY
npx @shipatmidnight/mockanything verify paystack --key sk_test_... --out report.md
npx @shipatmidnight/mockanything verify ./openapi.yaml --against https://api.example.com --key ...   # read-only list calls

  ✓ Create a customer                              200 / 200  <score>
  ✓ Declined card (error)                          402 / 402  <score>
  ...
  Fidelity <score>  status · fields · types · ids and codes

它仅使用测试模式密钥运行（会拒绝实时密钥）；在将密钥发送到非内置测试套件所用服务提供商 API 主机的主机之前会征求同意（使用 --yes 可跳过）；每秒大约发起一次调用，每次运行都有严格的调用上限；并会在你的沙盒中创建少量测试对象（Stripe 测试套件之后会删除其客户对象）。报告仅列出字段路径、类型和值代码，绝不包含响应数据或你的密钥。内置测试套件：stripe、paystack；你可以为任何 twin 编写自己的测试套件（参见 packs/verify/）。目前尚未比较 Webhook。

mockanything list 会显示每个 pack 已发布的评分和测量日期。使用 twin 快速构建和测试；发布前，请针对服务提供商的沙盒运行最终检查。

Twin 定义

每个 twin，无论是内置还是推断生成的，都是由同一个引擎运行的纯 YAML/JSON 定义。定义是数据，无法运行代码。示例请参见 packs/，格式说明请参见 src/mcp/guide.ts。

贡献

非常欢迎为更多 API 提供 pack，尤其是区域性 API。请先阅读 CONTRIBUTING.md：pack 仅包含事实（路径、字段、错误代码、文档中列出的测试值），不得包含复制的文档文本或徽标。

社区

有问题、想法或想展示分享？欢迎加入 Ship at Midnight Discord。这是一个面向所有工具的服务器，其中设有 Mock Anything 频道。

许可证和声明

Apache-2.0。请参阅 LICENSE 和 NOTICE。

Mock Anything 是一位独立开发者出于热情打造的免费非商业项目。它与其模拟 API 的任何公司均无关联，也未获得这些公司的认可或赞助。Stripe、Paystack、Twilio、Resend、GitHub、OpenAI、Anthropic、Claude 及其他名称均为其各自所有者的商标，仅用于描述兼容性。