Skip to content

사용법.md

Latest commit

 

History

History
242 lines (166 loc) · 6.69 KB

사용법.md

File metadata and controls

242 lines (166 loc) · 6.69 KB
Raw

VS Code에서 kordoc 도구 사용하기

이 문서는 .gitignore가 적용된 저장소를 새로 복제한 사람이 VS Code에서 kordoc MCP 도구를 사용하기 위해 밟아야 할 절차입니다.

.gitignore 때문에 node_modules/, dist/, .vscode/, .tools/, input/, output/은 저장소에 포함되지 않습니다. 따라서 복제 후 의존성 설치, 빌드, VS Code MCP 설정을 직접 한 번 해줘야 합니다.

1. 준비물

  • Git
  • VS Code
  • Node.js 18 이상 (일반적으로 시스템에 설치된 Node.js 사용)
  • PDF 파싱까지 테스트하려면 pdfjs-dist가 설치되어 있어야 합니다. 이 저장소에서는 npm install을 하면 개발 의존성으로 함께 설치됩니다.
  • Windows에서 DRM 배포용 HWPX 추출까지 쓰려면 한컴 오피스가 설치되어 있어야 합니다.

Node.js가 설치되어 있는지 확인:

node -v
npm -v

2. 저장소 복제

git clone <저장소 URL>
cd kordoc
code .

3. 의존성 설치

복제한 저장소에는 node_modules/가 없으므로 먼저 설치합니다.

npm ci

package.json을 직접 수정해 새 패키지를 추가/업데이트하는 경우에만 npm install을 사용합니다.

4. 빌드

복제한 저장소에는 dist/가 없으므로 MCP 서버와 CLI를 실행하기 전에 빌드해야 합니다.

npm run build

빌드가 끝나면 dist/cli.js, dist/mcp.js 등이 생성됩니다.

간단히 확인:

node .\dist\cli.js --help

5. 입력/출력 폴더 만들기

input/과 output/은 개인 문서와 결과물을 넣는 폴더라서 Git에 올라가지 않습니다.

mkdir input
mkdir output

예를 들어 문서를 변환하려면:

node .\dist\cli.js .\input\보고서.hwpx -o .\output\보고서.md

6. VS Code MCP 설정

VS Code 설정 파일인 .vscode/mcp.json도 Git에 포함되지 않으므로 직접 생성해야 합니다.

방법 A: npm에 배포된 kordoc 사용

로컬 저장소의 소스 코드가 아니라 npm에 배포된 최신 kordoc을 VS Code 도구로 쓰려면 이 방법이 가장 간단합니다.

npx -y kordoc setup

대화형 메뉴에서 VS Code (현재 디렉토리)를 선택합니다. 완료 후 VS Code 창을 다시 로드하거나 재시작합니다.

방법 B: 지금 복제한 로컬 저장소의 빌드 결과 사용

이 저장소의 현재 코드, 또는 직접 수정한 코드를 VS Code 도구로 쓰려면 이 방법을 사용합니다.

.vscode/mcp.json 파일을 만들고 아래 내용을 저장합니다.

Windows:

{
  "servers": {
    "kordoc": {
      "command": "node",
      "args": ["${workspaceFolder}\\dist\\mcp.js"]
    }
  }
}

macOS / Linux:

{
  "servers": {
    "kordoc": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/mcp.js"]
    }
  }
}

설정 후 VS Code 창을 다시 로드하거나 재시작합니다.

코드를 수정했다면 MCP 서버에 반영하기 전에 다시 빌드합니다.

npm run build

개발 중 자동 빌드가 필요하면:

npm run dev

7. VS Code에서 도구 확인

VS Code를 다시 연 뒤 MCP 서버 목록에서 kordoc가 보이는지 확인합니다.

사용 가능한 주요 도구:

도구 용도
parse_document HWP/HWPX/PDF/XLSX/DOCX를 Markdown으로 변환
detect_format 문서 포맷 감지
parse_metadata 메타데이터만 추출
parse_pages 특정 페이지 범위만 파싱
parse_table 특정 표 추출
compare_documents 두 문서 비교
parse_form 양식 필드 추출
fill_form HWPX 양식에 값 채우기

예시 요청:

input/보고서.hwpx 파일을 parse_document 도구로 읽고 핵심 내용을 요약해줘.

input/구버전.hwpx와 input/신버전.hwpx를 compare_documents 도구로 비교해서 변경사항을 표로 정리해줘.

input/신청서.hwpx의 양식 필드를 parse_form 도구로 추출해줘.

참고: MCP 도구 사용 시에는 상대 경로보다 절대 경로를 쓰면 작업 디렉토리 차이로 인한 경로 오류를 줄일 수 있습니다.

8. 자주 나는 문제

Cannot find module ...\dist\mcp.js

아직 빌드하지 않았거나 dist/가 삭제된 상태입니다.

npm run build

node 명령을 찾을 수 없음

Node.js가 설치되어 있지 않거나 VS Code 터미널이 PATH를 새로 읽지 못한 상태입니다. Node.js 18 이상을 설치한 뒤 VS Code를 완전히 다시 엽니다. 포터블 Node.js를 쓰는 경우는 아래 10. 고급: 포터블 Node.js 사용 (선택)을 참고하세요.

VS Code에서 kordoc 도구가 보이지 않음

다음을 확인합니다.

  • .vscode/mcp.json 파일이 현재 저장소 루트 아래에 있는지
  • npm run build를 실행해서 dist/mcp.js가 존재하는지
  • VS Code 창을 다시 로드했는지
  • node .\dist\cli.js --help가 정상 실행되는지

PDF 파싱에서 pdfjs-dist 관련 오류가 남

의존성이 빠진 상태일 수 있습니다.

npm ci

필요하면 직접 설치합니다.

npm install pdfjs-dist

.tools/가 없음

정상입니다. .tools/는 개인 로컬 도구나 포터블 Node.js를 넣는 용도라 Git에 포함하지 않습니다. 일반적으로는 시스템에 설치된 Node.js를 사용하면 됩니다.

9. Git에 올리지 않는 파일

아래 파일과 폴더는 복제한 사람이 각자 로컬에서 다시 만들거나 생성하는 대상입니다.

경로 이유
node_modules/ npm ci로 복원
dist/ npm run build로 생성
.vscode/ 사용자별 VS Code 설정
.tools/ 사용자별 로컬 도구
input/ 개인 입력 문서
output/ 변환 결과물
tests/fixtures/sample.* 실제 개인 문서 fixture

10. 고급: 포터블 Node.js 사용 (선택)

기본 경로(시스템 Node.js 설치) 대신 포터블 Node.js를 쓰고 싶다면 아래처럼 터미널 PATH에 직접 추가할 수 있습니다.

$nodeDir = (Resolve-Path '.tools\node\node-*-win-x64').Path
$env:Path = "$nodeDir;$env:Path"
node -v
npm -v
npx -v

VS Code 터미널을 새로 열 때마다 자동으로 적용하려면 .vscode/settings.json에 다음을 설정합니다.

{
  "terminal.integrated.env.windows": {
    "PATH": "${workspaceFolder}\\.tools\\node\\node-v24.15.0-win-x64;${env:PATH}"
  }
}

포터블 Node.js를 쓰는 경우 MCP 설정에서도 command에 node 대신 포터블 node.exe 절대 경로를 넣으면 안정적입니다.