korean-stats-mcp 1.4.0

package/dist/utils/errorHandler.js

@@ -0,0 +1,94 @@
+/**
+ * 에러 처리 유틸리티
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["INVALID_API_KEY"] = "INVALID_API_KEY";
+    ErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+    ErrorCode["INVALID_PARAMETER"] = "INVALID_PARAMETER";
+    ErrorCode["NO_DATA_FOUND"] = "NO_DATA_FOUND";
+    ErrorCode["API_UNAVAILABLE"] = "API_UNAVAILABLE";
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+const ERROR_MESSAGES = {
+    [ErrorCode.INVALID_API_KEY]: 'API 키가 유효하지 않습니다. 환경 설정을 확인해주세요.',
+    [ErrorCode.RATE_LIMIT_EXCEEDED]: '요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.',
+    [ErrorCode.INVALID_PARAMETER]: '검색 조건이 올바르지 않습니다. 다른 조건으로 시도해주세요.',
+    [ErrorCode.NO_DATA_FOUND]: '해당 조건에 맞는 데이터가 없습니다.',
+    [ErrorCode.API_UNAVAILABLE]: 'KOSIS 서비스가 일시적으로 응답하지 않습니다. 잠시 후 다시 시도해주세요.',
+    [ErrorCode.NETWORK_ERROR]: '네트워크 연결을 확인해주세요.',
+    [ErrorCode.UNKNOWN_ERROR]: '알 수 없는 오류가 발생했습니다.',
+};
+/**
+ * 사용자 친화적 에러 메시지 반환
+ */
+export function getErrorMessage(code) {
+    return ERROR_MESSAGES[code] || ERROR_MESSAGES[ErrorCode.UNKNOWN_ERROR];
+}
+/**
+ * 에러를 안전하게 처리하고 결과 반환
+ */
+export function handleToolError(error) {
+    console.error('Tool error:', error);
+    if (error instanceof Error) {
+        // KOSIS API 에러
+        if ('code' in error) {
+            const code = error.code;
+            return {
+                success: false,
+                error: getErrorMessage(code),
+                code,
+            };
+        }
+        return {
+            success: false,
+            error: error.message,
+            code: ErrorCode.UNKNOWN_ERROR,
+        };
+    }
+    return {
+        success: false,
+        error: getErrorMessage(ErrorCode.UNKNOWN_ERROR),
+        code: ErrorCode.UNKNOWN_ERROR,
+    };
+}
+/**
+ * 재시도 래퍼 함수
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxRetries = 3, baseDelay = 1000, maxDelay = 10000 } = options;
+    let lastError;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // 재시도 불가능한 에러인 경우 즉시 throw
+            if (isNonRetryableError(error)) {
+                throw error;
+            }
+            // 마지막 시도가 아니면 대기
+            if (attempt < maxRetries - 1) {
+                const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+function isNonRetryableError(error) {
+    if (error instanceof Error && 'code' in error) {
+        const code = error.code;
+        return [
+            ErrorCode.INVALID_API_KEY,
+            ErrorCode.INVALID_PARAMETER,
+        ].includes(code);
+    }
+    return false;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=errorHandler.js.map

package/dist/utils/errorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.js","sourceRoot":"","sources":["../../src/utils/errorHandler.ts"],"names":[],"mappings":"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"}

package/dist/utils/metaLookup.d.ts

@@ -0,0 +1,93 @@
+export interface MetaItem {
+    ITM_ID: string;
+    ITM_NM: string;
+    OBJ_NM: string;
+    OBJ_ID: string;
+    /** OBJ_ID_SN — 분류 순서 (1=objL1, 2=objL2, ...). ITEM 항목은 비어있음 */
+    OBJ_ID_SN?: string;
+    UP_ITM_ID?: string;
+}
+/**
+ * 통계표 분류·항목 메타 조회 (캐싱)
+ */
+export declare function fetchTableMeta(orgId: string, tblId: string): Promise<MetaItem[]>;
+export interface MetaGroup {
+    objNm: string;
+    objId: string;
+    objIdSn: string;
+    items: MetaItem[];
+}
+/**
+ * 메타를 OBJ별로 그룹화
+ */
+export declare function groupMetaByObj(meta: MetaItem[]): MetaGroup[];
+/**
+ * 분류명(예: "자치구별", "성별") 매칭 + 항목명(예: "광진구") 매칭으로 ITM_ID를 찾는다.
+ * objNmHint가 비면 모든 분류 그룹을 후보로 검사.
+ *
+ * 매칭 규칙(우선순위):
+ *   1) ITM_NM 완전 일치
+ *   2) ITM_NM이 itmNameQuery로 시작
+ *   3) ITM_NM에 itmNameQuery 포함
+ */
+export declare function findItmIdInMeta(meta: MetaItem[], itmNameQuery: string, objNmHint?: string): {
+    match: MetaItem;
+    group: MetaGroup;
+} | null;
+/**
+ * objL1/objL2/itmId 자동 채우기
+ *
+ * regionName이 있으면 분류 중 "자치구별/시군구별/행정구역별/지역별" 류의 OBJ에서 매칭한다.
+ * 나머지 분류값은 "기본값"(첫 번째 항목, 보통 합계/전체)을 사용한다.
+ *
+ * 반환값에 누락된 필드(undefined)는 호출 측에서 처리.
+ */
+export interface ResolveResult {
+    itmId?: string;
+    objL1?: string;
+    objL2?: string;
+    objL3?: string;
+    objL4?: string;
+    /** 매칭에 사용된 정보 (디버깅·응답용) */
+    resolved: Array<{
+        objNm: string;
+        itmNm: string;
+        itmId: string;
+        reason: 'region' | 'default';
+    }>;
+    /** 매칭 실패시 후보군 */
+    candidates?: Record<string, string[]>;
+    /** 사용자가 regionName/itemName을 줬는데 어느 OBJ에서도 매칭 못한 경우 */
+    unmatched?: {
+        regionName?: string;
+        itemName?: string;
+    };
+}
+export declare function resolveDimensions(orgId: string, tblId: string, options?: {
+    regionName?: string;
+    itemName?: string;
+    /** 추가로 강제할 OBJ_NM → ITM_NM 매핑 (예: { '성별': '여자' }) */
+    overrides?: Record<string, string>;
+}): Promise<ResolveResult>;
+/**
+ * 메타 요약 — get_table_info 경량화용
+ */
+export interface MetaSummary {
+    orgId: string;
+    tblId: string;
+    groups: Array<{
+        objNm: string;
+        objIdSn: string;
+        totalItems: number;
+        /** 처음 10개 + 사용자가 자주 찾을 만한 일부 (전국/합계 등) */
+        sample: Array<{
+            ITM_ID: string;
+            ITM_NM: string;
+        }>;
+    }>;
+}
+export declare function summarizeTableMeta(orgId: string, tblId: string, options?: {
+    sampleSize?: number;
+    filter?: string;
+}): Promise<MetaSummary>;
+//# sourceMappingURL=metaLookup.d.ts.map

