claude-code-hwp-mcp 0.2.0

package/dist/hwp-bridge.js

@@ -0,0 +1,320 @@
+/**
+ * HWP Python Bridge for MCP Server
+ * Adapted from electron/services/hwp-bridge.ts — no Electron dependencies.
+ * All logging via console.error() to protect stdout (MCP JSON-RPC).
+ */
+import { spawn, execFile } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const execFileAsync = promisify(execFile);
+export class HwpBridge {
+    process = null;
+    requestId = 0;
+    pending = new Map();
+    buffer = '';
+    MAX_BUFFER_SIZE = 10 * 1024 * 1024; // 10MB
+    startPromise = null;
+    pythonRunning = false;
+    currentDocumentPath = null;
+    currentDocumentFormat = null;
+    lastAnalysis = null;
+    lastError = null;
+    startTime = Date.now();
+    getPythonScriptDir() {
+        // npm 패키지: dist/hwp-bridge.js → ../python (패키지 내 python/)
+        const npmPath = path.resolve(__dirname, '../python');
+        if (fs.existsSync(path.join(npmPath, 'hwp_service.py')))
+            return npmPath;
+        // 개발 환경: mcp-server/dist/hwp-bridge.js → ../../python (프로젝트 루트)
+        return path.resolve(__dirname, '../../python');
+    }
+    findPython() {
+        return process.env.PYTHON_PATH || 'python';
+    }
+    async ensureRunning() {
+        if (this.process && this.pythonRunning)
+            return;
+        // 동시 재시작 방지: 이미 시작 중이면 기다림
+        if (this.startPromise)
+            return this.startPromise;
+        // Clean up previous process
+        if (this.process) {
+            this.process.kill();
+            this.process = null;
+        }
+        this.pythonRunning = false;
+        this.currentDocumentPath = null;
+        this.currentDocumentFormat = null;
+        this.lastAnalysis = null;
+        this.lastError = null;
+        this.startPromise = this.start();
+        try {
+            await this.startPromise;
+        }
+        finally {
+            this.startPromise = null;
+        }
+    }
+    async start() {
+        const pythonExe = this.findPython();
+        const scriptPath = path.join(this.getPythonScriptDir(), 'hwp_service.py');
+        console.error(`[HWP MCP Bridge] Starting Python: ${pythonExe} ${scriptPath}`);
+        this.process = spawn(pythonExe, [scriptPath], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, PYTHONUNBUFFERED: '1' },
+        });
+        // Python 실행 파일 자체를 찾을 수 없는 경우 (ENOENT)
+        this.process.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                this.lastError = 'Python을 찾을 수 없습니다. Python 3.8+을 설치하고 PATH에 추가하세요.\n→ https://www.python.org/downloads/ (설치 시 "Add to PATH" 체크)';
+            }
+            else {
+                this.lastError = `Python 프로세스 시작 실패: ${err.message}`;
+            }
+            console.error('[HWP MCP Bridge] Spawn error:', err.message);
+            this.pythonRunning = false;
+            this.rejectAllPending(new Error(this.lastError));
+        });
+        this.process.stdout?.on('data', (chunk) => {
+            this.buffer += chunk.toString('utf-8');
+            // Buffer 크기 제한 (10MB) — 메모리 폭증 방지
+            if (this.buffer.length > this.MAX_BUFFER_SIZE) {
+                console.error(`[HWP MCP Bridge] Buffer exceeded ${this.MAX_BUFFER_SIZE / 1024 / 1024}MB, clearing`);
+                this.buffer = '';
+                this.rejectAllPending(new Error('응답 크기가 너무 큽니다. 문서를 닫고 다시 열어주세요.'));
+                return;
+            }
+            this.processBuffer();
+        });
+        this.process.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf-8').trim();
+            console.error('[HWP MCP Bridge][stderr]', text);
+            if (text.includes('ModuleNotFoundError')) {
+                this.lastError = 'Python 모듈을 찾을 수 없습니다. pip install pyhwpx pywin32 를 실행해주세요.';
+            }
+            else if (text.includes('COM class not registered') || text.includes('CoInitialize')) {
+                this.lastError = '한글(HWP) 프로그램이 설치되어 있어야 합니다. 한글이 설치되어 있는지 확인하세요.';
+            }
+            else if (text.includes('RPC') || text.includes('사용할 수 없습니다')) {
+                this.lastError = 'RPC 서버를 사용할 수 없습니다. 한글 프로그램이 실행 중인지 확인하세요.';
+            }
+            else if (text.includes('SyntaxError') || text.includes('ImportError')) {
+                this.lastError = `Python 오류가 발생했습니다: ${text.split('\n').pop()}`;
+            }
+        });
+        this.process.on('exit', (code) => {
+            console.error(`[HWP MCP Bridge] Python exited with code ${code}`);
+            this.rejectAllPending(new Error(`Python process exited with code ${code}`));
+            this.process = null;
+            this.pythonRunning = false;
+            this.currentDocumentPath = null;
+            this.currentDocumentFormat = null;
+            this.lastAnalysis = null;
+        });
+        // Verify connection (with 2 retries, 5초 간격)
+        let lastErr;
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                // ping 시 Python에서 Hwp() COM 초기화 — 한글 프로그램 시작까지 최대 90초
+                const response = await this.send('ping', {}, 90000);
+                if (response.success) {
+                    this.pythonRunning = true;
+                    console.error('[HWP MCP Bridge] Python bridge connected');
+                    return;
+                }
+            }
+            catch (err) {
+                lastErr = err;
+                console.error(`[HWP MCP Bridge] Ping attempt ${attempt}/3 failed:`, err);
+                if (attempt < 3) {
+                    console.error('[HWP MCP Bridge] Retrying in 5 seconds...');
+                    await new Promise(resolve => setTimeout(resolve, 5000));
+                }
+            }
+        }
+        // All 3 attempts failed — 단계별 안내 제공
+        const detail = this.lastError || '';
+        let hint;
+        if (detail.includes('Python을 찾을 수 없습니다')) {
+            hint = detail;
+        }
+        else if (detail.includes('RPC') || detail.includes('사용할 수 없습니다')) {
+            hint = '한글 프로그램이 응답하지 않습니다. 한글을 닫고 다시 시도해주세요.';
+        }
+        else if (detail.includes('ModuleNotFoundError') || detail.includes('pyhwpx')) {
+            hint = 'pyhwpx가 설치되지 않았습니다. 터미널에서 실행: pip install pyhwpx';
+        }
+        else if (detail.includes('COM') || detail.includes('한글')) {
+            hint = '한글(HWP) 프로그램이 설치되지 않았거나 COM 등록이 실패했습니다.';
+        }
+        else {
+            hint = 'hwp_check_setup 도구로 환경을 진단해보세요.\n  확인사항: 1) Python 3.8+ 설치  2) pip install pyhwpx  3) 한글 프로그램 설치';
+        }
+        throw new Error(`HWP MCP 시작 실패: ${hint}`);
+    }
+    processBuffer() {
+        let newlineIndex;
+        while ((newlineIndex = this.buffer.indexOf('\n')) !== -1) {
+            const line = this.buffer.slice(0, newlineIndex).trim();
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+            if (!line)
+                continue;
+            try {
+                const response = JSON.parse(line);
+                const pending = this.pending.get(response.id);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pending.delete(response.id);
+                    pending.resolve(response);
+                }
+            }
+            catch {
+                console.error('[HWP MCP Bridge] Invalid JSON from Python:', line);
+            }
+        }
+    }
+    async send(method, params, timeoutMs = 30000) {
+        // start() 내부의 ping 호출 시에는 이미 process가 있으므로 재시작 하지 않음
+        if (!this.process || !this.process.stdin?.writable) {
+            if (method !== 'ping') {
+                this.lastError = null;
+                await this.ensureRunning();
+            }
+        }
+        if (!this.process?.stdin?.writable) {
+            const detail = this.lastError || 'Python과 pyhwpx가 설치되어 있는지 확인하세요.';
+            throw new Error(`Python 프로세스를 시작할 수 없습니다. ${detail}`);
+        }
+        const id = `req_${++this.requestId}`;
+        const request = { id, method, params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                const detail = this.lastError ? ` 원인: ${this.lastError}` : '';
+                reject(new Error(`요청 시간 초과 (${timeoutMs / 1000}초): ${method}.${detail}`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            this.process.stdin.write(JSON.stringify(request) + '\n', (err) => {
+                if (err) {
+                    clearTimeout(timer);
+                    this.pending.delete(id);
+                    reject(new Error(`Failed to write to Python stdin: ${err.message}`));
+                }
+            });
+        });
+    }
+    async shutdown() {
+        if (!this.process)
+            return;
+        try {
+            await this.send('shutdown', {}, 5000);
+        }
+        catch {
+            // ignore timeout on shutdown
+        }
+        this.process.kill();
+        this.process = null;
+        this.pythonRunning = false;
+        this.rejectAllPending(new Error('Bridge shut down'));
+    }
+    rejectAllPending(error) {
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+            this.pending.delete(id);
+        }
+    }
+    // ── 사전 요구사항 체크 (Python/pyhwpx/한글) ──
+    async checkPrerequisites() {
+        const result = {
+            ok: false,
+            python: { found: false },
+            pyhwpx: { found: false },
+            hwp: { found: false },
+            os: { ok: process.platform === 'win32', platform: process.platform },
+        };
+        if (!result.os.ok) {
+            result.os.error = 'HWP MCP는 Windows 전용입니다. 한글(HWP)은 Windows COM API를 사용합니다.';
+            return result;
+        }
+        const pythonExe = this.findPython();
+        // 1) Python 체크
+        try {
+            const { stdout } = await execFileAsync(pythonExe, ['--version'], { timeout: 5000 });
+            const ver = stdout.trim().replace('Python ', '');
+            result.python = { found: true, version: ver };
+        }
+        catch {
+            result.python = {
+                found: false,
+                guide: 'Python 3.8+ 설치 필요\n→ https://www.python.org/downloads/\n→ 설치 시 "Add Python to PATH" 반드시 체크\n→ 설치 후 터미널 재시작',
+            };
+            return result;
+        }
+        // 2) pyhwpx 체크
+        try {
+            const { stdout } = await execFileAsync(pythonExe, ['-c', 'import pyhwpx; print(getattr(pyhwpx, "__version__", "installed"))'], { timeout: 5000 });
+            result.pyhwpx = { found: true, version: stdout.trim() };
+        }
+        catch {
+            result.pyhwpx = {
+                found: false,
+                guide: 'pyhwpx 패키지 설치 필요\n→ 터미널에서 실행: pip install pyhwpx\n→ pywin32도 함께 필요: pip install pywin32',
+            };
+            return result;
+        }
+        // 3) 한글(HWP) COM 등록 체크
+        try {
+            await execFileAsync(pythonExe, ['-c', 'import win32com.client; o = win32com.client.gencache.EnsureDispatch("HWPFrame.HwpObject"); o.XHwpDocuments.Close(False); del o'], { timeout: 15000 });
+            result.hwp = { found: true };
+        }
+        catch (err) {
+            const msg = err.message || '';
+            if (msg.includes('COM class not registered') || msg.includes('gencache')) {
+                result.hwp = {
+                    found: false,
+                    guide: '한글(HWP) 프로그램이 설치되지 않았습니다.\n→ 한컴오피스 한글 설치 필요 (한글 2014 이상)\n→ 설치 후 한글을 한번 실행하여 초기 설정 완료',
+                };
+            }
+            else {
+                // COM은 등록되어 있지만 다른 에러 (이미 실행 중 등) → 설치는 된 것
+                result.hwp = { found: true };
+            }
+        }
+        result.ok = result.python.found && result.pyhwpx.found && result.hwp.found;
+        return result;
+    }
+    // State management
+    getState() {
+        return {
+            pythonRunning: this.pythonRunning,
+            currentDocumentPath: this.currentDocumentPath,
+            currentDocumentFormat: this.currentDocumentFormat,
+            lastAnalysis: this.lastAnalysis,
+            uptimeMs: Date.now() - this.startTime,
+        };
+    }
+    setCurrentDocument(filePath) {
+        this.currentDocumentPath = filePath;
+        if (filePath) {
+            const ext = path.extname(filePath).toLowerCase();
+            this.currentDocumentFormat = ext === '.hwpx' ? 'HWPX' : 'HWP';
+        }
+        else {
+            this.currentDocumentFormat = null;
+        }
+    }
+    getCurrentDocument() {
+        return this.currentDocumentPath;
+    }
+    getCachedAnalysis() {
+        return this.lastAnalysis;
+    }
+    setCachedAnalysis(data) {
+        this.lastAnalysis = data;
+    }
+}

