docx-comparison-mcp
docx-comparison-mcp
Servidor MCP para generar documentos de Word: Tabla comparativa antiguo/nuevo (A3 horizontal) / Especificaciones (A4 vertical)
Es un servidor MCP local que puede ser invocado desde cualquier marco de trabajo de IA como Dify, LangFlow, LangChain o Claude Desktop.
Filosofía de diseño: GET schema → POST generate
Adopta el mismo patrón que excel-mcp: "obtener primero el esquema y luego generar".
Sin embargo, existen diferencias fundamentales con excel-mcp:
excel-mcp | docx-mcp | |
Origen del esquema | Lee la fila de encabezado del archivo Excel en tiempo de ejecución (dinámico) | Formato de salida fijo en tiempo de compilación (estático) |
"Destino de escritura" | Archivo Excel determinado (siempre la misma ruta) | Generación nueva cada vez (un documento nuevo por cada carga de PDF) |
Concepto de append | Sí (añadir a filas existentes) | No (1 PDF = 1 nuevo docx) |
Posicionamiento en el flujo de trabajo de Dify:
[HTTP ノード] GET /schema/comparison
↓ prompt_context（列定義の代わりに出力フォーマット定義）
[LLM ノード] アップロードされた PDF を Gemini が読む + schema context を注入
↓ { doc_title, sections: [...] } の JSON
[HTTP ノード] POST /generate { spec: { ... } }
↓ download_url
[End]El campo prompt_context tiene un formato que se puede pegar directamente en el prompt del sistema del nodo LLM de Dify.
Funcionalidades
Formato A3 horizontal, 3 columnas: Antiguo/Nuevo/Notas (Tabla comparativa)
Formato A4 vertical, portada, tabla de historial de revisiones, cuerpo del documento (Especificaciones)
Texto en rojo (secciones modificadas/añadidas)
Anclas de comentarios de Word con subrayado azul
Soporte para múltiples secciones (portada, historial de revisiones, cláusulas individuales)
Modo stdio (para Claude Desktop / Claude Code)
Modo HTTP (para Dify / LangFlow)
Configuración
# 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 で起動Registro en Claude Desktop
Añadir a ~/.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"
}
}
}
}Lista de endpoints
Método | Ruta | Descripción |
|
| Verificación de estado del servidor |
|
| Documentación de la API (estática) |
|
| Esquema para inyección de LLM en tabla comparativa |
|
| Esquema para inyección de LLM en especificaciones |
|
| Generación de tabla comparativa (guardado local) |
|
| Generación de tabla comparativa (flujo directo de archivo) |
|
| Generación de especificaciones (guardado local) |
|
| Generación de especificaciones (flujo directo de archivo) |
GET /schema/comparison — Esquema de tabla comparativa
Devuelve la definición de formato para inyectar en el LLM. Por favor, pegue el campo prompt_context en el prompt del sistema del nodo LLM de Dify.
Resumen de respuesta:
{
"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 — Esquema de especificaciones
{
"doc_type": "manual",
"description": "仕様書（A4縦、表紙・経歴表・本文）Word文書の生成スキーマ",
"prompt_context": "## 仕様書 生成形式\n\nPOST /generate/manual に渡す spec を...",
"required_fields": ["doc_title", "sections"],
"sections_schema": { ... },
"history_schema": { ... },
"example": { ... }
}Patrón de integración de flujo de trabajo de Dify
Tabla comparativa (comparación de 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 lee el PDF cargado de forma multimodal. No es necesario analizar el PDF en el lado del servidor.
Generación de especificaciones
[HTTP ノード] GET /schema/manual
↓ prompt_context
[LLM ノード] 仕様書内容の構造化
[HTTP ノード] POST /generate/manual { "spec": {...} }Especificaciones de JSON (Tabla comparativa)
Especificaciones de párrafo (cada elemento de 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
}Se utiliza text o segments. segments se usa cuando hay múltiples formatos mezclados dentro de un mismo párrafo.
Anclas de comentarios
{
"anchor": "作業手順確認書類",
"text": "名称変更：作業手順確認書類→作業安全確認表",
"column": "old"
}anchor: Texto al que se desea añadir un comentario (coincidencia exacta)text: Contenido que se mostrará en el globo de comentario de Wordcolumn:"old"|"new"|"both"
Ejemplo de uso en 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": "...", ...}Estructura de archivos
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.mdVariables de entorno
Variable | Predeterminado | Descripción |
|
| Destino de guardado de archivos generados |
|
| Número de puerto para el modo 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.
