@nhnpayco-dev/mcp-devcenter 1.0.4 → 1.2.0

package/dist/data/guides/offline-authapi.md

@@ -1,6 +1,6 @@
 # PAYCO 오프라인 POS 인증승인형 연동 가이드
 
-> **원본:** PAYCO_오프라인POS_인증승인형연동가이드_v1.0.1.0.docx (사내 배포 문서)
+> **원본:** PAYCO_오프라인POS_인증승인형연동가이드_v1.0.1.0.docx (개발자센터 미게시 문서)
 > **카테고리:** `offline-authapi`
 > **연동 방식:** 가맹점 단말이 결제 인증·승인을 직접 수행하는 인증승인형
 > **API 5종:** POS 인증 / 결제 인증 / 결제 승인 / 결제취소 / 망취소

package/dist/data/guides/online-extradata.md

@@ -1,6 +1,6 @@
 # PAYCO 부가정보(extraData) 명세
 
-> **원본:** PAYCO_부가정보(extraData)_v1.1.14.docx (사내 배포 문서)
+> **원본:** PAYCO_부가정보(extraData)_v1.1.14.docx (개발자센터 미게시 문서)
 > **카테고리:** `online-extradata`
 > **용도:** 온라인결제 주문예약 API의 extraData 파라미터(JSON String) 내부 구조 정의
 > **사용 위치:** online-easypay-01 (reserve), online-autopay-01, online-easypay-nonmember/checkout/ordersheet 등 reserve 계열 API

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-13T07:16:43+00:00",
+  "generated_at": "2026-10-26T02:06:57+00:00",
   "category_count": 28,
   "categories": [
     {

package/dist/excel.js

@@ -1,9 +1,9 @@
 // 검수 결과 → xlsx 변환.
 // 3 시트: 검수요약 / 항목별 상세 / 공통검수체크리스트
 // 양식 참조: data/samples/payco_nonmember_checklist.xlsx (Arial 10pt, 진남색 헤더)
-import { mkdir } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, resolve, isAbsolute } from "node:path";
+import { join } from "node:path";
 import ExcelJS from "exceljs";
 import { CHECKLISTS, SERVICE_LABELS } from "./tools.js";
 // ── 디자인 토큰 ──────────────────────────────────────────────
@@ -30,21 +30,49 @@ const STATUS_LABEL = {
     manual: "⬜ 수동확인",
 };
 // ── 경로/파일명 ──────────────────────────────────────────────
-export function defaultOutputPath() {
+// 저장 위치는 항상 다운로드 폴더로 고정한다. 경로는 AI 가 정해 넘기므로
+// 다른 폴더 저장·폴더 생성·기존 파일 덮어쓰기를 허용하지 않는다.
+export function downloadsDir() {
+    return join(homedir(), "Downloads");
+}
+function defaultFileName() {
     const now = new Date();
     const pad = (n) => String(n).padStart(2, "0");
     const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
         `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
-    return join(homedir(), "Downloads", `payco-validation-${stamp}.xlsx`);
+    return `payco-validation-${stamp}.xlsx`;
+}
+/** 요청 경로에서 파일명만 남긴다. 폴더 부분이 있었으면 relocated=true. */
+function toFileName(userPath) {
+    const raw = userPath?.trim() ?? "";
+    if (!raw)
+        return { name: defaultFileName(), relocated: false };
+    const parts = raw.split(/[\\/]/);
+    const relocated = parts.length > 1;
+    let name = parts[parts.length - 1]
+        .replace(/[<>:"|?*\u0000-\u001f]/g, "_")
+        .replace(/[. ]+$/, "");
+    if (!name || name === "..")
+        name = defaultFileName();
+    if (!name.toLowerCase().endsWith(".xlsx"))
+        name = `${name}.xlsx`;
+    return { name, relocated };
 }
-async function ensureOutputPath(userPath) {
-    let p = userPath?.trim() || defaultOutputPath();
-    if (!isAbsolute(p))
-        p = resolve(p);
-    if (!p.toLowerCase().endsWith(".xlsx"))
-        p = `${p}.xlsx`;
-    await mkdir(dirname(p), { recursive: true });
-    return p;
+/** 같은 이름이 있으면 ' (2)', ' (3)' … 을 붙여 새 파일로 쓴다(덮어쓰기 금지). */
+async function writeNoOverwrite(dir, name, data) {
+    const base = name.slice(0, -".xlsx".length);
+    for (let i = 1; i < 1000; i++) {
+        const p = join(dir, i === 1 ? name : `${base} (${i}).xlsx`);
+        try {
+            await writeFile(p, data, { flag: "wx" });
+            return p;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+    }
+    throw new Error(`같은 이름의 파일이 너무 많습니다: ${name}`);
 }
 // ── 공통 헬퍼 ────────────────────────────────────────────────
 function fillSolid(argb) {
@@ -313,8 +341,16 @@ export async function exportValidationToExcel(records, userPath) {
     buildSummarySheet(wb, records);
     buildDetailSheet(wb, records);
     buildChecklistSheet(wb, records);
-    const outPath = await ensureOutputPath(userPath);
-    await wb.xlsx.writeFile(outPath);
+    const dir = downloadsDir();
+    await mkdir(dir, { recursive: true }); // 다운로드 폴더만 없으면 만든다
+    const { name, relocated } = toFileName(userPath);
+    const data = Buffer.from(await wb.xlsx.writeBuffer());
+    const outPath = await writeNoOverwrite(dir, name, data);
+    const notes = [];
+    if (relocated)
+        notes.push("요청한 위치 대신 다운로드 폴더에 저장했습니다(다운로드 폴더에만 저장 가능).");
+    if (!outPath.endsWith(name))
+        notes.push(`같은 이름의 파일이 있어 새 이름으로 저장했습니다(기존 파일은 그대로 둠).`);
     const detailRows = records.reduce((sum, r) => sum + r.specIssues.length + r.checklistRuns.length, 0);
-    return { path: outPath, recordCount: records.length, rowCount: detailRows };
+    return { path: outPath, recordCount: records.length, rowCount: detailRows, notes };
 }

package/dist/index.js

@@ -8,6 +8,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadDataStore } from "./data.js";
 import { registerAllTools } from "./tools.js";
+/** MCP initialize 응답의 instructions. 클라이언트가 연결 시점에 받아 세션 내내 참고한다.
+ *  검색 결과와 무관하게 항상 지킬 규칙만 둔다(세션마다 점유하므로 짧게).
+ *  근거: online-start·offline-start 「PAYCO 통신 방화벽 OPEN」, online-easypay orderSheetUrl. */
+const SERVER_INSTRUCTIONS = `PAYCO 연동 코드를 생성할 때 문서 검색 결과와 무관하게 항상 지킬 것:
+- PAYCO API(주문 예약, 결제 승인·취소 등)는 방화벽에 IP를 등록한 가맹점 서버에서만 정상 처리됩니다. 브라우저나 모바일 앱에서 직접 호출하는 코드를 만들지 마세요.
+- 브라우저는 가맹점 서버가 주문 예약 API로 받은 결제창 URL(orderSheetUrl)을 여는 역할만 합니다.`;
 /** package.json 의 version 을 그대로 사용한다.
  *  하드코딩하면 배포 버전과 어긋난다(1.0.0 배포본이 0.2.0 으로 보고된 전례). */
 async function packageVersion() {
@@ -29,7 +35,7 @@ async function main() {
     const server = new McpServer({
         name: "payco-mcp-devcenter",
         version,
-    });
+    }, { instructions: SERVER_INSTRUCTIONS });
     registerAllTools(server, store);
     const transport = new StdioServerTransport();
     await server.connect(transport);

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,35 +289,40 @@ 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 }
             : { pass: false, message: `${allowFull ? "YYYYMMDD(8자리) 또는 YYYYMMDDHHmmss(14자리)" : "YYYYMMDD(8자리)"} 필요. 현재: '${val}'` };
     };
 }
+// -- 개인정보 체크 항목 --
+// 온라인 검수 가이드 「Request 파라미터에 개인정보가 유입되지는 않는지」 기반.
+// 온라인·오프라인·오더 요청에는 개인정보 칸이 없어 실수 검출용으로 적용한다.
+// 멤버십은 적립 대상 휴대폰번호·회원카드번호 등이 정상 요청값이라 적용하지 않는다.
+const ITEM_PII = {
+    id: "common-pii",
+    category: "보안",
+    title: "개인정보 파라미터 미포함",
+    detail: "주민번호·카드번호·전화번호 등 개인정보가 request 파라미터에 유입되지 않아야 함",
+    autoCheck: autoCheckPii,
+};
 // -- 공통 체크 항목 --
 const ITEMS_COMMON = [
-    {
-        id: "common-pii",
-        category: "보안",
-        title: "개인정보 파라미터 미포함",
-        detail: "주민번호·카드번호·전화번호 등 개인정보가 request 파라미터에 유입되지 않아야 함",
-        autoCheck: autoCheckPii,
-    },
     {
         id: "common-encoding",
         category: "기타",
@@ -227,6 +352,7 @@ const ITEMS_COMMON = [
 ];
 // -- 온라인결제 체크리스트 --
 const CHECKLIST_ONLINE = [
+    ITEM_PII,
     ...ITEMS_COMMON,
     { id: "online-firewall", category: "사전준비", title: "PAYCO 방화벽 등록 완료" },
     { id: "online-merchant-code", category: "사전준비", title: "PAYCO 가맹점 코드 발급 완료" },
@@ -307,6 +433,7 @@ const CHECKLIST_ONLINE = [
 ];
 // -- 오프라인결제 체크리스트 --
 const CHECKLIST_OFFLINE = [
+    ITEM_PII,
     ...ITEMS_COMMON,
     { id: "offline-btn", category: "결제노출", title: "단말기에 PAYCO 결제 버튼 정상 노출 (디자인 가이드 준수)" },
     { id: "offline-receipt", category: "공통", title: "영수증 필요 정보 정상 노출" },
@@ -340,6 +467,7 @@ const CHECKLIST_OFFLINE = [
 ];
 // -- 오더클라우드 체크리스트 --
 const CHECKLIST_ORDER = [
+    ITEM_PII,
     ...ITEMS_COMMON,
     { id: "order-receipt", category: "공통", title: "영수증 필요 정보 정상 노출" },
     { id: "order-sales", category: "매출처리", title: "주문 수락 시 POS 단말기에 매출 정상 등록" },
@@ -444,6 +572,16 @@ function groupByCategory(items) {
 export function registerAllTools(server, store) {
     const slugs = store.index.categories.map((c) => c.slug);
     const slugList = slugs.join(", ");
+    // 가이드 참고 링크: index.json 의 실제 주소를 쓴다(주소를 조립하면 ?id= 가 없어 개발자센터에서 열리지 않음).
+    // 개발자센터에 없는 문서(internal://)는 주소 대신 MCP 안에서 여는 방법을 안내한다.
+    const guideLink = (slug) => {
+        const url = store.index.categories.find((c) => c.slug === slug)?.url;
+        if (!url)
+            return `get_guide('${slug}')`;
+        return url.startsWith("internal://")
+            ? `개발자센터 미게시 문서 (전체 내용: get_guide('${slug}'))`
+            : url;
+    };
     // 1) search_devcenter ----------------------------------------------------
     server.registerTool("search_devcenter", {
         title: "개발자센터 검색",
@@ -462,7 +600,7 @@ export function registerAllTools(server, store) {
             const snippets = snippetLines(md, query, 5);
             if (titleHit || snippets.length > 0) {
                 let block = `## [${cat.slug}] ${cat.title}\n`;
-                block += `   ${cat.url}\n`;
+                block += `   ${guideLink(cat.slug)}\n`;
                 if (snippets.length > 0) {
                     for (const s of snippets)
                         block += `   > ${s}\n`;
@@ -503,7 +641,7 @@ export function registerAllTools(server, store) {
         lines.push("");
         for (const cat of store.index.categories) {
             lines.push(`## [${cat.slug}] ${cat.title}`);
-            lines.push(`   ${cat.url}`);
+            lines.push(`   ${guideLink(cat.slug)}`);
             if (cat.sections.length > 0) {
                 for (const s of cat.sections) {
                     lines.push(`   - ${s.label}`);
@@ -587,7 +725,7 @@ export function registerAllTools(server, store) {
                 .describe("서비스 유형: online(온라인결제) | offline(오프라인결제) | order(오더클라우드) | membership(멤버십 클라우드)"),
         },
     }, async ({ service }) => {
-        const checklist = CHECKLISTS[service] ?? ITEMS_COMMON;
+        const checklist = CHECKLISTS[service] ?? [ITEM_PII, ...ITEMS_COMMON];
         const label = SERVICE_LABELS[service] ?? service;
         const autoItems = checklist.filter((c) => c.autoCheck);
         const manualItems = checklist.filter((c) => !c.autoCheck);
@@ -624,7 +762,7 @@ export function registerAllTools(server, store) {
             lines.push("");
         }
         const checkGuideSlug = `${service}-check`;
-        lines.push(`> 상세 검수 가이드: get_guide('${checkGuideSlug}') 또는 https://devcenter.payco.com/guide/${service}/check`);
+        lines.push(`> 상세 검수 가이드: get_guide('${checkGuideSlug}') 또는 ${guideLink(checkGuideSlug)}`);
         return text(lines.join("\n"));
     });
     // 8) validate_payload ---------------------------------------------------
@@ -632,7 +770,7 @@ export function registerAllTools(server, store) {
         title: "API 요청 페이로드 자동 검증 + 검수 체크리스트",
         description: "PAYCO API 요청 페이로드(JSON)를 검증하고 서비스별 검수 체크리스트를 반환한다. " +
             "반환값은 반드시 사용자에게 전체 그대로 보여줄 것 — 요약하거나 생략하지 말 것. " +
-            "체크리스트 항목은 ✓(자동통과) / ✗(자동실패, 이유 포함) / ⊘(필드 없어 스킵) / ⬜(수동확인 필요) 로 표시됨. " +
+            "체크리스트 항목은 ✓(통과) / ✗(수정 필요, 이유 포함) / ⊘(필드 없어 스킵) / ⬜(수동확인 필요) 로 표시됨. " +
             "⚠️ 운영 로그(실제 카드번호/주민번호/연락처)는 절대 그대로 붙여넣지 말 것.",
         inputSchema: {
             api: z
@@ -661,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; // 같은 키의 다음 값들은 검사 스킵
@@ -699,11 +854,11 @@ export function registerAllTools(server, store) {
         }
         // --- 체크리스트 실행 ---
         const service = serviceOf(api);
-        const checklist = CHECKLISTS[service] ?? ITEMS_COMMON;
+        const checklist = CHECKLISTS[service] ?? [ITEM_PII, ...ITEMS_COMMON];
         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);
@@ -770,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}개)`);
@@ -825,7 +980,7 @@ export function registerAllTools(server, store) {
             lines.push("## API 명세 검증 ✓ — 이상 없음");
         }
         lines.push("");
-        lines.push(`참고 가이드: https://devcenter.payco.com/guide/${spec.guide.replace(/-/g, "/")}`);
+        lines.push(`참고 가이드: ${guideLink(spec.guide)}`);
         lines.push("");
         lines.push("---");
         lines.push(`📊 **검수 결과 누적**: ${bufferSize()}건 — 검수가 끝났다면 사용자에게 **\"엑셀로 추출할까요?\"** 라고 물어보고, 원하면 \`export_validation_excel\` 도구를 호출하세요.`);
@@ -843,7 +998,8 @@ export function registerAllTools(server, store) {
             path: z
                 .string()
                 .optional()
-                .describe("저장할 파일 경로(절대 경로 권장). 미지정 시 %USERPROFILE%/Downloads/payco-validation-{timestamp}.xlsx 에 저장."),
+                .describe("저장할 파일 이름(선택, 예: '검수결과'). 항상 사용자의 다운로드 폴더에 저장되며 폴더 경로는 무시된다. " +
+                "같은 이름이 있으면 덮어쓰지 않고 ' (2)' 를 붙인다. 미지정 시 payco-validation-{timestamp}.xlsx."),
             clearAfter: z
                 .boolean()
                 .optional()
@@ -855,7 +1011,7 @@ export function registerAllTools(server, store) {
             return notFound("누적된 검수 결과가 없습니다. 먼저 validate_payload 로 1건 이상 검수를 수행하세요.");
         }
         try {
-            const { path: outPath, recordCount, rowCount } = await exportValidationToExcel(records, path);
+            const { path: outPath, recordCount, rowCount, notes } = await exportValidationToExcel(records, path);
             const cleared = clearAfter ? clearAllRecords() : 0;
             const lines = [];
             lines.push(`✅ 엑셀 추출 완료`);
@@ -864,6 +1020,8 @@ export function registerAllTools(server, store) {
             lines.push(`- 포함 검수 건수: ${recordCount}건`);
             lines.push(`- 항목별 상세 행 수: ${rowCount}행`);
             lines.push(`- 시트: 검수요약 / 항목별 상세 / 공통검수체크리스트 (3개)`);
+            for (const n of notes)
+                lines.push(`- 안내: ${n}`);
             if (clearAfter) {
                 lines.push(`- 추출 후 버퍼 초기화: ${cleared}건 삭제됨`);
             }
@@ -871,7 +1029,7 @@ export function registerAllTools(server, store) {
                 lines.push(`- 누적 버퍼 유지 (다음 검수 결과도 동일 버퍼에 누적됨)`);
             }
             lines.push("");
-            lines.push("Windows 탐색기에서 위 경로를 열어 결과를 확인하세요.");
+            lines.push("다운로드 폴더에서 위 파일을 열어 결과를 확인하세요.");
             return text(lines.join("\n"));
         }
         catch (e) {
@@ -891,7 +1049,8 @@ export function registerAllTools(server, store) {
     server.registerTool("get_error_code", {
         title: "에러코드/코드값 조회",
         description: "PAYCO 코드정리 표에서 특정 코드 값을 조회. API 응답코드(1000, 4802...), " +
-            "결제수단/주문유형/카드사/은행코드 등 모든 코드 카테고리를 한번에 검색.",
+            "결제수단/주문유형/카드사/은행코드 등 모든 코드 카테고리를 한번에 검색. " +
+            "같은 코드가 서비스마다 다른 뜻일 수 있으므로 결과의 [서비스 > 코드표] 표시로 구분해 답할 것.",
         inputSchema: {
             code: z
                 .string()
@@ -899,11 +1058,13 @@ export function registerAllTools(server, store) {
                 .describe("조회할 코드 (예: '1000', 'CHECKOUT', 'CCBC', '02')"),
         },
     }, async ({ code }) => {
+        // 같은 코드가 서비스마다 다른 뜻일 수 있어(예: 1001 온라인/오프라인) 서비스명을 함께 표시
+        const where = (cat) => `${SERVICE_LABELS[cat.root] ?? cat.root} > ${cat.title}`;
         const hits = [];
         for (const cat of store.errorCodes.categories) {
             const found = cat.items.find((it) => it.code === code);
             if (found) {
-                hits.push(`[${cat.title}] ${found.code} = ${found.description}`);
+                hits.push(`[${where(cat)}] ${found.code} = ${found.description}`);
             }
         }
         if (hits.length === 0) {
@@ -911,7 +1072,7 @@ export function registerAllTools(server, store) {
             for (const cat of store.errorCodes.categories) {
                 for (const it of cat.items) {
                     if (it.code.startsWith(code) || it.description.includes(code)) {
-                        partial.push(`[${cat.title}] ${it.code} = ${it.description}`);
+                        partial.push(`[${where(cat)}] ${it.code} = ${it.description}`);
                         if (partial.length >= 10)
                             break;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhnpayco-dev/mcp-devcenter",
-  "version": "1.0.4",
+  "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",
@@ -64,5 +64,8 @@
   "homepage": "https://devcenter.payco.com",
   "bugs": {
     "email": "dl_payco_ts@nhn.com"
+  },
+  "overrides": {
+    "uuid": "^11.1.1"
   }
 }