# 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)
