hwpConverMdMCP Server

hwpConverMdMCP

HWP/HWPX 파일을 Markdown으로 변환하는 hwpConverMd API의 MCP(Model Context Protocol) 서버입니다.

Claude Desktop, Cursor, Claude Code, Flowise 등 MCP 클라이언트에서 HWP 문서 변환 기능을 사용할 수 있습니다.

아키텍처

MCP 클라이언트 (Claude Desktop / Cursor / Flowise CustomFunction)
        │
        │  stdio 또는 Streamable HTTP (JSON-RPC + SSE)
        ▼
  hwpConverMdMCP (Node.js MCP Server)
        │
        │  HTTP (multipart/form-data)
        ▼
  hwpConverMd (Python FastAPI Server)
        │
        ├── HwpFastConverter (XML 직접 파싱, 고속)
        ├── HwpConverter (hwp5html 폴백)
        │
        ├── POST /api/v1/convert        → JSON (markdown + download_url)
        ├── POST /api/v1/convert/base64  → JSON (Base64 입력, Flowise용)
        ├── POST /api/v1/upload-md       → JSON (임의 MD 저장 → download_url 발급)
        └── GET  /api/v1/download/{file} → 파일 다운로드

전제조건

• Node.js >= 18.0.0
• hwpConverMd Python 서버가 실행 중이어야 합니다

hwpConverMd 서버 실행

# Docker로 실행 (권장)
cd ../hwpConverMd
docker compose up --build

# 또는 직접 실행
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

서버가 정상 동작하면 http://localhost:8000/ 에서 {"status": "ok"} 응답을 확인할 수 있습니다.

설치

npm install
npm run build

MCP Tools

convert_hwp_content_to_md 응답 형식

이 도구는 MCP content 배열로 두 가지 텍스트 블록을 반환합니다:

{
  "content": [
    { "type": "text", "text": "# 변환된 마크다운 내용..." },
    { "type": "text", "text": "[DOWNLOAD_URL]/api/v1/download/파일명.md" }
  ]
}

• 첫 번째 블록: 변환된 마크다운 전체 텍스트
• 두 번째 블록: [DOWNLOAD_URL] 접두사 + HWP API의 다운로드 경로 (없을 수도 있음)

사용법

1. Claude Desktop에서 사용 (stdio)

claude_desktop_config.json에 추가:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hwp-converter": {
      "command": "node",
      "args": ["/absolute/path/to/hwpConverMdMCP/dist/transport/stdio.js"],
      "env": {
        "HWP_API_URL": "http://localhost:8000"
      }
    }
  }
}

2. Cursor에서 사용 (stdio)

프로젝트 루트에 .cursor/mcp.json 생성:

{
  "mcpServers": {
    "hwp-converter": {
      "command": "node",
      "args": ["/absolute/path/to/hwpConverMdMCP/dist/transport/stdio.js"],
      "env": {
        "HWP_API_URL": "http://localhost:8000"
      }
    }
  }
}

3. Claude Code에서 사용 (stdio)

claude mcp add hwp-converter \
  -e HWP_API_URL=http://localhost:8000 \
  -- node /absolute/path/to/hwpConverMdMCP/dist/transport/stdio.js

4. Streamable HTTP 모드 (Flowise / 웹 클라이언트용)

# 빌드 후 실행
npm run start:http

# 또는 개발 모드
npm run dev:http

MCP 엔드포인트: http://localhost:3000/mcp

Docker Compose

루트 디렉토리의 docker-compose.yml로 전체 스택(API + MCP + Flowise)을 함께 기동합니다:

# 루트 디렉토리에서
cd ..
docker compose up -d --build

MCP 컨테이너의 HWP_API_URL=http://api:8000 (Docker 내부 네트워크)

환경변수

개발

npm install

npm run dev:stdio     # stdio 모드 개발
npm run dev:http      # HTTP 모드 개발
npm run build         # TypeScript 빌드

npm run start:stdio   # stdio 모드 실행
npm run start:http    # HTTP 모드 실행

Kubernetes 배포

매니페스트 구조

k8s_manifest/
├── common/
│   ├── namespace.yaml         # 네임스페이스
│   ├── default-deny.yaml      # 기본 NetworkPolicy deny-all
│   └── resource-quota.yaml    # 리소스 제한
└── mcp/
    ├── serviceaccount.yaml    # 전용 ServiceAccount
    ├── rbac.yaml              # 최소 권한 RBAC
    ├── configmap.yaml         # 설정
    ├── mcp-deployment.yaml    # Deployment + Service
    ├── networkpolicy.yaml     # MCP → API 통신 허용
    └── ingress.yaml           # 외부 접근

배포

# 공통 리소스
kubectl apply -f k8s_manifest/common/

# MCP 서버
kubectl apply -f k8s_manifest/mcp/

K8s 운영 시 주의사항

MCP 서버는 1대로 운영 (권장)

MCP 서버는 인메모리 세션을 사용합니다. 복수 Pod에서 운영하면 initialize 요청을 받은 Pod과 tools/call 요청을 받는 Pod이 달라져 "Server not initialized" 에러가 발생합니다.

# MCP는 1대 고정 (stateful)
kubectl scale deploy hwp-mcp --replicas=1

# HPA가 걸려있으면 제거
kubectl delete hpa hwp-mcp

MCP 서버는 프로토콜 중계만 하므로 (CPU 사용 거의 없음) 1대로 충분합니다. 실제 변환 부하는 HWP API가 담당하며 HPA로 스케일링됩니다.

복수 Pod이 필요한 경우 Ingress에 세션 어피니티를 추가하세요:

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "MCP_ROUTE"
nginx.ingress.kubernetes.io/session-cookie-max-age: "600"

Ingress 설정 (필수)

Base64 인코