Swagger Ts Gen

MCP开发工具

提供方 lhbDesign

开发工具 stdio · 本地进程 Token 社区 / 第三方 Cursor
查看接入方式

从Swagger/OpenAPI文档自动为前端接口文件生成TypeScript类型定义,支持命令行和AI IDE集成调用。

一句话选型结论

按资料字段整理

Swagger Ts Gen 属于开发工具类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Cursor,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 2 仓库热度,无公开仓库时显示未标注
工具数 1 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量1暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

前端开发TypeScript本地部署API文档自动化工具代码生成

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
npx --no-install swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 1 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 1 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Swagger Ts Gen当前 1 stdio · 本地进程 本地部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方lhbDesign上游标注的维护方 lhbDesign
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Node.js本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

13.7 KB
来自项目仓库与上游目录的原文,未做删改

swagger-ts-mcp

中文 | English

从 Swagger/OpenAPI 文档自动为前端接口文件生成 TypeScript 类型定义。

支持两种调用方式:命令行(CLI) 和 MCP Server(AI IDE 集成)。


目录

  • 安装与执行方式
  • 快速开始
  • 配置文件
  • 配置读取规则与优先级
  • 命令行使用
  • MCP Server 使用
  • 针对不同 API 工具的使用方式
  • 工作原理
  • 常见问题

安装与执行方式

方式一:全局安装(适合经常使用)```bash

npm install -g swagger-ts-mcp


执行:```bash
swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

注意:--file 路径是相对于当前命令行所在目录的,需要在项目根目录下执行,或使用绝对路径。


方式二:安装到项目依赖(推荐团队协作)

> 安装后会固定版本,团队成员执行行为一致。

npm:```bash
npm i -D swagger-ts-mcp
npx --no-install swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html


pnpm:```bash
pnpm add -D swagger-ts-mcp
pnpm exec swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

yarn:```bash
yarn add -D swagger-ts-mcp
yarn swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html


---

### 方式三:npx 临时使用(不安装)```bash
npx swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

> npx 在本地没安装时会尝试从 npm 拉取。
> 如果你只想用“本地已安装版本”,请使用 npx --no-install swagger-ts-mcp。


快速开始

第一步:在项目根目录创建配置文件 swagger-ts-gen.config.json:```json
{
"swaggerUrl": "https://your-api/doc.html",
"defaultFiles": ["src/api/user.ts"]
}


**第二步**:运行命令(按你的安装方式选择其一):```bash
# A. 全局安装后可直接用
swagger-ts-mcp

# B. 安装到项目依赖(npm)
npx --no-install swagger-ts-mcp

# C. 安装到项目依赖(pnpm)
pnpm exec swagger-ts-mcp

工具会自动:

  1. 解析接口文件,找出参数类型为 any 或未定义的函数
  2. 从 Swagger 文档获取对应接口的 Schema
  3. 生成 TypeScript interface/type,插入到函数定义上方
  4. 将函数参数的 any 替换为生成的具体类型名

示例:

处理前:```typescript
// 取消发布
export async function cancelPublishApi(params?: any) {
return requestClient.get("/model/publish/cancel", { params });
}


处理后:```typescript
/** 取消发布请求参数 */
export interface CancelPublishParams {
/** 模型ID */
modelId?: number;
}

// 取消发布
export async function cancelPublishApi(params?: CancelPublishParams) {
return requestClient.get("/model/publish/cancel", { params });
}

配置文件

在项目根目录创建 swagger-ts-gen.config.json:```json
{
"swaggerUrl": "https://your-api/doc.html",
"defaultFiles": ["src/api/user.ts", "src/api/order.ts"],
"endpointPrefix": "/algo",
"clientName": "requestClient",
"outputStyle": "interface"
}


配置项 · 类型 · 默认值 · 说明
`swaggerUrl` · `string` · — · Swagger 文档地址,支持 `doc.html`、`/v3/api-docs`、`/v2/api-docs`
`defaultFiles` · `string[]` · — · 默认处理的接口文件路径列表
`endpointPrefix` · `string` · `""` · 接口路径前缀。代码里路径是 `/algo/user/list`,但 Swagger 里是 `/user/list`,则设为 `/algo`
`clientName` · `string` · `"requestClient"` · HTTP 客户端对象名称,如 `axios`、`http`、`request`
`outputStyle` · `"interface" \ · "type"` · `"interface"` · 生成类型的风格

---

## 配置读取规则与优先级

- 工具读取:`{当前工作目录}/swagger-ts-gen.config.json`
- 也就是:你从哪个目录执行命令,就从哪个目录找配置文件
- `--file` 相对路径也是相对于当前工作目录
- CLI 参数优先级高于配置文件(会覆盖配置):
- `--swagger`
- `--endpoint-prefix`
- `--client-name`

示例:```bash
npx --no-install swagger-ts-mcp \
--file src/api/algo/scheme.ts \
--swagger https://optimos.dev.d2d.ai/api/algo/doc.html \
--endpoint-prefix /algo

命令行使用

