@nhnpayco-dev/mcp-devcenter 1.1.0 → 1.2.0

package/dist/data/index.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "source_site": "https://devcenter.payco.com",
   "scope": "PAYCO 가이드 전체 (온라인결제·자동결제·오프라인결제·오더클라우드·멤버십클라우드·결제정산대사)",
-  "generated_at": "2026-10-14T04:35:38+00:00",
+  "generated_at": "2026-10-26T02:06:57+00:00",
   "category_count": 28,
   "categories": [
     {

package/dist/tools.js

@@ -72,6 +72,106 @@ function flattenPayload(payload) {
         visit(k, v);
     return out;
 }
+/** 명세 필수 항목(점 경로)이 payload 에 없는 위치를 찾는다.
+ *
+ *  - 배열은 원소마다 확인하고 위치를 표시한다. 예) orderProducts[1].productId
+ *  - 하위 항목은 상위 항목을 보냈을 때만 확인한다(상위가 없으면 상위 자체의 필수 여부로 판단).
+ *    예) sign 을 보내지 않으면 sign.signData 는 확인하지 않는다.
+ */
+function findMissingRequired(root, path) {
+    const segs = path.split(".");
+    const out = [];
+    const walk = (val, i, at) => {
+        if (Array.isArray(val)) {
+            val.forEach((el, k) => walk(el, i, `${at}[${k}]`));
+            return;
+        }
+        if (i === segs.length)
+            return;
+        if (!val || typeof val !== "object")
+            return; // 상위가 객체가 아니면 타입 검사에서 다룬다
+        const key = segs[i];
+        const here = at ? `${at}.${key}` : key;
+        const obj = val;
+        if (!(key in obj) || obj[key] === undefined || obj[key] === null) { // null 은 보내지 않은 것으로 본다
+            if (i === segs.length - 1)
+                out.push(here); // 마지막 단계에서만 누락으로 본다
+            return;
+        }
+        walk(obj[key], i + 1, here);
+    };
+    walk(root, 0, "");
+    return out;
+}
+/** 명세 타입 표기(string(10), integer, double, list<string>, 형식 등)와 실제 값이 맞는지.
+ *  - 숫자 계열(number/integer/int/long/float/double)은 숫자 또는 숫자 형태의 문자열("67300")을 허용한다.
+ *    PAYCO 서버가 숫자 문자열도 처리한다(2026-10-23 확인). 가이드 공식 샘플도 문자열로 보낸다.
+ *  - 판별할 수 없는 표기(unknown, 표 파싱 잔재 등)는 검사하지 않는다(null 반환).
+ */
+function typeMatches(declared, value) {
+    const t = declared.toLowerCase();
+    const actual = Array.isArray(value) ? "array" : typeof value;
+    if (/^(number|integer|int|long|float|double)\b/.test(t)) {
+        return actual === "number" || (actual === "string" && /^-?\d+(\.\d+)?$/.test(value.trim()));
+    }
+    if (/^(array|list)/.test(t))
+        return actual === "array";
+    if (/^string/.test(t))
+        return actual === "string";
+    if (/^object/.test(t))
+        return actual === "object";
+    if (/^boolean/.test(t))
+        return actual === "boolean";
+    return null;
+}
+/** 조건부 항목(when)이 이 payload 에 해당하는지. 예) sign 하위 항목은 vanCorpCode 가 맞을 때만 */
+function whenApplies(root, when) {
+    if (!when)
+        return true;
+    return Object.entries(when).every(([field, values]) => {
+        const v = root[field];
+        return typeof v === "string" && values.includes(v.trim());
+    });
+}
+/** extraData 는 가이드상 JSON 문자열이다. 검사용 사본에서 문자열을 풀어 안쪽 항목까지 검사한다.
+ *  - 문자열이면 JSON 으로 풀어 객체로 바꾼다(타입은 정상).
+ *  - 깨진 JSON 이면 문제로 보고하고 안쪽은 검사하지 않는다.
+ *  - 객체로 보냈으면 안쪽은 검사하되, 문자열로 보내야 한다는 타입 문제를 보고한다.
+ */
+function expandExtraData(obj) {
+    const ed = obj["extraData"];
+    if (ed === undefined)
+        return { view: obj, issues: [] };
+    if (typeof ed === "string") {
+        try {
+            const parsed = JSON.parse(ed);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return { view: { ...obj, extraData: parsed }, issues: [] };
+            }
+            return { view: obj, issues: ["extraData: 올바른 JSON 문자열이 아닙니다 — JSON 객체를 문자열로 바꾼 값이어야 합니다"] };
+        }
+        catch (e) {
+            return { view: obj, issues: [`extraData: 올바른 JSON 문자열이 아닙니다 — ${e.message}`] };
+        }
+    }
+    if (ed && typeof ed === "object" && !Array.isArray(ed)) {
+        return {
+            view: obj,
+            issues: ["extraData: 명세 'string' / 실제 'object' — JSON 객체를 문자열로 바꿔서(JSON.stringify) 보내야 합니다"],
+        };
+    }
+    return { view: obj, issues: [] }; // 그 밖의 타입은 일반 타입 검사에서 다룬다
+}
+/** 최상위에 없으면 extraData(검사용으로 풀린 객체) 안에서 찾는다 */
+function pickField(obj, field) {
+    if (field in obj)
+        return obj[field];
+    const ed = obj["extraData"];
+    if (ed && typeof ed === "object" && !Array.isArray(ed) && field in ed) {
+        return ed[field];
+    }
+    return undefined;
+}
 /** 본문에서 query 가 포함된 줄(앞뒤 줄 포함) 발췌 */
 function snippetLines(md, query, maxHits = 5) {
     const q = query.toLowerCase();
@@ -89,14 +189,34 @@ function autoCheckPii(obj) {
     // 객체의 문자열 값들을 개별 검사 (JSON 직렬화 시 인접 숫자들이 false-positive 유발 방지)
     const hits = [];
     // 앞뒤에 추가 숫자가 없을 때만 매칭 (timestamp 같은 긴 숫자에서 부분 매칭 회피)
-    const RE_RRN = /(?<!\d)\d{6}-?[1-4]\d{6}(?!\d)/; // 주민번호 13자리
-    const RE_CARD = /(?<!\d)\d{4}-?\d{4}-?\d{4}-?\d{4}(?!\d)/; // 카드 16자리
+    // 주민번호 13자리. 앞 6자리가 실제 날짜(YYMMDD)일 때만 본다 — 주문번호의 13자리 시각 값(1640064545311) 오탐 방지
+    const RE_RRN = /(?<!\d)(\d{2})(\d{2})(\d{2})-?[1-4]\d{6}(?!\d)/g;
+    // 카드 16자리. 카드번호 검증 규칙(Luhn)을 통과할 때만 본다 — 16자리 거래번호(2022021610443637) 오탐 방지
+    const RE_CARD = /(?<!\d)\d{4}-?\d{4}-?\d{4}-?\d{4}(?!\d)/g;
     const RE_PHONE = /(?<!\d)01[0-9]-?\d{3,4}-?\d{4}(?!\d)/; // 휴대전화 10~11자리
+    const hasRrn = (s) => [...s.matchAll(RE_RRN)].some((m) => {
+        const mm = Number(m[2]), dd = Number(m[3]);
+        return mm >= 1 && mm <= 12 && dd >= 1 && dd <= 31;
+    });
+    const luhn = (digits) => {
+        let sum = 0;
+        for (let i = 0; i < digits.length; i++) {
+            let d = Number(digits[digits.length - 1 - i]);
+            if (i % 2 === 1) {
+                d *= 2;
+                if (d > 9)
+                    d -= 9;
+            }
+            sum += d;
+        }
+        return sum % 10 === 0;
+    };
+    const hasCard = (s) => [...s.matchAll(RE_CARD)].some((m) => luhn(m[0].replace(/-/g, "")));
     const visit = (v) => {
         if (typeof v === "string") {
-            if (RE_RRN.test(v) && !hits.includes("주민번호 패턴"))
+            if (hasRrn(v) && !hits.includes("주민번호 패턴"))
                 hits.push("주민번호 패턴");
-            if (RE_CARD.test(v) && !hits.includes("카드번호 패턴"))
+            if (hasCard(v) && !hits.includes("카드번호 패턴"))
                 hits.push("카드번호 패턴");
             if (RE_PHONE.test(v) && !hits.includes("전화번호 패턴"))
                 hits.push("전화번호 패턴");
@@ -169,20 +289,21 @@ function makeEnumCheck(field, allowed) {
 }
 function makeDateYmdtCheck(fields) {
     return (obj) => {
-        const present = fields.filter((f) => f in obj && typeof obj[f] === "string");
+        const present = fields.filter((f) => typeof pickField(obj, f) === "string");
         if (present.length === 0)
             return null;
-        const fails = present.filter((f) => !/^\d{14}$/.test(obj[f]));
+        const fails = present.filter((f) => !/^\d{14}$/.test(pickField(obj, f)));
         return fails.length === 0
             ? { pass: true }
-            : { pass: false, message: `YYYYMMDDHHmmss 14자리 필요: ${fails.map((f) => `${f}='${obj[f]}'`).join(", ")}` };
+            : { pass: false, message: `YYYYMMDDHHmmss 14자리 필요: ${fails.map((f) => `${f}='${pickField(obj, f)}'`).join(", ")}` };
     };
 }
 function makeDateYmdCheck(field, allowFull = false) {
     return (obj) => {
-        if (!(field in obj) || typeof obj[field] !== "string")
+        const picked = pickField(obj, field);
+        if (typeof picked !== "string")
             return null;
-        const val = obj[field];
+        const val = picked;
         const ok = /^\d{8}$/.test(val) || (allowFull && /^\d{14}$/.test(val));
         return ok
             ? { pass: true }
@@ -649,7 +770,7 @@ export function registerAllTools(server, store) {
         title: "API 요청 페이로드 자동 검증 + 검수 체크리스트",
         description: "PAYCO API 요청 페이로드(JSON)를 검증하고 서비스별 검수 체크리스트를 반환한다. " +
             "반환값은 반드시 사용자에게 전체 그대로 보여줄 것 — 요약하거나 생략하지 말 것. " +
-            "체크리스트 항목은 ✓(자동통과) / ✗(자동실패, 이유 포함) / ⊘(필드 없어 스킵) / ⬜(수동확인 필요) 로 표시됨. " +
+            "체크리스트 항목은 ✓(통과) / ✗(수정 필요, 이유 포함) / ⊘(필드 없어 스킵) / ⬜(수동확인 필요) 로 표시됨. " +
             "⚠️ 운영 로그(실제 카드번호/주민번호/연락처)는 절대 그대로 붙여넣지 말 것.",
         inputSchema: {
             api: z
@@ -678,36 +799,53 @@ export function registerAllTools(server, store) {
             return notFound(`JSON 파싱 실패: ${e.message}`);
         }
         // --- API 명세 검증 (nested 평탄화 비교) ---
+        // extraData(JSON 문자열)는 검사용 사본(view)에서 풀어 안쪽까지 검사한다
+        const { view, issues: extraDataIssues } = expandExtraData(obj);
         const specByName = new Map(spec.request_params.map((p) => [p.name, p]));
-        const flat = flattenPayload(obj);
+        const hasChildren = (name) => spec.request_params.some((q) => q.name.startsWith(name + "."));
+        const flat = flattenPayload(view);
         const missingRequired = [];
         const unknownParams = [];
-        const typeMismatches = [];
-        // 필수 누락: 명세 required 키가 평탄화된 payload 키에 없음
+        const typeMismatches = [...extraDataIssues];
+        // 필수 누락: 배열은 원소마다, 하위 항목은 상위를 보냈을 때만 확인
         for (const p of spec.request_params) {
-            if (p.required && !flat.has(p.name)) {
-                missingRequired.push(`${p.name} (${p.type}) — ${p.description.slice(0, 60)}`);
+            if (!p.required || !whenApplies(view, p.when))
+                continue;
+            for (const at of findMissingRequired(view, p.name)) {
+                missingRequired.push(`${at} (${p.type}) — ${p.description.slice(0, 60)}`);
             }
         }
         // 알 수 없는 파라미터: payload 의 평탄화 키 중 명세에 없는 것
+        // 하위 항목이 정의되지 않은 객체(예: 결제 취소의 extras)는 안쪽을 판단할 수 없으므로 명세 외로 보지 않는다
+        const underOpaqueObject = (key) => {
+            const parts = key.split(".");
+            for (let i = 1; i < parts.length; i++) {
+                const anc = parts.slice(0, i).join(".");
+                if (specByName.has(anc) && !hasChildren(anc))
+                    return true;
+            }
+            return false;
+        };
         for (const key of flat.keys()) {
-            if (!specByName.has(key))
+            if (!specByName.has(key) && !underOpaqueObject(key))
                 unknownParams.push(key);
         }
         // 타입 불일치: 평탄화 키마다 명세 타입과 실제 값 타입 비교 (배열 안 객체는 동일 키로 여러 값)
         for (const [key, values] of flat.entries()) {
+            if (key === "extraData")
+                continue; // expandExtraData 에서 원본 기준으로 검사함
             const p = specByName.get(key);
             if (!p)
                 continue;
             const expected = p.type.toLowerCase();
             for (const value of values) {
                 const actual = Array.isArray(value) ? "array" : typeof value;
-                const ok = (expected.includes("string") && actual === "string") ||
-                    (expected.includes("number") && actual === "number") ||
-                    (expected.includes("boolean") && actual === "boolean") ||
-                    (expected.includes("array") && actual === "array") ||
-                    (expected.includes("object") && actual === "object") ||
-                    expected === "unknown";
+                // 하위 항목이 정의된 항목은 가이드 표기가 string 이어도 객체/배열을 허용(예: extraData.viewOptions)
+                if ((actual === "object" || actual === "array") && hasChildren(key))
+                    continue;
+                if (value === null)
+                    continue; // null 은 보내지 않은 것으로 본다
+                const ok = typeMatches(expected, value) !== false;
                 if (!ok) {
                     typeMismatches.push(`${key}: 명세 '${p.type}' / 실제 '${actual}'`);
                     break; // 같은 키의 다음 값들은 검사 스킵
@@ -720,7 +858,7 @@ export function registerAllTools(server, store) {
         const serviceLabel = SERVICE_LABELS[service] ?? service;
         const runResults = checklist.map((item) => ({
             item,
-            result: item.autoCheck ? item.autoCheck(obj) : null,
+            result: item.autoCheck ? item.autoCheck(view) : null,
         }));
         const autoFailed = runResults.filter((r) => r.item.autoCheck && r.result !== null && !r.result.pass);
         const autoPassed = runResults.filter((r) => r.item.autoCheck && r.result !== null && r.result.pass);
@@ -787,7 +925,7 @@ export function registerAllTools(server, store) {
         // ── 헤더 ──────────────────────────────────────────────
         lines.push(`# ${pass ? "✓ PASS" : "✗ FAIL"} — ${spec.slug}`);
         lines.push(`[${spec.method ?? "?"}] ${spec.url ?? "(no url)"}  |  ${spec.title}`);
-        lines.push(`서비스: ${serviceLabel}  |  자동실패 ${checkFails + specFails}개`);
+        lines.push(`서비스: ${serviceLabel}  |  수정 필요 ${checkFails + specFails}개`);
         lines.push("");
         // ── 검수 체크리스트 (항상 맨 앞에 전체 표시) ──────────
         lines.push(`## 검수 체크리스트 — ${serviceLabel} (${checklist.length}개)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhnpayco-dev/mcp-devcenter",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "PAYCO 개발자센터 가이드 전체(온라인·오프라인·오더·멤버십·결제정산) 를 AI 개발 도구에서 바로 조회·검색할 수 있게 해주는 MCP 서버 (PAYCO Developer Center integration guide MCP server for Claude, Cursor and AI agents)",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     "typescript": "^5.5.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "keywords": [
     "mcp",