convez.ai
MCP ServerAutomaçãoIntermediário
airmang

HWPX MCP Server

airmang/hwpx-mcp-server

Automação de documentos HWPX via MCP para agentes de IA

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que permite agentes de IA ler, editar, inspecionar e validar documentos HWPX locais sem dependências de processadores de texto coreanos. Implementa suporte completo ao padrão Model Context Protocol para integração com Claude Desktop, VS Code e outras plataformas compatíveis.

Instalação

$npx convez-ai airmang/hwpx-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
69
Forks
21
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v7.5.0
Issues abertas
16
Contribuidores
2

Casos de uso

  • Automação de leitura e edição de documentos HWPX em pipelines CI/CD
  • Integração com Claude Desktop para processamento de documentos em coreano
  • Validação e inspeção de estrutura de documentos HWPX sem aplicações proprietárias
  • Processamento em batch de documentos Word coreanos em servidores Linux/macOS

Veredito

Ferramenta especializada e bem-implementada para automação de documentos HWPX via MCP. Preenche lacuna real em ambientes que precisam processar documentos coreanos sem ferramentas proprietárias, com excelente integração ao ecossistema Claude e arquitetura stateless apropriada.

README

A tradução para o português deste README ainda está na fila.


🧩 HWPX Stack (3종)

계층레포역할
📦 라이브러리python-hwpx순수 파이썬 HWPX 파싱·편집·생성 코어
🔌 MCP 서버hwpx-mcp-serverMCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작
🎯 에이전트 스킬hwpx-skill에이전트가 HWPX를 바로 쓰게 해주는 공식 온보딩 스킬

hwpx-mcp-server는 모델 컨텍스트 프로토콜(MCP) 표준을 따르는 서버로, python-hwpx 기반에서 HWPX 문서의 열람 · 검색 · 편집 · 추출을 AI 클라이언트에서 직접 수행할 수 있게 합니다.

참고 이 서버는 Open XML 기반 .hwpx 포맷을 지원합니다. 바이너리 .hwp 포맷은 직접 편집 대상이 아닙니다.

이 서버가 바로 해결하는 일

  • Claude Desktop, VS Code, Gemini CLI 같은 MCP 클라이언트에서 HWPX를 바로 읽기
  • 복사본을 만든 뒤 안전하게 검색·치환·표 편집·문단 추가 수행
  • 문서 개요, 표 맵, 패키지 구조를 AI가 직접 조회하고 후속 작업으로 연결
  • 한글 워드프로세서 없이 서버·CI·로컬 개발 환경에서 같은 흐름 유지
  • 고급 모드에서 검증, package inspection, edit planning까지 확장

Claude Desktop 5분 연결

아래 설정 하나만 넣으면 Claude Desktop에서 hwpx MCP 서버를 바로 잡는다.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

Screenshot placeholder: Claude Desktop 설정 화면에서 hwpx 서버가 활성화된 장면을 여기에 넣을 예정.

왜 필요한가?

국내 공공기관·학교·기업에서는 한글 문서 기반 업무가 많지만, 자동화는 오랫동안 운영체제와 프로그램에 크게 의존했습니다.

hwpx-mcp-server는 이 제약을 줄이는 데 초점을 둡니다.

  • ✅ 운영체제 무관 — Windows, macOS, Linux에서 동작
  • ✅ 한글 워드프로세서 불필요 — 순수 파이썬 기반 처리
  • ✅ AI 연동 중심 — Claude Desktop, VS Code, Gemini CLI 등 MCP 클라이언트와 직접 연결
  • ✅ 문서 편집을 도구 호출로 표준화 — 읽기, 편집, 복제, 검증을 MCP 도구 집합으로 노출
  • ✅ 실전 작업 흐름에 맞춘 설계 — read, copy, edit, inspect, validate를 한 서버 표면으로 정리
  • ✅ 일관된 호출 방식 — 도구 호출마다 filename을 명시하는 stateless 구조

사용 사례

빠른 시작

1. 설치 및 실행

uv 기준:

uvx hwpx-mcp-server

또는 pip 설치 후 실행:

pip install hwpx-mcp-server
hwpx-mcp-server

요구 사항:

  • Python >= 3.10
  • python-hwpx >= 2.11.1

