MCP Hwp

mcp-hwp

用于HWP/HWPX处理的Rust CLI构建于 hwpers，同一二进制文件中有一个可选的MCP stdio适配器。

它的作用

• 从中提取纯文本 .hwp 和 .hwpx
• 检查文档元数据
• 总结文档结构
• 将页面渲染为SVG
• 在HWP和HWPX之间转换
• 从文本创建纯HWP文档
• 从JSON创建丰富的HWP/HWPX文档
• 从现有文档中提取丰富的块结构

安装

来源

cargo install --path .

本地建设

cargo build --release

CLI快速入门

显示帮助：

mcp-hwp --help

提取文本：

mcp-hwp extract-text --path ./document.hwp

检查JSON格式的元数据：

mcp-hwp inspect-metadata --path ./document.hwp --json

总结有限制的结构：

mcp-hwp summarize-structure \
  --path ./document.hwp \
  --json \
  --max-paragraphs-per-section 1 \
  --preview-chars 20

转换为HWPX：

mcp-hwp convert \
  --path ./document.hwp \
  --to hwpx \
  --output ./converted.hwpx

将页面1渲染为SVG文件：

mcp-hwp render-svg \
  --path ./document.hwp \
  --page 1 \
  --output-dir ./svg-output

创建纯文档：

mcp-hwp create-document \
  --text "Hello\n안녕" \
  --output ./created.hwp

从JSON创建富文档：

mcp-hwp create-rich-document \
  --input ./document.json \
  --to hwp \
  --output ./rich.hwp

提取富块段模型：

mcp-hwp extract-rich --path ./document.hwp --json

使用写入目录的图像资源提取丰富内容：

mcp-hwp extract-rich \
  --path ./document.hwp \
  --images resource \
  --output-dir ./images \
  --json

CLI命令

• extract-text
• inspect-metadata
• summarize-structure
• render-svg
• convert
• create-document
• create-rich-document
• extract-rich
• serve --stdio

文件生成命令的设计是明确的：

• convert, create-document，以及 create-rich-document 需要 --output
• render-svg 需要 --output-dir

输入

读取操作接受：

• --path
• --base64
• 可选的 --format auto|hwp|hwpx

正是其中之一 --path 或 --base64 必须提供。

extract-rich --images 接受 none, metadata, inline，或 resource. 使用时 resource，通过 --output-dir 以控制提取的图像文件写入的位置。

富文档JSON

create-rich-document --input 需要一个JSON对象 document 有效载荷。该文件可以直接包含文档对象，也可以包含一个顶级的包装器 document 钥匙。

例子：

{
  "title": "Example",
  "blocks": [
    { "type": "heading", "level": 1, "text": "Intro" },
    { "type": "paragraph", "text": "Hello rich world" },
    { "type": "list", "items": ["one", "two"], "ordered": false },
    { "type": "page_break" },
    {
      "type": "table",
      "rows": [
        ["Name", "City"],
        ["Alice", "Seoul"]
      ],
      "header_row": true
    }
  ]
}

可选MCP集成

相同的二进制文件可以通过stdio为MCP提供服务：

mcp-hwp serve --stdio

此适配器保留现有的MCP工具名称：

• hwp.extract_text
• hwp.inspect_metadata
• hwp.summarize_structure
• hwp.render_svg
• hwp.convert
• hwp.create_document
• hwp.create_rich_document
• hwp.extract_rich

成功的MCP响应保持现有 content, structuredContent，以及 isError 形状。

克劳德桌面

{
  "mcpServers": {
    "mcp-hwp": {
      "command": "mcp-hwp",
      "args": ["serve", "--stdio"]
    }
  }
}

Codex CLI

[mcp_servers.mcp-hwp]
command = "mcp-hwp"
args = ["serve", "--stdio"]

重大变更

• 该项目现在首先以CLI的形式进行记录和结构化。
• 实现了完整的CLI命令界面，而不是部分截断的命令。
• MCP仍然可以作为同一二进制文件中的可选stdio适配器使用。

发展

运行测试套件：

cargo test

查看命令帮助：

cargo run -- --help
cargo run -- create-rich-document --help