package/dist/hwpx-engine.d.ts

@@ -0,0 +1,39 @@
+export interface HwpxTemplate {
+    id: string;
+    name: string;
+    category: string;
+    fields: string[];
+}
+export declare const TEMPLATES: HwpxTemplate[];
+/**
+ * HWPX(ZIP) 파일에서 특정 XML 파일을 읽어서 DOM으로 파싱.
+ */
+export declare function readHwpxXml(hwpxPath: string, xmlName: string): Promise<Document>;
+/**
+ * HWPX(ZIP) 파일의 특정 XML을 수정 후 저장.
+ * 기존 ZIP의 다른 파일은 그대로 유지.
+ */
+export declare function writeHwpxXml(sourcePath: string, outputPath: string, xmlName: string, doc: Document): Promise<void>;
+/**
+ * HWPX section XML에서 모든 텍스트를 추출.
+ * 경로: hp:p > hp:run > hp:t
+ */
+export declare function extractTextFromSection(doc: Document): string[];
+/**
+ * HWPX section XML에서 텍스트 찾아 바꾸기.
+ * CLAUDE.md 규칙: 수정 후 linesegarray 삭제 필수.
+ */
+export declare function replaceTextInSection(doc: Document, find: string, replace: string): number;
+/**
+ * 빈 HWPX 파일 생성.
+ * blank_template.hwpx를 복사하고, 필요시 제목 삽입.
+ */
+export declare function createBlankHwpx(outputPath: string, title?: string): Promise<void>;
+/**
+ * 템플릿 기반 문서 생성.
+ * blank_template.hwpx를 복사 → 변수 치환.
+ */
+export declare function generateFromTemplate(templateId: string, variables: Record<string, string>, outputPath: string): Promise<{
+    filledFields: number;
+    emptyFields: string[];
+}>;

