swagger-parser-mcp-server 2.3.4 → 3.0.0

package/README.md

@@ -1,111 +1,97 @@
 # Swagger Parser MCP Server
 
-Swagger/OpenAPI JSON 파일을 파싱하고, snapshot 캡처 및 diff 조회까지 지원하는 MCP 서버입니다.
+Swagger/OpenAPI JSON 파일을 파싱하여 API 정보를 분석하는 MCP 서버입니다.
 
-MCP 클라이언트에서 API 문서 분석과 변경 추적을 함께 사용할 수 있습니다.
+Claude와 함께 사용하여 API 문서를 쉽게 분석하고 이해할 수 있습니다.
 
 ## 주요 기능
 
-- Swagger/OpenAPI JSON 로드
-- 컨트롤러(태그) 목록 조회
-- 컨트롤러별 path 목록 조회
-- path별 parameters, request body, response schema 조회
-- `$ref` 스키마 해석
-- Postgres에 snapshot 영속화
-- snapshot 이력 조회
-- 두 snapshot 간 diff summary 조회
-- 특정 endpoint의 before/after diff detail 조회
+- ✅ 원하는 컨트롤러에 대한 path 리스트 조회
+- ✅ JSON에서 컨트롤러(태그) 리스트 추출
+- ✅ Path에 대한 parameters, requestBody, responseBody 정보 및 스키마 조회
+- ✅ $ref로 참조된 스키마의 실제 타입 정보 제공 (자동 해결)
 
-## 빠른 시작
+## 설치 및 사용법
 
-권장 방식은 `npx`로 MCP를 등록하는 것입니다. 로컬에 저장소를 clone해서 `node dist/index.js`를 직접 실행할 필요는 없습니다.
+### 방법 1: npx 등록 (권장)
 
-MCP 설정 파일(`mcp.json`, Claude Desktop 설정 등)에 아래와 같이 등록합니다.
+#### 1. MCP 설정
+MCP 설정 파일(`mcp.json` 또는 Claude 설정)에 다음 내용을 추가합니다:
 
 ```json
 {
   "mcpServers": {
     "swagger-parser": {
       "command": "npx",
-      "args": ["-y", "swagger-parser-mcp-server"],
-      "env": {
-        "DATABASE_URL": "postgresql://<db-user>:<db-password>@<db-host>:5432/<db-name>",
-        "PROJECT_KEY": "frontend-diff",
-        "SWAGGER_URL": "https://api.example.com/openapi.json",
-        "SNAPSHOT_WEB_ENABLED": "false"
-      }
+      "args": ["-y","swagger-parser-mcp-server"]
     }
   }
 }
 ```
 
-팀 공유용 예시:
+**Claude Code CLI 사용시:**
+```bash
+claude mcp add swagger-parser -- npx -y swagger-parser-mcp-server
+```
+
+### 방법 2: 소스코드 직접 사용
+
+#### 1. 소스코드 다운로드 및 빌드
+```bash
+# 저장소 클론 또는 파일 다운로드 후
+cd swagger-parser-mcp-server
+
+# 의존성 설치
+pnpm install
 
+# TypeScript 빌드
+pnpm run build
+```
+
+#### 2. MCP 설정
+
+MCP 설정 파일을 열어 다음 내용을 추가합니다:
 ```json
 {
   "mcpServers": {
-    "swagger-parser-team": {
-      "command": "npx",
-      "args": ["-y", "swagger-parser-mcp-server"],
-      "env": {
-        "DATABASE_URL": "postgresql://<db-user>:<db-password>@<db-host>:5432/<db-name>",
-        "PROJECT_KEY": "team.frontend-diff",
-        "SWAGGER_URL": "https://api.example.com/openapi.json",
-        "SNAPSHOT_WEB_ENABLED": "false"
-      }
+    "swagger-parser": {
+      "command": "node",
+      "args": ["<프로젝트 절대경로>/dist/index.js"]
     }
   }
 }
 ```
 
-주의:
-
-- README나 저장소에는 실제 DB 주소, 계정, 비밀번호를 커밋하지 마세요.
-- 실제 값은 각자 로컬 MCP 설정 파일이나 사내 비밀 관리 수단에만 넣어야 합니다.
-- snapshot/diff는 현재 설정된 `PROJECT_KEY` + `SWAGGER_URL` source에 고정됩니다.
-- 보통 API source 하나당 MCP 서버 엔트리 하나로 등록하는 것이 가장 단순합니다.
-
-## 환경 변수
-
-필수:
-
-- `DATABASE_URL`: snapshot/diff 저장용 Postgres 연결 문자열
-- `PROJECT_KEY`: source 식별자. 영문, 숫자, `.`, `_`, `-`만 허용
-- `SWAGGER_URL`: 캡처 대상 OpenAPI JSON URL
-
-선택:
+**Claude Code CLI 사용시:**
+```bash
+claude mcp add swagger-parser node <프로젝트 절대경로>/dist/index.js
+```
+> IDE에서 ./dist/index.js 파일 우클릭 후 절대 경로 복사 가능합니다.
 
-- `SNAPSHOT_WEB_ENABLED`: `false`면 MCP stdio 실행 시 내장 HTTP 서버를 비활성화합니다. MCP 전용이면 `false` 권장
-- `HTTP_HOST`: HTTP 서버 바인딩 주소. 기본값 `0.0.0.0`
-- `HTTP_PORT`: HTTP 서버 포트. 기본값 `3100`
+### 3. Claude 재시작
 
-## Snapshot / Diff 사용 순서
+설정을 저장한 후 Claude Desktop/Cursor/Claude Code를 재시작합니다.
 