현재 저장소 기준 검증 버전은 python-hwpx 2.11.1입니다 (2026-06-12 검증). 최소 지원 버전은 python-hwpx >= 2.11.1입니다.

2. MCP 클라이언트 설정

HWPX plugin companion launcher

The hwpx-plugins repository builds per-host bundles whose MCP launcher (plugins/<host>/hwpx-plugin/scripts/hwpx-mcp-server) can run this server. In local development, set HWPX_MCP_SERVER_REPO=/absolute/path/to/hwpx-mcp-server and PYTHON_HWPX_REPO=/absolute/path/to/python-hwpx when the repositories are not under a common parent. The launcher otherwise discovers them by walking up from the bundle directory and uses uv run --project "$HWPX_MCP_SERVER_REPO" --with-editable "$PYTHON_HWPX_REPO" --with-editable "$HWPX_MCP_SERVER_REPO" hwpx-mcp-server.

claude_desktop_config.json

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

~/.gemini/settings.json

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

각 에디터의 MCP 설정 파일에 같은 블록을 추가하면 됩니다.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

작업별 빠른 경로

처음부터 모든 도구를 외울 필요는 없다. 보통은 아래 네 흐름 중 하나로 시작하면 된다.

1. 읽기 전용으로 문서를 파악할 때

  1. get_document_info
  2. get_document_outline 또는 get_document_text
  3. find_text, get_table_text, get_table_map 같은 읽기 도구로 필요한 부분만 더 본다.

이 흐름은 원본을 저장하지 않는다.

2. 안전하게 수정할 때

  1. copy_document로 작업용 사본을 만든다.
  2. 읽기 도구로 수정 대상을 다시 확인한다.
  3. search_and_replace, batch_replace, set_table_cell_text, add_paragraph 같은 가장 작은 변경 도구만 쓴다.
  4. 수정 후 다시 읽기 도구로 결과를 확인한다.
  5. 납품이나 handoff가 필요하면 검토가 끝난 복사본 파일을 그대로 넘긴다.

핵심은 copy first, smallest edit, re-read after edits다.

3. 구조 점검과 검증이 목적일 때

  1. MCP 설정에서 HWPX_MCP_ADVANCED=1
  2. package_parts, package_get_xml, package_get_text로 내부 파트를 본다.
  3. validate_structure, lint_text_conventions, plan_edit, preview_edit는 기본 편집 흐름과 섞지 않고 점검/검증 단계에서만 사용한다.

4. 한컴에서 열리지 않는 HWPX를 복구할 때

  1. 원본을 직접 덮어쓰지 않고 repair_hwpx(source_filename, output_filename)로 복구 복사본을 만든다.
  2. 일반 ZIP open이 실패하거나 central directory 손상이 의심되면 recover=true를 지정한다.
  3. 반환값의 crcOk, validatePackage.ok, reordered, recovered를 확인한다.
  4. 최종 handoff 전에는 가능하면 Hancom Office HWP 또는 viewer로 실제 열람한다.

안전한 사용 원칙

이 서버의 공개 표면은 현재 README에 적힌 MCP 도구 집합이다. 워크플로 문서나 스킬 예시는 이 도구들을 조합하는 사용 패턴이지, 별도의 새 public tool 계약이 아니다.

실전에서는 아래 순서가 가장 안전하다.

  1. 먼저 get_document_info, get_document_text, find_text 같은 읽기 도구로 문서를 파악한다.
  2. 수정 전 결과물을 보존해야 하면 copy_document를 먼저 호출한다.
  3. 수정 도구는 호출 즉시 저장되므로, 검토용 경로가 필요하면 원본 대신 복사본에서 작업한다.
  4. 결과물을 따로 넘겨야 하면 검토가 끝난 복사본 파일을 handoff 경계로 사용한다.
  5. package inspection, edit planning, validation은 HWPX_MCP_ADVANCED=1일 때만 쓰고, 기본 흐름과 섞어 쓰지 않는다.

짧게 말하면:

  • read first
  • copy before risky edits
  • mutating tools persist immediately
  • explicit handoff uses the reviewed copy
  • advanced mode는 점검/검증용으로 분리

도구 동작 빠른 감각

