swagger-parser-mcp-server 2.0.4 → 2.3.0

package/README.md

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

package/dist/application/snapshot/createSnapshotRuntime.d.ts

@@ -0,0 +1,2 @@
+export { createSnapshotRuntime, type SnapshotRuntime, type SnapshotRuntimeDependencies, type SnapshotRuntimeDependencyFactory, } from '../../infrastructure/runtime/createSnapshotRuntime.js';
+//# sourceMappingURL=createSnapshotRuntime.d.ts.map

package/dist/application/snapshot/createSnapshotRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSnapshotRuntime.d.ts","sourceRoot":"","sources":["../../../src/application/snapshot/createSnapshotRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,2BAA2B,EAChC,KAAK,gCAAgC,GACtC,MAAM,uDAAuD,CAAC"}

package/dist/application/snapshot/createSnapshotRuntime.js

@@ -0,0 +1,2 @@
+export { createSnapshotRuntime, } from '../../infrastructure/runtime/createSnapshotRuntime.js';
+//# sourceMappingURL=createSnapshotRuntime.js.map

package/dist/application/snapshot/createSnapshotRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSnapshotRuntime.js","sourceRoot":"","sources":["../../../src/application/snapshot/createSnapshotRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAItB,MAAM,uDAAuD,CAAC"}

package/dist/application/snapshot/snapshotCaptureService.d.ts

@@ -0,0 +1,90 @@
+import { OpenAPIDocument } from '../../utils/types.js';
+import { CanonicalEndpointSnapshot, CanonicalOperationShape } from '../../domain/canonical/canonicalSnapshot.js';
+import { EndpointChangeDetail } from '../../domain/diff/endpointDiffClassifier.js';
+import { RuntimeEnvironment } from '../../domain/contracts/runtimeEnvironmentContract.js';
+import { SnapshotDiffResult } from '../../domain/contracts/snapshotDiffContract.js';
+import { SnapshotProjectRecord, SnapshotRecord, SnapshotRepository, SnapshotSourceRecord } from './snapshotRepository.js';
+export interface SnapshotDocumentLoader {
+    loadFresh(url: string): Promise<OpenAPIDocument>;
+}
+export interface SnapshotCaptureBootstrapResult {
+    environment: RuntimeEnvironment;
+    project: SnapshotProjectRecord;
+    source: SnapshotSourceRecord;
+}
+export interface SnapshotCaptureResult extends SnapshotCaptureBootstrapResult {
+    specHash: string;
+    snapshot: SnapshotRecord;
+    previousSnapshot: SnapshotRecord | null;
+    isNoopCapture: boolean;
+    diffResult: SnapshotDiffResult;
+}
+export interface SnapshotReplayInput {
+    baselineSnapshotId: string;
+    targetSnapshotId: string;
+}
+export interface SnapshotListItem {
+    id: string;
+    sourceId: string;
+    specHash: string;
+    documentFingerprint: string;
+    capturedAt: string;
+}
+export interface EndpointDiffDetailInput extends SnapshotReplayInput {
+    path: string;
+    method: CanonicalEndpointSnapshot['method'];
+}
+export interface EndpointDiffDetailResult {
+    baselineSnapshotId: string;
+    targetSnapshotId: string;
+    path: string;
+    method: CanonicalEndpointSnapshot['method'];
+    hasChange: boolean;
+    classification: 'breaking' | 'non-breaking' | 'info' | null;
+    changeReason: string | null;
+    details: EndpointChangeDetail[];
+    before: CanonicalOperationShape | null;
+    after: CanonicalOperationShape | null;
+}
+export interface EndpointChangeHistoryFilterInput {
+    sourceId: string;
+    limit?: number;
+    path?: string;
+    method?: CanonicalEndpointSnapshot['method'];
+}
+export interface EndpointChangeHistoryEvent {
+    baselineSnapshotId: string;
+    targetSnapshotId: string;
+    path: string;
+    method: CanonicalEndpointSnapshot['method'];
+    classification: 'breaking' | 'non-breaking' | 'info';
+    changeReason: string;
+    changedAt: string;
+}
+export interface EndpointChangeHistoryTransportResult {
+    projectKey: string;
+    sourceUrl: string;
+    filter: {
+        path: string | null;
+        method: CanonicalEndpointSnapshot['method'] | null;
+    };
+    events: EndpointChangeHistoryEvent[];
+}
+export declare function createSpecHash(document: OpenAPIDocument): string;
+export declare class SnapshotCaptureService {
+    private readonly repository;
+    private readonly loader;
+    private readonly now;
+    private initializePromise;
+    constructor(repository: SnapshotRepository, loader: SnapshotDocumentLoader, now?: () => Date);
+    initialize(): Promise<void>;
+    private resolveBootstrapContext;
+    bootstrap(env: RuntimeEnvironment | NodeJS.ProcessEnv): Promise<SnapshotCaptureBootstrapResult>;
+    capture(env: RuntimeEnvironment | NodeJS.ProcessEnv): Promise<SnapshotCaptureResult>;
+    listSnapshotsBySource(sourceId: string, limit?: number): Promise<SnapshotListItem[]>;
+    listEndpointChangeHistory(input: EndpointChangeHistoryFilterInput): Promise<EndpointChangeHistoryEvent[]>;
+    private resolveReplaySnapshots;
+    replayDiff(input: SnapshotReplayInput): Promise<SnapshotDiffResult>;
+    getEndpointDiffDetail(input: EndpointDiffDetailInput): Promise<EndpointDiffDetailResult>;
+}
+//# sourceMappingURL=snapshotCaptureService.d.ts.map

package/dist/application/snapshot/snapshotCaptureService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotCaptureService.d.ts","sourceRoot":"","sources":["../../../src/application/snapshot/snapshotCaptureService.ts"],"names":[],"mappings":"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"}