> 说明:#1 ~ #3 适用于“全局安装”;如果是“安装到项目依赖”,请使用 #4 / #5。```bash

1) 使用配置文件(推荐,需全局安装)

swagger-ts-mcp

2) 指定文件和文档地址(需全局安装)

swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

3) 预览模式,不修改文件(需全局安装)

swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html --dry-run

4) 项目本地安装后执行(npm)

npx --no-install swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

5) 项目本地安装后执行(pnpm)

pnpm exec swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html


### 所有参数

| 参数                | 是否必填 | 默认处理(未传时)                                            | 说明                                     | 示例                                         |
| ------------------- | -------- | ------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------- |
| `--file`            | 是       | 未传则读取配置文件 `defaultFiles`;若仍为空则报错退出         | 目标接口文件路径                         | `--file src/api/user.ts`                     |
| `--swagger`         | 是       | 未传则读取配置文件 `swaggerUrl`;若仍为空则报错退出           | Swagger 文档地址或本地 JSON 文件路径     | `--swagger https://api.example.com/doc.html` |
| `--dry-run`         | 否       | 默认 `false`                                                  | 预览模式,不修改文件                     | `--dry-run`                                  |
| `--functions`       | 否       | 不传则处理目标文件内所有待处理函数                            | 只处理指定函数(支持逗号分隔或重复传参) | `--functions getUserApi,createUserApi`       |
| `--json`            | 否       | 默认 `false`                                                  | 成功场景输出结构化 JSON                  | `--json`                                     |
| `--silent`          | 否       | 默认 `false`                                                  | 静默成功日志(失败错误仍输出)           | `--silent`                                   |
| `--mcp`             | 否       | 默认 `false`                                                  | 以 MCP Server 模式启动                   | `--mcp`                                      |
| `--endpoint-prefix` | 否       | 未传则读取配置文件 `endpointPrefix`;再没有则按空字符串处理   | 接口路径前缀(覆盖配置文件)             | `--endpoint-prefix /algo`                    |
| `--client-name`     | 否       | 未传则读取配置文件 `clientName`;再没有则默认 `requestClient` | HTTP 客户端名称(覆盖配置文件)          | `--client-name axios`                        |

---

## MCP Server 使用

MCP(Model Context Protocol)模式允许 AI IDE 直接调用本工具生成类型,无需手动运行命令。

### 配置 MCP Server — Kiro

在项目的 `.kiro/settings/mcp.json` 中添加:```json
{
"mcpServers": {
"swagger-ts-mcp": {
"command": "npx",
"args": ["swagger-ts-mcp", "--mcp"],
"disabled": false,
"autoApprove": ["generate_types"]
}
}
}

配置 MCP Server — Cursor

在 .cursor/mcp.json 或对应 IDE 配置中添加:```json
{
"mcpServers": {
"swagger-ts-mcp": {
"command": "npx",
"args": ["swagger-ts-mcp", "--mcp"]
}
}
}


配置完成后,在 Cursor 中按 `Cmd+Shift+P` 搜索 `MCP`,点击 **Reload MCP Servers** 使配置生效。

> 因为版本或配置不同,如果提示 MCP 文件无法读取,按照提示创建文件并输入上面的 JSON 即可。

### 在 AI IDE 中使用

**Kiro**:直接在聊天框中说:

> 帮我给 `cancelPublishApi` 生成 TypeScript 类型(调用 generate_types 工具)

**Cursor**:在 Composer(`Cmd+I`)或 Chat 中说:

> 使用 swagger-ts-mcp 工具,帮我给 `cancelPublishApi` 生成 TypeScript 类型,文件路径是 src/api/user.ts

### MCP 工具参数

工具名:`generate_types`

| 参数            | 类型       | 必填 | 说明                                          |
| --------------- | ---------- | ---- | --------------------------------------------- |
| `filePath`      | `string`   | ✅   | 目标接口文件路径                              |
| `swaggerUrl`    | `string`   | —    | Swagger 文档地址(优先于配置文件)            |
| `functionNames` | `string[]` | —    | 只处理指定函数,不传则处理所有 `any` 类型函数 |
| `dryRun`        | `boolean`  | —    | 预览模式,不修改文件                          |

---

## 针对不同 API 工具的使用方式

### Swagger / SpringDoc(默认支持)

