@nhnpayco-dev/mcp-devcenter 1.0.0

package/dist/tools.js

@@ -0,0 +1,929 @@
+// MCP 도구 11개 등록.
+// 외부 제휴사 LLM 사용자가 호출하는 도구 표면.
+import { z } from "zod";
+import { pushRecord, getAll as getAllRecords, clearAll as clearAllRecords, size as bufferSize, extractOrderKeys, } from "./validation-buffer.js";
+import { exportValidationToExcel } from "./excel.js";
+// ---------- 공통 헬퍼 ----------
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+function notFound(msg) {
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+/** 본문 markdown 에서 모든 ```...``` 코드 블록 추출 */
+function extractCodeBlocks(md, language) {
+    const re = /```([a-zA-Z0-9_-]*)\s*\n([\s\S]*?)```/g;
+    const out = [];
+    let m;
+    while ((m = re.exec(md)) !== null) {
+        const lang = m[1].toLowerCase();
+        if (language && lang && lang !== language.toLowerCase())
+            continue;
+        out.push(m[0]);
+    }
+    return out;
+}
+/** payload 의 nested 객체/배열을 `parent.field` 형식으로 평탄화.
+ *
+ *  - 객체: 키를 점(.)으로 연결
+ *  - 배열: 인덱스는 무시하고 같은 키로 모든 객체 평탄화 (각 객체가 동일 스키마라고 가정)
+ *  - 같은 평탄화 키에 여러 값이 매핑될 수 있어 Map<string, unknown[]> 반환
+ *  - 객체/배열 자체도 키로 등록 (예: `orderProducts` → 배열 값)
+ *
+ *  예) {orderProducts: [{cpId: "X"}]} → {
+ *        "orderProducts": [[{cpId:"X"}]],
+ *        "orderProducts.cpId": ["X"]
+ *      }
+ */
+function flattenPayload(payload) {
+    const out = new Map();
+    const add = (k, v) => {
+        const arr = out.get(k);
+        if (arr)
+            arr.push(v);
+        else
+            out.set(k, [v]);
+    };
+    const visit = (prefix, v) => {
+        if (Array.isArray(v)) {
+            if (prefix)
+                add(prefix, v); // 배열 자체도 등록
+            for (const item of v) {
+                if (item && typeof item === "object" && !Array.isArray(item)) {
+                    for (const [k, val] of Object.entries(item)) {
+                        visit(prefix ? `${prefix}.${k}` : k, val);
+                    }
+                }
+            }
+        }
+        else if (v && typeof v === "object") {
+            if (prefix)
+                add(prefix, v); // 객체 자체도 등록
+            for (const [k, val] of Object.entries(v)) {
+                visit(prefix ? `${prefix}.${k}` : k, val);
+            }
+        }
+        else {
+            if (prefix)
+                add(prefix, v);
+        }
+    };
+    for (const [k, v] of Object.entries(payload))
+        visit(k, v);
+    return out;
+}
+/** 본문에서 query 가 포함된 줄(앞뒤 줄 포함) 발췌 */
+function snippetLines(md, query, maxHits = 5) {
+    const q = query.toLowerCase();
+    const lines = md.split("\n");
+    const hits = [];
+    for (let i = 0; i < lines.length && hits.length < maxHits; i++) {
+        if (lines[i].toLowerCase().includes(q)) {
+            hits.push(lines[i].trim());
+        }
+    }
+    return hits;
+}
+// -- auto-check 함수 --
+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자리
+    const RE_PHONE = /(?<!\d)01[0-9]-?\d{3,4}-?\d{4}(?!\d)/; // 휴대전화 10~11자리
+    const visit = (v) => {
+        if (typeof v === "string") {
+            if (RE_RRN.test(v) && !hits.includes("주민번호 패턴"))
+                hits.push("주민번호 패턴");
+            if (RE_CARD.test(v) && !hits.includes("카드번호 패턴"))
+                hits.push("카드번호 패턴");
+            if (RE_PHONE.test(v) && !hits.includes("전화번호 패턴"))
+                hits.push("전화번호 패턴");
+        }
+        else if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x);
+        }
+        else if (v && typeof v === "object") {
+            for (const x of Object.values(v))
+                visit(x);
+        }
+    };
+    visit(obj);
+    return hits.length === 0
+        ? { pass: true }
+        : { pass: false, message: `감지된 패턴: ${hits.join(", ")} — 운영 로그 사용 시 마스킹 후 검증하세요` };
+}
+function autoCheckEncoding(obj) {
+    const str = JSON.stringify(obj);
+    const match = str.match(/%[0-9A-Fa-f]{2}|%u[0-9A-Fa-f]{4}/);
+    return match
+        ? { pass: false, message: `URL 인코딩 문자 감지('${match[0]}'). 디코딩 후 전달하세요.` }
+        : { pass: true };
+}
+function autoCheckWhitespace(obj) {
+    const issues = Object.entries(obj)
+        .filter(([, v]) => typeof v === "string" && (/^\s/.test(v) || /\s$/.test(v)))
+        .map(([k]) => k);
+    return issues.length === 0
+        ? { pass: true }
+        : { pass: false, message: `앞뒤 공백 감지 필드: ${issues.join(", ")}` };
+}
+function autoCheckAmtSum(obj) {
+    const total = obj["totalPaymentAmt"];
+    const tf = obj["totalTaxfreeAmt"];
+    const ta = obj["totalTaxableAmt"];
+    const vat = obj["totalVatAmt"];
+    if (typeof total !== "number" ||
+        typeof tf !== "number" ||
+        typeof ta !== "number" ||
+        typeof vat !== "number")
+        return null;
+    const expected = tf + ta + vat;
+    return total === expected
+        ? { pass: true }
+        : { pass: false, message: `${total} ≠ ${tf} + ${ta} + ${vat} (= ${expected})` };
+}
+function autoCheckReturnUrl(obj) {
+    if (!("returnUrl" in obj))
+        return null;
+    const val = obj["returnUrl"];
+    if (typeof val !== "string")
+        return null;
+    return /^https?:\/\//.test(val)
+        ? { pass: true }
+        : { pass: false, message: `http:// 또는 https://로 시작해야 함. 현재: '${val}'` };
+}
+function makeEnumCheck(field, allowed) {
+    return (obj) => {
+        if (!(field in obj))
+            return null;
+        const val = obj[field];
+        if (typeof val !== "string")
+            return null;
+        return allowed.includes(val)
+            ? { pass: true }
+            : { pass: false, message: `'${val}' — 허용값: ${allowed.join(" | ")}` };
+    };
+}
+function makeDateYmdtCheck(fields) {
+    return (obj) => {
+        const present = fields.filter((f) => f in obj && typeof obj[f] === "string");
+        if (present.length === 0)
+            return null;
+        const fails = present.filter((f) => !/^\d{14}$/.test(obj[f]));
+        return fails.length === 0
+            ? { pass: true }
+            : { pass: false, message: `YYYYMMDDHHmmss 14자리 필요: ${fails.map((f) => `${f}='${obj[f]}'`).join(", ")}` };
+    };
+}
+function makeDateYmdCheck(field, allowFull = false) {
+    return (obj) => {
+        if (!(field in obj) || typeof obj[field] !== "string")
+            return null;
+        const val = obj[field];
+        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}'` };
+    };
+}
+// -- 공통 체크 항목 --
+const ITEMS_COMMON = [
+    {
+        id: "common-pii",
+        category: "보안",
+        title: "개인정보 파라미터 미포함",
+        detail: "주민번호·카드번호·전화번호 등 개인정보가 request 파라미터에 유입되지 않아야 함",
+        autoCheck: autoCheckPii,
+    },
+    {
+        id: "common-encoding",
+        category: "기타",
+        title: "파라미터 URL 인코딩 문자 미포함",
+        detail: "'%XX' 또는 '%uXXXX' 형태의 인코딩 문자가 파라미터값에 포함되면 안 됨",
+        autoCheck: autoCheckEncoding,
+    },
+    {
+        id: "common-whitespace",
+        category: "기타",
+        title: "파라미터 앞뒤 공백 없음",
+        detail: "문자열 파라미터 값의 앞/뒤에 불필요한 공백이 없어야 함",
+        autoCheck: autoCheckWhitespace,
+    },
+    {
+        id: "common-amt-sum",
+        category: "결제금액",
+        title: "금액 합산 일치 (totalPaymentAmt = 면세 + 과세 + 부가세)",
+        autoCheck: autoCheckAmtSum,
+    },
+    {
+        id: "common-return-url",
+        category: "결제인증/승인",
+        title: "returnUrl HTTP(S) 형식",
+        autoCheck: autoCheckReturnUrl,
+    },
+];
+// -- 온라인결제 체크리스트 --
+const CHECKLIST_ONLINE = [
+    ...ITEMS_COMMON,
+    { id: "online-firewall", category: "사전준비", title: "PAYCO 방화벽 등록 완료" },
+    { id: "online-merchant-code", category: "사전준비", title: "PAYCO 가맹점 코드 발급 완료" },
+    {
+        id: "online-btn-design",
+        category: "결제노출",
+        title: "PAYCO 버튼 디자인 가이드 준수",
+        detail: "PAYCO 영문자·붉은색 원칙. 별도 요청 시 버튼 이미지·PSD 제공",
+    },
+    { id: "online-btn-show", category: "결제노출", title: "주문서에 PAYCO 결제 버튼 정상 노출" },
+    {
+        id: "online-popup",
+        category: "결제노출",
+        title: "결제창 팝업 정상 노출",
+        detail: "'결제하기' 클릭 시 PAYCO 결제창(popup)이 열려야 함",
+    },
+    {
+        id: "online-popup-block",
+        category: "결제노출",
+        title: "팝업 차단 미적용 또는 허용 안내 Alert 노출",
+        detail: "팝업 차단 해제가 어렵다면 사용자에게 허용 요청 Alert 노출",
+    },
+    {
+        id: "online-order-method",
+        category: "결제인증/승인",
+        title: "orderMethod 유효값 (CHECKOUT | EASYPAY | EASYPAY_F)",
+        autoCheck: makeEnumCheck("orderMethod", ["CHECKOUT", "EASYPAY", "EASYPAY_F"]),
+    },
+    {
+        id: "online-order-channel",
+        category: "결제인증/승인",
+        title: "orderChannel 유효값 (PC | MOBILE)",
+        autoCheck: makeEnumCheck("orderChannel", ["PC", "MOBILE"]),
+    },
+    {
+        id: "online-inapp",
+        category: "결제인증/승인",
+        title: "inAppYn 유효값 (Y | N)",
+        autoCheck: makeEnumCheck("inAppYn", ["Y", "N"]),
+    },
+    {
+        id: "online-date",
+        category: "결제인증/승인",
+        title: "날짜 형식 YYYYMMDDHHmmss (payExpiryYmdt 등)",
+        autoCheck: makeDateYmdtCheck(["payExpiryYmdt"]),
+    },
+    {
+        id: "online-vbank-date",
+        category: "결제인증/승인",
+        title: "가상계좌 만료일 형식 (YYYYMMDD 또는 YYYYMMDDHHmmss)",
+        autoCheck: makeDateYmdCheck("virtualAccountExpiryYmd", true),
+    },
+    {
+        id: "online-amt-match",
+        category: "결제인증/승인",
+        title: "주문금액 ↔ PAYCO 결제창 최종결제금액 일치 여부 육안 확인",
+    },
+    {
+        id: "online-auth-recv",
+        category: "결제인증/승인",
+        title: "결제인증 정보(인증토큰·주문예약번호) 정상 수신",
+        detail: "PAYCO 결제비밀번호 인증 후 returnUrl로 인증정보가 정상 전달되는지 확인",
+    },
+    {
+        id: "online-timeout",
+        category: "결제인증/승인",
+        title: "승인결과 미수신 시 망취소 처리",
+        detail: "통신장애·타임아웃 등으로 미수신 시 결제취소(망취소) 또는 실패 인지 처리 구현",
+    },
+    {
+        id: "online-cancel",
+        category: "결제취소",
+        title: "전체취소 / 부분취소 정상 동작",
+        detail: "PAYCO 파트너센터(partner.payco.com)에서도 취소 가능",
+    },
+    { id: "online-cancel-fail", category: "결제취소", title: "취소 실패 시 실패 사유(에러코드·메시지) 노출" },
+    { id: "online-receipt", category: "영수증", title: "영수증 API 구현 및 주문명(상품명) 정상 노출" },
+];
+// -- 오프라인결제 체크리스트 --
+const CHECKLIST_OFFLINE = [
+    ...ITEMS_COMMON,
+    { id: "offline-btn", category: "결제노출", title: "단말기에 PAYCO 결제 버튼 정상 노출 (디자인 가이드 준수)" },
+    { id: "offline-receipt", category: "공통", title: "영수증 필요 정보 정상 노출" },
+    { id: "offline-approval", category: "결제처리", title: "승인요청 후 승인결과 정상 수신" },
+    { id: "offline-fail", category: "결제처리", title: "결제 실패 시 실패 사유 노출" },
+    { id: "offline-timeout", category: "결제처리", title: "승인결과 미수신 시 망취소 처리" },
+    {
+        id: "offline-success",
+        category: "결제처리",
+        title: "단독결제 / 복합결제(+쿠폰) 등 다양한 케이스 성공 확인",
+    },
+    { id: "offline-cancel", category: "결제취소", title: "결제취소 성공 확인" },
+    {
+        id: "offline-dll-lifecycle",
+        category: "VCAT 연동",
+        title: "DLL 연결/해제를 프로그램 시작·종료 시 1회만 수행 (결제마다 반복 금지)",
+    },
+    {
+        id: "offline-dll-func",
+        category: "VCAT 연동",
+        title: "DLL 함수 사용 확인",
+        detail: "NfcDailyRun 구동 / NfcInit 초기화(SetPaycoData 전) / NfcASyncRun 후 NfcSendASyncEnd 호출",
+    },
+    { id: "offline-signature", category: "API 연동", title: "Signature 생성 및 결제 승인·취소 정상 동작 확인" },
+    {
+        id: "offline-pos-reg",
+        category: "API 연동",
+        title: "POS 등록 API 언제든 호출 가능",
+        detail: "가맹점·단말기 정보 변경 시 재호출 가능한지 확인",
+    },
+];
+// -- 오더클라우드 체크리스트 --
+const CHECKLIST_ORDER = [
+    ...ITEMS_COMMON,
+    { id: "order-receipt", category: "공통", title: "영수증 필요 정보 정상 노출" },
+    { id: "order-sales", category: "매출처리", title: "주문 수락 시 POS 단말기에 매출 정상 등록" },
+    {
+        id: "order-dll-daily",
+        category: "VORDER 연동",
+        title: "단말기 구동 시 DailyRun 함수 사용 확인",
+    },
+    {
+        id: "order-dll-senddata",
+        category: "VORDER 연동",
+        title: "수락·완료·취소 등 윈도우 이벤트 수신 시 SendData 처리 확인",
+        detail: "일시적 POS 오류 발생 시에도 SendData 처리가 되는지 확인",
+    },
+    { id: "order-dll-end", category: "VORDER 연동", title: "종료 시 ProcessEnd 함수 호출 확인" },
+    { id: "order-soldout", category: "VORDER 연동", title: "품절 / 품절해제 정상 동작" },
+    {
+        id: "order-light-query",
+        category: "라이트 VORDER",
+        title: "QueryInfo 함수 및 조회 조건 파라미터 정상 호출 확인",
+    },
+    {
+        id: "order-light-bulk",
+        category: "라이트 VORDER",
+        title: "수백 건 이상 대량 주문건 매출 연동 이상 없음",
+        detail: "결제·할인 수단별 정상 집계도 확인",
+    },
+];
+// -- 멤버십 클라우드 체크리스트 --
+const CHECKLIST_MEMBERSHIP = [
+    ...ITEMS_COMMON,
+    { id: "mem-vmem-run", category: "VMEM 연동", title: "VMEM 정상 실행 확인" },
+    {
+        id: "mem-dll-daily",
+        category: "VMEM 연동",
+        title: "단말기 구동 시 ExecDailyRun 함수 사용 확인",
+    },
+    {
+        id: "mem-dll-init",
+        category: "VMEM 연동",
+        title: "비동기 주문 승인 전 MemInit 초기화 확인",
+    },
+    {
+        id: "mem-dll-product",
+        category: "VMEM 연동",
+        title: "주문 승인 이후 완료 시점까지 상품 정보(종류·가격) 변경 없음",
+    },
+    {
+        id: "mem-dll-ext-cancel",
+        category: "VMEM 연동",
+        title: "주문 취소 시 외부결제 취소처리 먼저 진행",
+    },
+    { id: "mem-dll-side-effect", category: "VMEM 연동", title: "DLL 함수 결과가 외부결제에 영향 없음" },
+    {
+        id: "mem-kiosk",
+        category: "VMEM 기능",
+        title: "KIOSK 모드 시 제휴사 설정·스펙에 맞는 화면 노출",
+    },
+    { id: "mem-comm", category: "VMEM 기능", title: "DLL ↔ EXE 통신 원활" },
+    { id: "mem-query", category: "API 연동", title: "멤버십 회원 및 재화 정상 조회" },
+    {
+        id: "mem-process",
+        category: "API 연동",
+        title: "멤버십 재화 사용 주문 생성~완료 프로세스 이상 없음",
+    },
+    { id: "mem-fail", category: "API 연동", title: "멤버십 처리 실패 시 실패 사유 노출" },
+    {
+        id: "mem-timeout",
+        category: "API 연동",
+        title: "승인결과 미수신 시 멤버십 취소 또는 실패 처리",
+        detail: "통신장애·타임아웃 등으로 미수신 시 대응 구현",
+    },
+    { id: "mem-cancel", category: "API 연동", title: "멤버십 취소 다양한 케이스 이상 없음" },
+];
+export const CHECKLISTS = {
+    online: CHECKLIST_ONLINE,
+    offline: CHECKLIST_OFFLINE,
+    order: CHECKLIST_ORDER,
+    membership: CHECKLIST_MEMBERSHIP,
+};
+export const SERVICE_LABELS = {
+    online: "온라인결제",
+    offline: "오프라인결제",
+    order: "오더클라우드",
+    membership: "멤버십 클라우드",
+};
+/** API 슬러그에서 서비스명 추출 (예: "online-easypay-01" → "online") */
+function serviceOf(apiSlug) {
+    return apiSlug.split("-")[0];
+}
+/** 체크리스트를 카테고리별로 그룹화 */
+function groupByCategory(items) {
+    const map = new Map();
+    for (const item of items) {
+        if (!map.has(item.category))
+            map.set(item.category, []);
+        map.get(item.category).push(item);
+    }
+    return map;
+}
+// ---------- 도구 등록 ----------
+export function registerAllTools(server, store) {
+    const slugs = store.index.categories.map((c) => c.slug);
+    const slugList = slugs.join(", ");
+    // 1) search_devcenter ----------------------------------------------------
+    server.registerTool("search_devcenter", {
+        title: "개발자센터 검색",
+        description: "PAYCO 개발자센터 가이드(온라인결제·자동결제)를 키워드로 검색. " +
+            "제목·섹션·본문 텍스트에서 매칭되는 가이드와 발췌를 반환.",
+        inputSchema: {
+            query: z.string().min(1).describe("검색어 (예: '결제 승인', 'orderProducts')"),
+        },
+    }, async ({ query }) => {
+        const results = [];
+        for (const cat of store.index.categories) {
+            const titleHit = cat.title.includes(query) ||
+                cat.keywords.some((k) => k.includes(query)) ||
+                cat.sections.some((s) => s.label.includes(query));
+            const md = store.guides.get(cat.slug) ?? "";
+            const snippets = snippetLines(md, query, 5);
+            if (titleHit || snippets.length > 0) {
+                let block = `## [${cat.slug}] ${cat.title}\n`;
+                block += `   ${cat.url}\n`;
+                if (snippets.length > 0) {
+                    for (const s of snippets)
+                        block += `   > ${s}\n`;
+                }
+                results.push(block);
+            }
+        }
+        if (results.length === 0) {
+            return text(`'${query}' 검색 결과 없음. 사용 가능한 슬러그: ${slugList}`);
+        }
+        return text(`검색어: "${query}" — ${results.length}건\n\n${results.join("\n")}`);
+    });
+    // 2) get_guide ----------------------------------------------------------
+    server.registerTool("get_guide", {
+        title: "가이드 본문 조회",
+        description: `특정 가이드의 전체 본문(Markdown)을 반환. 사용 가능한 슬러그: ${slugList}`,
+        inputSchema: {
+            slug: z
+                .string()
+                .describe(`가이드 슬러그 (${slugList})`),
+        },
+    }, async ({ slug }) => {
+        const md = store.guides.get(slug);
+        if (!md) {
+            return notFound(`'${slug}' 가이드 없음. 사용 가능한 슬러그: ${slugList}`);
+        }
+        return text(md);
+    });
+    // 3) list_apis ----------------------------------------------------------
+    server.registerTool("list_apis", {
+        title: "가이드 / API 목록",
+        description: "PAYCO 개발자센터에 정리된 가이드 카테고리와 각 카테고리의 단계(섹션) 목록을 반환. " +
+            "외부 제휴사가 어떤 가이드/단계가 있는지 한눈에 파악할 때 사용.",
+        inputSchema: {},
+    }, async () => {
+        const lines = [];
+        lines.push(`# PAYCO 개발자센터 가이드 목록 (${store.index.scope})`);
+        lines.push("");
+        for (const cat of store.index.categories) {
+            lines.push(`## [${cat.slug}] ${cat.title}`);
+            lines.push(`   ${cat.url}`);
+            if (cat.sections.length > 0) {
+                for (const s of cat.sections) {
+                    lines.push(`   - ${s.label}`);
+                }
+            }
+            lines.push("");
+        }
+        return text(lines.join("\n"));
+    });
+    // 4) get_api_spec -------------------------------------------------------
+    server.registerTool("get_api_spec", {
+        title: "API 명세 조회",
+        description: "특정 카테고리(easypay, autopay 등)의 API 명세·파라미터·응답 형식을 담은 가이드를 반환. " +
+            "현재 버전은 가이드 전체를 돌려주고, LLM 이 해당 API 섹션을 활용.",
+        inputSchema: {
+            category: z
+                .string()
+                .describe(`카테고리 슬러그 (${slugList})`),
+        },
+    }, async ({ category }) => {
+        const md = store.guides.get(category);
+        if (!md) {
+            return notFound(`'${category}' 카테고리 없음. 사용 가능: ${slugList}`);
+        }
+        return text(md);
+    });
+    // 5) get_sample_code ----------------------------------------------------
+    server.registerTool("get_sample_code", {
+        title: "샘플 코드 조회",
+        description: "특정 가이드의 코드 블록만 추출해 반환. 가이드 슬러그와(선택적으로) 언어를 지정.",
+        inputSchema: {
+            slug: z
+                .string()
+                .describe(`가이드 슬러그 (${slugList})`),
+            language: z
+                .string()
+                .optional()
+                .describe("필터할 언어 태그 (예: json, java, javascript). 미지정 시 모든 코드 블록 반환."),
+        },
+    }, async ({ slug, language }) => {
+        const md = store.guides.get(slug);
+        if (!md) {
+            return notFound(`'${slug}' 가이드 없음. 사용 가능한 슬러그: ${slugList}`);
+        }
+        const blocks = extractCodeBlocks(md, language);
+        if (blocks.length === 0) {
+            return text(`'${slug}' 가이드에 ${language ? `'${language}' ` : ""}코드 블록 없음.`);
+        }
+        const header = `# ${slug} — 코드 블록 ${blocks.length}개${language ? ` (${language})` : ""}\n\n`;
+        return text(header + blocks.join("\n\n"));
+    });
+    // 6) list_validatable_apis ----------------------------------------------
+    server.registerTool("list_validatable_apis", {
+        title: "검증 가능한 API 목록",
+        description: "validate_payload 로 자동 검증 가능한 PAYCO API 목록(슬러그·URL·메서드·파라미터 수)을 반환. " +
+            "외부 제휴사가 자신의 요청 로그를 어떤 API 슬러그로 검증해야 할지 확인하는 용도.",
+        inputSchema: {},
+    }, async () => {
+        const lines = [];
+        lines.push(`# 검증 가능한 API (${store.apiSpecs.api_count}개)`);
+        lines.push("");
+        for (const api of store.apiSpecs.apis) {
+            const url = api.url ?? "(URL 정보 없음)";
+            const method = api.method ?? "?";
+            const req = api.request_params.length;
+            const reqRequired = api.request_params.filter((p) => p.required).length;
+            lines.push(`- **${api.slug}** [${method}] ${url}`);
+            lines.push(`  title: ${api.title}`);
+            lines.push(`  request: ${req} params (${reqRequired} required)  / response: ${api.response_params.length} params`);
+        }
+        return text(lines.join("\n"));
+    });
+    // 7) get_checklist ------------------------------------------------------
+    server.registerTool("get_checklist", {
+        title: "서비스별 사전 검수 체크리스트",
+        description: "PAYCO 연동 완료 후 자체 검수 시 사용하는 서비스별 사전 체크리스트를 반환. " +
+            "자동 검증 가능한 항목(payload 기반)과 수동 확인이 필요한 항목을 구분해 표시.",
+        inputSchema: {
+            service: z
+                .enum(["online", "offline", "order", "membership"])
+                .describe("서비스 유형: online(온라인결제) | offline(오프라인결제) | order(오더클라우드) | membership(멤버십 클라우드)"),
+        },
+    }, async ({ service }) => {
+        const checklist = CHECKLISTS[service] ?? ITEMS_COMMON;
+        const label = SERVICE_LABELS[service] ?? service;
+        const autoItems = checklist.filter((c) => c.autoCheck);
+        const manualItems = checklist.filter((c) => !c.autoCheck);
+        const lines = [];
+        lines.push(`# PAYCO ${label} 사전 검수 체크리스트 (${checklist.length}개)`);
+        lines.push("");
+        lines.push(`> validate_payload 호출 시 자동 검증 항목(${autoItems.length}개)은 payload 기반으로 자동 확인됩니다.`);
+        lines.push(`> 수동 확인 항목(${manualItems.length}개)은 직접 검수가 필요합니다.`);
+        lines.push("");
+        if (autoItems.length > 0) {
+            lines.push(`## 자동 검증 항목 (${autoItems.length}개) — validate_payload 호출 시 자동 확인`);
+            const byCategory = groupByCategory(autoItems);
+            for (const [cat, items] of byCategory) {
+                lines.push(`\n**[${cat}]**`);
+                for (const item of items) {
+                    lines.push(`- ☑ ${item.title}`);
+                    if (item.detail)
+                        lines.push(`  → ${item.detail}`);
+                }
+            }
+            lines.push("");
+        }
+        if (manualItems.length > 0) {
+            lines.push(`## 수동 확인 항목 (${manualItems.length}개) — 직접 검수 필요`);
+            const byCategory = groupByCategory(manualItems);
+            for (const [cat, items] of byCategory) {
+                lines.push(`\n**[${cat}]**`);
+                for (const item of items) {
+                    lines.push(`- ⬜ ${item.title}`);
+                    if (item.detail)
+                        lines.push(`  → ${item.detail}`);
+                }
+            }
+            lines.push("");
+        }
+        const checkGuideSlug = `${service}-check`;
+        lines.push(`> 상세 검수 가이드: get_guide('${checkGuideSlug}') 또는 https://devcenter.payco.com/guide/${service}/check`);
+        return text(lines.join("\n"));
+    });
+    // 8) validate_payload ---------------------------------------------------
+    server.registerTool("validate_payload", {
+        title: "API 요청 페이로드 자동 검증 + 검수 체크리스트",
+        description: "PAYCO API 요청 페이로드(JSON)를 검증하고 서비스별 검수 체크리스트를 반환한다. " +
+            "반환값은 반드시 사용자에게 전체 그대로 보여줄 것 — 요약하거나 생략하지 말 것. " +
+            "체크리스트 항목은 ✓(자동통과) / ✗(자동실패, 이유 포함) / ⊘(필드 없어 스킵) / ⬜(수동확인 필요) 로 표시됨. " +
+            "⚠️ 운영 로그(실제 카드번호/주민번호/연락처)는 절대 그대로 붙여넣지 말 것.",
+        inputSchema: {
+            api: z
+                .string()
+                .describe("검증할 API 슬러그 (list_validatable_apis 로 확인). 예: online-easypay-01"),
+            payload: z
+                .string()
+                .describe("요청 페이로드 JSON 문자열. 예: '{\"sellerKey\":\"...\",\"totalPaymentAmt\":1000}'"),
+        },
+    }, async ({ api, payload }) => {
+        const spec = store.apiSpecs.apis.find((a) => a.slug === api);
+        if (!spec) {
+            const available = store.apiSpecs.apis.map((a) => a.slug).join(", ");
+            return notFound(`'${api}' API 명세 없음. 사용 가능: ${available}`);
+        }
+        // JSON 파싱
+        let obj;
+        try {
+            const parsed = JSON.parse(payload);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return notFound("payload 는 JSON 객체(중괄호)여야 합니다.");
+            }
+            obj = parsed;
+        }
+        catch (e) {
+            return notFound(`JSON 파싱 실패: ${e.message}`);
+        }
+        // --- API 명세 검증 (nested 평탄화 비교) ---
+        const specByName = new Map(spec.request_params.map((p) => [p.name, p]));
+        const flat = flattenPayload(obj);
+        const missingRequired = [];
+        const unknownParams = [];
+        const typeMismatches = [];
+        // 필수 누락: 명세 required 키가 평탄화된 payload 키에 없음
+        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)}`);
+            }
+        }
+        // 알 수 없는 파라미터: payload 의 평탄화 키 중 명세에 없는 것
+        for (const key of flat.keys()) {
+            if (!specByName.has(key))
+                unknownParams.push(key);
+        }
+        // 타입 불일치: 평탄화 키마다 명세 타입과 실제 값 타입 비교 (배열 안 객체는 동일 키로 여러 값)
+        for (const [key, values] of flat.entries()) {
+            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";
+                if (!ok) {
+                    typeMismatches.push(`${key}: 명세 '${p.type}' / 실제 '${actual}'`);
+                    break; // 같은 키의 다음 값들은 검사 스킵
+                }
+            }
+        }
+        // --- 체크리스트 실행 ---
+        const service = serviceOf(api);
+        const checklist = CHECKLISTS[service] ?? ITEMS_COMMON;
+        const serviceLabel = SERVICE_LABELS[service] ?? service;
+        const runResults = checklist.map((item) => ({
+            item,
+            result: item.autoCheck ? item.autoCheck(obj) : 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);
+        const autoSkipped = runResults.filter((r) => r.item.autoCheck && r.result === null);
+        const manualItems = runResults.filter((r) => !r.item.autoCheck);
+        const specFails = missingRequired.length + unknownParams.length + typeMismatches.length;
+        const checkFails = autoFailed.length;
+        const pass = specFails === 0 && checkFails === 0;
+        // ── 결과 버퍼에 저장 (엑셀 추출용) ─────────────────────
+        const { sellerOrderRefKey, reserveOrderNo } = extractOrderKeys(obj);
+        const specIssueRows = [];
+        for (const m of missingRequired) {
+            const fieldMatch = m.match(/^([^\s(]+)/);
+            specIssueRows.push({
+                kind: "missing_required",
+                field: fieldMatch?.[1] ?? "",
+                message: m,
+            });
+        }
+        for (const u of unknownParams) {
+            specIssueRows.push({
+                kind: "unknown_param",
+                field: u,
+                message: `'${u}' 는 ${spec.slug} 명세에 없는 파라미터 (오타 또는 가이드 최신본 확인 필요)`,
+            });
+        }
+        for (const t of typeMismatches) {
+            const fieldMatch = t.match(/^([^:]+):/);
+            specIssueRows.push({
+                kind: "type_mismatch",
+                field: fieldMatch?.[1]?.trim() ?? "",
+                message: t,
+            });
+        }
+        const checklistRunRows = runResults.map(({ item, result }) => {
+            if (!item.autoCheck) {
+                return { category: item.category, title: item.title, status: "manual", detail: item.detail };
+            }
+            if (result === null) {
+                return { category: item.category, title: item.title, status: "skip" };
+            }
+            if (result.pass) {
+                return { category: item.category, title: item.title, status: "pass" };
+            }
+            return {
+                category: item.category, title: item.title, status: "fail",
+                message: result.message,
+            };
+        });
+        const record = {
+            timestamp: new Date().toISOString(),
+            api: spec.slug,
+            endpoint: `[${spec.method ?? "?"}] ${spec.url ?? "(no url)"}`,
+            service,
+            serviceLabel,
+            sellerOrderRefKey,
+            reserveOrderNo,
+            pass,
+            specIssues: specIssueRows,
+            checklistRuns: checklistRunRows,
+        };
+        pushRecord(record);
+        const lines = [];
+        // ── 헤더 ──────────────────────────────────────────────
+        lines.push(`# ${pass ? "✓ PASS" : "✗ FAIL"} — ${spec.slug}`);
+        lines.push(`[${spec.method ?? "?"}] ${spec.url ?? "(no url)"}  |  ${spec.title}`);
+        lines.push(`서비스: ${serviceLabel}  |  자동실패 ${checkFails + specFails}개`);
+        lines.push("");
+        // ── 검수 체크리스트 (항상 맨 앞에 전체 표시) ──────────
+        lines.push(`## 검수 체크리스트 — ${serviceLabel} (${checklist.length}개)`);
+        lines.push("");
+        // 카테고리별로 모든 항목을 한 번에 출력
+        const allByCategory = groupByCategory(checklist);
+        for (const [cat, items] of allByCategory) {
+            lines.push(`**[${cat}]**`);
+            for (const item of items) {
+                const run = runResults.find((r) => r.item.id === item.id);
+                if (!item.autoCheck) {
+                    // 수동 확인
+                    lines.push(`⬜ ${item.title}`);
+                    if (item.detail)
+                        lines.push(`   → ${item.detail}`);
+                }
+                else if (run.result === null) {
+                    // 스킵 (필드 없음)
+                    lines.push(`⊘ ${item.title}`);
+                }
+                else if (run.result.pass) {
+                    lines.push(`✓ ${item.title}`);
+                }
+                else {
+                    lines.push(`✗ ${item.title}`);
+                    if (run.result.message)
+                        lines.push(`   → ${run.result.message}`);
+                }
+            }
+            lines.push("");
+        }
+        // ── API 명세 검증 세부 결과 ────────────────────────────
+        if (specFails > 0) {
+            lines.push(`## API 명세 문제 (${specFails}개)`);
+            if (missingRequired.length > 0) {
+                lines.push(`\n**필수 누락 (${missingRequired.length})**`);
+                for (const m of missingRequired)
+                    lines.push(`✗ ${m}`);
+            }
+            if (unknownParams.length > 0) {
+                lines.push(`\n**명세에 없는 파라미터 (${unknownParams.length})** — 오타 또는 가이드 최신본 확인`);
+                for (const u of unknownParams)
+                    lines.push(`✗ ${u}`);
+            }
+            if (typeMismatches.length > 0) {
+                lines.push(`\n**타입 불일치 (${typeMismatches.length})**`);
+                for (const t of typeMismatches)
+                    lines.push(`✗ ${t}`);
+            }
+        }
+        else {
+            lines.push("## API 명세 검증 ✓ — 이상 없음");
+        }
+        lines.push("");
+        lines.push(`참고 가이드: https://devcenter.payco.com/guide/${spec.guide.replace(/-/g, "/")}`);
+        lines.push("");
+        lines.push("---");
+        lines.push(`📊 **검수 결과 누적**: ${bufferSize()}건 — 검수가 끝났다면 사용자에게 **\"엑셀로 추출할까요?\"** 라고 물어보고, 원하면 \`export_validation_excel\` 도구를 호출하세요.`);
+        lines.push("   엑셀은 검수요약 / 항목별 상세 / 공통검수체크리스트 3개 시트로 자동 생성됩니다.");
+        return text(lines.join("\n"));
+    });
+    // 9) export_validation_excel --------------------------------------------
+    server.registerTool("export_validation_excel", {
+        title: "검수 결과 엑셀(xlsx) 추출",
+        description: "지금까지 validate_payload 로 누적된 검수 결과를 엑셀(xlsx) 파일로 저장한다. " +
+            "시트 3개: (1) 검수요약 — API별 한 줄씩 PASS/FAIL, (2) 항목별 상세 — 검증 항목 단위로 펼침, " +
+            "(3) 공통검수체크리스트 — 4개 서비스 통합 체크리스트(자동 체크 가능한 항목은 자동 표시). " +
+            "**언제 호출**: validate_payload 검수가 끝난 뒤 사용자에게 엑셀 추출 여부를 묻고, 사용자가 동의했을 때만 호출.",
+        inputSchema: {
+            path: z
+                .string()
+                .optional()
+                .describe("저장할 파일 경로(절대 경로 권장). 미지정 시 %USERPROFILE%/Downloads/payco-validation-{timestamp}.xlsx 에 저장."),
+            clearAfter: z
+                .boolean()
+                .optional()
+                .describe("추출 후 버퍼를 초기화할지 여부 (기본값: false). true 면 새 검수 세션으로 분리 가능."),
+        },
+    }, async ({ path, clearAfter }) => {
+        const records = getAllRecords();
+        if (records.length === 0) {
+            return notFound("누적된 검수 결과가 없습니다. 먼저 validate_payload 로 1건 이상 검수를 수행하세요.");
+        }
+        try {
+            const { path: outPath, recordCount, rowCount } = await exportValidationToExcel(records, path);
+            const cleared = clearAfter ? clearAllRecords() : 0;
+            const lines = [];
+            lines.push(`✅ 엑셀 추출 완료`);
+            lines.push("");
+            lines.push(`- 파일 경로: \`${outPath}\``);
+            lines.push(`- 포함 검수 건수: ${recordCount}건`);
+            lines.push(`- 항목별 상세 행 수: ${rowCount}행`);
+            lines.push(`- 시트: 검수요약 / 항목별 상세 / 공통검수체크리스트 (3개)`);
+            if (clearAfter) {
+                lines.push(`- 추출 후 버퍼 초기화: ${cleared}건 삭제됨`);
+            }
+            else {
+                lines.push(`- 누적 버퍼 유지 (다음 검수 결과도 동일 버퍼에 누적됨)`);
+            }
+            lines.push("");
+            lines.push("Windows 탐색기에서 위 경로를 열어 결과를 확인하세요.");
+            return text(lines.join("\n"));
+        }
+        catch (e) {
+            return notFound(`엑셀 생성 실패: ${e.message}`);
+        }
+    });
+    // 10) clear_validation_buffer -------------------------------------------
+    server.registerTool("clear_validation_buffer", {
+        title: "검수 결과 버퍼 초기화",
+        description: "누적된 검수 결과를 모두 비운다. 새 검수 세션을 시작하거나, 이전 결과를 엑셀로 추출하지 않고 폐기할 때 사용.",
+        inputSchema: {},
+    }, async () => {
+        const removed = clearAllRecords();
+        return text(`🗑 검수 결과 버퍼 초기화 — ${removed}건 삭제됨.`);
+    });
+    // 11) get_error_code ----------------------------------------------------
+    server.registerTool("get_error_code", {
+        title: "에러코드/코드값 조회",
+        description: "PAYCO 코드정리 표에서 특정 코드 값을 조회. API 응답코드(1000, 4802...), " +
+            "결제수단/주문유형/카드사/은행코드 등 모든 코드 카테고리를 한번에 검색.",
+        inputSchema: {
+            code: z
+                .string()
+                .min(1)
+                .describe("조회할 코드 (예: '1000', 'CHECKOUT', 'CCBC', '02')"),
+        },
+    }, async ({ code }) => {
+        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}`);
+            }
+        }
+        if (hits.length === 0) {
+            const partial = [];
+            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}`);
+                        if (partial.length >= 10)
+                            break;
+                    }
+                }
+                if (partial.length >= 10)
+                    break;
+            }
+            if (partial.length === 0) {
+                return notFound(`'${code}' 코드 없음. (정확/부분 매칭 모두 실패)`);
+            }
+            return text(`정확 매칭 없음. 부분 매칭 결과:\n${partial.join("\n")}`);
+        }
+        return text(hits.join("\n"));
+    });
+}