Openapi To Ts MCP Server

ts mcp服务器的openapi

中文文档

一 MCP（模型上下文协议）服务器 其根据OpenAPI 3.0规范生成TypeScript/JavaScriptneneneba API客户端代码。

配置一次，然后简单地告诉Claude _“为订单模块生成API代码”_ --无需手动复制文档或手写类型定义。

______________________________________________________________________

特性

• 通过以下方式生成代码 标签组 或 特定端点
• 输出 .ts （带类型导入）， .d.ts （类型定义），以及 .js （纯JS）
• 自动将非英文标签名转换为英文camelCase文件名
• 自动解决函数名称冲突（AI驱动或方法前缀回退）
• 多服务（微服务） 支持——每个实例指向不同的OpenAPI文档
• 支持Apifox私有文档（POST身份验证模式）

______________________________________________________________________

安装

npm install openapi-to-ts-mcp-server

需要Node.js>=18

______________________________________________________________________

快速开始

将MCP配置添加到项目的 .claude/settings.json:

{
  "mcpServers": {
    "openapi-to-ts": {
      "command": "npx",
      "args": ["openapi-to-ts-mcp-server"],
      "env": {
        "OPENAPI_DOCS_URL": "https://your-api-host/openapi.json",
        "OPENAPI_IMPORT_CODE": "import request from '@/utils/request'"
      }
    }
  }
}

然后在克劳德代码中：

Generate the TypeScript API code for the "Order Management" module

______________________________________________________________________

多服务（微服务）设置

当你的后端有多个微服务时，用以下命令配置多个实例 OPENAPI_SERVICE_NAME:

{
  "mcpServers": {
    "payment-api": {
      "command": "npx",
      "args": ["openapi-to-ts-mcp-server"],
      "env": {
        "OPENAPI_DOCS_URL": "https://payment.example.com/openapi.json",
        "OPENAPI_IMPORT_CODE": "import request from '@/utils/request'",
        "OPENAPI_SERVICE_NAME": "Payment System"
      }
    },
    "order-api": {
      "command": "npx",
      "args": ["openapi-to-ts-mcp-server"],
      "env": {
        "OPENAPI_DOCS_URL": "https://order.example.com/openapi.json",
        "OPENAPI_IMPORT_CODE": "import request from '@/utils/request'",
        "OPENAPI_SERVICE_NAME": "Order System"
      }
    }
  }
}

Claude会根据以下内容自动匹配正确的MCP实例 [ServiceName] 工具描述中的标签。

配置位置

安装后，运行 /mcp 在Claude Code中检查连接的MCP服务器的状态。

______________________________________________________________________

环境变量

Apifox私人文档

如果您的文档需要身份验证（Apifox团队项目），请配置 OPENAPI_APIFOX_BODY:

{
  "mcpServers": {
    "openapi-to-ts": {
      "command": "npx",
      "args": ["openapi-to-ts-mcp-server"],
      "env": {
        "OPENAPI_DOCS_URL": "https://api.apifox.com/api/v1/projects/123456/export-openapi",
        "OPENAPI_IMPORT_CODE": "import request from '@/utils/request'",
        "OPENAPI_APIFOX_BODY": "{\"version\":\"3.0\",\"apiDetailRequested\":true}"
      }
    }
  }
}

______________________________________________________________________

工具： generate_api_code

至少一个 tags 或 interfaces 必须提供。它们可以组合在一起。

响应结构

{
  "tagNameMap": { "货品入库": "goodsInbound" },
  "ts": "// TypeScript code (with type imports)\nexport const getUserListApi...",
  "dts": "// Type definition file\nexport interface UserListParams...",
  "js": "// Plain JavaScript code\nexport const getUserListApi..."
}

• tagNameMap --将源标记名称映射到英文camelCase文件名
• 当 language: "ts"，仅 ts + dts 被退回；当 language: "js"，仅 js

______________________________________________________________________

使用场景

场景1：生成新文件

生成“入站货物”模块的API代码

克劳德调用该工具并写道 ts 到 goodsInbound.ts, dts 到 goodsInbound.types.ts.

重要提示： 生成的代码基于MCP响应。如果结果中没有端点，则OpenAPI规范中不存在端点——不会进行手动添加。

场景2：更新现有文件

更新goodsInbound.ts中的API代码

克劳德读 tags/interfaces 从文件头注释中提取元数据，重新调用MCP工具，并用最新结果覆盖文件。

生成的文件在头部包含元数据：

/**
 * Auto-generated by openapi-to-ts
 * time: 2026-03-25 14:30:00
 * tags: ["货品入库"]
 */

______________________________________________________________________

例子

按模块生成

为“用户中心”模块生成API代码

{ "tags": ["UserCenter"] }

生成多个模块

生成“订单管理”和“产品列表”的API代码，仅TypeScript

{ "tags": ["OrderManagement", "ProductList"], "language": "ts" }

生成特定端点

为POST/api/登录和GET/api/user/info生成代码

{ "interfaces": ["post_/api/login", "get_/api/user/info"] }

结合标签和界面

生成“权限”模块，加上DELETE/api/cache/clear

{ "tags": ["Permission"], "interfaces": ["delete_/api/cache/clear"] }

多服务场景

从支付服务生成“退款管理”API

Claude会自动将MCP实例与 OPENAPI_SERVICE_NAME 着手 Payment System.

______________________________________________________________________

常见问题解答

Q： 获取 No matching interfaces found

检查一下 tags 名称与OpenAPI规范中的标签完全匹配（区分大小写）。

Q： 函数名称冲突警告

配置 DEEPSEEK_API_KEY 以实现人工智能驱动的独特命名。如果没有它，回退会添加HTTP方法前缀（例如。， getUsers / postUsers).

Q： Claude在多服务设置中选择了错误的工具

确保每个实例都有 OPENAPI_SERVICE_NAME 配置有独特的名称。

Q： MCP服务器连接失败

1. 验证 npx openapi-to-ts-mcp-server 成功运行
2. 跑 /mcp 在Claude Code中检查错误详细信息

______________________________________________________________________

发展

# Install dependencies
npm install

# Build (outputs to dist/)
npm run build

# Watch mode
npm run dev

# Run the server
npm start

______________________________________________________________________

出版

# Build + publish (prepublishOnly runs tsc automatically)
npm publish

这 files 字段配置为仅包括 dist/ 和 bin.js --源代码未发布。

______________________________________________________________________

项目结构

src/
├── index.ts              # MCP server entry, tool definition
├── config.ts             # Environment variable parsing
├── fetch-spec.ts         # Fetch & cache OpenAPI spec
├── filter.ts             # Filter paths by tags/interfaces
├── alias-resolver.ts     # Function name conflict resolution
├── tag-name-resolver.ts  # Non-English tag name translation
├── types.ts              # Shared type definitions
└── gen/
    ├── gen-code.ts        # Code generation orchestrator
    ├── core.ts            # Schema -> TypeScript type converter
    ├── request-type-tools.ts  # Request/response type extraction
    └── tools.ts           # Utility functions
bin.js                    # CLI entry point

______________________________________________________________________

许可证

麻省理工学院