@koseha/api-mcp 0.0.8 → 0.0.10

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,26 +1,16 @@
 /**
  * openapi.json HTTP 요청으로 읽기 + TTL 캐시
  */
-const DEFAULT_OPENAPI_URL = "https://petstore3.swagger.io/api/v3/openapi.json";
-let cache = null;
-let cachedAt = 0;
-const TTL = 5 * 60 * 1000; // 5분
+const OPENAPI_URL = process.env.OPENAPI_URL;
 export async function loadSwagger() {
-    if (cache && Date.now() - cachedAt < TTL) {
-        return cache;
-    }
-    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) {
             throw new Error(`HTTP ${response.status}: ${response.statusText} - ${openapiUrl}`);
         }
         const fileContent = await response.text();
-        cache = JSON.parse(fileContent);
-        cachedAt = Date.now();
-        return cache;
+        return JSON.parse(fileContent);
     }
     catch (error) {
         if (error instanceof Error) {

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) }],
         };