package/dist/hwpx-engine.js

@@ -0,0 +1,187 @@
+/**
+ * HWPX XML Engine — 한글 프로그램 없이 HWPX 파일 직접 생성/편집
+ *
+ * HWPX = ZIP(application/hwp+zip) + XML 형식
+ * Python execSync 제거 — Node.js jszip + @xmldom/xmldom만 사용
+ *
+ * CLAUDE.md 규칙 준수:
+ * - @xmldom/xmldom 사용 (fast-xml-parser 금지)
+ * - element.localName 사용 (tagName 금지)
+ * - 텍스트 수정 후 linesegarray 삭제 필수
+ * - charPrIDRef 변경 금지
+ * - 표 셀 경로: tc → subList → p → run → t
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import JSZip from 'jszip';
+export const TEMPLATES = [
+    // 공문서
+    { id: 'gov_official_letter', name: '공문서 (기안문/시행문)', category: '공문서', fields: ['수신자', '발신부서', '발신자', '제목', '본문', '시행일자', '문서번호'] },
+    { id: 'gov_report', name: '보고서', category: '공문서', fields: ['보고제목', '보고자', '부서', '보고일', '요약', '현황', '문제점', '개선방안', '기대효과'] },
+    { id: 'gov_draft', name: '기안문', category: '공문서', fields: ['기안자', '검토자', '결재자', '제목', '내용', '시행일', '근거'] },
+    { id: 'gov_minutes', name: '회의록', category: '공문서', fields: ['회의명', '일시', '장소', '참석자', '안건', '토의내용', '결정사항', '향후계획'] },
+    { id: 'gov_plan', name: '사업계획서', category: '공문서', fields: ['사업명', '기관명', '사업기간', '사업목적', '추진내용', '기대효과', '예산'] },
+    { id: 'gov_notice', name: '공고문', category: '공문서', fields: ['공고제목', '공고내용', '공고일', '기관명'] },
+    { id: 'gov_budget', name: '예산서', category: '공문서', fields: ['사업명', '항목', '금액', '산출근거'] },
+    // 기업
+    { id: 'biz_proposal', name: '사업제안서', category: '기업', fields: ['회사명', '제안제목', '제안배경', '제안내용', '기대효과', '일정', '예산'] },
+    { id: 'biz_contract', name: '계약서', category: '기업', fields: ['갑', '을', '계약명', '계약금액', '계약기간'] },
+    { id: 'biz_invoice', name: '견적서', category: '기업', fields: ['발행처', '수신처', '품목', '합계', '부가세', '총액'] },
+    { id: 'biz_meeting', name: '기업 회의록', category: '기업', fields: ['회의명', '일시', '참석자', '안건', '결정사항'] },
+    { id: 'biz_memo', name: '업무 메모', category: '기업', fields: ['수신', '발신', '제목', '내용'] },
+    { id: 'biz_mou', name: '양해각서(MOU)', category: '기업', fields: ['기관1', '기관2', '목적', '협력내용', '기간'] },
+    { id: 'biz_nda', name: '비밀유지계약서(NDA)', category: '기업', fields: ['갑', '을', '비밀정보범위', '기간'] },
+    // 학술
+    { id: 'academic_paper', name: '학술 논문', category: '학술', fields: ['제목', '저자', '초록', '키워드', '서론', '본론', '결론', '참고문헌'] },
+    { id: 'academic_report', name: '학술 보고서', category: '학술', fields: ['제목', '작성자', '과목', '내용'] },
+    // 개인
+    { id: 'personal_resume', name: '이력서', category: '개인', fields: ['이름', '생년월일', '연락처', '이메일', '학력', '경력', '자격증'] },
+    { id: 'personal_letter', name: '자기소개서', category: '개인', fields: ['이름', '지원분야', '성장배경', '지원동기', '입사후포부'] },
+    { id: 'personal_certificate', name: '증명서', category: '개인', fields: ['성명', '생년월일', '발급사유', '발급일'] },
+];
+// ── HWPX 네임스페이스 ──
+const NS_HP = 'http://www.hancom.co.kr/hwpml/2011/paragraph';
+// ── HWPX ZIP 유틸 (Node.js jszip — Python execSync 제거) ──
+/**
+ * HWPX(ZIP) 파일에서 특정 XML 파일을 읽어서 DOM으로 파싱.
+ */
+export async function readHwpxXml(hwpxPath, xmlName) {
+    const data = fs.readFileSync(hwpxPath);
+    const zip = await JSZip.loadAsync(data);
+    const xmlFile = zip.file(xmlName);
+    if (!xmlFile) {
+        throw new Error(`HWPX 내에 ${xmlName}을 찾을 수 없습니다.`);
+    }
+    const xmlStr = await xmlFile.async('string');
+    const parser = new DOMParser();
+    return parser.parseFromString(xmlStr, 'text/xml');
+}
+/**
+ * HWPX(ZIP) 파일의 특정 XML을 수정 후 저장.
+ * 기존 ZIP의 다른 파일은 그대로 유지.
+ */
+export async function writeHwpxXml(sourcePath, outputPath, xmlName, doc) {
+    const serializer = new XMLSerializer();
+    const xmlStr = serializer.serializeToString(doc);
+    const data = fs.readFileSync(sourcePath);
+    const zip = await JSZip.loadAsync(data);
+    zip.file(xmlName, xmlStr);
+    const newData = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+    fs.writeFileSync(outputPath, newData);
+}
+// ── 텍스트 추출 ──
+/**
+ * HWPX section XML에서 모든 텍스트를 추출.
+ * 경로: hp:p > hp:run > hp:t
+ */
+export function extractTextFromSection(doc) {
+    const texts = [];
+    const paragraphs = doc.getElementsByTagNameNS(NS_HP, 'p');
+    for (let i = 0; i < paragraphs.length; i++) {
+        const p = paragraphs[i];
+        const runs = p.getElementsByTagNameNS(NS_HP, 'run');
+        let paraText = '';
+        for (let j = 0; j < runs.length; j++) {
+            const tNodes = runs[j].getElementsByTagNameNS(NS_HP, 't');
+            for (let k = 0; k < tNodes.length; k++) {
+                paraText += tNodes[k].textContent || '';
+            }
+        }
+        texts.push(paraText);
+    }
+    return texts;
+}
+// ── 텍스트 치환 ──
+/**
+ * HWPX section XML에서 텍스트 찾아 바꾸기.
+ * CLAUDE.md 규칙: 수정 후 linesegarray 삭제 필수.
+ */
+export function replaceTextInSection(doc, find, replace) {
+    let count = 0;
+    const tNodes = doc.getElementsByTagNameNS(NS_HP, 't');
+    for (let i = 0; i < tNodes.length; i++) {
+        const t = tNodes[i];
+        const text = t.textContent || '';
+        if (text.includes(find)) {
+            t.textContent = text.replaceAll(find, replace);
+            count++;
+        }
+    }
+    // CLAUDE.md 규칙 8: 텍스트 수정 후 linesegarray 삭제 필수
+    if (count > 0) {
+        removeLinesegarray(doc);
+    }
+    return count;
+}
+/**
+ * linesegarray 요소 삭제 (CLAUDE.md 규칙 8).
+ */
+function removeLinesegarray(doc) {
+    const linesegArrays = doc.getElementsByTagNameNS(NS_HP, 'linesegarray');
+    const toRemove = [];
+    for (let i = 0; i < linesegArrays.length; i++) {
+        toRemove.push(linesegArrays[i]);
+    }
+    for (const el of toRemove) {
+        el.parentNode?.removeChild(el);
+    }
+}
+// ── 빈 HWPX 생성 ──
+function getTemplatePath() {
+    // ESM에서 __dirname 대안
+    const thisFile = new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1');
+    return path.join(path.dirname(thisFile), '../../blank_template.hwpx');
+}
+/**
+ * 빈 HWPX 파일 생성.
+ * blank_template.hwpx를 복사하고, 필요시 제목 삽입.
+ */
+export async function createBlankHwpx(outputPath, title) {
+    const templatePath = getTemplatePath();
+    if (!fs.existsSync(templatePath)) {
+        throw new Error(`빈 HWPX 템플릿을 찾을 수 없습니다: ${templatePath}. 한글에서 빈 문서를 HWPX로 저장하세요.`);
+    }
+    fs.copyFileSync(templatePath, outputPath);
+    if (title) {
+        const doc = await readHwpxXml(outputPath, 'Contents/section0.xml');
+        const tNodes = doc.getElementsByTagNameNS(NS_HP, 't');
+        if (tNodes.length > 0) {
+            tNodes[0].textContent = title;
+            removeLinesegarray(doc);
+        }
+        await writeHwpxXml(outputPath, outputPath, 'Contents/section0.xml', doc);
+    }
+}
+// ── 템플릿 생성 ──
+/**
+ * 템플릿 기반 문서 생성.
+ * blank_template.hwpx를 복사 → 변수 치환.
+ */
+export async function generateFromTemplate(templateId, variables, outputPath) {
+    const template = TEMPLATES.find(t => t.id === templateId);
+    if (!template) {
+        throw new Error(`템플릿을 찾을 수 없습니다: ${templateId}. hwp_template_list로 사용 가능한 템플릿을 확인하세요.`);
+    }
+    // 빈 HWPX 복사
+    await createBlankHwpx(outputPath);
+    // 변수로 텍스트 생성
+    const lines = [];
+    lines.push(template.name);
+    lines.push('');
+    for (const field of template.fields) {
+        const value = variables[field] || `{{${field}}}`;
+        lines.push(`${field}: ${value}`);
+    }
+    // section0.xml에 텍스트 삽입
+    const doc = await readHwpxXml(outputPath, 'Contents/section0.xml');
+    const tNodes = doc.getElementsByTagNameNS(NS_HP, 't');
+    if (tNodes.length > 0) {
+        tNodes[0].textContent = lines.join('\n');
+        removeLinesegarray(doc);
+    }
+    await writeHwpxXml(outputPath, outputPath, 'Contents/section0.xml', doc);
+    const filledFields = template.fields.filter(f => variables[f]).length;
+    const emptyFields = template.fields.filter(f => !variables[f]);
+    return { filledFields, emptyFields };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * HWP Studio MCP Server — Entry Point
+ * stdio transport for Claude Code integration.
+ * WARNING: console.log() is forbidden — stdout is MCP JSON-RPC only.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { HwpBridge } from './hwp-bridge.js';
+import { setupServer } from './server.js';
+// --toolset 파라미터 파싱 (minimal | standard | full, 기본: standard)
+const toolsetArg = process.argv.find(a => a.startsWith('--toolset'));
+const toolset = toolsetArg?.split('=')[1]
+    ?? process.argv[process.argv.indexOf('--toolset') + 1]
+    ?? 'standard';
+const validToolsets = ['minimal', 'standard', 'full'];
+const resolvedToolset = validToolsets.includes(toolset)
+    ? toolset
+    : 'standard';
+const bridge = new HwpBridge();
+const server = new McpServer({
+    name: 'hwp-studio',
+    version: '0.2.0',
+});
+setupServer(server, bridge, resolvedToolset);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[HWP MCP] 서버 시작됨 (toolset: ${resolvedToolset}) — Claude Code에서 HWP 도구 사용 가능`);
+// 시작 시 환경 자동 체크 (비동기, 서버 시작을 차단하지 않음)
+bridge.checkPrerequisites().then(prereq => {
+    if (!prereq.ok) {
+        console.error('[HWP MCP] ⚠️ 환경 설정 필요:');
+        if (!prereq.os.ok)
+            console.error(`  ❌ ${prereq.os.error}`);
+        if (!prereq.python.found)
+            console.error('  ❌ Python 미설치 → https://www.python.org/downloads/ (PATH 추가 필수)');
+        else if (!prereq.pyhwpx.found)
+            console.error('  ❌ pyhwpx 미설치 → pip install pyhwpx');
+        else if (!prereq.hwp.found)
+            console.error('  ❌ 한글(HWP) 미설치 → 한컴오피스 설치 필요');
+        console.error('  💡 자세한 진단: hwp_check_setup 도구를 호출하세요');
+    }
+    else {
+        console.error(`[HWP MCP] ✅ 환경 준비 완료 (Python ${prereq.python.version})`);
+    }
+}).catch(() => { });
+process.on('SIGINT', async () => {
+    await bridge.shutdown();
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    await bridge.shutdown();
+    process.exit(0);
+});

package/dist/prompts/hwp-prompts.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPrompts(server: McpServer): void;