DOCX MCP Server

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;
}

Tool Definition Quality

A4.1/5.0

Behavior3/5

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 states the tool creates a document and returns an ID, which implies a write operation. It also mentions image support options (data, path, url with fallback), adding useful context about capabilities. However, it doesn't address error conditions, performance characteristics, or what happens if the JSON is malformed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely efficient with only two sentences. The first sentence covers the core purpose and return value, while the second provides crucial prerequisite guidance and specific implementation details about image support. Every word serves a clear purpose with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complex nested schema (with 1 parameter but extensive structure) and no output schema, the description does a reasonable job but has gaps. It mentions the prerequisite tool and image support, but doesn't address the broader JSON structure complexity, error handling, or what the returned ID can be used for. For a creation tool with such a complex input, more guidance would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It explains that the single parameter 'json' must follow a specific structure and mentions image support options, which adds meaningful context beyond the bare schema. However, it doesn't detail the full complexity of the JSON structure or mention other content types like tables, lists, or headers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Create a new docx from JSON'), identifies the resource (a docx document), and specifies the return value ('returns an id'). It distinguishes from siblings by focusing on creation from JSON rather than editing, querying, or saving existing documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance to 'Use docx-getSchema first to understand the required JSON structure,' which is crucial context for when to use this tool. However, it doesn't specify when NOT to use it or mention alternatives like docx-open or docx-openFile for working with existing documents.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lihongjie0209/docx-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server