# Swagger MCP (Multi-API Edition)

**[English](./README.en.md)** | 한국어

---

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

> 이 버전은 [Vizioz/Swagger-MCP](https://github.com/Vizioz/Swagger-MCP)를 포크하여 **다중 API 지원** 기능을 추가한 커스텀 버전입니다.

## 주요 기능

- **다중 API 지원**: `apis.yaml` 설정 파일로 여러 API를 단일 MCP 서버에서 관리
- **API 목록 조회**: `listApis` 도구로 설정된 모든 API 확인
- **엔드포인트 조회**: 특정 API의 모든 엔드포인트 목록 조회
- **모델 조회**: 특정 엔드포인트에서 사용하는 모델 정보 조회
- **TypeScript 코드 생성**: 모델 및 MCP 도구 정의 코드 자동 생성
- **캐싱**: Swagger 정의를 로컬에 캐싱하여 빠른 조회

## 빠른 시작

### 1. Docker로 실행 (권장)

```bash
# 이미지 빌드
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`을 참고하여 작성하세요:

```yaml
# .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` 파일에 추가:

```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를 추가/수정:

```yaml
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

### 설치 및 빌드

```bash
# 의존성 설치
npm install

# TypeScript 빌드
npm run build

# 로컬 실행
node build/index.js
```

### Docker Compose

```bash
# 서비스 시작
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](https://github.com/Vizioz/Swagger-MCP)