hwpx-bridge 0.3.1 → 0.3.4

package/README.md

@@ -9,29 +9,40 @@ AI 에이전트가 한글 문서(HWP·HWPX)를 다룰 수 있게 해 주는 **MC
 
 ## 설치 — 한 줄
 
-[Node.js](https://nodejs.org) 20 이상이 있으면(kordoc과 같은 조건) 아무 터미널에서:
-
 ```
 npx -y hwpx-bridge setup
 ```
 
-등록할 앱을 고르면 끝입니다: Claude 앱, Claude Code, Codex, Cursor, Gemini CLI, Windsurf. 앱을 한 번 다시 시작하면 도구가 나타납니다.
+터미널(PowerShell 등)에 입력하든, Codex·Claude Code에 "이 명령 실행해줘"라고 하든 결과는 같습니다. **이 PC에 설치된 AI 앱을 모두 찾아 한 번에 등록**합니다. 묻는 것은 없습니다.
+
+| 찾는 앱 | 등록 위치 |
+| --- | --- |
+| Claude 앱 | `claude_desktop_config.json` |
+| Claude Code | `claude mcp add --scope user` |
+| Codex (ChatGPT 데스크톱 앱·CLI·IDE 확장이 함께 쓰는 설정) | `~/.codex/config.toml` |
+| Cursor, Gemini CLI, Windsurf | 각 앱의 MCP 설정 파일 |
+
+등록한 앱을 한 번 완전히 종료했다가 다시 열면, 그 앱의 **모든 대화**에서 도구가 보입니다. 작업 폴더와 상관없이 PC 안의 어느 파일이든 경로로 다룰 수 있습니다. 나중에 새 AI 앱을 설치했다면 같은 명령을 한 번 더 실행하면 됩니다. 기존 설정은 백업(`.bak-…`)을 남기고 유지됩니다.
 
-번호를 고르지 않고 바로 등록하려면:
+**Node.js가 없는 Windows PC**: `npx`가 없다는 오류가 나면 PowerShell에 아래 한 줄을 넣으세요. Node.js LTS를 설치한 뒤(winget이 있으면 winget, 없으면 nodejs.org 공식 파일을 SHA-256 확인 후 사용자 폴더에 설치 — 관리자 권한 불필요) 위 명령을 대신 실행합니다.
 
 ```
-npx -y hwpx-bridge setup --client claude-desktop,claude-code,codex
+irm https://raw.githubusercontent.com/ThisIsMarkive/foryourdocument/main/install.ps1 | iex
 ```
 
-직접 넣는 경우 (`npx -y hwpx-bridge config`가 출력하는 것과 같음):
+일부 앱에만 등록하려면 `npx -y hwpx-bridge setup --client claude-desktop,codex` (값: `claude-desktop, claude-code, codex, cursor, gemini, windsurf`).
+
+웹·모바일(claude.ai 웹, ChatGPT 웹, 휴대폰 앱)은 내 PC의 프로그램을 실행할 수 없어 지원되지 않습니다.
+
+설정 파일에 직접 넣는 경우 (`npx -y hwpx-bridge config`가 출력하는 것과 같음):
 
 ```json
-{ "mcpServers": { "hwpx-bridge": { "command": "npx", "args": ["-y", "hwpx-bridge@0.3.1", "mcp"] } } }
+{ "mcpServers": { "hwpx-bridge": { "command": "npx", "args": ["-y", "hwpx-bridge@0.3.4", "mcp"] } } }
 ```
 
-Windows의 Claude 앱은 `"command": "cmd", "args": ["/c", "npx", "-y", "hwpx-bridge@0.3.1", "mcp"]` 형식이 필요하며, `setup`이 자동으로 맞춥니다. 처음 실행할 때 엔진(약 100 MB)을 내려받으므로, `setup`을 먼저 실행해 두면 앱 첫 실행이 빠릅니다.
+Windows의 Claude 앱은 `"command": "cmd", "args": ["/c", "npx", "-y", "hwpx-bridge@0.3.4", "mcp"]` 형식이 필요하며, `setup`이 자동으로 맞춥니다. 처음 실행할 때 엔진(약 100 MB)을 내려받으므로, `setup`을 먼저 실행해 두면 앱 첫 실행이 빠릅니다.
 
-Claude Code·Codex 플러그인 마켓플레이스(`ThisIsMarkive/foryourdocument`)로 설치해도 같은 서버(`npx -y hwpx-bridge@0.3.1 mcp`)와 사용 안내 스킬이 등록됩니다.
+Claude Code·Codex 플러그인 마켓플레이스(`ThisIsMarkive/foryourdocument`)로 설치해도 같은 서버(`npx -y hwpx-bridge@0.3.4 mcp`)와 사용 안내 스킬이 등록됩니다.
 
 확인: `npx -y hwpx-bridge doctor`
 
@@ -79,7 +90,7 @@ 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에서 같은 태그로 릴리스를 만듭니다.
+2. 세 `package.json`과 플러그인 매니페스트의 버전을 올리고 GitHub Releases에서 `vX.Y.Z` 태그로 릴리스를 만듭니다(태그만 푸시하면 배포되지 않습니다).
 3. GitHub Actions가 Filee 준비 → 패키지 생성 → Windows·Linux에서 실제 설치·변환 테스트 → npm 배포를 순서대로 합니다.
 
 로컬에서 확인하려면: `node npm/scripts/prepare-filee.mjs all` 후 각 폴더에서 `npm pack`.

package/bin/hwpx-bridge.mjs

@@ -7,8 +7,8 @@ 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 setup            이 PC의 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 서버 실행 (앱이 이 명령을 실행합니다)

package/lib/filee.mjs

@@ -21,7 +21,10 @@ export function locateFilee() {
   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 supported = ['win32-x64', 'linux-x64'].includes(`${process.platform}-${process.arch}`);
+    return { error: supported
+      ? `${PLATFORM_PACKAGE} is not installed (npm skipped it). Clear the npx cache (%LOCALAPPDATA%\\npm-cache\\_npx on Windows, ~/.npm/_npx elsewhere) and run setup again. kordoc tools still work.`
+      : `Filee conversion is not available on ${process.platform}-${process.arch} (Windows x64 and Linux x64 only). 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.` };

package/lib/setup.mjs

@@ -1,13 +1,14 @@
-// `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.
+// `npx -y hwpx-bridge setup` — register the MCP server in every AI app found on this computer.
+//
+// No questions: wherever the command runs (a terminal, Codex, Claude Code ...), every installed app gets
+// the same entry. `--client a,b` limits it to some apps. Config files are merged in place with a backup;
+// Claude Code is registered through its own CLI. 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 { execFile, spawnSync } from 'node:child_process';
 import { promisify } from 'node:util';
-import { createInterface } from 'node:readline/promises';
 import { createRequire } from 'node:module';
 
 const run = promisify(execFile);
@@ -15,77 +16,122 @@ const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 const NAME = 'hwpx-bridge';
 const isWin = process.platform === 'win32';
+const home = () => os.homedir();
 
 /** 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`. */
+/** Apps 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 onPath(command) {
+  const result = spawnSync(isWin ? 'where' : 'which', [command], { stdio: 'ignore', windowsHide: true });
+  return result.status === 0;
+}
+
+const exists = file => fss.existsSync(file);
+
 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');
+    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');
+    return path.join(exists(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');
+  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');
+}
+
+function claudeDesktopInstalled() {
+  if (exists(path.dirname(claudeDesktopConfig()))) return true;
+  if (isWin) return exists(path.join(process.env.LOCALAPPDATA ?? path.join(home(), 'AppData/Local'), 'AnthropicClaude'));
+  if (process.platform === 'darwin') return exists('/Applications/Claude.app');
+  return false;
 }
 
+const codexHome = () => process.env.CODEX_HOME || path.join(home(), '.codex');
+
 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') }
+  { id: 'claude-desktop', label: 'Claude 앱', found: claudeDesktopInstalled, register: () => registerJson(claudeDesktopConfig()) },
+  { id: 'claude-code', label: 'Claude Code', found: () => onPath('claude'), register: registerClaudeCode },
+  { id: 'codex', label: 'Codex (ChatGPT 데스크톱·CLI·IDE)', found: () => exists(codexHome()) || onPath('codex'), register: registerCodex },
+  { id: 'cursor', label: 'Cursor', found: () => exists(path.join(home(), '.cursor')), register: () => registerJson(path.join(home(), '.cursor/mcp.json')) },
+  { id: 'gemini', label: 'Gemini CLI', found: () => exists(path.join(home(), '.gemini')), register: () => registerJson(path.join(home(), '.gemini/settings.json')) },
+  { id: 'windsurf', label: 'Windsurf', found: () => exists(path.join(home(), '.codeium/windsurf')), register: () => registerJson(path.join(home(), '.codeium/windsurf/mcp_config.json')) }
 ];
 
+async function backup(file) {
+  if (exists(file)) await fs.copyFile(file, `${file}.bak-${Date.now()}`);
+}
+
 async function registerJson(file) {
   let config = {};
-  if (fss.existsSync(file)) {
+  if (exists(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()}`);
+  await backup(file);
   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
+/** Codex keeps MCP servers in config.toml, shared by the Codex app, CLI and IDE extension. */
+export function codexBlock() {
   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)`;
+  return [
+    `[mcp_servers.${NAME}]`,
+    `command = ${JSON.stringify(entry.command)}`,
+    `args = [${entry.args.map(a => JSON.stringify(a)).join(', ')}]`,
+    'startup_timeout_sec = 180   # first start downloads the engines',
+    'tool_timeout_sec = 1800     # OCR model download, long conversions',
+    ''
+  ].join('\n');
 }
 
-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(); }
+/** Replace an existing [mcp_servers.hwpx-bridge] table (and its sub-tables) or append one. */
+export function mergeCodexToml(text) {
+  const header = /^\s*\[\s*mcp_servers\s*\.\s*(?:"hwpx-bridge"|hwpx-bridge)\s*(?:\.[^\]]*)?\]\s*(#.*)?$/;
+  const lines = text.replace(/^/, '').split(/\r?\n/);
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (/^\s*\[/.test(line)) skipping = header.test(line);
+    if (!skipping) kept.push(line);
+  }
+  const body = kept.join('\n').replace(/\s+$/, '');
+  return (body ? `${body}\n\n` : '') + codexBlock();
+}
+
+async function registerCodex() {
+  const file = path.join(codexHome(), 'config.toml');
+  const before = exists(file) ? await fs.readFile(file, 'utf8') : '';
+  const after = mergeCodexToml(before);
+  if (before.replace(/\r\n/g, '\n') === after) return `이미 등록됨 (${file})`;
+  await backup(file);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, after, 'utf8');
+  return `등록 완료 (${file})`;
+}
+
+async function registerClaudeCode() {
+  const options = { windowsHide: true, timeout: 60_000, shell: isWin }; // claude is a .cmd shim on Windows
+  const entry = serverEntry();
+  // Replace an earlier registration (e.g. an older pinned version).
+  await run('claude', ['mcp', 'remove', '--scope', 'user', NAME], options).catch(() => {});
+  await run('claude', ['mcp', 'add', '--scope', 'user', NAME, '--', entry.command, ...entry.args], options);
+  return '등록 완료 (claude mcp add --scope user)';
 }
 
 export async function runSetup(argv) {
@@ -95,25 +141,33 @@ export async function runSetup(argv) {
     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(',')} 중에서 지정하세요.`);
-
+  } else {
+    clients = CLIENTS.filter(client => client.found());
+    const missing = CLIENTS.filter(client => !clients.includes(client)).map(client => client.label);
+    console.log(`\nhwpx-bridge ${pkg.version}: 이 PC에서 찾은 AI 앱 모두에 등록합니다.`);
+    if (missing.length) console.log(`  (설치되지 않아 건너뜀: ${missing.join(', ')})`);
+    if (!clients.length) {
+      console.log('\n등록할 AI 앱을 찾지 못했습니다. 앱을 설치한 뒤 다시 실행하거나, 아래 설정을 앱에 직접 넣으세요.\n');
+      printConfig();
+      process.exitCode = 1;
+      return;
+    }
+  }
+  console.log('');
   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}`);
+      console.log(`  + ${client.label}: ${await client.register()}`);
     } catch (error) {
       failed = true;
-      const hint = error.code === 'ENOENT' ? `${client.cli} 명령을 찾을 수 없습니다.` : error.message;
-      console.log(`  x ${client.label}: ${hint}`);
+      console.log(`  x ${client.label}: ${error.code === 'ENOENT' ? '명령을 찾을 수 없습니다.' : error.message.split('\n')[0]}`);
     }
   }
-  console.log(`\n앱을 다시 시작하면 'hwpx-bridge' 도구가 나타납니다 (kordoc 도구 + filee_convert).`);
-  console.log(`직접 설정하려면: npx -y ${packageSpec()} config`);
+  console.log('\n등록한 앱을 완전히 종료했다가 다시 열면 hwpx-bridge 도구(kordoc 전체 + filee_convert)가 모든 대화에서 보입니다.');
   if (failed) process.exitCode = 1;
 }
 
 export function printConfig() {
   console.log(JSON.stringify({ mcpServers: { [NAME]: serverEntry() } }, null, 2));
+  console.log(`\nCodex (~/.codex/config.toml):\n\n${codexBlock()}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hwpx-bridge",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "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" },
@@ -11,8 +11,8 @@
     "kordoc": "4.24.62"
   },
   "optionalDependencies": {
-    "hwpx-bridge-filee-win32-x64": "0.3.1",
-    "hwpx-bridge-filee-linux-x64": "0.3.1"
+    "hwpx-bridge-filee-win32-x64": "0.3.4",
+    "hwpx-bridge-filee-linux-x64": "0.3.4"
   },
   "keywords": ["hwp", "hwpx", "docx", "mcp", "kordoc", "filee", "korean", "ocr", "claude", "codex"],
   "license": "MIT",