package/dist/utils/metaLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaLookup.d.ts","sourceRoot":"","sources":["../../src/utils/metaLookup.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAUtF;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,SAAS,EAAE,CAW5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,EAAE,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG,IAAI,CAmB9C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,QAAQ,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IAC/F,iBAAiB;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,uDAAuD;IACvD,SAAS,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAID,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B,GACL,OAAO,CAAC,aAAa,CAAC,CA4ExB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,0CAA0C;QAC1C,MAAM,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACnD,CAAC,CAAC;CACJ;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,OAAO,CAAC,WAAW,CAAC,CAuBtB"}

package/dist/utils/metaLookup.js

@@ -0,0 +1,170 @@
+/**
+ * 메타 자동 lookup
+ *
+ * KOSIS 통계표의 분류값(자치구·연령·성별·항목 등) ITM_ID는 통계표마다 다르다.
+ * 같은 「서울특별시 기본통계」시리즈에서도 광진구 코드가:
+ *   DT_201004_O110047 → "001005"
+ *   DT_201004_O110054 → "13102127569D1.HCD_11050"
+ * 식으로 갈린다.
+ *
+ * 정적 매핑은 불가능하므로 메타 API(getMeta type=ITM)로 OBJ_NM을 가져와
+ * 사용자 입력(예: "광진구")에 매칭되는 ITM_ID를 동적으로 찾는다. 캐싱 24h.
+ */
+import { getKosisClient } from '../api/client.js';
+import { getCacheManager } from '../cache/index.js';
+/**
+ * 통계표 분류·항목 메타 조회 (캐싱)
+ */
+export async function fetchTableMeta(orgId, tblId) {
+    const cache = getCacheManager();
+    return cache.getTableMeta({ orgId, tblId, type: 'ITM' }, async () => {
+        const client = getKosisClient();
+        const rows = await client.getTableMeta(orgId, tblId, 'ITM');
+        return rows;
+    });
+}
+/**
+ * 메타를 OBJ별로 그룹화
+ */
+export function groupMetaByObj(meta) {
+    const map = new Map();
+    for (const r of meta) {
+        const sn = r.OBJ_ID_SN ?? '0';
+        const key = `${sn}|${r.OBJ_ID}`;
+        if (!map.has(key)) {
+            map.set(key, { objNm: r.OBJ_NM, objId: r.OBJ_ID, objIdSn: sn, items: [] });
+        }
+        map.get(key).items.push(r);
+    }
+    return [...map.values()].sort((a, b) => a.objIdSn.localeCompare(b.objIdSn));
+}
+/**
+ * 분류명(예: "자치구별", "성별") 매칭 + 항목명(예: "광진구") 매칭으로 ITM_ID를 찾는다.
+ * objNmHint가 비면 모든 분류 그룹을 후보로 검사.
+ *
+ * 매칭 규칙(우선순위):
+ *   1) ITM_NM 완전 일치
+ *   2) ITM_NM이 itmNameQuery로 시작
+ *   3) ITM_NM에 itmNameQuery 포함
+ */
+export function findItmIdInMeta(meta, itmNameQuery, objNmHint) {
+    const q = itmNameQuery.trim();
+    if (!q)
+        return null;
+    const groups = groupMetaByObj(meta);
+    const targets = objNmHint
+        ? groups.filter((g) => g.objNm === objNmHint || g.objNm.includes(objNmHint))
+        : groups;
+    for (const tier of [
+        (it) => it.ITM_NM === q,
+        (it) => it.ITM_NM.startsWith(q),
+        (it) => it.ITM_NM.includes(q),
+    ]) {
+        for (const g of targets) {
+            const hit = g.items.find(tier);
+            if (hit)
+                return { match: hit, group: g };
+        }
+    }
+    return null;
+}
+const REGION_OBJ_HINTS = ['자치구별', '시군구별', '행정구역별', '지역별', '시도별', '구별', '시·군·구별'];
+export async function resolveDimensions(orgId, tblId, options = {}) {
+    const meta = await fetchTableMeta(orgId, tblId);
+    const groups = groupMetaByObj(meta);
+    const resolved = [];
+    const out = { resolved };
+    // 항목 (ITEM)
+    let itemMatched = !options.itemName; // itemName 미지정시는 매칭 시도 자체가 없으므로 true
+    const itemGroup = groups.find((g) => g.objId === 'ITEM' || g.objNm === '항목');
+    if (itemGroup) {
+        let item = itemGroup.items[0];
+        if (options.itemName) {
+            const r = findItmIdInMeta(meta, options.itemName, itemGroup.objNm);
+            if (r) {
+                item = r.match;
+                itemMatched = true;
+            }
+        }
+        out.itmId = item.ITM_ID;
+        resolved.push({ objNm: itemGroup.objNm, itmNm: item.ITM_NM, itmId: item.ITM_ID, reason: options.itemName && itemMatched ? 'region' : 'default' });
+    }
+    // 분류 1~4
+    let regionMatched = !options.regionName; // regionName 미지정시 true (검사 불필요)
+    const dimGroups = groups.filter((g) => g.objIdSn !== '0' && g.objId !== 'ITEM');
+    const candidates = {};
+    for (const g of dimGroups) {
+        let picked;
+        let reason = 'default';
+        // 명시적 override
+        const overrideName = options.overrides?.[g.objNm];
+        if (overrideName) {
+            const r = findItmIdInMeta(meta, overrideName, g.objNm);
+            if (r) {
+                picked = r.match;
+                reason = 'region';
+            }
+        }
+        // 지역명 매칭 (REGION 힌트 분류에 한해)
+        if (!picked && options.regionName && REGION_OBJ_HINTS.some((h) => g.objNm.includes(h.replace('별', '')) || g.objNm === h)) {
+            const r = findItmIdInMeta(meta, options.regionName, g.objNm);
+            if (r) {
+                picked = r.match;
+                reason = 'region';
+                regionMatched = true;
+            }
+        }
+        // 기본값 (첫 항목 — 보통 합계/전체)
+        if (!picked) {
+            picked = g.items[0];
+        }
+        if (picked) {
+            resolved.push({ objNm: g.objNm, itmNm: picked.ITM_NM, itmId: picked.ITM_ID, reason });
+            const sn = parseInt(g.objIdSn || '0', 10);
+            if (sn === 1)
+                out.objL1 = picked.ITM_ID;
+            else if (sn === 2)
+                out.objL2 = picked.ITM_ID;
+            else if (sn === 3)
+                out.objL3 = picked.ITM_ID;
+            else if (sn === 4)
+                out.objL4 = picked.ITM_ID;
+        }
+        candidates[g.objNm] = g.items.slice(0, 10).map((it) => it.ITM_NM);
+    }
+    // 매칭 실패 신호
+    if (!regionMatched || !itemMatched) {
+        out.unmatched = {};
+        if (!regionMatched)
+            out.unmatched.regionName = options.regionName;
+        if (!itemMatched)
+            out.unmatched.itemName = options.itemName;
+    }
+    out.candidates = candidates;
+    return out;
+}
+export async function summarizeTableMeta(orgId, tblId, options = {}) {
+    const meta = await fetchTableMeta(orgId, tblId);
+    const groups = groupMetaByObj(meta);
+    const size = options.sampleSize ?? 10;
+    const filter = options.filter?.trim();
+    return {
+        orgId,
+        tblId,
+        groups: groups.map((g) => {
+            const items = filter
+                ? g.items.filter((it) => it.ITM_NM.includes(filter))
+                : g.items;
+            return {
+                objNm: g.objNm,
+                objIdSn: g.objIdSn,
+                totalItems: g.items.length,
+                sample: (filter && items.length === 0 ? g.items : items).slice(0, size).map((it) => ({
+                    ITM_ID: it.ITM_ID,
+                    ITM_NM: it.ITM_NM,
+                })),
+            };
+        }),
+    };
+}
+//# sourceMappingURL=metaLookup.js.map

