@koseha/api-mcp 0.0.9 → 0.0.11

package/README.md

@@ -45,7 +45,10 @@ Cursor 설정 파일에 추가:
   "mcpServers": {
     "api-mcp": {
       "command": "node",
-      "args": ["./node_modules/@koseha/api-mcp/dist/index.js"]
+      "args": ["./node_modules/@koseha/api-mcp/dist/index.js"],
+      "env": {
+        "OPENAPI_URL": <your swagger.json url ex.'https://petstore3.swagger.io/api/v3/openapi.json'>
+      }
     }
   }
 }
@@ -75,7 +78,10 @@ Claude Desktop 설정 파일에 추가:
   "mcpServers": {
     "api-mcp": {
       "command": "npx",
-      "args": ["-y", "@koseha/api-mcp"]
+      "args": ["-y", "@koseha/api-mcp"],
+      "env": {
+        "OPENAPI_URL": "https://api.example.com/openapi.json"
+      }
     }
   }
 }
@@ -88,7 +94,10 @@ Claude Desktop 설정 파일에 추가:
   "mcpServers": {
     "api-mcp": {
       "command": "node",
-      "args": ["/path/to/api-mcp/dist/index.js"]
+      "args": ["/path/to/api-mcp/dist/index.js"],
+      "env": {
+        "OPENAPI_URL": "https://api.example.com/openapi.json"
+      }
     }
   }
 }
@@ -203,8 +212,11 @@ api-mcp/
 │   ├── resources/            # 리소스 모듈
 │   │   ├── index.ts
 │   │   └── greeting.resource.ts
-│   └── swagger/              # Swagger 로더
-│       └── swaggerLoader.ts
+│   └── swagger/              # Swagger 로더 및 변환기
+│       ├── swaggerLoader.ts
+│       ├── apiTransformer.ts
+│       ├── schemaResolver.ts
+│       └── types.ts
 ├── dist/                     # 빌드된 파일
 ├── openapi.json             # OpenAPI 스펙 파일
 ├── package.json
