hwpx-bridge 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HWPX Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# HWPX Bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI 에이전트가 한글 문서(HWP·HWPX)를 다룰 수 있게 해 주는 **MCP 서버 하나**입니다.
+
+- **[kordoc](https://github.com/chrisryugj/kordoc)의 모든 기능**: HWP·HWPX·PDF·DOCX·XLSX·이미지 읽기, 스캔 문서 OCR, Markdown → 새 HWPX 작성, 양식 채우기, 서식 유지 수정, HWP → HWPX, 렌더링, 공문서 검수 (22개 도구)
+- **[Filee](https://github.com/KnifeLemon/Filee)의 문서 변환 기능만**: DOCX → HWPX를 글꼴·색·정렬·머리말·쪽번호·표 서식까지 유지해 변환, 그 밖의 문서 형식 간 변환 (`filee_convert`)
+
+문서는 내 컴퓨터에서 처리되며 변환 서비스에 업로드되지 않습니다.
+
+## 설치 — 한 줄
+
+[Node.js](https://nodejs.org) 20 이상이 있으면(kordoc과 같은 조건) 아무 터미널에서:
+
+```
+npx -y hwpx-bridge setup
+```
+
+등록할 앱을 고르면 끝입니다: Claude 앱, Claude Code, Codex, Cursor, Gemini CLI, Windsurf. 앱을 한 번 다시 시작하면 도구가 나타납니다.
+
+번호를 고르지 않고 바로 등록하려면:
+
+```
+npx -y hwpx-bridge setup --client claude-desktop,claude-code,codex
+```
+
+직접 넣는 경우 (`npx -y hwpx-bridge config`가 출력하는 것과 같음):
+
+```json
+{ "mcpServers": { "hwpx-bridge": { "command": "npx", "args": ["-y", "hwpx-bridge@0.3.1", "mcp"] } } }
+```
+
+Windows의 Claude 앱은 `"command": "cmd", "args": ["/c", "npx", "-y", "hwpx-bridge@0.3.1", "mcp"]` 형식이 필요하며, `setup`이 자동으로 맞춥니다. 처음 실행할 때 엔진(약 100 MB)을 내려받으므로, `setup`을 먼저 실행해 두면 앱 첫 실행이 빠릅니다.
+
+Claude Code·Codex 플러그인 마켓플레이스(`ThisIsMarkive/foryourdocument`)로 설치해도 같은 서버(`npx -y hwpx-bridge@0.3.1 mcp`)와 사용 안내 스킬이 등록됩니다.
+
+확인: `npx -y hwpx-bridge doctor`
+
+## 도구
+
+| 하고 싶은 일 | 도구 |
+| --- | --- |
+| 기존 DOCX → HWPX (서식 유지) | `filee_convert` |
+| HWPX → PDF/DOCX, PDF → DOCX, PPTX·XLSX → PDF, 이미지 → PDF 등 | `filee_convert` (`to`) |
+| 문서 읽기, 스캔 OCR | `parse_document` |
+| 새 HWPX 작성 | `generate_document` |
+| 양식 채우기, 기존 HWPX 수정 | `fill_form`, `patch_document` |
+| HWP → HWPX | `convert_to_hwpx` |
+| 미리보기 | `render_document` |
+| 상태 확인 | `hwpx_bridge_status` |
+
+그 밖의 kordoc 도구: `detect_format`, `parse_metadata`, `parse_pages`, `parse_table`, `parse_chunks`, `parse_form`, `compare_documents`, `place_seal`, `add_memo`, `redact_document`, `crop_regions`, `extract_tables`, `extract_profile`, `build_agency_pack`, `agency_pack_info`, `lint_document`.
+
+`filee_convert`가 받는 입력: 문서(docx, doc, odt, rtf …), hwp/hwpx, pdf, pptx/xlsx 등 오피스, md/txt/html 등 텍스트, 이미지와 벡터 그림.
+출력: `hwpx, hwp, docx, odt, rtf, pdf, pptx, xlsx, csv, md, txt, html, png, jpg, webp, tiff, svg`.
+동영상·오디오·압축·전자책·CAD·3D·폰트 등 문서와 무관한 Filee 기능은 노출하지 않습니다. 같은 이름의 결과 파일이 있으면 덮어쓰지 않고 건너뜁니다.
+
+## 지원 환경
+
+| | kordoc 도구 | `filee_convert` |
+| --- | --- | --- |
+| Windows x64 | O | O |
+| Linux x64 | O | O |
+| macOS 등 | O | X (안내 메시지) |
+
+OCR 모델은 kordoc이 처음 OCR할 때 자동으로 받습니다(약 18 MB부터). OCR 결과는 오인식이 있을 수 있습니다.
+
+## 구조
+
+```
+npm/hwpx-bridge                 MCP 서버 (Node). kordoc npm 패키지를 그대로 실행하고 도구를 함께 노출
+npm/filee-win32-x64             Filee 2.4.0 공식 릴리스의 CLI만 추린 것 (Windows)
+npm/filee-linux-x64             〃 (Linux)
+npm/scripts/prepare-filee.mjs   공식 릴리스를 SHA-256으로 확인하고 CLI에 필요한 파일만 복사
+plugins/hwpx-bridge             Claude Code·Codex 플러그인 (MCP 등록 + 사용 안내 스킬)
+```
+
+Filee는 소스를 빌드하지 않고 **공식 릴리스의 파일을 그대로** 씁니다. 그중 `filee-cli`가 로드하는 파일(`filee-cli.deps.json` 기준)과 HWP 렌더링 엔진 rhwp만 남기고, 데스크톱 앱(GUI, Ctrl 단축키, 탐색기 메뉴), 7-Zip, 디버그 심볼, 번역 파일은 뺍니다. 변환 결과는 원본 Filee와 같습니다.
+
+## 배포 (관리자용)
+
+1. npm 계정을 만들고(2단계 인증 필수) Granular Access Token을 만듭니다: 권한 Read and write, 대상 All packages, **Bypass 2FA** 체크, 만료 최대 90일. GitHub 저장소 Secret `NPM_TOKEN`으로 등록합니다. 첫 배포 뒤에는 각 패키지 설정에서 Trusted Publishing(GitHub Actions)을 켜면 토큰 갱신이 필요 없습니다.
+2. 세 `package.json`과 플러그인 매니페스트의 버전을 올리고, `vX.Y.Z` 태그를 푸시하거나 GitHub Releases에서 같은 태그로 릴리스를 만듭니다.
+3. GitHub Actions가 Filee 준비 → 패키지 생성 → Windows·Linux에서 실제 설치·변환 테스트 → npm 배포를 순서대로 합니다.
+
+로컬에서 확인하려면: `node npm/scripts/prepare-filee.mjs all` 후 각 폴더에서 `npm pack`.
+
+이 프로젝트는 kordoc·Filee의 공식 제품이 아닌 독립적인 연결 도구입니다. 라이선스: MIT. [제3자 고지](npm/hwpx-bridge/THIRD_PARTY_NOTICES.md)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party notices
+
+hwpx-bridge combines two independent open-source projects. Neither project endorses this package.
+
+| Component | How it is used | License |
+| --- | --- | --- |
+| [kordoc](https://github.com/chrisryugj/kordoc) by chrisryugj | npm dependency `kordoc`, run unmodified as an MCP server | MIT |
+| [Filee](https://github.com/KnifeLemon/Filee) by Myeonggu Kim (KnifeLemon) and contributors | Command-line converter from the official release archive, unmodified, in `hwpx-bridge-filee-<platform>` | MIT (`filee/LICENSE-Filee.txt` in each platform package) |
+| [rhwp](https://github.com/edwardkim/rhwp) | Bundled by Filee for HWP/HWPX rendering (`filee/engines/rhwp`) | MIT |
+| [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) | npm dependency | MIT |
+
+The Filee platform packages also contain the .NET runtime and libraries listed in Filee's own
+`THIRD-PARTY-NOTICES.md` (shipped in the Linux package; the same components are used on Windows).

package/bin/hwpx-bridge.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const [command = 'help', ...rest] = process.argv.slice(2);
+
+const HELP = `hwpx-bridge ${pkg.version} — kordoc + Filee document conversion as one MCP server
+
+  npx -y hwpx-bridge setup            AI 앱(Claude, Claude Code, Codex, Cursor ...)에 등록
+  npx -y hwpx-bridge setup --client claude-desktop,codex
+  npx -y hwpx-bridge config           직접 붙여 넣을 MCP 설정 JSON 출력
+  npx -y hwpx-bridge doctor           kordoc·Filee 실행 확인
+  npx -y hwpx-bridge mcp              MCP 서버 실행 (앱이 이 명령을 실행합니다)
+`;
+
+try {
+  switch (command) {
+    case 'mcp': await (await import('../lib/server.mjs')).startServer(); break;
+    case 'setup': await (await import('../lib/setup.mjs')).runSetup(rest); break;
+    case 'config': (await import('../lib/setup.mjs')).printConfig(); break;
+    case 'doctor': await (await import('../lib/doctor.mjs')).runDoctor(); break;
+    case '-v': case '--version': case 'version': console.log(pkg.version); break;
+    default: console.log(HELP);
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/lib/doctor.mjs

@@ -0,0 +1,28 @@
+// `npx -y hwpx-bridge doctor` — start the MCP server once, as an AI app would, and report what works.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { locateFilee } from './filee.mjs';
+import { runProcess } from './process.mjs';
+
+export async function runDoctor() {
+  const filee = locateFilee();
+  if (filee.error) console.log(`x Filee: ${filee.error}`);
+  else {
+    const version = await runProcess(filee.cli, ['version'], { timeout: 60_000 }).catch(error => ({ code: 1, stdout: '', stderr: error.message }));
+    console.log(version.code === 0 ? `+ Filee: ${version.stdout.trim()} (${filee.cli})` : `x Filee: ${version.stderr.trim() || 'failed to start'}`);
+  }
+  const bin = path.join(path.dirname(fileURLToPath(import.meta.url)), '../bin/hwpx-bridge.mjs');
+  const client = new Client({ name: 'hwpx-bridge-doctor', version: '0' });
+  try {
+    await client.connect(new StdioClientTransport({ command: process.execPath, args: [bin, 'mcp'], stderr: 'inherit' }));
+    const { tools } = await client.listTools();
+    console.log(`+ MCP: ${tools.length} tools — ${tools.map(t => t.name).join(', ')}`);
+    const status = await client.callTool({ name: 'hwpx_bridge_status', arguments: {} });
+    console.log(status.content[0].text);
+  } catch (error) {
+    console.log(`x MCP: ${error.message}`);
+    process.exitCode = 1;
+  } finally { await client.close().catch(() => {}); }
+}

package/lib/filee.mjs

@@ -0,0 +1,93 @@
+// Filee document conversion. The converter is the unmodified Filee command-line program from the
+// official release, shipped in the platform package hwpx-bridge-filee-<platform>-<arch>.
+import fs from 'node:fs/promises';
+import fss from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { checkPath } from './paths.mjs';
+import { runProcess } from './process.mjs';
+import { INPUT_EXTENSIONS, OUTPUT_FORMATS } from './formats.mjs';
+
+const require = createRequire(import.meta.url);
+const PLATFORM_PACKAGE = `hwpx-bridge-filee-${process.platform}-${process.arch}`;
+
+/** Locate the bundled Filee CLI, or return null with the reason. */
+export function locateFilee() {
+  if (process.env.HWPX_BRIDGE_FILEE) {
+    const cli = path.resolve(process.env.HWPX_BRIDGE_FILEE);
+    return fss.existsSync(cli) ? { cli, source: 'HWPX_BRIDGE_FILEE' } : { error: `HWPX_BRIDGE_FILEE does not exist: ${cli}` };
+  }
+  let root;
+  try { root = path.dirname(require.resolve(`${PLATFORM_PACKAGE}/package.json`)); }
+  catch {
+    return { error: `Filee is not available for ${process.platform}-${process.arch}. Supported: Windows x64, Linux x64. kordoc tools still work.` };
+  }
+  const cli = path.join(root, 'filee', process.platform === 'win32' ? 'filee-cli.exe' : 'filee-cli');
+  if (!fss.existsSync(cli)) return { error: `${PLATFORM_PACKAGE} is installed but ${cli} is missing.` };
+  let source = {};
+  try { source = JSON.parse(fss.readFileSync(path.join(root, 'filee', 'SOURCE.json'), 'utf8')); } catch { /* optional */ }
+  return { cli, source: PLATFORM_PACKAGE, version: source.version };
+}
+
+export const fileeTool = {
+  name: 'filee_convert',
+  title: 'Filee document conversion',
+  description: [
+    'Convert a document file to another document format with Filee (local, no upload).',
+    'Best choice for DOCX -> HWPX: keeps fonts, sizes, colors, bold/italic/underline, alignment, indentation,',
+    'line spacing, lists, headers/footers, page numbers, page margins, page breaks, table shading and images.',
+    'Also converts HWP/HWPX/DOCX/PPTX/XLSX/PDF/Markdown/HTML/images between each other (e.g. HWPX -> PDF or DOCX,',
+    'PDF -> DOCX, DOCX -> PDF, image -> PDF).',
+    'To read a document use parse_document; to write a new HWPX from text use generate_document; for scans/OCR',
+    'use parse_document OCR options. Existing output files are never overwritten (they are skipped).'
+  ].join(' '),
+  inputSchema: {
+    type: 'object',
+    properties: {
+      input_path: { type: 'string', description: 'Absolute path of an existing local input file.' },
+      output_dir: { type: 'string', description: 'Absolute output directory (created if missing). The output keeps the input file name with the new extension.' },
+      to: { type: 'string', enum: OUTPUT_FORMATS, default: 'hwpx', description: 'Target format. Default hwpx.' }
+    },
+    required: ['input_path', 'output_dir'],
+    additionalProperties: false
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+};
+
+export async function callFilee(args, { signal } = {}) {
+  const located = locateFilee();
+  if (located.error) throw new Error(located.error);
+  const documentRoot = process.env.HWPX_BRIDGE_DOCUMENT_ROOT || process.env.KORDOC_ROOT;
+  const input = await checkPath(args?.input_path, { documentRoot });
+  const output = await checkPath(args?.output_dir, { directory: true, create: true, documentRoot });
+  const extension = path.extname(input).slice(1).toLowerCase();
+  if (!INPUT_EXTENSIONS.has(extension)) throw new Error(`Unsupported input type .${extension}. Only document, office, HWP, PDF, text and image files are accepted.`);
+  const target = args?.to ?? 'hwpx';
+  if (!OUTPUT_FORMATS.includes(target)) throw new Error(`Unsupported target format ${target}. Use one of: ${OUTPUT_FORMATS.join(', ')}.`);
+
+  // A private Filee data folder per job: no user settings are read or written, and the optional
+  // downloadable engines (LibreOffice, Pandoc, Ghostscript, FFmpeg, Tesseract ...) are never used.
+  const job = await fs.mkdtemp(path.join(os.tmpdir(), 'hwpx-bridge-filee-'));
+  try {
+    await fs.writeFile(path.join(job, 'settings.json'), JSON.stringify({
+      libreOfficeForHwp: false, libreOfficeForDocuments: false, libreOfficeForSheets: false
+    }));
+    const result = await runProcess(located.cli, ['convert', input, '--to', target, '-o', output, '--skip', '--json'], {
+      env: { ...process.env, FILEE_DATA_DIR: job, DOTNET_CLI_TELEMETRY_OPTOUT: '1' }, signal
+    });
+    // --json prints progress events as JSON lines, then the summary object.
+    const text = result.stdout.replace(/^/, '');
+    const start = text.search(/^\{\s*$/m);
+    let summary;
+    try { summary = JSON.parse(start >= 0 ? text.slice(start) : text); }
+    catch { throw new Error(`Filee returned no result (exit ${result.code}). ${result.stderr.slice(-4000) || text.slice(-4000)}`); }
+    const failed = result.code !== 0 || summary.failed > 0 || summary.converted + summary.skipped === 0;
+    return {
+      isError: failed,
+      content: [{ type: 'text', text: JSON.stringify({ engine: `Filee ${located.version ?? ''}`.trim(), ...summary }, null, 2) }]
+    };
+  } finally {
+    await fs.rm(job, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}

package/lib/formats.mjs

@@ -0,0 +1,4 @@
+// Generated from `filee formats --json` (Filee 2.4.0): document, HWP, PDF, office, text, image and vector
+// categories only. Media, archive, e-book, CAD, 3D, font, subtitle, geo and e-mail formats are not exposed.
+export const INPUT_EXTENSIONS = new Set(["3fr", "602", "abw", "adoc", "ahk", "ai", "apng", "arw", "asciidoc", "avif", "bat", "bmp", "bw", "c", "cc", "cdr", "cgm", "cmd", "command", "cpp", "cr2", "cr3", "crw", "cs", "css", "csv", "cur", "cwk", "cxx", "dart", "dbk", "dbml", "dcm", "dcr", "dds", "dib", "dicom", "dng", "doc", "docbook", "docm", "docx", "dot", "dotm", "dotx", "dps", "dst", "emf", "eps", "epsf", "epsi", "erf", "et", "exr", "fff", "fits", "fodg", "fodp", "fods", "fodt", "fts", "gif", "h", "hdp", "hdr", "heic", "heif", "hgl", "hh", "hif", "hpg", "hpgl", "hpp", "hql", "htm", "html", "hwp", "hwpx", "hxx", "icb", "icns", "ico", "iiq", "ini", "ipynb", "j2k", "java", "jfif", "jif", "jp2", "jpe", "jpeg", "jpf", "jpg", "jpx", "jxl", "jxr", "kdc", "key", "kra", "kra~", "latex", "livp", "log", "lua", "lwp", "man", "markdown", "mcw", "md", "mediawiki", "mef", "mht", "mhtml", "miff", "mng", "mos", "mrw", "nef", "nrw", "numbers", "odg", "odp", "ods", "odt", "ofd", "opml", "orf", "org", "otp", "ots", "ott", "pac", "pages", "pam", "pbm", "pcd", "pcx", "pdf", "pef", "pfm", "pgm", "plt", "png", "pnm", "pot", "potm", "potx", "ppm", "pps", "ppsx", "ppt", "pptm", "pptx", "ps", "ps1", "psb", "psd", "psw", "pub", "py", "qoi", "raf", "ras", "raw", "rgb", "rgba", "rsc", "rst", "rtf", "rw2", "rwl", "sda", "sdc", "sdd", "sdw", "sgi", "sql", "sr2", "srf", "srw", "sun", "svg", "svgz", "tab", "tex", "textile", "tga", "tif", "tiff", "tsv", "txt", "typ", "vda", "vsd", "vsdx", "vst", "wbmp", "wdp", "webp", "wiki", "wmf", "wpd", "wps", "x3f", "xbm", "xcf", "xhtml", "xls", "xlsm", "xlsx", "xlt", "xltx", "xpm", "zabw"]);
+export const OUTPUT_FORMATS = ["hwpx", "hwp", "docx", "odt", "rtf", "pdf", "pptx", "xlsx", "csv", "md", "txt", "html", "png", "jpg", "webp", "tiff", "svg"];

package/lib/paths.mjs

@@ -0,0 +1,34 @@
+// From HWPX Bridge 0.2.x server/paths.mjs (unchanged).
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export function inside(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+export async function checkPath(value, { directory = false, create = false, documentRoot } = {}) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) || /[\0*?]/.test(value)) {
+    throw new Error('Use an absolute local file/directory path without wildcards.');
+  }
+  // Avoid UNC/network paths so the local-only tools cannot send file data to a share.
+  if (/^\\\\|^\/\//.test(value) || /^\\\?\//.test(value)) throw new Error('Network and device paths are not supported.');
+  let resolved = path.resolve(value);
+  let ancestor = resolved;
+  const missing = [];
+  while (true) {
+    try { ancestor = await fs.realpath(ancestor); break; }
+    catch (error) {
+      if (error.code !== 'ENOENT' || !create) throw error;
+      missing.unshift(path.basename(ancestor));
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) throw error;
+      ancestor = parent;
+    }
+  }
+  resolved = path.join(ancestor, ...missing);
+  if (documentRoot && !inside(await fs.realpath(documentRoot), resolved)) throw new Error('Path is outside HWPX_BRIDGE_DOCUMENT_ROOT.');
+  if (create) await fs.mkdir(resolved, { recursive: true });
+  const stat = await fs.stat(resolved);
+  if (directory ? !stat.isDirectory() : !stat.isFile()) throw new Error(directory ? 'Expected a directory.' : 'Expected a regular file.');
+  return resolved;
+}

package/lib/process.mjs

@@ -0,0 +1,38 @@
+// From HWPX Bridge 0.2.x server/process.mjs (unchanged).
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+export async function runProcess(command, args, { env, signal, timeout = 900_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env, shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    let stdout = ''; let stderr = ''; let stopped;
+    const stop = reason => {
+      if (stopped) return;
+      stopped = reason;
+      if (process.platform === 'win32' && child.pid) {
+        // Filee may own Tesseract children; stop this owned process tree together.
+        const killer = spawn(path.join(process.env.SystemRoot, 'System32/taskkill.exe'), ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, shell: false, stdio: 'ignore' });
+        killer.on('error', () => child.kill());
+        killer.on('close', code => { if (code !== 0) child.kill(); });
+      } else child.kill();
+    };
+    const abort = () => stop('Operation cancelled.');
+    const timer = setTimeout(() => stop(`Operation exceeded ${timeout / 1000} seconds.`), timeout);
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    child.stdout.on('data', bytes => {
+      stdout += bytes.toString('utf8');
+      if (stdout.length > 8_000_000) stop('Engine output exceeded the 8 MB limit.');
+    });
+    child.stderr.on('data', bytes => { stderr = (stderr + bytes.toString('utf8')).slice(-32_000); });
+    const finish = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); };
+    child.on('error', error => { finish(); reject(error); });
+    child.on('close', code => {
+      finish();
+      if (stopped) reject(new Error(stopped));
+      else resolve({ code, stdout, stderr });
+    });
+  });
+}

package/lib/server.mjs

@@ -0,0 +1,108 @@
+// One MCP server = every kordoc tool + Filee document conversion.
+//
+// kordoc runs as its own MCP server (the unmodified kordoc npm package) in a child process; this server
+// lists its tools next to filee_convert and forwards calls. kordoc's OCR models are downloaded by kordoc
+// on first use, as kordoc normally does.
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { fileeTool, callFilee, locateFilee } from './filee.mjs';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const KORDOC_CALL_TIMEOUT = 30 * 60_000; // OCR model downloads and long renders
+
+function kordocInfo() {
+  const main = require.resolve('kordoc'); // dist/index.cjs; the package exports only "."
+  const dist = path.dirname(main);
+  return { mcp: path.join(dist, 'mcp.js'), version: pkg.dependencies.kordoc };
+}
+
+const statusTool = {
+  name: 'hwpx_bridge_status',
+  title: 'HWPX Bridge status',
+  description: 'Show hwpx-bridge, kordoc and Filee versions and whether each engine is available on this computer.',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  annotations: { readOnlyHint: true, openWorldHint: false }
+};
+
+const INSTRUCTIONS = `hwpx-bridge: kordoc (read/write/edit Korean documents) + Filee (document format conversion).
+- Existing DOCX -> HWPX (or any document format change: HWPX->PDF/DOCX, PDF->DOCX, PPTX/XLSX->PDF ...): filee_convert. Do not re-create a DOCX through parse_document + generate_document; that loses fonts, colors and layout.
+- Read HWP/HWPX/PDF/DOCX/XLSX/images (incl. OCR): parse_document. New HWPX from text: generate_document. Fill or edit an existing HWPX keeping its layout: fill_form / patch_document. HWP -> HWPX keeping formatting: convert_to_hwpx.
+- Use absolute local paths and a new output path; never overwrite the source file without permission.`;
+
+export async function startServer() {
+  let kordoc;          // Client once connected
+  let kordocError;     // string when kordoc failed to start
+  let kordocTools = [];
+  let kordocInstructions = '';
+  const info = kordocInfo();
+
+  const kordocReady = (async () => {
+    try {
+      const client = new Client({ name: 'hwpx-bridge', version: pkg.version });
+      await client.connect(new StdioClientTransport({
+        command: process.execPath, args: [info.mcp], env: process.env, stderr: 'inherit'
+      }));
+      kordocTools = (await client.listTools()).tools.filter(tool => tool.name !== fileeTool.name && tool.name !== statusTool.name);
+      kordocInstructions = client.getInstructions() ?? '';
+      kordoc = client;
+    } catch (error) {
+      kordocError = `kordoc MCP failed to start: ${error.message}`;
+      process.stderr.write(`[hwpx-bridge] ${kordocError}\n`);
+    }
+  })();
+
+  // kordoc starts in about a second; waiting lets its own usage guide travel with ours.
+  await kordocReady;
+  const server = new Server(
+    { name: 'hwpx-bridge', version: pkg.version },
+    { capabilities: { tools: {} }, instructions: kordocInstructions ? `${INSTRUCTIONS}\n\n${kordocInstructions}` : INSTRUCTIONS }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    await kordocReady;
+    return { tools: [fileeTool, ...kordocTools, statusTool] };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const { name, arguments: args } = request.params;
+    try {
+      if (name === fileeTool.name) return await callFilee(args, { signal: extra.signal });
+      if (name === statusTool.name) {
+        await kordocReady;
+        const filee = locateFilee();
+        return { content: [{ type: 'text', text: JSON.stringify({
+          hwpxBridge: pkg.version, node: process.version, platform: `${process.platform}-${process.arch}`,
+          kordoc: kordoc ? { version: info.version, tools: kordocTools.length } : { error: kordocError },
+          filee: filee.error ? { error: filee.error } : { version: filee.version, executable: filee.cli }
+        }, null, 2) }] };
+      }
+      await kordocReady;
+      if (!kordoc) throw new Error(kordocError ?? 'kordoc is not available.');
+      if (!kordocTools.some(tool => tool.name === name)) throw new Error(`Unknown tool: ${name}`);
+      return await kordoc.callTool({ name, arguments: args ?? {} }, undefined, {
+        signal: extra.signal, timeout: KORDOC_CALL_TIMEOUT, resetTimeoutOnProgress: true
+      });
+    } catch (error) {
+      return { isError: true, content: [{ type: 'text', text: error.message }] };
+    }
+  });
+
+  let closing = false;
+  const close = async () => {
+    if (closing) return;
+    closing = true;
+    await kordoc?.close().catch(() => {});
+    await server.close().catch(() => {});
+    process.exit(0);
+  };
+  process.on('SIGINT', close);
+  process.on('SIGTERM', close);
+  process.stdin.on('end', close);
+  await server.connect(new StdioServerTransport());
+}

package/lib/setup.mjs

@@ -0,0 +1,119 @@
+// `npx -y hwpx-bridge setup` — register the MCP server in AI clients.
+// Same approach as kordoc's src/setup.ts (MIT, chrisryugj): JSON config files are merged in place,
+// Claude Code and Codex are registered through their own CLIs. Nothing else on the computer is changed.
+import fs from 'node:fs/promises';
+import fss from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { createRequire } from 'node:module';
+
+const run = promisify(execFile);
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const NAME = 'hwpx-bridge';
+const isWin = process.platform === 'win32';
+
+/** Pinned so a client never silently runs a newer (or hijacked) npm release. */
+export function packageSpec(version = pkg.version) {
+  return /^\d+\.\d+\.\d+$/.test(version) ? `${NAME}@${version}` : NAME;
+}
+
+/** Claude Desktop on Windows cannot start npx.cmd directly, hence `cmd /c`. */
+export function serverEntry() {
+  return isWin
+    ? { command: 'cmd', args: ['/c', 'npx', '-y', packageSpec(), 'mcp'] }
+    : { command: 'npx', args: ['-y', packageSpec(), 'mcp'] };
+}
+
+function claudeDesktopConfig() {
+  const home = os.homedir();
+  if (isWin) {
+    const appData = process.env.APPDATA ?? path.join(home, 'AppData/Roaming');
+    const localAppData = process.env.LOCALAPPDATA ?? path.join(home, 'AppData/Local');
+    // The Microsoft Store build of Claude reads a package-local copy of %APPDATA%.
+    const store = path.join(localAppData, 'Packages/Claude_pzs8sxrjxfjjc/LocalCache/Roaming/Claude');
+    return path.join(fss.existsSync(store) ? store : path.join(appData, 'Claude'), 'claude_desktop_config.json');
+  }
+  if (process.platform === 'darwin') return path.join(home, 'Library/Application Support/Claude/claude_desktop_config.json');
+  return path.join(home, '.config/Claude/claude_desktop_config.json');
+}
+
+export const CLIENTS = [
+  { id: 'claude-desktop', label: 'Claude 앱 (Claude Desktop)', kind: 'json', file: claudeDesktopConfig },
+  { id: 'claude-code', label: 'Claude Code (사용자 전체)', kind: 'cli', cli: 'claude' },
+  { id: 'codex', label: 'Codex (ChatGPT)', kind: 'cli', cli: 'codex' },
+  { id: 'cursor', label: 'Cursor', kind: 'json', file: () => path.join(os.homedir(), '.cursor/mcp.json') },
+  { id: 'gemini', label: 'Gemini CLI', kind: 'json', file: () => path.join(os.homedir(), '.gemini/settings.json') },
+  { id: 'windsurf', label: 'Windsurf', kind: 'json', file: () => path.join(os.homedir(), '.codeium/windsurf/mcp_config.json') }
+];
+
+async function registerJson(file) {
+  let config = {};
+  if (fss.existsSync(file)) {
+    const raw = (await fs.readFile(file, 'utf8')).replace(/^/, '');
+    config = raw.trim() ? JSON.parse(raw) : {};
+  }
+  if (typeof config !== 'object' || config === null || Array.isArray(config)) throw new Error(`설정 파일 형식이 올바르지 않아 그대로 두었습니다: ${file}`);
+  const entry = serverEntry();
+  if (JSON.stringify(config.mcpServers?.[NAME]) === JSON.stringify(entry)) return `이미 등록됨 (${file})`;
+  if (fss.existsSync(file)) await fs.copyFile(file, `${file}.bak-${Date.now()}`);
+  config.mcpServers = { ...(config.mcpServers ?? {}), [NAME]: entry };
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  return `등록 완료 (${file})`;
+}
+
+async function registerCli(cli) {
+  const options = { windowsHide: true, timeout: 60_000, shell: isWin }; // claude/codex are .cmd shims on Windows
+  const entry = serverEntry();
+  const scope = cli === 'claude' ? ['--scope', 'user'] : [];
+  // Replace an earlier hwpx-bridge registration (e.g. an older pinned version).
+  await run(cli, ['mcp', 'remove', ...scope, NAME], options).catch(() => {});
+  await run(cli, ['mcp', 'add', ...scope, NAME, '--', entry.command, ...entry.args], options);
+  return `등록 완료 (${cli} mcp add)`;
+}
+
+async function choose() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log('\nhwpx-bridge를 등록할 AI 앱을 고르세요 (여러 개는 쉼표로, 예: 1,3)\n');
+    CLIENTS.forEach((client, i) => console.log(`  ${i + 1}. ${client.label}`));
+    const answer = await rl.question('\n번호: ');
+    const picked = answer.split(/[,\s]+/).filter(Boolean).map(n => CLIENTS[Number(n) - 1]);
+    if (!picked.length || picked.some(c => !c)) throw new Error('올바른 번호를 입력하세요.');
+    return picked;
+  } finally { rl.close(); }
+}
+
+export async function runSetup(argv) {
+  const flag = argv.indexOf('--client');
+  let clients;
+  if (flag >= 0) {
+    const ids = (argv[flag + 1] ?? '').split(',').filter(Boolean);
+    clients = ids.map(id => CLIENTS.find(c => c.id === id));
+    if (!ids.length || clients.some(c => !c)) throw new Error(`--client 값: ${CLIENTS.map(c => c.id).join(', ')}`);
+  } else if (process.stdin.isTTY) clients = await choose();
+  else throw new Error(`대화형 터미널이 아닙니다. --client ${CLIENTS.map(c => c.id).join(',')} 중에서 지정하세요.`);
+
+  let failed = false;
+  for (const client of clients) {
+    try {
+      const message = client.kind === 'json' ? await registerJson(client.file()) : await registerCli(client.cli);
+      console.log(`  + ${client.label}: ${message}`);
+    } catch (error) {
+      failed = true;
+      const hint = error.code === 'ENOENT' ? `${client.cli} 명령을 찾을 수 없습니다.` : error.message;
+      console.log(`  x ${client.label}: ${hint}`);
+    }
+  }
+  console.log(`\n앱을 다시 시작하면 'hwpx-bridge' 도구가 나타납니다 (kordoc 도구 + filee_convert).`);
+  console.log(`직접 설정하려면: npx -y ${packageSpec()} config`);
+  if (failed) process.exitCode = 1;
+}
+
+export function printConfig() {
+  console.log(JSON.stringify({ mcpServers: { [NAME]: serverEntry() } }, null, 2));
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "hwpx-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "One MCP server for Korean documents: every kordoc tool (read/write/edit HWP·HWPX·PDF, OCR) plus Filee document conversion (DOCX→HWPX with formatting). One-line setup for Claude, Codex, Cursor and more.",
+  "type": "module",
+  "bin": { "hwpx-bridge": "bin/hwpx-bridge.mjs" },
+  "files": ["bin/", "lib/", "README.md", "LICENSE", "THIRD_PARTY_NOTICES.md"],
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "kordoc": "4.24.62"
+  },
+  "optionalDependencies": {
+    "hwpx-bridge-filee-win32-x64": "0.3.1",
+    "hwpx-bridge-filee-linux-x64": "0.3.1"
+  },
+  "keywords": ["hwp", "hwpx", "docx", "mcp", "kordoc", "filee", "korean", "ocr", "claude", "codex"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/ThisIsMarkive/foryourdocument.git", "directory": "npm/hwpx-bridge" },
+  "homepage": "https://github.com/ThisIsMarkive/foryourdocument#readme"
+}