AI导哈

HWP文档查询工具

一个帮助AI查询HWP/HWPX格式PDF文档的工具，支持MCP服务器和OpenClaw Skill两种方式。

  • by devcode-kr
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 devcode-kr/fxxk-hwpjs-mcp

使用说明

fxxk-hwpj-mcp

帮助您在需要AI时查看HWP/HWPX规格的PDF文档的工具。
MCP服务器 （Claude Desktop/Claude Code） 开爪技能 （CLI包装器）支持两种方式。

目录

安装

git clone https://github.com/devcode-kr/fxxk-hwpjs-mcp.git
cd fxxk-hwpjs-mcp
npm install
npm run build

PDF文件设置

specs/ 文件夹（或 HWP_SPECS_DIR 将PDF作为以下文件名放入环境变量指定的路径）：

文档ID文件名说明页面范围 |------------|--------------|---------------------------------------------|-------------| | hwp3-bin |hwp-v3.pdf | hwp 3.x 二进制 文件结构：p.1~54 | hwp3-xml |hwp-v3.pdf| HWPML -HWP3.x XML（SGML）结构| p.55~122 | hwp5 | hwp-v5.pdf | HWP5.0规格|全部| | formula 公式.pdf公式规格完整 | chart 图表规格完整 | dist | dist.pdf |分发文档规格（加密/DRM结构）|完整|

hwp3-bin 对比 hwp3-xml: hwp-v3.pdf 两个文档合并在一个文件中。
前半部分（p.1~54）为HWP3.x二进制格式，后半部分（p.55~122）为HWPML（XML）结构。
共享相同的文件，但独立于不同的docId进行索引/查询。

HWPX指南：不包括HWPX，因为它是KS X6101收费标准。
HWPX文件是ZIP结构，因此扩展名为 .zip可以更改为进行直接分析。

OpenClaw Skill（推荐）

在OpenClaw环境中，代替MCP协议 CLI包装器Skill使用。
无需浪费令牌，只需及时查看所需的规格。

Skill文件位置

~/.openclaw/workspace/skills/hwp-spec/SKILL.md

环境变量

变量 默认值 说明
HWP_SPECS_DIR ./specs PDF文件目录路径
HWP_CACHE_DIR ./cache 解析缓存存储路径
QDRANT_URL http://localhost:6333 Qdrant服务器URL
GEMINI_API_KEY （无） Gemini API密钥（用于语义搜索）

CLI命令

export HWP_SPECS_DIR=/path/to/specs
export QDRANT_URL=http://localhost:30333
export GEMINI_API_KEY=your_api_key

CLI="node /path/to/fxxk-hwpjs-mcp/dist/cli.js"

浏览目录（toc）

$CLI toc hwp5               # 기본 depth 2
$CLI toc hwp3-bin --depth 3
$CLI toc hwp3-xml

关键字搜索（search，exact match）

$CLI search "FileHeader" --doc hwp5
$CLI search "HWPTAG_PARA_SHAPE"          # 전체 문서 검색
$CLI search "하이퍼링크" --doc hwp3-bin

查看节内容（section）

$CLI section hwp5 "4.2.6"          # 섹션 번호
$CLI section hwp5 "글자 모양"       # 섹션 제목 부분 매칭
$CLI section hwp3-bin "3.1"
$CLI section hwp3-xml "5.16"       # HWPML 머리말/꼬리말

表格查询（table）

$CLI table hwp5 "표 43"            # 한글 표 번호
$CLI table hwp5 "43"               # 숫자만도 가능
$CLI table hwp5 "글자 모양"        # 이름 부분 매칭

自然语言语义搜索（semantic）

前提条件：Qdrant正在运行+矢量索引创建完成

$CLI semantic "문단 들여쓰기 저장 방식" --doc hwp5
$CLI semantic "이미지 그림 삽입 데이터 구조"   # 전체 문서 교차 검색
$CLI semantic "HWPML 문단 속성 엘리먼트" --doc hwp3-xml
$CLI semantic "암호화 배포용 문서" --doc dist
$CLI semantic "How to store paragraph indent" --doc hwp5  # 영어도 가능

创建矢量索引（index）

$CLI index                       # 전체 문서 인덱싱
$CLI index --doc hwp5            # 특정 문서만
$CLI index --doc hwp3-bin
$CLI index --doc hwp3-xml
$CLI index --force               # 강제 재인덱싱

设置西蒙蒂克搜索（Gemini+Qdrant）

嵌入模型

项目 值
型号 gemini-embedding-001
API版本 v1beta
向量维度 3072
语言多语言（韩语、英语等）
API키 발급 https://aistudio.google.com/app/apikey

1.Qdrant部署（Kubenetes）

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/qdrant.yaml

# 배포 확인
kubectl get pods -n openclaw-support
kubectl get svc -n openclaw-support

访问方法地址 |-------------------|--------------------------------------------------| |集群内部| http://qdrant.openclaw-support.svc.cluster.local:6333 | |外部（NodePort）| http://<node-ip>:30333 |

2.生成矢量索引

首次运行一次（每个文档约2-5分钟）。之后将永久保存在Qdrant中。

export HWP_SPECS_DIR=/path/to/specs
export QDRANT_URL=http://localhost:30333
export GEMINI_API_KEY=your_api_key

node dist/cli.js index

docId区块数（请参见） |------------|---------------| | hwp3-bin | ~149 | | hwp3-xml | ~178 | | hwp5 | ~208 | | formula | ~38 | | chart | ~131 | | dist | ~17 |

MCP 서버 （克劳德桌面/克劳德代码）

克劳德桌面

claude_desktop_config.json:

{
  "mcpServers": {
    "hwp-spec": {
      "command": "node",
      "args": ["/path/to/fxxk-hwpjs-mcp/dist/index.js"],
      "env": {
        "HWP_SPECS_DIR": "/path/to/specs",
        "QDRANT_URL": "http://localhost:6333",
        "GEMINI_API_KEY": "your_api_key"
      }
    }
  }
}

克劳德代码（CLI）

claude mcp add hwp-spec -- node /path/to/fxxk-hwpjs-mcp/dist/index.js

工具参考

search / search_spec

关键字exact match搜索。不区分大小写。

参数 必需 说明
query 宣传词（HWPTAG常量，韩文关键字等）
documentdocId（跳过时搜索整个文档）

semantic / semantic_search

基于自然语言语义的搜索（Gemini Embedding+Qdrant Cosine）。

参数 必需 说明
query 自然语言问题（韩语/英语都可以）
document 目标docId（跳过时进行完全交叉搜索）
limit 结果计数（默认值5，最大值20）

section / get_section

查询特定部分的全部内容。

参数 必需 说明
document ✅ docId
section 区号（"4.2.6"）或标题部分（"글자 모양")

table / get_table

查询表格内容。支持部分匹配编号/名称。

参数 必需 说明
document ✅ docId
table_name ✅ "표 43", "43", "글자 모양" 全部可用

toc / list_sections

查询文档目录。

参数 必需 说明
document ✅ docId
depth 目录深度（默认为2）

注意事项

hwp3-bin 对比 hwp3-xml 区分

hwp-v3.pdf 文件只有一个，但内容 两个独立的文档由组成：

  • hwp3-bin （p.1~54）：HWP3.x二进制格式-基于offset的结构体、特殊字符代码等
  • hwp3-xml （p.55-122）：基于HWPML-XML/SGML标记的HWP文档表示

两个文档的节编号分别从1开始。 必须指定正确的docId必须。
hwp3 docId不再使用。

# ❌ 예전 방식 (제거됨)
$CLI section hwp3 "3.1"

# ✅ 올바른 방식
$CLI section hwp3-bin "3.1"   # 바이너리 포맷 파일 인식 정보
$CLI section hwp3-xml "3"     # HWPML 루트 엘리먼트

Gemini嵌入式API

  • text-embedding-004Google AI Studio密钥不支持。
  • gemini-embedding-001（3072维） v1beta 用作endpoint。
  • API密钥 谷歌AI工作室请在发放。

PDF解析限制

  • 查询表（table）：由于基于PDF文本层的解析，复杂的多级表格可能会缺少一些行。
    需要表格内容时 section 使用命令获取整个部分的可靠性更高。
  • PDF字体编码：某些PDF可能会将韩文解析为PUA（Private Use Area）Unicode。
    段提取器被处理为对其进行校正。
  • TOC页面：虚线（······）目录页面将自动从语义索引中排除。

矢量索引

  • Qdrant集合名称： hwp_spec
  • docId独立管理，因此仅重新编制一个文档的索引不会影响其他文档
  • 重新编制索引时自动删除现有数据，然后重新上载

缓存结构

路径内容 |----------------------|----------------------------------------| | cache/<docId>.json | PDF解析结果（部分/表格/页面文本）| |Qdrant hwp_spec |矢量嵌入（区分为docId字段）|

  • PDF文件MD5哈希更改时自动重新生成缓存
  • 矢量索引 index --force强制再生到

工作历史记录

v0.2.0（2026-02-21）

主要更改

  • hwp3 分离: hwp3-bin （二进制，p.1~54）+ hwp3-xml （HWPML，第55~122页）
    hwp-v3.pdf包含两个独立文档，以解决区号冲突问题
  • Gemini嵌入模型更改: text-embedding-004 → gemini-embedding-001 （3072维）
    从Google AI Studio API密钥更改为支持的模型，采用直接调用REST API的方式

改进段提取（section-extractor.ts)

  • PDF PUA Unicode修改：部分PDF中的韩文 U+F53A 解析到同一PUA区域时
    [가-힣] 模式匹配失败→ [\u0080-\uFFFF]扩展到允许所有非ASCII字符
    → "1. 개요", "3. 글 파일 구조" 等恢复之前丢失的顶层部分
  • 允许简短的部分标题: {3,} → {1,} 支持短标题，如缓解（“概述”（2个字符）

改进表解析（table-extractor.ts)

  • 修改标题图案: "표 N: 제목" （需要冒号）→ "표 N 제목" （实际HWP规格PDF格式）
  • 反向导航：HWP规格PDF首先显示表格内容，标题位于下面
    更改为根据标题反向浏览顶部
  • 解析查询: "표 43", "43", "문단 모양" 支持多种输入格式，例如
  • 五探 (표 N 참조) 模式） TABLE_HEADER_PATTERN 通过卸载解决

改进了西蒙蒂克索引（doc-indexer.ts)

  • 不包括TOC页面：自动检测虚线目录页面并将其排除在矢量索引之外
    →优化到总区块数909→721，提高搜索质量

docId体系（types.ts, index-manager.ts)

  • DocumentInfo呃 pageRange?: { start, end } 添加
  • hwp3-bin, hwp3-xml 每页范围切片后独立编制索引

v0.1.0（2026-02-21）

  • 添加CLI包装器（src/cli.ts): search, section, table, toc, semantic, index
  • Gemini Embedding+Qdrant实现语义搜索
  • 改进PDF部分提取（584到88部分，目录噪音过滤）
  • Kubernetes YAML(k8s/) — openclaw-support 命名空间，NodePort 30333/30334
  • OpenClaw Skill文件（skills/hwp-spec/SKILL.md)

开发

npm run build      # TypeScript 빌드
npm run typecheck  # 타입 체크만
npm test           # 테스트 실행

许可证

麻省理工学院

相关 MCP