@@ -212,9 +224,15 @@ api-mcp/
 └── README.md
 ```
 
-## OpenAPI 스펙 파일
+## OpenAPI 스펙 설정
 
-프로젝트 루트의 `openapi.json` 파일을 수정하여 사용할 API 스펙을 설정할 수 있습니다. 기본적으로 5분간 캐시되며, 파일 변경 시 자동으로 다시 로드됩니다.
+`OPENAPI_URL` 환경 변수를 통해 OpenAPI 문서의 URL을 설정해야 합니다. 서버 시작 시 이 환경 변수가 설정되지 않으면 서버가 시작되지 않습니다.
+
+예시:
+
+```bash
+export OPENAPI_URL=https://api.example.com/openapi.json
+```
 
 ## 의존성
 
@@ -231,13 +249,14 @@ api-mcp/
 
 ## 버전
 
-현재 버전: **0.0.7**
+현재 버전: **0.0.10**
 
 ## History
 
-| 버전  | 날짜           | 변경사항                                                                                                                                      |
-| ----- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| 0.0.7 | KST 2025.12.31 | - tool 요청 시 openapi.json 문서의 특정 부분만 추출하여 사용하도록 변경 <br/> >> 전체 openapi.json 문서 내용이 사용되지 않도록 함. token 절약 |
+| 버전   | 날짜           | 변경사항                                                                                                                                                |
+| ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0.0.10 | KST 2025.12.31 | - OpenAPI 문서를 HTTP 요청으로 로드하도록 변경 <br/> - OPENAPI_URL 환경 변수 필수 검증 추가 <br/> - API 상세 조회 로직 리팩토링 (apiTransformer 모듈화) |
+| 0.0.7  | KST 2025.12.31 | - tool 요청 시 openapi.json 문서의 특정 부분만 추출하여 사용하도록 변경 <br/> >> 전체 openapi.json 문서 내용이 사용되지 않도록 함. token 절약           |
 
 ## 라이선스
 

package/dist/index.js

@@ -6,6 +6,14 @@ import { createServer } from "./server.js";
 import { registerTools } from "./tools/index.js";
 import { registerResources } from "./resources/index.js";
 async function main() {
+    // OPENAPI_URL 환경 변수 검증
+    if (!process.env.OPENAPI_URL) {
+        const error = new Error("OPENAPI_URL 환경 변수가 설정되지 않았습니다. 서버를 시작할 수 없습니다.\n" +
+            "환경 변수를 설정한 후 다시 시도해주세요.\n" +
+            "예: export OPENAPI_URL=https://api.example.com/openapi.json");
+        process.stderr.write(error.message + "\n");
+        process.exit(1);
+    }
     const server = createServer();
     registerTools(server);
     registerResources(server);

package/dist/swagger/apiTransformer.js

@@ -0,0 +1,96 @@
+/**
+ * OpenAPI Operation을 변환하는 유틸리티
+ */
+import { resolveSchema } from "./schemaResolver.js";
+/**
+ * 스키마를 간소화된 형태로 변환
+ */
+function transformSchema(schema) {
+    if (!schema)
+        return null;
+    return {
+        type: schema.type || null,
+        format: schema.format || null,
+        enum: schema.enum || null,
+        properties: schema.properties || null,
+        items: schema.items || null,
+        required: schema.required || null,
+    };
+}
+/**
+ * Parameters를 변환
+ */
+function transformParameters(parameters, swagger) {
+    if (!parameters || !Array.isArray(parameters)) {
+        return [];
+    }
+    return parameters.map((param) => {
+        let resolvedSchema = null;
+        if (param.schema) {
+            resolvedSchema = resolveSchema(param.schema, swagger);
+        }
+        return {
+            name: param.name,
+            in: param.in,
+            required: param.required || false,
+            description: param.description || null,
+            schema: transformSchema(resolvedSchema),
+        };
+    });
+}
+/**
+ * RequestBody를 변환
+ */
+function transformRequestBody(requestBody, swagger) {
+    if (!requestBody?.content) {
+        return null;
+    }
+    const jsonContent = requestBody.content["application/json"];
+    if (!jsonContent?.schema) {
+        return null;
+    }
+    const resolvedSchema = resolveSchema(jsonContent.schema, swagger);
+    return {
+        required: resolvedSchema.required || [],
+        type: resolvedSchema.type || "object",
+        properties: resolvedSchema.properties || {},
+        description: requestBody.description || null,
+    };
+}
+/**
+ * Response를 변환 (200 응답 우선)
+ */
+function transformResponse(responses, swagger) {
+    if (!responses?.["200"]?.content?.["application/json"]?.schema) {
+        return null;
+    }
+    const schema = responses["200"].content["application/json"].schema;
+    const resolvedSchema = resolveSchema(schema, swagger);
+    return {
+        type: resolvedSchema.type || "object",
+        properties: resolvedSchema.properties || undefined,
+        items: resolvedSchema.items || undefined,
+    };
+}
+/**
+ * OpenAPI Operation을 API 상세 정보로 변환
+ */
+export function transformApiDetail(operation, swagger) {
+    const result = {};
+    // Parameters 변환
+    const parameters = transformParameters(operation.parameters, swagger);
+    if (parameters.length > 0) {
+        result.parameters = parameters;
+    }
+    // RequestBody 변환
+    const requestBody = transformRequestBody(operation.requestBody, swagger);
+    if (requestBody) {
+        result.requestBody = requestBody;
+    }
+    // Response 변환
+    const responses = transformResponse(operation.responses, swagger);
+    if (responses) {
+        result.responses = responses;
+    }
+    return result;
+}

package/dist/swagger/schemaResolver.js

@@ -0,0 +1,84 @@
+/**
+ * OpenAPI $ref 참조 해결 유틸리티
+ */
+/**
+ * $ref 경로를 실제 객체 경로로 변환
+ * @example "#/components/schemas/Pet" -> swagger.components.schemas.Pet
+ */
+function resolveRefPath(ref, swagger) {
+    if (!ref.startsWith("#/")) {
+        return null; // 외부 참조는 지원하지 않음
+    }
+    const path = ref.substring(2).split("/"); // "#/components/schemas/Pet" -> ["components", "schemas", "Pet"]
+    let result = swagger;
+    for (const key of path) {
+        if (result && typeof result === "object" && key in result) {
+            result = result[key];
+        }
+        else {
+            return null;
+        }
+    }
+    return result;
+}
+/**
+ * 스키마 객체의 모든 $ref를 재귀적으로 해결
+ * @param schema - 해결할 스키마 객체
+ * @param swagger - 전체 OpenAPI 스펙
+ * @param visited - 순환 참조 방지를 위한 방문한 $ref 경로 Set
+ */
+export function resolveSchema(schema, swagger, visited = new Set()) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return schema;
+    }
+    // $ref가 있으면 해결
+    if (schema.$ref) {
+        const refPath = schema.$ref;
+        // 순환 참조 방지
+        if (visited.has(refPath)) {
+            return { $ref: refPath, _circular: true };
+        }
+        visited.add(refPath);
+        const resolved = resolveRefPath(refPath, swagger);
+        if (resolved) {
+            // 해결된 스키마를 재귀적으로 처리 (중첩된 $ref도 해결)
+            const resolvedSchema = resolveSchema(resolved, swagger, visited);
+            visited.delete(refPath);
+            return resolvedSchema;
+        }
+        visited.delete(refPath);
+        return schema;
+    }
+    // 배열인 경우 items 처리
+    if (schema.type === "array" && schema.items) {
+        return {
+            ...schema,
+            items: resolveSchema(schema.items, swagger, visited),
+        };
+    }
+    // 객체인 경우 properties와 allOf, anyOf, oneOf 처리
+    if (schema.type === "object" ||
+        schema.properties ||
+        schema.allOf ||
+        schema.anyOf ||
+        schema.oneOf) {
+        const resolved = { ...schema };
+        if (schema.properties) {
+            resolved.properties = {};
+            for (const [key, value] of Object.entries(schema.properties)) {
+                resolved.properties[key] = resolveSchema(value, swagger, visited);
+            }
+        }
+        if (schema.allOf) {
+            resolved.allOf = schema.allOf.map((item) => resolveSchema(item, swagger, visited));
+        }
+        if (schema.anyOf) {
+            resolved.anyOf = schema.anyOf.map((item) => resolveSchema(item, swagger, visited));
+        }
+        if (schema.oneOf) {
+            resolved.oneOf = schema.oneOf.map((item) => resolveSchema(item, swagger, visited));
+        }
+        return resolved;
+    }
+    return schema;
+}

package/dist/swagger/swaggerLoader.js

@@ -1,11 +1,9 @@
 /**
  * openapi.json HTTP 요청으로 읽기 + TTL 캐시
  */
-const DEFAULT_OPENAPI_URL = "https://petstore3.swagger.io/api/v3/openapi.json";
+const OPENAPI_URL = process.env.OPENAPI_URL;
 export async function loadSwagger() {
-    const openapiUrl = process.env.OPENAPI_URL ||
-        process.env.OPENAPI_JSON_URL ||
-        DEFAULT_OPENAPI_URL;
+    const openapiUrl = OPENAPI_URL;
     try {
         const response = await fetch(openapiUrl);
         if (!response.ok) {

package/dist/swagger/types.js

@@ -0,0 +1,4 @@
+/**
+ * OpenAPI 스펙 관련 타입 정의
+ */
+export {};

package/dist/tools/getApiDetail.tool.js

@@ -3,6 +3,7 @@
  */
 import { z } from "zod";
 import { loadSwagger } from "../swagger/swaggerLoader.js";
+import { transformApiDetail } from "../swagger/apiTransformer.js";
 export function registerGetApiDetail(server) {
     server.registerTool("getApiDetail", {
         title: "API 상세 조회",
@@ -20,55 +21,13 @@ export function registerGetApiDetail(server) {
             };
         }
         const swagger = await loadSwagger();
-        const api = swagger.paths?.[requestUrl]?.[httpMethod];
-        if (!api) {
+        const operation = swagger.paths?.[requestUrl]?.[httpMethod];
+        if (!operation) {
             return {
                 content: [{ type: "text", text: "해당 API를 찾을 수 없습니다." }],
             };
         }
-        // parameters 변환
-        const parameters = (api.parameters || []).map((param) => ({
-            name: param.name,
-            in: param.in,
-            required: param.required || false,
-            schema: {
-                type: param.schema?.type || null,
-                format: param.schema?.format || null,
-                enum: param.schema?.enum || null,
-            },
-        }));
-        // requestBody 변환
-        let requestBody = null;
-        if (api.requestBody?.content) {
-            const jsonContent = api.requestBody.content["application/json"];
-            if (jsonContent?.schema) {
-                const schema = jsonContent.schema;
-                requestBody = {
-                    required: schema.required || [],
-                    type: schema.type || "object",
-                    properties: schema.properties || {},
-                };
-            }
-        }
-        // responses 변환 (200 응답의 schema 추출)
-        let responses = null;
-        if (api.responses?.["200"]?.content?.["application/json"]?.schema) {
-            const schema = api.responses["200"].content["application/json"].schema;
-            responses = {
-                type: schema.type || "object",
-                properties: schema.properties || {},
-            };
-        }
-        const result = {};
-        if (parameters.length > 0) {
-            result.parameters = parameters;
-        }
-        if (requestBody) {
-            result.requestBody = requestBody;
-        }
-        if (responses) {
-            result.responses = responses;
-        }
+        const result = transformApiDetail(operation, swagger);
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };

package/dist/tools/getServices.tool.js

@@ -0,0 +1,48 @@
+/**
+ * Tool: 서비스 목록 조회
+ */
+import { loadSwagger } from "../swagger/swaggerLoader.js";
+/**
+ * Swagger 문서에서 모든 고유한 tags 추출
+ */
+function extractApiGroups(swagger) {
+    const tags = new Set();
+    // tags 배열에서 추출
+    if (Array.isArray(swagger.tags)) {
+        swagger.tags.forEach((tag) => {
+            if (typeof tag === "string") {
+                tags.add(tag);
+            }
+            else if (tag?.name) {
+                tags.add(tag.name);
+            }
+        });
+    }
+    // paths에서 tags 추출
+    if (swagger.paths && typeof swagger.paths === "object") {
+        for (const path of Object.values(swagger.paths)) {
+            if (path && typeof path === "object") {
+                for (const method of Object.values(path)) {
+                    if (method &&
+                        typeof method === "object" &&
+                        Array.isArray(method.tags)) {
+                        method.tags.forEach((tag) => tags.add(tag));
+                    }
+                }
+            }
+        }
+    }
+    return Array.from(tags).sort();
+}
+export function registerGetServices(server) {
+    server.registerTool("getServices", {
+        title: "서비스 목록 조회",
+        description: "서비스 목록을 조회합니다.",
+    }, async () => {
+        const swagger = await loadSwagger();
+        const apiGroups = extractApiGroups(swagger);
+        return {
+            content: [{ type: "text", text: JSON.stringify(apiGroups, null, 2) }],
+        };
+    });
+}

package/dist/utils/envParser.js

@@ -0,0 +1,84 @@
+/**
+ * 환경 변수 파싱 및 검증 유틸리티
+ */
+/**
+ * URL 유효성 검증
+ */
+function isValidUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * OPENAPI_URL 환경 변수를 파싱하여 URL 배열로 반환
+ *
+ * 지원 형식:
+ * 1. JSON 배열: ["https://api1.com/openapi.json","https://api2.com/openapi.json"]
+ * 2. 단일 문자열: https://api.example.com/openapi.json (하위 호환성)
+ *
+ * @returns URL 배열
+ * @throws Error - 파싱 실패 또는 유효하지 않은 URL이 있는 경우
+ */
+export function parseOpenApiUrls(envValue) {
+    if (!envValue) {
+        throw new Error("OPENAPI_URL 환경 변수가 설정되지 않았습니다. 서버를 시작할 수 없습니다.\n" +
+            "환경 변수를 설정한 후 다시 시도해주세요.\n" +
+            '예: export OPENAPI_URL=["https://api.example.com/openapi.json"]\n' +
+            "또는: export OPENAPI_URL=https://api.example.com/openapi.json");
+    }
+    let urls;
+    // JSON 배열 형식인지 확인
+    const trimmed = envValue.trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            // 배열인지 확인
+            if (!Array.isArray(parsed)) {
+                throw new Error("OPENAPI_URL이 JSON 배열 형식이지만 배열이 아닙니다.\n" +
+                    '올바른 형식: ["https://api1.com/openapi.json","https://api2.com/openapi.json"]');
+            }
+            // 각 요소가 문자열인지 확인
+            if (!parsed.every((item) => typeof item === "string")) {
+                throw new Error("OPENAPI_URL 배열의 모든 요소는 문자열이어야 합니다.\n" +
+                    '올바른 형식: ["https://api1.com/openapi.json","https://api2.com/openapi.json"]');
+            }
+            urls = parsed;
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error("OPENAPI_URL의 JSON 형식이 올바르지 않습니다.\n" +
+                    '올바른 형식: ["https://api1.com/openapi.json","https://api2.com/openapi.json"]\n' +
+                    `오류: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    else {
+        // 단일 문자열 형식 (하위 호환성)
+        urls = [trimmed];
+    }
+    // 빈 배열 검증
+    if (urls.length === 0) {
+        throw new Error("OPENAPI_URL 배열이 비어있습니다. 최소 1개 이상의 URL이 필요합니다.\n" +
+            '올바른 형식: ["https://api1.com/openapi.json","https://api2.com/openapi.json"]');
+    }
+    // 중복 제거
+    urls = [...new Set(urls)];
+    // 각 URL 유효성 검증
+    const invalidUrls = [];
+    urls.forEach((url, index) => {
+        if (!isValidUrl(url)) {
+            invalidUrls.push(`인덱스 ${index}: "${url}"`);
+        }
+    });
+    if (invalidUrls.length > 0) {
+        throw new Error("OPENAPI_URL에 유효하지 않은 URL이 있습니다:\n" +
+            invalidUrls.join("\n") +
+            "\n\n모든 URL은 http:// 또는 https://로 시작하는 유효한 URL이어야 합니다.");
+    }
+    return urls;
+}