-snapshot 관련 툴은 환경 변수에 고정된 source를 기준으로 동작합니다.
+## 사용 예시
 
-1. `capture_snapshot`
-2. `list_snapshots`
-3. `get_snapshot_diff`
-4. 필요하면 `get_endpoint_diff_detail`
+⚠️ JSON 형태 스웨거를 반환하는 URL을 줘야합니다.
 
-예시:
+Claude에서 다음과 같이 사용할 수 있습니다:
 
-```text
-현재 설정된 Swagger source를 snapshot으로 캡처해줘
-최근 snapshot 20개를 보여줘
-가장 최근 두 snapshot의 diff를 보여줘
-GET /users endpoint diff detail을 보여줘
 ```
-
-## 일반 Swagger 분석 예시
-
-⚠️ JSON 형태의 Swagger/OpenAPI 문서를 반환하는 URL이어야 합니다.
-
-```text
+# Swagger JSON 로드
 이 API 문서를 분석해줘: https://petstore.swagger.io/v2/swagger.json
+
+# 컨트롤러 목록 보기
 어떤 컨트롤러들이 있는지 보여줘
+
+# 특정 컨트롤러의 API 목록
 pet 컨트롤러의 모든 API를 보여줘
+
+# API 상세 정보
 GET /pet/{petId} API의 파라미터와 응답 스키마를 자세히 보여줘
+
+# 스키마 정보
 Pet 모델의 전체 스키마 구조를 보여줘
 ```
 
@@ -124,76 +110,51 @@ pnpm run build
 pnpm run dev
 ```
 
-HTTP 서버만 실행:
+## 테스트
 
 ```bash
-pnpm run dev:http
+pnpm run test
 ```
 
-Postgres migration 실행:
+## 지원하는 OpenAPI 버전
 
-```bash
-DATABASE_URL=postgresql://<user>:<pass>@<host>:5432/<db> pnpm run migrate
-```
+- ✅ Swagger 2.0
+- ✅ OpenAPI 3.0.x
 
-## 테스트
+## 문제 해결
 
-메모리 DB 기반 회귀 테스트:
+### "MCP 서버를 찾을 수 없습니다" 오류
+1. 설정 파일의 경로가 올바른지 확인하세요
+2. Node.js가 설치되어 있는지 확인하세요 (`node --version`)
+3. 프로젝트가 빌드되었는지 확인하세요 (`pnpm run build`)
 
+### 패키지 실행 오류
 ```bash
-pnpm run test:db:mem
-```
-
-실 Postgres 영속성 테스트:
+# npx 캐시 클리어
+npx clear-npx-cache
 
-```bash
-TEST_DATABASE_URL=postgresql://<user>:<pass>@<host>:5432/<db> pnpm run test:db:real
+# 패키지 재설치
+npm uninstall swagger-parser-mcp-server
+npm install swagger-parser-mcp-server
 ```
 
-## 선택 사항: Read-only Dashboard
+### Swagger JSON 로드 실패
+1. URL이 CORS를 허용하는지 확인하세요
+2. JSON 형식이 올바른 Swagger/OpenAPI 형식인지 확인하세요
 
-snapshot 이력과 diff를 브라우저에서 확인하려면 HTTP 서버를 사용할 수 있습니다.
+### Cursor 에서 MCP 설정시 에러 로그 발생
+> 서버 실행에서 에러나는 경우
 
-```bash
-HTTP_HOST=127.0.0.1 HTTP_PORT=3100 pnpm run start:http
+1. npx cache 삭제
 ```
-
-접속 경로:
-
-- `/dashboard`
-- `/api/snapshots`
-- `/api/snapshots/diff`
-- `/api/snapshots/endpoint-detail`
-
-MCP만 사용할 경우에는 `SNAPSHOT_WEB_ENABLED=false`를 권장합니다.
-
-## 문제 해결
-
-### MCP 서버가 뜨지 않는 경우
-
-1. Node.js 버전이 `>= 20`인지 확인하세요.
-2. `npx -y swagger-parser-mcp-server`가 로컬에서 실행되는지 확인하세요.
-3. MCP 설정 파일 JSON 문법이 올바른지 확인하세요.
-
-### DB 연결 실패
-
-1. `DATABASE_URL`이 Postgres 연결 문자열인지 확인하세요.
-2. MCP가 실행되는 환경에서 DB host/port로 접속 가능한지 확인하세요.
-3. 계정 권한과 방화벽 정책을 확인하세요.
-
-### Swagger 로드 실패
-
-1. `SWAGGER_URL`이 MCP가 실행되는 환경에서 접근 가능한지 확인하세요.
-2. 응답이 실제 JSON Swagger/OpenAPI 문서인지 확인하세요.
-3. 사내망 URL이라면 MCP 실행 위치에서 해당 네트워크에 접근 가능한지 확인하세요.
-
-### npx 실행 오류
-
-```bash
-npx clear-npx-cache
 npm cache clean --force
 ```
+2. IDE 종료후 재 실행
 
 ## 라이선스
 
 MIT
+
+## 기여하기
+
+이슈와 PR은 언제나 환영합니다!

package/dist/index.d.ts

@@ -1,6 +1,3 @@
 #!/usr/bin/env node
-type StdioInput = Pick<NodeJS.ReadStream, 'once' | 'off'>;
-export declare function attachStdioShutdownHooks(stdin: StdioInput, onClosed: () => void): () => void;
-export declare function isDirectExecution(argv?: readonly string[]): boolean;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AASA,KAAK,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;AAE1D,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAiB5F;AA2ED,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,OAAO,CAQjF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}