스웨거 익스플로러 MCP
Claude를 통해 Swagger/OpenAPI 사양을 탐색하고 분석하기 위한 MCP(Management Control Plane) 서버입니다.
빠른 시작
npx를 사용하여 전역적으로 설치하고 실행합니다.
지엑스피1
또는 환경 변수를 사용하여 설치합니다.
npx -y @johnneerdael/swagger-mcp \
--env BASE_URL=/api \
--env AUTH_TOKEN=your-token \
--env PORT=3000
Claude Desktop 설치
- 클로드 데스크톱 열기
- 설정(기어 아이콘)을 클릭하세요
- "도구 및 통합"을 선택하세요
- "MCP 서버 추가"를 클릭하세요
- 다음을 입력하세요.
Name: Swagger Explorer
Command: npx -y @johnneerdael/swagger-mcp
Arguments: --swagger-url=$SWAGGER_URL
- "설치"를 클릭하세요
Claude와 함께 사용
클로드와의 상호작용 사례는 다음과 같습니다.
기본 스웨거 탐색
Human: Can you explore the Swagger documentation at http://localhost:8080/docs?
Claude: I'll help you explore that Swagger documentation using the Swagger Explorer MCP.
Let me analyze the API endpoints and schemas for you:
[Claude would then use the MCP to fetch and analyze the Swagger documentation]
특정 엔드포인트 분석
Human: What are the available response schemas for the /pets POST endpoint?
Claude: I'll check the response schemas for that endpoint using the MCP.
[Claude would use the MCP to fetch specific endpoint details]
스키마 분석
Human: Can you show me the detailed structure of the Pet schema?
Claude: I'll retrieve the detailed schema information using the MCP.
[Claude would use the MCP to analyze the schema structure]
특징
- 인증 지원
- 사용자 정의 응답 형식
- 최소 형식: null/빈 값 제거
- 자세한 형식: 메타데이터 및 타임스탬프 포함
- 원시 형식: 수정되지 않은 응답
- 스키마 분석
- 자세한 부동산 탐색
- 응답 스키마 분석
- 스키마 관계
- API 탐색
구성
환경 변수:
BASE_URL : API의 기본 경로(기본값: '')AUTH_TOKEN : 인증을 위한 전달 토큰PORT : 서버 포트(기본값: 3000)SWAGGER_URL : 기본 Swagger 문서 URL
API 엔드포인트
API 탐색
curl -X POST http://localhost:3000/api/explore \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
"url": "http://your-swagger-url",
"options": {
"paths": true,
"schemas": true
}
}'
스키마 세부 정보 가져오기
curl -X POST http://localhost:3000/api/schema-details \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
"url": "http://your-swagger-url",
"schemaName": "Pet"
}'
응답 스키마 가져오기
curl -X POST http://localhost:3000/api/response-schemas \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
"url": "http://your-swagger-url",
"path": "/pets",
"method": "post"
}'
응답 형식
미니멀 포맷
{
"status": "success",
"data": {
// Only non-null values
}
}
자세한 형식
{
"status": "success",
"timestamp": "2025-01-29T10:00:00.000Z",
"data": {
// Full response
},
"metadata": {
"version": "1.0",
"format": "detailed"
}
}
일반적인 사용 사례
- API 문서 검토
Human: Can you summarize all the available endpoints and their purposes?
- 스키마 검증
Human: What fields are required for creating a new pet?
- 반응 분석
Human: What are the possible error responses for the login endpoint?
- 통합 계획
Human: How should I structure my request to create a new order?
문제 해결
- 연결 문제
- Swagger URL에 액세스할 수 있는지 확인하세요.
- 인증 토큰이 올바른지 확인하세요
- 포트가 사용 중이 아닌지 확인하세요
- 권한 부여 오류
- AUTH_TOKEN이 올바르게 설정되었는지 확인하세요
- 베어러 토큰이 요청에 포함되어 있는지 확인하세요.
- 스키마를 찾을 수 없습니다
- 스키마 이름이 정확히 일치하는지 확인하세요
- Swagger 사양이 올바르게 로드되었는지 확인하세요.
보안 참고 사항
- AUTH_TOKEN이 설정된 경우 MCP는 인증을 요구합니다.
- 모든 요청은 디버깅을 위해 기록됩니다.
- 민감한 정보는 캐시되지 않습니다.
- 남용을 방지하기 위해 속도 제한이 적용됩니다.
개발
기여하거나 수정하려면:
- 저장소를 복제합니다
- 종속성 설치:
- 짓다:
- 로컬로 실행:
특허
MIT 라이선스 - 자세한 내용은 라이선스 파일을 참조하세요.