Fxxk Hwpjs MCP

fxxk-hwpj-mcp

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

______________________________________________________________________

目录

• 安装
• PDF文件设置
• OpenClaw Skill（推荐）
• 设置西蒙蒂克搜索（Gemini+Qdrant）
• MCP服务器
• 工具参考
• 注意事项
• 工作历史记录

______________________________________________________________________

安装

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

环境变量

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）

嵌入模型

语言多语言（韩语、英语等） 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://: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搜索。不区分大小写。

semantic / semantic_search

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

section / get_section

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

table / get_table

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

toc / list_sections

查询文档目录。

______________________________________________________________________

注意事项

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/.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           # 테스트 실행

______________________________________________________________________

许可证

麻省理工学院