Swagger MCP (Multi-API Edition)

Swagger MCP（Multi-API版）

英语 |韩语

______________________________________________________________________

帮助AI理解和利用Swagger/OpenAPI文档的MCP服务器。

此版本为 Vizioz/Swagger MCP叉起 多API支持 添加功能的自定义版本。

主要功能

• 多API支持: apis.yaml 通过配置文件在单个MCP服务器上管理多个API
• 查看API列表: listApis 验证工具设置的所有API
• 端点查询：查看特定API的所有端点列表
• 查看模型：查看特定端点使用的模型信息
• 生成TypeScript代码：自动生成模型和MCP工具定义代码
• 缓存：通过本地缓存Swagger定义快速查看

快速入门

1.作为Docker运行（建议）

# 이미지 빌드
docker build -t swagger-mcp-multi:latest .

# 테스트 실행
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"listApis","arguments":{}}}' | \
  docker run -i --rm swagger-mcp-multi:latest

2.生成API配置文件

项目的 .cursor/ 文件夹呃 apis.yaml 创建文件。

apis.yaml.example请参考填写：

# .cursor/apis.yaml
apis:
  - name: petstore
    description: Petstore API (Example)
    url: https://petstore.swagger.io/v2/swagger.json

  - name: my-api
    description: My API Description
    url: https://my-api.example.com/v3/api-docs

重要: apis.yaml可能包含API URL等敏感信息，因此项目的 .gitignore建议添加到。

3.Cursor MCP设置

项目的 .cursor/mcp.json 添加到文件：

{
  "mcpServers": {
    "api-docs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project/.cursor/apis.yaml:/app/apis.yaml:ro",
        "swagger-mcp-multi:latest"
      ]
    }
  }
}

重要: /path/to/your/project/.cursor/apis.yaml 请将路径更改为实际项目路径。

4.设置其他API（可选）

apis.yaml 向文件添加/修改API：

apis:
  - name: api-1
    description: API
    url: https://~~~

  - name: api-2
    description: Core API
    url: https://api.~~~~

  # 새 API 추가
  - name: new-api
    description: 새로운 API 설명
    url: https://new-api.example.com/v3/api-docs

可用工具

listApis

查看所有已设置API的列表。

입력: 없음
출력: API 이름, 설명, URL 목록

list端点

查看特定API的所有端点。

입력:
  - apiName: API 이름 (예: "oi-api")
출력: 엔드포인트 경로, HTTP 메서드, 설명 목록

ListendPointModels

查看特定端点使用的模型。

입력:
  - apiName: API 이름
  - path: 엔드포인트 경로 (예: "/users")
  - method: HTTP 메서드 (예: "GET")
출력: 모델 이름, 스키마 정보

生成模型代码

为模型生成TypeScript接口代码。

입력:
  - apiName: API 이름
  - modelName: 모델 이름
출력: TypeScript 인터페이스 코드

生成工具代码

为端点生成MCP工具定义代码。

입력:
  - apiName: API 이름
  - path: 엔드포인트 경로
  - method: HTTP 메서드
출력: MCP 도구 정의 TypeScript 코드

版本

返回MCP服务器版本。

使用示例

向AI请求API信息

"OI API의 엔드포인트 목록을 보여줘"
→ AI가 listApis로 API 확인 후 listEndpoints(apiName: "oi-api") 호출

"dalpha-api의 /users GET 엔드포인트에서 사용하는 모델 알려줘"
→ AI가 listEndpointModels(apiName: "dalpha-api", path: "/users", method: "GET") 호출

"User 모델의 TypeScript 인터페이스 생성해줘"
→ AI가 generateModelCode(apiName: "oi-api", modelName: "User") 호출

本地开发

要求

• Node.js v20或更高版本
• npm或pnpm

安装和构建

# 의존성 설치
npm install

# TypeScript 빌드
npm run build

# 로컬 실행
node build/index.js

Docker Compose

# 서비스 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f

文件结构

swagger-mcp/                    # MCP 서버 (Git 저장소)
├── apis.yaml.example          # API 설정 예시 파일
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts               # MCP 서버 진입점
    ├── tools/                 # MCP 도구 정의
    │   ├── listApis.ts        # [신규] API 목록 조회
    │   ├── listEndpoints.ts
    │   ├── listEndpointModels.ts
    │   ├── generateModelCode.ts
    │   └── generateEndpointToolCode.ts
    ├── services/              # 비즈니스 로직
    └── utils/
        ├── apiConfigLoader.ts # [신규] API 설정 로더
        ├── swaggerLoader.ts   # Swagger 로더 (다중 API 지원)
        └── logger.ts

your-project/                   # 사용하는 프로젝트
└── .cursor/
    ├── apis.yaml              # API 설정 파일 (여기에 생성!)
    └── mcp.json               # MCP 서버 설정

与现有版本的区别

许可证

MIT License-原始项目： Vizioz/Swagger MCP