Swagger Parser MCP Server

Swagger/OpenAPI JSON 파일을 파싱하여 API 정보를 분석하는 MCP 서버입니다.

Claude와 함께 사용하여 API 문서를 쉽게 분석하고 이해할 수 있습니다.

주요 기능

• ✅ 원하는 컨트롤러에 대한 path 리스트 조회
• ✅ JSON에서 컨트롤러(태그) 리스트 추출
• ✅ Path에 대한 parameters, requestBody, responseBody 정보 및 스키마 조회
• ✅ $ref로 참조된 스키마의 실제 타입 정보 제공 (자동 해결)

프로젝트 구조

swagger-parser-mcp-server/
├── swagger-parser-server.ts    # MCP 서버 메인 코드
├── example-client.ts          # 클라이언트 예제 코드
├── package.json              # 프로젝트 설정
├── tsconfig.json            # TypeScript 설정
├── README.md               # 이 파일
└── dist/                   # 빌드된 파일 (빌드 후 생성)

설치 및 사용법

방법 1: npx 등록 (권장)

1. MCP 설정

MCP 설정 파일(mcp.json 또는 Claude 설정)에 다음 내용을 추가합니다:

{
  "mcpServers": {
    "swagger-parser": {
      "command": "npx",
      "args": ["-y","swagger-parser-mcp-server"]
    }
  }
}

Claude Code CLI 사용시:

claude mcp add swagger-parser -- npx -y swagger-parser-mcp-server

방법 2: 소스코드 직접 사용

1. 소스코드 다운로드 및 빌드

# 저장소 클론 또는 파일 다운로드 후
cd swagger-parser-mcp-server

# 의존성 설치
npm install

# TypeScript 빌드
npm run build

2. MCP 설정

MCP 설정 파일을 열어 다음 내용을 추가합니다:

{
  "mcpServers": {
    "swagger-parser": {
      "command": "node",
      "args": ["<프로젝트 절대경로>/dist/index.js"]
    }
  }
}

Claude Code CLI 사용시:

claude mcp add swagger-parser node <프로젝트 절대경로>/dist/index.js

IDE에서 ./dist/index.js 파일 우클릭 후 절대 경로 복사 가능합니다.

3. Claude 재시작

설정을 저장한 후 Claude Desktop/Cursor/Claude Code를 재시작합니다.

사용 예시

⚠️ JSON 형태 스웨거를 반환하는 URL을 줘야합니다. 참고

Claude에서 다음과 같이 사용할 수 있습니다:

# Swagger JSON 로드
이 API 문서를 분석해줘: https://petstore.swagger.io/v2/swagger.json

# 컨트롤러 목록 보기
어떤 컨트롤러들이 있는지 보여줘

# 특정 컨트롤러의 API 목록
pet 컨트롤러의 모든 API를 보여줘

# API 상세 정보
GET /pet/{petId} API의 파라미터와 응답 스키마를 자세히 보여줘

# 스키마 정보
Pet 모델의 전체 스키마 구조를 보여줘

개발 모드

개발 중에는 TypeScript를 직접 실행할 수 있습니다:

npm run dev

프로그래밍 방식으로 사용하기

MCP 클라이언트를 구현하여 프로그래밍 방식으로도 사용할 수 있습니다:

import { SwaggerParserClient } from './example-client.js';

const client = new SwaggerParserClient();
await client.connect();

const url = "https://your-api.com/swagger.json";
const controllers = await client.getControllers(url);
const paths = await client.getPathsByController(url, "users");

await client.disconnect();

지원하는 OpenAPI 버전

• ✅ Swagger 2.0
• ✅ OpenAPI 3.0.x

문제 해결

"MCP 서버를 찾을 수 없습니다" 오류

1. 설정 파일의 경로가 올바른지 확인하세요
2. Node.js가 설치되어 있는지 확인하세요 (node --version)
3. 프로젝트가 빌드되었는지 확인하세요 (npm run build)

패키지 실행 오류

# npx 캐시 클리어
npx clear-npx-cache

# 패키지 재설치
npm uninstall swagger-parser-mcp-server
npm install swagger-parser-mcp-server

Swagger JSON 로드 실패

1. URL이 CORS를 허용하는지 확인하세요
2. JSON 형식이 올바른 Swagger/OpenAPI 형식인지 확인하세요

Cursor 에서 MCP 설정시 에러 로그 발생

서버 실행에서 에러나는 경우

1. npx cache 삭제

npm cache clean --force

2. IDE 종료후 재 실행

라이선스

MIT

기여하기

이슈와 PR은 언제나 환영합니다!