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 は1段落内に複数フォーマットが混在する場合に使います。
コメントアンカー
{
"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.