直接传 `doc.html` 地址,工具自动转换为 `/v3/api-docs` 或 `/v2/api-docs`:```bash
swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html

本地 Swagger/OpenAPI JSON 文件格式要求

当 --swagger 传本地文件(如 ./openapi.json)时,文件需满足:

  • 必须是合法 JSON(建议 UTF-8 编码,扩展名通常为 .json)
  • 顶层需是 Swagger/OpenAPI 文档对象
  • 必须包含 paths 字段(对象)
  • openapi(OpenAPI3)或 swagger(Swagger2)建议保留
  • 引用模型建议放在 components.schemas(OpenAPI3)或 definitions(Swagger2)

最小示例:```json
{
"openapi": "3.0.0",
"paths": {
"/user/get": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}


swagger 中 离线文档-导出 openAPI 其他工具同理。将导出的 json 文件放入到项目中或任何为止, --swagger 后的路径改为此文档的路径地址 如 /Users/code/Desktop/work/2025/apps/algo/default_OpenAPI.json

使用 YApi 导出接口:```text
https://your-yapi.com/api/plugin/export?type=swagger&pid=<项目ID>&token=<项目token>
``````bash
swagger-ts-mcp --file src/api/user.ts --swagger "https://your-yapi.com/api/plugin/export?type=swagger&pid=123&token=abc123"

Apifox

在 Apifox 中导出 OpenAPI 3.0 在线 URL 后直接使用。


工作原理```text

接口文件 (*.ts)
↓ 解析 AST,找出 requestClient.xxx() 调用
↓ 过滤参数类型为 any 或未定义的函数
↓
Swagger 文档
↓ 根据 endpoint + method 查找接口定义
↓ 提取 request schema 和 response schema
↓
TypeScript 类型生成
↓ Schema → interface/type 定义
↓ 处理 $ref 递归引用、oneOf/anyOf/allOf
↓
写入文件
↓ 插入类型定义到函数上方
↓ 将 any 替换为具体类型名


### 命名规范

| 类型               | 命名规则           | 示例                |
| ------------------ | ------------------ | ------------------- |
| 请求参数类型       | `{BaseName}Params` | `GetUserListParams` |
| 响应体类型         | `{BaseName}Result` | `GetUserListResult` |
| 响应 data 字段类型 | `{BaseName}Data`   | `GetUserListData`   |

函数名转换规则:`getUserListApi` → 去掉 `Api` 后缀 → 首字母大写 → `GetUserList`

---

## 常见问题

**Q:`npx swagger-ts-mcp` 为什么会提示去远程下载?**

A:因为当前项目没有本地安装该包。`npx` 默认会尝试从 npm 拉取。
如果你只希望使用本地版本,请用:```bash
npx --no-install swagger-ts-mcp

Q:我已经安装到项目里了,推荐怎么执行?

A:

  • npm 项目:npx --no-install swagger-ts-mcp ...
  • pnpm 项目:pnpm exec swagger-ts-mcp ...
  • yarn 项目:yarn swagger-ts-mcp ...

Q:下载到项目里后,还会读取 swagger-ts-gen.config.json 吗?

A:会。无论全局安装、本地安装还是 npx 执行,都会读取“当前工作目录”下的配置文件。

Q:路径报 ENOENT 怎么办?

A:检查 --file 路径是否相对“当前执行目录”。
例如你在项目根目录执行,通常应写 src/...,而不是重复加项目前缀路径。

Q:接口路径在代码里有前缀,但 Swagger 里没有,怎么处理?

A:使用 --endpoint-prefix 或配置 endpointPrefix。
Q:项目用的是 axios 而不是 requestClient,怎么办?```json
{ "clientName": "axios" }


**Q:想先预览生成结果,不修改文件怎么做?**

加上 `--dry-run` 参数。

**Q:只想处理某几个函数?**

CLI 可通过 `--functions` 指定(支持逗号分隔或重复传参)。
例如:`--functions getUserApi,createUserApi` 或 `--functions getUserApi --functions createUserApi`。

MCP 模式下传 `functionNames` 参数。
**Q:Swagger 文档需要登录认证怎么办?**

目前不支持带认证头的请求。可以在浏览器中打开 `/v3/api-docs`,将 JSON 内容保存为本地文件后使用。
CLI 示例:`swagger-ts-mcp --file src/api/user.ts --swagger ./openapi.json`。
**Q:npx tsx packages/swagger-ts-gen/bin/index.ts 报错?**

包下载以后```bash
npx tsx packages/swagger-ts-gen/bin/index.ts \
--file 路径 \
--swagger swagger地址

执行命令如图

报错 sh: tsx: command not found

tsx 没有全局安装,npx tsx 找不到。改成从 packages/swagger-ts-gen 的本地 node_modules 里调用:```bash
npx --prefix packages/swagger-ts-gen tsx packages/swagger-ts-gen/bin/index.ts \
--file 路径 \
--swagger 地址


或者直接用 `node_modules/.bin/tsx`:```bash
packages/swagger-ts-gen/node_modules/.bin/tsx packages/swagger-ts-gen/bin/index.ts \
--file 路径 \
--swagger 地址

或者全局装一下 tsx,以后就不用每次这样了:bash npm install -g tsx

装完之后原来的命令就能用了。

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Swagger Ts Gen 怎么安装?

在客户端按下面的安装命令接入:npx --no-install swagger-ts-mcp --file src/api/user.ts --swagger https://your-api/doc.html。装完在客户端配置里引用同一个包或端点。

Swagger Ts Gen 怎么在 Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Swagger Ts Gen 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Swagger Ts Gen 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Swagger Ts Gen 支持哪些客户端?

资料标注支持 Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Swagger Ts Gen 能提供哪些能力?

资料显示约 1 个工具;能力标签包括 开发工具、代码生成、TypeScript、Cursor、API文档。具体工具清单以官方文档为准。

Swagger Ts Gen 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

Swagger Ts Gen 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。