docx-comparison-mcp
docx-comparison-mcp
A3 가로형 신구 대비표 / A4 세로형 사양서 Word 문서 생성 MCP 서버
Dify / LangFlow / LangChain / Claude Desktop 등 원하는 AI 프레임워크에서 호출할 수 있는 로컬 MCP 서버입니다.
설계 사상: GET schema → POST generate
excel-mcp와 동일한 "스키마를 먼저 가져온 후 생성하는" 패턴을 채택하고 있습니다.
단, excel-mcp와는 근본적인 차이가 있습니다:
excel-mcp | docx-mcp | |
스키마의 유래 | 실행 시 Excel 파일의 헤더 행을 읽음 (동적) | 컴파일 시 고정된 출력 형식 (정적) |
"저장 위치" | 정해진 Excel 파일 (항상 동일한 경로) | 매번 새로 생성 (PDF 업로드 시마다 새로운 문서) |
append 개념 | 있음 (기존 행에 추가) | 없음 (PDF 1회 = 새로운 docx 1개) |
Dify 워크플로우에서의 위치:
[HTTP ノード] GET /schema/comparison
↓ prompt_context（列定義の代わりに出力フォーマット定義）
[LLM ノード] アップロードされた PDF を Gemini が読む + schema context を注入
↓ { doc_title, sections: [...] } の JSON
[HTTP ノード] POST /generate { spec: { ... } }
↓ download_url
[End]prompt_context 필드는 Dify의 LLM 노드 시스템 프롬프트에 그대로 붙여넣을 수 있는 형식으로 되어 있습니다.
기능
A3 가로형, 구/신/비고 3열 형식 (신구 대비표)
A4 세로형, 표지·제정 및 개폐 이력표·본문 (사양서)
빨간색 텍스트 (변경/추가 부분)
파란색 밑줄이 있는 Word 댓글 앵커
다중 섹션 지원 (표지, 제정 및 개폐 이력, 각 조항)
stdio 모드 (Claude Desktop / Claude Code용)
HTTP 모드 (Dify / LangFlow용)
설정
# 1. 依存パッケージのインストール
npm install
# 2. テスト実行
npm test
# → test-output.docx が生成されます
# 3a. MCP (stdio) モード起動 — Claude Desktop / Claude Code 向け
npm start
# 3b. HTTP モード起動 — Dify / LangFlow / REST 向け
npm run start:http
# → http://localhost:3456 で起動Claude Desktop 등록
~/.claude/claude_desktop_config.json에 추가:
{
"mcpServers": {
"docx-comparison": {
"command": "node",
"args": ["/absolute/path/to/docx-mcp/src/index.js"],
"env": {
"OUTPUT_DIR": "/Users/yourname/Desktop/docx-output"
}
}
}
}엔드포인트 목록
메서드 | 경로 | 설명 |
|
| 서버 상태 확인 |
|
| API 문서 (정적) |
|
| 신구 대비표 LLM 주입용 스키마 |
|
| 사양서 LLM 주입용 스키마 |
|
| 신구 대비표 생성 (로컬 저장) |
|
| 신구 대비표 생성 (파일 직접 스트림) |
|
| 사양서 생성 (로컬 저장) |
|
| 사양서 생성 (파일 직접 스트림) |
GET /schema/comparison — 신구 대비표 스키마
LLM에 주입할 형식 정의를 반환합니다. prompt_context 필드를 Dify의 LLM 노드 시스템 프롬프트에 붙여넣으십시오.
응답 개요:
{
"doc_type": "comparison",
"description": "新旧比較表（A3横、旧/新/備考 3カラム）Word文書の生成スキーマ",
"prompt_context": "## 新旧比較表 生成形式\n\nPOST /generate に渡す spec を...",
"required_fields": ["doc_title", "sections"],
"sections_schema": { ... },
"paragraph_schema": { ... },
"example": { ... }
}GET /schema/manual — 사양서 스키마
{
"doc_type": "manual",
"description": "仕様書（A4縦、表紙・経歴表・本文）Word文書の生成スキーマ",
"prompt_context": "## 仕様書 生成形式\n\nPOST /generate/manual に渡す spec を...",
"required_fields": ["doc_title", "sections"],
"sections_schema": { ... },
"history_schema": { ... },
"example": { ... }
}Dify 워크플로우 통합 패턴
신구 대비표 (PDF 비교)
[ファイルアップロード] ユーザーが PDF をアップロード
↓
[HTTP ノード] GET /schema/comparison
↓ body.prompt_context を変数に格納
[LLM ノード]
システムプロンプト: {{schema_prompt_context}}
ユーザーメッセージ: {{uploaded_pdf_content}}
↓ spec JSON（新旧比較表形式）
[HTTP ノード] POST /generate { "spec": {{llm_output}} }
↓ { "download_url": "http://...", "filename": "...", "sections": N }
[End]Gemini는 업로드된 PDF를 멀티모달로 읽어들입니다. 서버 측에서의 PDF 파싱은 필요하지 않습니다.
사양서 생성
[HTTP ノード] GET /schema/manual
↓ prompt_context
[LLM ノード] 仕様書内容の構造化
[HTTP ノード] POST /generate/manual { "spec": {...} }JSON 스펙 사양 (신구 대비표)
단락 스펙 (old_paragraphs / new_paragraphs의 각 요소)
{
"text": "テキスト（シンプルな場合）",
"segments": [
{ "text": "通常テキスト" },
{ "text": "赤い変更箇所", "color": "red", "underline": true },
{ "text": "続き" }
],
"bold": false,
"color": "black",
"underline": false,
"align": "justify",
"indent": 0,
"sz": 19
}text와 segments 중 하나를 사용합니다. segments는 한 단락 내에 여러 형식이 혼재할 경우 사용합니다.
댓글 앵커
{
"anchor": "作業手順確認書類",
"text": "名称変更：作業手順確認書類→作業安全確認表",
"column": "old"
}anchor: 댓글을 달고 싶은 텍스트 (완전 일치)text: Word 댓글 풍선에 표시되는 내용column:"old"|"new"|"both"
LangFlow / Python 사용 예시
import requests
# 1. スキーマ取得（Dify HTTP ノードの代替）
schema = requests.get("http://localhost:3456/schema/comparison").json()
print(schema["prompt_context"]) # → LLM に注入するテキスト
# 2. 新旧比較表生成
spec = {
"doc_title": "通信関係請負工事共通仕様書 比較表",
"sections": [
{
"id": "section19",
"title": "【１９．施工方法】",
"status": "changed",
"old_paragraphs": [{"text": "１９．施工方法および工事工程", "bold": True}],
"new_paragraphs": [{"text": "２０．施工方法および工事工程", "bold": True}],
"notes": ["・名称変更に伴う見直し"],
"comments": [{"anchor": "作業手順確認書類", "text": "名称変更", "column": "old"}],
}
]
}
# ローカル保存 + パス返却
response = requests.post("http://localhost:3456/generate", json={
"spec": spec,
"output_filename": "比較表_第３回改正",
})
print(response.json())
# → {"success": true, "path": ".../比較表_第３回改正.docx", "download_url": "...", ...}파일 구성
docx-mcp/
├── src/
│ ├── index.js # MCP stdio サーバー（Claude Desktop / Code）
│ ├── http-server.js # HTTP REST サーバー（Dify / LangFlow）
│ ├── docx-generator.js # コア: JSON → 新旧比較表 .docx 変換エンジン
│ ├── manual-generator.js # コア: JSON → 仕様書 .docx 変換エンジン
│ ├── schema.js # Zod バリデーション + LLM 注入用スキーマ定義
│ └── test.js # テスト
├── docs/
│ └── dify-tool.yaml # Dify Custom Tool / OpenAPI 定義
├── package.json
└── README.md환경 변수
변수 | 기본값 | 설명 |
|
| 생성 파일 저장 경로 |
|
| HTTP 모드 포트 번호 |
Available Tools
3 toolsgenerate_comparison_docA
Generate a 新旧比較表 (before/after comparison) Word document (.docx). The document follows A3 landscape layout with 旧/新/備考 three-column format. Supports red text for new content, blue underline anchors, and Word comments. Returns base64-encoded docx and saves to local output directory.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | Yes | Document specification. Use get_template_schema to see the full format. | |
| output_filename | No | Output filename (without extension). Defaults to doc_title. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: document layout (A3 landscape), formatting features (red text, blue underline, Word comments), dual output behavior (returns base64 and saves locally), and file type (.docx). It doesn't mention error conditions, performance characteristics, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: first describes the document generation with formatting details, second explains the dual output behavior. Every element serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a document generation tool with no annotations and no output schema, the description provides substantial context: document purpose, layout, formatting features, and output behavior. It references get_template_schema for parameter details. The main gap is lack of explicit error handling or performance information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description doesn't add meaningful parameter semantics beyond what's in the schema, though it references get_template_schema for the full spec format, which provides some guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (generate), resource (新旧比較表/before-after comparison Word document), and output format (.docx). It distinguishes from sibling tools by specifying document generation rather than schema retrieval or previewing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating comparison documents with specific formatting requirements, and references get_template_schema for parameter details. However, it doesn't explicitly state when to use this tool versus alternatives like preview_sections, or provide clear prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_template_schemaA
Returns the JSON schema and a complete example for the generate_comparison_doc tool. Call this first to understand how to structure the spec parameter. Pass doc_type="manual" to get the schema for generate_manual_doc instead.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_type | No | Which schema to return. "comparison" (default) = 新旧比較表, "manual" = 仕様書. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by stating it returns a JSON schema and example, specifies a prerequisite action ('Call this first'), and mentions the default behavior for doc_type. However, it lacks details on error handling or response format, which could enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, uses two efficient sentences with zero waste, and each sentence earns its place by providing essential usage instructions and parameter context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete, covering purpose, usage, and parameter semantics. However, it could be more complete by briefly mentioning the response structure or potential errors, though this is not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds value by explaining the purpose of the doc_type parameter ('to get the schema for generate_manual_doc instead') and clarifying the default value ('comparison' for 新旧比較表), which goes beyond the schema's enum and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Returns', 'Call this first') and resources ('JSON schema and a complete example for the generate_comparison_doc tool'), distinguishing it from siblings like generate_comparison_doc and preview_sections by focusing on schema retrieval rather than document generation or previewing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool ('Call this first to understand how to structure the spec parameter') and includes an alternative usage case ('Pass doc_type="manual" to get the schema for generate_manual_doc instead'), clearly differentiating it from other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
preview_sectionsA
Preview the text content of a document spec without generating a file. Useful for verifying the structure before calling generate_comparison_doc.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | Yes | Document specification |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the tool doesn't generate a file, which is useful behavioral context. However, it doesn't disclose other important traits like whether this is a read-only operation, what permissions are needed, what the output format looks like (text content preview), or any rate limits. For a tool with no annotations, this leaves significant gaps in behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise and well-structured: two sentences that each earn their place. The first sentence states the core purpose with key constraint, and the second provides usage guidance. No wasted words, and the most important information (what it does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations, no output schema, and a single but complex parameter (nested object 'spec'), the description is minimally adequate. It covers the purpose and basic usage context but lacks details about output format, error conditions, or what 'preview' actually returns. For a tool that presumably returns text content previews, more information about the return value would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage (the 'spec' parameter is documented as 'Document specification'), so the baseline is 3. The description doesn't add any parameter-specific information beyond what the schema provides—it doesn't explain what constitutes a valid 'document specification' or provide examples. The description's value is in tool purpose, not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Preview the text content of a document spec without generating a file.' This specifies the verb ('preview'), resource ('text content of a document spec'), and key constraint ('without generating a file'). However, it doesn't explicitly differentiate from sibling tools like 'get_template_schema' beyond mentioning 'generate_comparison_doc' in usage context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Useful for verifying the structure before calling generate_comparison_doc.' This explicitly states when to use this tool (for verification before generation) and references an alternative sibling tool. However, it doesn't mention when NOT to use it or address other siblings like 'get_template_schema'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v1.0.0- First observed
generate_comparison_doc - First observed
get_template_schema - First observed
preview_sections
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose with no overlap: generate_comparison_doc creates the final document, get_template_schema provides metadata and examples, and preview_sections offers a validation step. The descriptions clearly differentiate their roles in the document generation workflow.
All tool names follow a consistent snake_case pattern with descriptive verb_noun combinations (generate_comparison_doc, get_template_schema, preview_sections). The naming is uniform and predictable across the set.
Three tools is well-scoped for a specialized document comparison server. Each tool serves a distinct, necessary function in the workflow (schema retrieval, preview, and generation), with no redundancy or obvious missing pieces for the stated purpose.
The toolset provides complete coverage for the document comparison domain: get_template_schema enables understanding the input format, preview_sections allows validation, and generate_comparison_doc handles final output. This creates a logical, end-to-end workflow with no gaps.
Related MCP Connectors
Create real Word .docx files from your AI chat: proposals, quotes, contracts, statements of work.
Use your own Word templates to convert Markdown → DOCX/PDF/HTML from any MCP-compatible AI.
Automate production-ready PDF, Word, Excel and PowerPoint documents from templates and JSON data
Create, review and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
