让 Claude / Cursor 直接生成 API 客户端:ApiSorcery MCP 实战把 apisorcery

你在 Cursor 里让 AI 写业务代码,它先问你:"接口的类型定义放哪儿?"你只好切到终端跑 apisorcery generate,回来复制路径,再复述一遍字段结构——上下文没了,AI 也懵了。

如果你已经用ApiSorcery生成 API 客户端一段时间,大概会遇到这种断层:代码生成在终端,业务开发在 AI 助手里。这两个流程之间来回切,AI 拿不到最新的接口结构,你也懒得频繁复述。

装完 CLI 你其实已经拿到了另一个可执行文件—— apisorcery-mcp。把它接进 Claude Code / Cursor / Windsurf,AI 就能自己调 generate,拿到刚生成的类型定义,直接接着写业务。你只用说一句"帮我更新一下接口",它包办剩下的。

这篇文章讲怎么接、能怎么用、有哪些不明显的甜头。

一、MCP 是什么,ApiSorcery 为什么要做

MCP(Model Context Protocol)是 Anthropic 提出、后来被主流 AI 编程工具广泛支持的一套协议,目标是让 AI 助手能通过标准接口调用外部工具——不再依赖"AI 生成一段 shell 命令,你手动复制执行"这种低效的 loop。

对 ApiSorcery 这类 CLI 工具来说,MCP 化的收益特别直接:

场景	无 MCP	有 MCP
AI 想给你写一个调用 `getUserOne` 的组件	只能瞎猜方法签名	先跑 `generate` 拿到最新类型,再写
后端加了三个字段	你切终端 → 跑命令 → 回 AI → 复述新字段	一句"接口更新一下"就搞定
换电脑首次配置	AI 只能生成 `register` 命令让你自己跑	AI 直接问你要 token,然后调 `register`
生成失败	报错在终端,AI 看不见	报错回到 AI 面板,它能读懂并给建议

关键在于:AI 不再是"教你怎么用工具"的角色,而是"直接用工具的手"。你的 prompt 从"跑一下这个命令"变成"帮我更新接口",一层抽象消失了。

二、装完 CLI = 装完 MCP

ApiSorcery 的 npm 包 @apisorcery/cli 同时提供两个可执行文件:

apisorcery      
# 传统 CLI(init / generate / register)
      
apisorcery-mcp
# MCP 服务器(stdio 传输)

装一次搞定:

npm i -g @apisorcery/cli

验证:

apisorcery -v      
# 输出 1.5.x
      
which apisorcery-mcp
# 应能定位到二进制

MCP 暴露三个 tool,与 CLI 一一对应:

Tool	说明
`init`	在当前工作目录生成 `.apisorceryrc.json`
`generate`	读 `.apisorceryrc.json` 拉 Swagger 生成 API 客户端
`register`	把当前机器绑定到你的账号(需要临时令牌)

没有隐藏 tool,也没有 AI-only 的黑魔法——所有能力都是你熟悉的三个 CLI 命令,只是换了触发方式。

三、给主流 AI 工具接上

配置文件位置各家不同,但格式几乎一样。这里给出四种常见工具的接入方式,全都验证过。

3.1 Claude Code

全局: ~/.claude/mcp.json
项目: 项目根目录下的 .mcp.json(可提交 git,团队共享)

{
  ”mcpServers”: {
    ”apisorcery”: {
      ”command”: ”apisorcery-mcp”
    }
  } 
}

Claude Code 会自动加载项目根的 .mcp.json,无需重启。改完让 Claude 列一下当前可用的 tool,能看到 init / generate / register 就算成了。

3.2 Cursor

全局: ~/.cursor/mcp.json
项目: .cursor/mcp.json

{
  ”mcpServers”: {
    ”apisorcery”: {
      ”command”: ”apisorcery-mcp”
    }
  } 
}

Cursor 改完配置需要重启一次(Cmd/Ctrl+Shift+P → Reload Window),右下角能看到 MCP 状态灯变绿。

3.3 Windsurf / Trae / Cline / Continue

统一都是这套 schema,写到各自的 MCP 配置面板即可:

{
  ”mcpServers”: {
    ”apisorcery”: {
      ”command”: ”apisorcery-mcp”
    }
  } 
}

3.4 不想全局装?用 npx

{
  ”mcpServers”: {
    ”apisorcery”: {
      ”command”: ”npx”,
      ”args”: [”-y”, ”@apisorcery/cli/mcp”]
    }
  } 
}

npx 会自动拉最新版本,但首次启动会有几秒下载延迟——日常开发还是推荐全局装,启动瞬时。

3.5 一个隐蔽的坑:工作目录(cwd)

MCP 服务器继承宿主进程的工作目录。多数 AI 工具启动时 cwd = 项目根,但 Windsurf / 部分 IDE 可能不是。表现就是:AI 调 generate 时报"找不到 .apisorceryrc.json"。