구분대표 도구특징
파일 기반 읽기 전용get_document_info, get_document_text, get_paragraph_text, get_location_text, get_paragraphs_text, find_text, get_table_text, get_table_map, find_cell_by_label, list_styles, list_available_documents기존 .hwpx 파일을 읽거나 탐색만 한다. 저장하지 않는다.
파일 기반 즉시 저장 생성/편집create_document, create_document_from_plan, create_proposal_document, search_and_replace, batch_replace, replace_in_paragraph, replace_by_anchor, add_heading, add_paragraph, insert_paragraph, delete_paragraph, add_table, fill_by_path, set_table_cell_text, add_page_break, add_memo, add_memo_by_anchor, remove_memo, format_text, create_custom_style, merge_table_cells, split_table_cell, format_table호출 결과가 곧 대상 파일 변경이다. 검토용이면 먼저 복사본에서 작업한다.
선언형 생성 검증validate_document_plan, analyze_document_plan, inspect_document_authoring_quality, inspect_operating_plan_quality, inspect_document_quality, analyze_template_formfitagent가 만든 hwpx.document_plan.v1, P6 baseline, 또는 생성 결과를 검증한다. validate_document_plan, analyze_document_plan, analyze_template_formfit은 파일을 쓰지 않는다.
repair/recoverrepair_hwpx원본을 보존하고 새 output에 mimetype-first repair-repack 또는 Local File Header scan 복구를 수행한다.
복제 / handoff 경계copy_document원본 보호와 reviewable working copy 분리에 쓴다. 현재 FastMCP surface에는 별도 public save / save_as tool이 없다.
payload/url 기반 추출hwpx_to_markdown, hwpx_to_html, hwpx_extract_json파일명을 직접 수정하지 않는다. HWPX payload 또는 URL을 읽어 변환 결과만 돌려준다.
고급 점검/검증package_parts, package_get_xml, package_get_text, object_find_by_tag, object_find_by_attr, plan_edit, preview_edit, apply_edit, validate_structure, lint_text_conventionsHWPX_MCP_ADVANCED=1일 때만 활성화한다. package/구조 점검용이다.

주요 기능

기본 모드에서 85개 HWPX 도구를 제공하며, 고급 모드(HWPX_MCP_ADVANCED=1)에서는 점검·검증용 도구까지 총 95개가 활성화됩니다.

위치 계약

