Swagger (Multi API Edition)

English | 한국어

---

AI가 Swagger/OpenAPI 문서를 이해하고 활용할 수 있도록 도와주는 MCP 서버입니다.

이 버전은 Vizioz/Swagger-MCP를 포크하여 다중 API 지원 기능을 추가한 커스텀 버전입니다.

주요 기능

• 다중 API 지원: apis.yaml 설정 파일로 여러 API를 단일 MCP 서버에서 관리
• 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 목록

listEndpoints

특정 API의 모든 엔드포인트를 조회합니다.

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

listEndpointModels

특정 엔드포인트에서 사용하는 모델을 조회합니다.

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

generateModelCode

모델의 TypeScript 인터페이스 코드를 생성합니다.

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

generateEndpointToolCode

엔드포인트를 위한 MCP 도구 정의 코드를 생성합니다.

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

version

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 서버 설정

기존 버전과의 차이점

기능	기존 버전	Multi-API Edition
API 개수	1개 (CLI 인자)	무제한 (설정 파일)
API 추가	MCP 서버 재등록	apis.yaml 수정만
API 선택	불가	apiName 파라미터
설정 방식	CLI 인자	YAML 설정 파일

라이선스

MIT License - 원본 프로젝트: Vizioz/Swagger-MCP