显式指定 cwd 就好:

{
  ”mcpServers”: {
    ”apisorcery”: {
      ”command”: ”apisorcery-mcp”,
      ”cwd”: ”/path/to/your/project”
    }
  } 
}

四、AI + ApiSorcery 的六个真实场景

配置完之后,你和 AI 的对话会长这样。以下都是我自己在 Claude Code / Cursor 里用得最多的模板,可以直接抄。

场景 1:后端加了新接口,AI 帮我用起来

你说:

后端刚在用户模块加了个批量导出接口 POST /user/export,帮我更新一下 API 客户端,然后在 UserListPage.tsx 加个"导出"按钮调它。

AI 做的事:

调 generate tool → CLI 拉最新 Swagger、生成 ApiUser.exportUsers
读一下生成的 model.ts / ApiUser.ts 拿到方法签名
打开 UserListPage.tsx,加按钮 + 调 ApiUser.exportUsers({...})
顺手把 BlobResp 的下载逻辑写进去

你的操作:确认。

场景 2:新项目从零起步

你说:

我要在这个 Vue 3 项目里接入 ApiSorcery,后端 Swagger 在 https://api.mycompany.com/swagger-json,帮我配起来。

AI 做的事:

调 init tool 生成 .apisorceryrc.json
打开配置文件,改 servers[].source 为你给的 URL
调 generate 试跑一次
如果 CLI 报"设备未注册",AI 会引导你去控制台生成临时令牌 → 调 register

你的操作:粘贴一个临时令牌。

场景 3:多服务项目,分开生成

你说:

我们后端拆了 user-service 和 order-service 两个,给我配一下 ApiSorcery 让它们分别生成到 apis/user 和 apis/order。

AI 会编辑 .apisorceryrc.json 的 servers 数组,每个服务一个 code + outputDir,然后跑一次 generate 验证。多服务配置以前需要读文档手写,现在一句话搞定。

场景 4:字段改名,追踪影响面

你说:

后端把 userName 改成 nickName 了,帮我更新接口然后修所有用到的地方。

AI 做的事:

generate 更新类型定义
TS 编译器 / DevEco Studio / IDE 现在会飘红标出所有旧字段的位置
AI 一处处改过去

对 ArkTS / Flutter 这种严格类型的场景收益尤其大——生成器 + AI + 类型系统三者组合,几乎能做到"改一个字段全项目跟着调"。

场景 5:自定义拦截器,AI 也能改

生成器有个策略叫 httpClientStrategy: once,意思是拦截器文件只生成一次,后续不覆盖——给自定义拦截器留位置。

你说:

在响应拦截器里加一个 401 自动跳登录页的逻辑,如果 status 是 401 就 window.location = '/login'。

AI 会打开 httpClient/interceptors/response.ts 直接改。你之前可能得先在文档里找"生成的拦截器在哪个路径",现在 AI 自己就能找到——因为它可以先 generate 一次拿到目录结构。

场景 6:排查生成失败

你说:

跑一下 generate,看看报什么错。

AI 调generate,如果失败:tool response 里会带回 CLI 的错误 message(比如"设备已被禁用,请去控制台启用"、"额度已用完,请升级套餐")。AI 直接读到这段信息,给你下一步建议——通常是"我贴了一段命令,你去控制台操作后告诉我 token"。

对比无 MCP 时代:CLI 的错误只出现在你的终端,AI 面板一无所知,你得手动复述——信息断链的核心痛点被解决了。

五、这些设计细节,让 AI 用得更顺

apisorcery-mcp 不是简单把 CLI 命令套一层壳。为了在 AI 场景下用得顺,有几个细节值得单独讲。

5.1 stdout 保持洁净,日志走 stderr

MCP 协议基于 stdio 传 JSON-RPC——任何往 stdout 打的杂字都会破坏协议。ApiSorcery MCP 启动时会把 console.log / console.warn 全部重定向到 stderr:

[MCP process]
  ├─ stdout: 只跑 JSON-RPC(与 AI 宿主对话)
  └─ stderr: 所有业务日志(宿主可选择性展示)

结果就是:你永远不会因为 CLI 多打了一行日志导致 AI 面板挂掉。这是很多 MCP server 早期版本的通病,我们踩过所以避开。

5.2 升级提示追加到 tool response

CLI 的升级提示原本走 stderr,MCP 宿主可能不展示 stderr——那用户就永远看不到有新版本可用。

MCP 场景下换了通道:

tool 调用成功 → response.content 追加一条 ”有新版本 1.6.0,升级命令:npm i -g @apisorcery/cli”

直接出现在 AI 结果面板,不会被吞。同时进程内做了单例缓存(checkOnce),同一次 IDE 会话只请求一次 npm registry,不会刷屏。

