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

기존 버전과의 차이점

라이선스

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