docx-create
Generate DOCX documents from structured JSON data with support for text formatting, tables, images, and code blocks. Use docx-getSchema first to understand the required JSON structure.
Instructions
Create a new docx from JSON, returns an id. Use docx-getSchema first to understand the required JSON structure. Supports images via 'data' (base64), 'path' (local file), or 'url' (remote image with fallback).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| json | Yes |
Implementation Reference
- src/index.ts:149-166 (handler)Handler for the 'docx-create' tool: parses input arguments using the tool's inputSchema, generates a unique document ID, checks if the JSON contains images requiring async handling (local paths or URLs), calls the appropriate registry create method (sync or async), and returns the document ID.case "docx-create": { const { json } = parseArgs<{ json: any }>(args, tools["docx-create"].inputSchema); const id = nanoid(); // Check if JSON contains images with local paths or URLs const jsonStr = JSON.stringify(json); const hasImagePaths = jsonStr.includes('"path"') || jsonStr.includes('"url"'); if (hasImagePaths) { // Use async version for images with local paths or URLs const { id: docId } = await registry.createAsync(id, json); return ok({ id: docId }); } else { // Use sync version for base64 images or no images const { id: docId } = registry.create(id, json); return ok({ id: docId }); } }
- src/index.ts:37-44 (registration)Registration of the 'docx-create' tool in the tools dictionary, providing description and inputSchema that requires a 'json' property conforming to DocxSchema."docx-create": { description: "Create a new docx from JSON, returns an id. Use docx-getSchema first to understand the required JSON structure. Supports images via 'data' (base64), 'path' (local file), or 'url' (remote image with fallback).", inputSchema: { type: "object", required: ["json"], properties: { json: DocxSchema } } },
- src/schema.ts:4-596 (schema)Comprehensive JSON Schema (DocxSchema) defining the structure for DOCX documents, used to validate the 'json' input parameter for 'docx-create'. Supports metadata, page settings, headers/footers, footnotes, and various content blocks like paragraphs, tables, images (with base64/data, path, url), headings, lists, code blocks, etc.export const DocxSchema = { $id: "https://example.com/schemas/docx-schema.json", $schema: "https://json-schema.org/draft/2020-12/schema", title: "DocxDocument", type: "object", additionalProperties: false, required: ["content"], properties: { meta: { type: "object", additionalProperties: false, properties: { title: { type: "string" }, subject: { type: "string" }, creator: { type: "string" }, description: { type: "string" }, keywords: { type: "string" }, lastModifiedBy: { type: "string" }, category: { type: "string" }, company: { type: "string" }, manager: { type: "string" }, revision: { type: "string" }, createdAt: { type: "string", format: "date-time" }, modifiedAt: { type: "string", format: "date-time" } } }, styles: { type: "object", additionalProperties: false, properties: { defaultFont: { type: "string" }, defaultFontSize: { type: "number" } } }, pageSettings: { type: "object", additionalProperties: false, properties: { pageSize: { type: "string", enum: ["A4", "A3", "A5", "Letter", "Legal", "Tabloid", "Executive"], default: "A4" }, orientation: { type: "string", enum: ["portrait", "landscape"], default: "portrait" }, margins: { type: "object", additionalProperties: false, properties: { top: { type: "number", default: 1440 }, // in twips (1 inch = 1440 twips) bottom: { type: "number", default: 1440 }, left: { type: "number", default: 1440 }, right: { type: "number", default: 1440 } } }, headerMargin: { type: "number", default: 720 }, // 0.5 inch footerMargin: { type: "number", default: 720 } } }, headers: { type: "object", additionalProperties: false, properties: { default: { $ref: "#/$defs/HeaderFooterContent" }, first: { $ref: "#/$defs/HeaderFooterContent" }, even: { $ref: "#/$defs/HeaderFooterContent" } } }, footers: { type: "object", additionalProperties: false, properties: { default: { $ref: "#/$defs/HeaderFooterContent" }, first: { $ref: "#/$defs/HeaderFooterContent" }, even: { $ref: "#/$defs/HeaderFooterContent" } } }, footnotes: { type: "object", additionalProperties: false, patternProperties: { "^[a-zA-Z0-9_-]+$": { $ref: "#/$defs/NoteContent" } } }, content: { type: "array", items: { $ref: "#/$defs/Block" } } }, $defs: { Block: { type: "object", oneOf: [ { $ref: "#/$defs/Paragraph" }, { $ref: "#/$defs/Table" }, { $ref: "#/$defs/Image" }, { $ref: "#/$defs/Heading" }, { $ref: "#/$defs/CodeBlock" }, { $ref: "#/$defs/List" }, { $ref: "#/$defs/PageBreak" }, { $ref: "#/$defs/HorizontalRule" }, { $ref: "#/$defs/Blockquote" }, { $ref: "#/$defs/InfoBox" }, { $ref: "#/$defs/TextBox" } ] }, Heading: { type: "object", additionalProperties: false, required: ["type", "level", "children"], properties: { type: { const: "heading" }, level: { type: "integer", minimum: 1, maximum: 6 }, children: { $ref: "#/$defs/Inlines" }, spacingBefore: { type: "number" }, spacingAfter: { type: "number" }, alignment: { enum: ["left", "center", "right", "justify"] } } }, Paragraph: { type: "object", additionalProperties: false, required: ["type", "children"], properties: { type: { const: "paragraph" }, children: { $ref: "#/$defs/Inlines" }, alignment: { enum: ["left", "center", "right", "justify"] }, spacingBefore: { type: "number" }, spacingAfter: { type: "number" }, indent: { type: "object", additionalProperties: false, properties: { left: { type: "number" }, right: { type: "number" }, firstLine: { type: "number" } } } } }, Inlines: { type: "array", items: { $ref: "#/$defs/Inline" } }, Inline: { type: "object", oneOf: [ { $ref: "#/$defs/TextRun" }, { $ref: "#/$defs/Hyperlink" }, { $ref: "#/$defs/FootnoteReference" } ] }, TextRun: { type: "object", additionalProperties: false, required: ["type", "text"], properties: { type: { const: "text" }, text: { type: "string" }, bold: { type: "boolean" }, italics: { type: "boolean" }, underline: { type: "boolean" }, strike: { type: "boolean" }, color: { type: "string" }, size: { type: "number" }, fontFamily: { type: "string" }, superScript: { type: "boolean" }, subScript: { type: "boolean" }, highlight: { type: "string" }, smallCaps: { type: "boolean" }, allCaps: { type: "boolean" }, spacing: { type: "number" } } }, Hyperlink: { type: "object", additionalProperties: false, required: ["type", "url", "children"], properties: { type: { const: "hyperlink" }, url: { type: "string", format: "uri" }, children: { $ref: "#/$defs/Inlines" } } }, Table: { type: "object", additionalProperties: false, required: ["type", "rows"], properties: { type: { const: "table" }, rows: { type: "array", items: { $ref: "#/$defs/TableRow" } }, width: { type: "number" }, borders: { type: "boolean" }, borderStyle: { type: "string", enum: ["single", "double", "thick", "thin", "dotted", "dashed"], default: "single" }, borderColor: { type: "string", default: "#000000" }, borderSize: { type: "number", default: 1 }, style: { type: "string", enum: ["none", "table-grid", "table-list", "table-colorful"], default: "none" }, alignment: { type: "string", enum: ["left", "center", "right"], default: "left" } } }, TableRow: { type: "object", additionalProperties: false, required: ["cells"], properties: { cells: { type: "array", items: { $ref: "#/$defs/TableCell" } }, isHeader: { type: "boolean", default: false }, height: { type: "number" }, cantSplit: { type: "boolean", default: false } } }, TableCell: { type: "object", additionalProperties: false, required: ["children"], properties: { colSpan: { type: "integer", minimum: 1 }, rowSpan: { type: "integer", minimum: 1 }, children: { type: "array", items: { $ref: "#/$defs/Paragraph" } }, backgroundColor: { type: "string" }, verticalAlign: { type: "string", enum: ["top", "center", "bottom"], default: "top" }, margins: { type: "object", additionalProperties: false, properties: { top: { type: "number", default: 0 }, bottom: { type: "number", default: 0 }, left: { type: "number", default: 108 }, // 0.075 inch right: { type: "number", default: 108 } } }, borders: { type: "object", additionalProperties: false, properties: { top: { type: "boolean", default: true }, bottom: { type: "boolean", default: true }, left: { type: "boolean", default: true }, right: { type: "boolean", default: true } } } } }, Image: { type: "object", additionalProperties: false, required: ["type"], properties: { type: { const: "image" }, data: { type: "string", description: "base64-encoded image data" }, path: { type: "string", description: "local file path to image" }, url: { type: "string", description: "URL to download image from" }, format: { enum: ["png", "jpeg", "jpg"] }, width: { type: "number" }, height: { type: "number" } }, oneOf: [ { required: ["data", "format"] }, { required: ["path"] }, { required: ["url"] } ] }, CodeBlock: { type: "object", additionalProperties: false, required: ["type", "code"], properties: { type: { const: "codeBlock" }, code: { type: "string" }, language: { type: "string" }, showLineNumbers: { type: "boolean", default: false }, theme: { enum: ["default", "dark", "light", "github"], default: "default" }, fontSize: { type: "number", default: 10 }, fontFamily: { type: "string", default: "Consolas" }, title: { type: "string" }, caption: { type: "string" } } }, List: { type: "object", additionalProperties: false, required: ["type", "items"], properties: { type: { const: "list" }, ordered: { type: "boolean", default: false }, level: { type: "integer", minimum: 0, default: 0 }, items: { type: "array", items: { $ref: "#/$defs/ListItem" } }, numberFormat: { enum: ["decimal", "upperRoman", "lowerRoman", "upperLetter", "lowerLetter"], default: "decimal" }, bulletStyle: { enum: ["bullet", "circle", "square", "dash", "arrow"], default: "bullet" }, startNumber: { type: "integer", minimum: 1, default: 1 } } }, ListItem: { type: "object", additionalProperties: false, required: ["children"], properties: { children: { $ref: "#/$defs/Inlines" }, level: { type: "integer", minimum: 0, default: 0 }, subList: { $ref: "#/$defs/List" } } }, PageBreak: { type: "object", additionalProperties: false, required: ["type"], properties: { type: { const: "pageBreak" }, breakType: { enum: ["page", "section", "column"], default: "page" } } }, HorizontalRule: { type: "object", additionalProperties: false, required: ["type"], properties: { type: { const: "horizontalRule" }, style: { type: "string", enum: ["single", "double", "thick", "thin", "dotted", "dashed"], default: "single" }, color: { type: "string", default: "#000000" }, size: { type: "number", default: 1 }, alignment: { type: "string", enum: ["left", "center", "right"], default: "center" }, width: { type: "number" } // percentage width, 0-100 } }, Blockquote: { type: "object", additionalProperties: false, required: ["type", "children"], properties: { type: { const: "blockquote" }, children: { type: "array", items: { $ref: "#/$defs/Block" } }, style: { type: "string", enum: ["default", "emphasized", "minimal"], default: "default" }, borderColor: { type: "string", default: "#cccccc" }, backgroundColor: { type: "string" }, leftIndent: { type: "number", default: 720 } // 0.5 inch } }, InfoBox: { type: "object", additionalProperties: false, required: ["type", "boxType", "children"], properties: { type: { const: "infoBox" }, boxType: { type: "string", enum: ["info", "warning", "error", "success", "note"], default: "info" }, title: { type: "string" }, children: { type: "array", items: { $ref: "#/$defs/Block" } }, icon: { type: "boolean", default: true }, customColors: { type: "object", additionalProperties: false, properties: { backgroundColor: { type: "string" }, borderColor: { type: "string" }, textColor: { type: "string" } } } } }, TextBox: { type: "object", additionalProperties: false, required: ["type", "children"], properties: { type: { const: "textBox" }, children: { type: "array", items: { $ref: "#/$defs/Block" } }, width: { type: "number" }, height: { type: "number" }, position: { type: "object", additionalProperties: false, properties: { x: { type: "number" }, y: { type: "number" }, anchor: { type: "string", enum: ["page", "margin", "paragraph"], default: "paragraph" } } }, borders: { type: "object", additionalProperties: false, properties: { style: { type: "string", enum: ["single", "double", "thick", "thin", "dotted", "dashed", "none"], default: "single" }, color: { type: "string", default: "#000000" }, size: { type: "number", default: 1 } } }, fill: { type: "object", additionalProperties: false, properties: { color: { type: "string" }, transparency: { type: "number", minimum: 0, maximum: 100, default: 0 } } } } }, HeaderFooterContent: { type: "object", additionalProperties: false, properties: { alignment: { enum: ["left", "center", "right"], default: "left" }, children: { type: "array", items: { $ref: "#/$defs/HeaderFooterElement" } } } }, HeaderFooterElement: { type: "object", oneOf: [ { $ref: "#/$defs/HeaderFooterText" }, { $ref: "#/$defs/PageNumber" }, { $ref: "#/$defs/HeaderFooterImage" }, { $ref: "#/$defs/CurrentDate" }, { $ref: "#/$defs/DocumentTitle" } ] }, HeaderFooterText: { type: "object", additionalProperties: false, required: ["type", "text"], properties: { type: { const: "text" }, text: { type: "string" }, bold: { type: "boolean", default: false }, italics: { type: "boolean", default: false }, underline: { type: "boolean", default: false }, size: { type: "number", default: 12 }, color: { type: "string", default: "#000000" }, fontFamily: { type: "string", default: "Arial" } } }, PageNumber: { type: "object", additionalProperties: false, required: ["type"], properties: { type: { const: "pageNumber" }, format: { enum: ["decimal", "upperRoman", "lowerRoman", "upperLetter", "lowerLetter"], default: "decimal" }, start: { type: "number", default: 1 }, bold: { type: "boolean", default: false }, italics: { type: "boolean", default: false }, size: { type: "number", default: 12 }, color: { type: "string", default: "#000000" } } }, HeaderFooterImage: { type: "object", additionalProperties: false, required: ["type"], oneOf: [ { required: ["data", "format"] }, { required: ["path"] }, { required: ["url"] } ], properties: { type: { const: "image" }, data: { type: "string", description: "base64-encoded image data" }, format: { enum: ["png", "jpeg", "jpg"] }, path: { type: "string", description: "local file path to image" }, url: { type: "string", description: "URL to download image from" }, width: { type: "number" }, height: { type: "number" } } }, CurrentDate: { type: "object", additionalProperties: false, required: ["type"], properties: { type: { const: "currentDate" }, format: { type: "string", default: "MM/dd/yyyy", description: "Date format string" }, bold: { type: "boolean", default: false }, italics: { type: "boolean", default: false }, size: { type: "number", default: 12 }, color: { type: "string", default: "#000000" } } }, DocumentTitle: { type: "object", additionalProperties: false, required: ["type"], properties: { type: { const: "documentTitle" }, bold: { type: "boolean", default: false }, italics: { type: "boolean", default: false }, size: { type: "number", default: 12 }, color: { type: "string", default: "#000000" } } }, FootnoteReference: { type: "object", additionalProperties: false, required: ["type", "footnoteId"], properties: { type: { const: "footnoteReference" }, footnoteId: { type: "string" }, numberFormat: { enum: ["decimal", "upperRoman", "lowerRoman", "upperLetter", "lowerLetter", "symbol"], default: "decimal" }, customMark: { type: "string", description: "Custom reference mark (overrides numberFormat)" } } }, NoteContent: { type: "object", additionalProperties: false, required: ["children"], properties: { children: { type: "array", items: { $ref: "#/$defs/Block" } }, separator: { type: "string", enum: ["line", "none", "continuation"], default: "line", description: "Separator style before the note" } } } } } as const;
- src/docx-utils.ts:105-112 (helper)DocRegistry.create(): Synchronous helper method called by the handler to validate the input JSON against DocxSchema, convert JSON to a docx Document object using jsonToDoc, create a ManagedDoc entry, and store it in the registry.create(id: DocId, json: DocxJSON): ManagedDoc { this.assertValid(json); const doc = this.jsonToDoc(json); const now = new Date().toISOString(); const managed: ManagedDoc = { id, json, doc, createdAt: now, updatedAt: now }; this.docs.set(id, managed); return managed; }
- src/docx-utils.ts:119-126 (helper)DocRegistry.createAsync(): Asynchronous variant for cases with local file paths or remote image URLs in the JSON; uses jsonToDocAsync to handle image loading/downloading.async createAsync(id: DocId, json: DocxJSON): Promise<ManagedDoc> { this.assertValid(json); const doc = await this.jsonToDocAsync(json); const now = new Date().toISOString(); const managed: ManagedDoc = { id, json, doc, createdAt: now, updatedAt: now }; this.docs.set(id, managed); return managed; }