5.3 register 成功/更新差异化提示

同一台机器重复跑 register(比如你想改 remarks),后端会走 update 分支,不占席位。MCP handler 会把这段信息透传给 AI:

首次注册: Device registered successfully.
重复注册: Device already registered, updated instead.

AI 能据此判断"这次是新增还是改备注",避免误以为额度被消耗。

5.4 业务错误被明确标记 isError

tool response 里除了 content,还有 isError: true 标记。AI 宿主的红色高亮就靠这个字段。业务失败(设备超限 / 额度耗尽 / 版本过低)一律带 isError,AI 一眼就知道要停下来向你确认。

5.5 生成额度低会有软提示

如果你正常订阅的额度剩余 <20%,MCP tool response 会追加一条黄色警告(中/英按你账户语言):

[ApiSorcery] 订阅额度即将用完:剩余 87 / 500 (17%)

不影响生成成功,但你和 AI 都能提前意识到。

六、团队协作场景:.mcp.json 提交到 git

.mcp.json 是可以提交到仓库的(Claude Code 官方也是这么建议)。团队里任何人 clone 项目,只要装了 @apisorcery/cli,打开 Claude Code 就自动接上,零配置。

推荐的仓库根 .mcp.json:

{
  ”mcpServers”: {
    ”apisorcery”: {
      ”command”: ”apisorcery-mcp”
    }
  } 
}

配合项目根的 .apisorceryrc.json,团队新人的 onboarding 变成:

git clone
      
npm i -g @apisorcery/cli     
# 装工具
      
apisorcery register -t ... -r ...
# 绑一次设备
      
# 打开 Claude Code,说”帮我生成 API 客户端”

以前得写一大段 README 说明"怎么装 / 怎么配 / 怎么跑",现在AI 自己就是那份 README。

七、常见问题

Q1: MCP 会不会偷偷把我的 Swagger 传到 Anthropic?

不会。apisorcery-mcp 是本地进程,只与你配置的 AI 宿主(通过 stdio)通信,以及与 ApiSorcery 后端(用于解析 Swagger)通信。AI 宿主拿到的只有 tool response 的 content 字符串——里面是"生成成功"或"生成失败"这类元信息,没有 Swagger 原文,也没有生成的代码。

Q2: AI 会不会把我的临时令牌泄露?

临时令牌只在 register 调用时传给 MCP tool,MCP 直接转发给 ApiSorcery 后端,不会写入日志、不会返回给 AI 宿主。用完就过期(15 分钟有效),即使意外泄露风险也很有限。

Q3: 会不会因为 AI 频繁跑 generate 把额度用光?

generate 每次都会真实消耗 1 次额度。但实际使用下来,AI 触发 generate 的频率远低于你自己手动跑——因为 AI 会先看现有类型定义够不够用,只在真的需要更新时才跑。免费版每月 30 次(每月刷新),新注册还有 500 次一次性赠送额度、30 天有效,足够覆盖初期高频接入阶段。

Q4: 如果我的 IDE 不支持 MCP 呢?

那就继续用传统 CLI。MCP 是锦上添花,不是必须。传统 apisorcery generate 一切照旧。

Q5: 我能不能只让 AI 调 generate,禁掉 init 和 register?

MCP 协议本身没有细粒度权限,但大多数宿主(Claude Code / Cursor)允许你在 UI 里对具体 tool 做"每次询问"或"禁用"。可以把 register 设为"每次询问",避免 AI 误触。

Q6: 用 npx 启动的方式,会不会每次都下载?

npx -y 会在 npm 缓存里查,已装过就不会重新下载。但版本检查会走网络,启动比全局装慢 1-2 秒。长期使用推荐全局装,只在临时试用场景用 npx。

八、写在最后

工具链的价值,不在于"我能做多少事",而在于"我能帮用户少做多少事"。

apisorcery generate 已经把"写 API 客户端"从几天缩到几秒。接进 MCP 之后,连"想起来该跑 generate 了"这一步都省掉——AI 自己会判断什么时候需要。

配置成本近乎为零:

npm i -g @apisorcery/cli
      
# 在 .cursor/mcp.json 或 .mcp.json 里加 4 行 JSON

如果你日常用 Claude Code / Cursor / Windsurf 之一,而且项目里还在手动跑 API 生成命令——今天就接上,你的下一次"帮我加个接口调用"会明显轻松。

相关链接

官网: www.apisorcery.cn

MCP 文档: www.apisorcery.cn/help/zh/mcp…

GitHub Demo: 支持 React / Vue / Angular / Svelte / Flutter / HarmonyOS / UniApp

支持的 AI 工具: Claude Code / Cursor / Windsurf / Cline / Continue / Trae / 任何支持 MCP 协议的编辑器

觉得有用点个赞 👍 收藏 ⭐,下次接新项目就用得上。