package/dist/utils/metaLookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaLookup.js","sourceRoot":"","sources":["../../src/utils/metaLookup.ts"],"names":[],"mappings":"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"}

package/dist/utils/queryParser.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 자연어 쿼리 파서
+ * 사용자 질문을 KOSIS API 파라미터로 변환
+ */
+export declare const TOPIC_MAPPINGS: Record<string, {
+    category: string;
+    keywords: string[];
+    viewCode?: string;
+}>;
+/**
+ * 지역명 → 지역코드 매핑 (표준 행정구역 코드)
+ *
+ * ⚠️ 주의: KOSIS 통계표마다 다른 지역 코드 체계를 사용할 수 있습니다!
+ * - 아래 코드는 표준 행정구역 코드입니다
+ * - 일부 통계표는 단순화된 코드를 사용합니다 (예: 일부 표에서 부산=21)
+ * - 정확한 코드는 get_table_info를 호출하여 확인하세요
+ *
+ * 표준 행정구역 코드 참조:
+ * 00=전국, 11=서울, 26=부산, 27=대구, 28=인천, 29=광주, 30=대전, 31=울산
+ * 36=세종, 41=경기, 42=강원, 43=충북, 44=충남, 45=전북, 46=전남, 47=경북, 48=경남, 50=제주
+ */
+export declare const REGION_CODES: Record<string, string>;
+export interface ParsedQuery {
+    topics: string[];
+    regions: string[];
+    timeRange?: {
+        type: 'recent' | 'specific' | 'range';
+        value?: number;
+        start?: string;
+        end?: string;
+    };
+    keywords: string[];
+    intent: 'search' | 'compare' | 'trend' | 'explain';
+}
+/**
+ * 자연어 쿼리 파싱
+ */
+export declare function parseQuery(query: string): ParsedQuery;
+export declare const REGION_NAMES: Record<string, string>;
+/**
+ * 검색어 생성
+ * 지역명이 있는 경우 지역명을 검색어에 포함
+ */
+export declare function generateSearchTerms(parsed: ParsedQuery, originalQuery?: string): string[];
+//# sourceMappingURL=queryParser.d.ts.map

package/dist/utils/queryParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryParser.d.ts","sourceRoot":"","sources":["../../src/utils/queryParser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAsEA,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuC/C,CAAC;AAWF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE;QACV,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;QACtC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;CACpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CA4FrD;AAGD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAE/C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBzF"}