paragraph_index는 문서 본문 직속 문단의 0-based 인덱스다. 표 안 문단은 이 인덱스에 섞지 않고 location 객체로 지정한다. 표 셀 문단 location은 {"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0} 형태이며, get_table_map과 find_text가 반환한 값을 get_paragraph_text, get_location_text, add_memo, replace_in_paragraph에 그대로 넘길 수 있다.

📖 읽기 및 탐색

도구설명
get_document_info문서 메타데이터, 섹션, 문단, 표 개수 조회
get_document_text문서 전체 텍스트 추출 (max_chars 지원)
get_document_outline제목과 개요 구조 추출
get_paragraph_text본문 문단 또는 location으로 지정한 표 셀 문단 텍스트 조회
get_location_textget_table_map/find_text가 반환한 location으로 텍스트 조회
get_paragraphs_text문단 범위 조회
list_available_documents폴더 안의 .hwpx 파일 목록 조회
get_document_map아웃라인·표 지도·누름틀·앵커를 단일 호출로 반환 (왕복 최소화)

🔎 검색 및 치환

find_text는 읽기 전용이고, search_and_replace / batch_replace는 호출 즉시 저장된다.

도구설명
find_text키워드 검색과 주변 문맥, 재사용 가능한 location/anchor 반환
search_and_replace단일 텍스트 치환
replace_in_paragraph본문/표 셀 문단 하나에서 run 서식을 유지하며 부분 치환
replace_by_anchorfind_text가 반환한 anchor의 정확한 위치에서 부분 치환
batch_replace여러 치환 작업 일괄 실행

✏️ 문서 편집

이 카테고리의 도구는 대체로 대상 파일에 즉시 반영된다. 구조 변경 전에는 copy_document로 작업용 사본을 만들고, handoff는 검토가 끝난 복사본 파일 기준으로 잡는 편이 안전하다.

도구설명
add_heading제목(헤딩) 문단 추가 — 템플릿 내장 개요 N 스타일 적용(한컴 개요 번호 자동), 텍스트에 # 미저장
add_paragraph / insert_paragraph / delete_paragraph문단 추가, 삽입, 삭제
add_page_break페이지 나누기 추가
add_memo / add_memo_by_anchor / remove_memo본문 문단 또는 표 셀 문단에 메모 추가, 검색 anchor 기반 메모 추가, 제거

🔄 트랜잭션 편집과 안전망

쓰기 응답은 기본 verbosity="compact"로 openSafety 요약·시맨틱 diff·document_revision을 포함하고, 실패 시에만 상세 증거를 펼친다.

도구설명
apply_edits연산 목록 원자 적용 — 중간 실패 시 전체 롤백, dry_run 미리보기, expected_revision 동시성 가드, idempotency_key 재시도 안전
undo_last_edit자동 .bak 로테이션 기반 직전 편집 복원
byte_preserving_patchsection XML 바이트 splice 문단 패치 — 미수정 영역 바이트 보존

동시성: 읽기 도구는 document_revision(콘텐츠 해시)을 반환하고, 쓰기 도구는 expected_revision 불일치 시 거부한다. 한컴오피스가 파일을 열어둔 정황(잠금)도 경고로 알려준다.

🖥️ 렌더 프리뷰 (에이전트의 눈)

도구설명
render_preview페이지 박스·표·여백을 근사한 HTML/페이지별 PNG 생성 — 편집 결과 시각 자기검증용

📐 페이지·문단 서식 편집 (기존 문서)

입력은 전부 인간 단위(pt/mm/%)다.

도구설명
set_paragraph_format정렬·줄간격(%)·들여쓰기·문단 앞뒤 간격
set_page_setup용지·여백·방향
set_header_footer머리말/꼬리말 설정
set_page_number쪽번호 설정
set_list_format불릿·번호 목록 형식 변경

🖼️ 그림

도구설명
insert_picture이미지 삽입 (manifest 자동 등록·검증)
replace_picture기존 그림 자산 안전 치환

🖊️ 누름틀 양식

도구설명
list_form_fields문서 내 누름틀(클릭히어 필드) 목록 — 이름·안내문·현재값
fill_form_field서식 보존 누름틀 채움

analyze_form_fill은 항목별 매칭 신뢰도 등급(label-exact/label-fuzzy/position-guess)을 반환한다.

🏛️ 공문서·정합 lint

도구설명
inspect_official_document_style행정업무 규정 기반 lint — 항목기호 위계, "끝." 표시, 붙임 표기, 날짜 표기 + 수정 제안
inspect_reference_consistency붙임·표/그림 번호 등 문서 내 참조 정합 검사

🆚 문서 비교 (신구대조)

도구설명
doc_diff두 문서 문단 LCS diff — equal/added/removed/changed 분류
create_comparison_table_document신구대조표(좌 구/우 신) 문서 생성

📨 대량 생산·표 계산

도구설명
mail_merge템플릿 + CSV/JSON 데이터 → N부 일괄 생성, 파일명 패턴·zip 출력
inspect_mail_merge_placeholders템플릿 placeholder·데이터 결측 사전 점검
table_compute표 합계·평균·소계 행/열 계산

🪄 서식 이식·템플릿 레지스트리

도구설명
extract_style_profile참조 문서에서 스타일·페이지 설정·표 프로파일 추출
apply_style_profile_to_plan추출한 프로파일을 document plan에 적용
compare_style_profiles두 프로파일 비교
register_template / list_templates / describe_template사용자 서식 등록·조회

📷 고급 생성기

도구설명
build_image_grid사진대지(현장 사진 격자 표) 블록 생성
build_meeting_nameplates회의 명패 표 생성
build_organization_chart표 기반 조직도 생성

🧾 선언형 문서 생성

hwpx.document_plan.v1은 agent가 OWPML을 직접 만지지 않고 제목, 문단, bullet, 표, 품질 게이트를 선언하는 생성 계약이다.

도구설명
validate_document_planplan을 검증하고 정규화 결과를 반환한다. 파일은 생성하지 않는다.
analyze_document_plan파일을 쓰지 않고 생성 가능 여부, 정규화 plan, 선택한 품질 프로필의 preview를 반환한다.
create_document_from_planplan을 HWPX로 생성하고 즉시 저장한 뒤 reopen/package/schema 검증과 품질 프로필 결과를 반환한다.
inspect_document_authoring_quality생성된 HWPX의 document-plan 품질 근거를 다시 조회한다. quality_profile="operating_plan"을 지정할 수 있다.
inspect_operating_plan_quality운영 계획서 제출 후보의 섹션, 일정표, 사업비 근거, 기대 효과, 마감 문구, placeholder 잔여물을 직접 검사한다.
analyze_template_formfitP6 기준선 기반 양식 보존 생성 계획을 비파괴 분석한다.
apply_template_formfit분석된 계획을 원본과 다른 destination 복사본에만 적용하고 검증한다.
create_proposal_document / inspect_document_quality제안서/기획안 특화 호환 경로

visual_review_required=true는 구조/파일 기반 검증은 통과했지만 렌더링된 시각 레이아웃은 아직 증명되지 않았다는 뜻이다. 운영 계획서와 template-formfit 결과를 최종 제출 가능(submission-ready) 상태로 주장하려면 ../hwpx-skill/scripts/visual_review.py 또는 ComputerUse로 열린 문서를 검토해 hwpx.visual-review.v1 증거를 남기고 current.status="observed_pass"여야 한다. HWPX viewer가 없는 환경에서는 fallback 증거를 current.status="blocked"로 기록하고 잔여 위험을 유지한다.

validate_document_plan 결과가 ok=false이면 issues[].code, issues[].path, repairHints[]를 보고 plan을 수정한 뒤 다시 검증한다. 이때 can_create=false이므로 create_document_from_plan을 호출하지 않는다. table 오류는 columns[].key와 rows[] key를 맞추고, style warning은 지원 token으로 바꾸거나 생략한다. 생성 후 package/schema 오류가 있으면 quality.validation.*.issues[]와 quality.recovery.repair_hints[]를 확인해 재저장 또는 재생성한다.

운영 계획서 작성은 다음 순서를 권장한다.

  1. validate_document_plan(document_plan)으로 schema와 block/table 오류를 먼저 고친다.
  2. analyze_document_plan(document_plan, quality_profile="operating_plan")으로 파일 생성 없이 품질 preview를 확인한다.
  3. handoff_status="ready"이면 create_document_from_plan(filename, document_plan, quality_profile="operating_plan")으로 명시한 경로에만 생성한다.
  4. handoff_status="needs_revision"이면 quality.gaps[]와 quality.profiles.operating_plan.repair_hints[]를 반영해 plan을 보강한다.
  5. 생성 후 get_document_text, get_table_text로 결과를 다시 읽는다.
  6. visual_review_required=true이면 visual_review.py 또는 열린 문서 검토로 hwpx.visual-review.v1 증거를 생성한다. current.status="observed_pass"가 아니면 handoff_status="ready"를 최종 제출 가능(submission-ready)으로 설명하지 않는다.

승인된 HWPX 양식을 보존해야 하는 경우에는 create_document_from_plan으로 새 문서를 만들지 말고 P6 baseline 기반 form-fit 경로를 사용한다.

  1. analyze_template_formfit(source_filename, baseline, content, destination_filename)으로 원본이 변경되지 않는지와 required anchor 해소 여부를 확인한다.
  2. unresolved_count > 0이면 unresolved[].reason에 따라 content 또는 baseline locator를 보강한다.
  3. apply_template_formfit(analysis=..., confirm=true)로 원본과 다른 destination에만 적용한다.
  4. source.preserved, validation.validate_package.ok, validation.validate_document.ok, residual_markers.blocking == []를 확인한다.
  5. visual_review_required=true이면 visual_review.py 또는 열린 문서 검토로 hwpx.visual-review.v1 증거를 생성한다. current.status="observed_pass"가 아니면 handoff_status="ready"를 최종 제출 가능(submission-ready)으로 설명하지 않는다.

🧯 패키지 복구

repair_hwpx는 원본을 직접 수정하지 않고 새 output 경로에 복구 복사본을 만든다.

도구설명
repair_hwpxrecover=false이면 mimetype 첫 엔트리/ZIP_STORED 재패킹과 CRC self-check를 수행한다. recover=true이면 central directory 손상 ZIP을 Local File Header scan으로 복구한 뒤 재패킹한다.

확인할 응답 필드는 crcOk, validatePackage.ok, reordered, recovered, entryCount다. 기계 검증 후에도 제출·납품 전에는 가능하면 Hancom Office HWP 또는 viewer에서 실제 열람한다.

💾 복제

이 카테고리는 수정 워크플로의 안전 장치다. 원본 보호와 reviewable working copy 분리에 쓴다.

도구설명
copy_document원본을 건드리기 전에 작업용 사본 생성

📊 표 편집

get_table_text, get_table_map, find_cell_by_label는 읽기 전용이다. fill_by_path, set_table_cell_text, merge_table_cells, split_table_cell, format_table은 호출 즉시 저장된다.

도구설명
add_table / get_table_text표 생성, 조회
get_table_map표가 많은 문서에서 표 위치, 크기, caption/직전 문단 문맥, 셀 문단 location을 빠르게 탐색
find_cell_by_label한국어 양식/템플릿에서 라벨 셀 기준으로 입력 대상 셀 찾기
fill_by_path성명 > right, 소속 > right, 합계 > down > right 같은 경로 구문으로 셀 채우기
set_table_cell_text셀 텍스트 수정. 기본값은 기존 charPr 서식 보존이며, split_paragraphs=true로 멀티라인을 여러 hp:p로 분리
merge_table_cells / split_table_cell셀 병합, 분할
format_table표 헤더 등 기본 서식 적용

변경 도구는 호출 시 즉시 저장됩니다. 검토용 사본이 필요하면 copy_document를 먼저 사용하고, 납품본은 검토가 끝난 복사본 파일을 기준으로 관리하세요.

🎨 서식 및 스타일

list_styles는 읽기 전용이다. format_text, create_custom_style은 문서를 직접 갱신한다.

도구설명
format_text텍스트 범위 서식 적용
create_custom_style커스텀 스타일 생성
list_styles문서 스타일 목록 조회

스타일 참조 팁: add_paragraph(..., style=...)와 insert_paragraph(..., style=...)는 list_styles의 id, create_custom_style이 반환하는 style_id, 스타일 이름을 모두 받을 수 있습니다.

📤 추출

이 카테고리는 filename 기반 편집 도구가 아니다. HWPX payload 또는 URL을 읽어 변환 결과를 반환한다.

도구설명
hwpx_to_markdownHWPX 문서를 Markdown으로 변환
hwpx_to_htmlHWPX 문서를 HTML로 변환
hwpx_extract_jsonHWPX 문서를 구조화된 JSON으로 추출

🔬 고급 도구

HWPX_MCP_ADVANCED=1일 때 활성화:

도구설명
package_partsOPC 파트 목록 조회
package_get_xml / package_get_text파트 XML 또는 텍스트 조회
object_find_by_tag / object_find_by_attrXML 요소 검색
plan_edit / preview_edit / apply_edit편집 계획, 미리보기, 적용
validate_structure / lint_text_conventions구조 검증, 텍스트 규칙 점검

🩺 서버 진단

도구설명
mcp_server_health서버·python-hwpx·스킬 번들 버전과 도구 수(배포 스큐 자기진단), transport, timeout, sandbox 경로 안내, disconnect 가능 조건과 keepalive 점검 정보를 반환

환경 변수

변수설명기본값
HWPX_MCP_MAX_CHARS텍스트 반환 도구 기본 최대 길이10000
HWPX_MCP_AUTOBACKUP1이면 저장 전 .bak 백업 생성1
HWPX_MCP_ADVANCED1이면 고급 도구 활성화0
HWPX_MCP_SANDBOX_ROOT설정 시 이 root 내부 상대경로 또는 내부 절대경로만 허용unset
HWPX_MCP_FETCH_TIMEOUT_SECONDSURL 기반 HWPX fetch timeout20.0
LOG_LEVEL로그 레벨INFO

환경 변수 포함 MCP 설정 예시:

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"],
      "env": {
        "HWPX_MCP_MAX_CHARS": "12000",
        "HWPX_MCP_AUTOBACKUP": "1",
        "HWPX_MCP_ADVANCED": "0",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

테스트

# 테스트 의존성 설치
python -m pip install -e ".[test]"

# 전체 테스트
python -m pytest -q

추가 참고:

  • 사용 사례: docs/use-cases.md
  • 종합 리포트: tests/hwpx_mcp_report_updated.md
  • 스킬 기반 워크플로: docs/skill-first-workflows.md

License

Apache License 2.0. See LICENSE and NOTICE.

작성자

고규현 — 광교고등학교 정보·컴퓨터 교사

Ver o original no GitHub

Bom para

Relacionados