DOCX MCP Server

Instructions

Implementation Reference

• src/index.ts:78-133 (handler)

  Handler function that processes the DOCX file conversion to HTML using mammoth library. Resolves file path, handles options for styles, performs conversion, extracts warnings/errors, and returns structured JSON response or error.

  async ({ file_path, include_styles = true }) => {
    try {
      const absolutePath = path.resolve(file_path)
  
      if (!fs.existsSync(absolutePath)) {
        throw new Error(`File not found: ${absolutePath}`)
      }
  
      const options = include_styles
        ? {}
        : {
            styleMap: [
              "p[style-name='Heading 1'] => h1:fresh",
              "p[style-name='Heading 2'] => h2:fresh",
              "p[style-name='Heading 3'] => h3:fresh",
              "r[style-name='Strong'] => strong",
              "r[style-name='Emphasis'] => em",
            ],
          }
  
      const result = await mammoth.convertToHtml(
        { path: absolutePath },
        options
      )
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                html: result.value,
                messages: result.messages,
                warnings: result.messages.filter(
                  (m: any) => m.type === 'warning'
                ),
                errors: result.messages.filter((m: any) => m.type === 'error'),
              },
              null,
              2
            ),
          },
        ],
      }
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error converting to HTML: ${(error as Error).message}`,
          },
        ],
        isError: true,
      }
    }
  }

• src/index.ts:71-77 (schema)

  Zod input schema defining parameters: required file_path (string) and optional include_styles (boolean).

  {
    file_path: z.string().describe('Path to the .docx file'),
    include_styles: z
      .boolean()
      .optional()
      .describe('Include inline styles (default: true)'),
  },

• src/index.ts:68-134 (registration)

  MCP server.tool registration call that defines the tool name, description, input schema, and references the handler function.

  server.tool(
    'convert_to_html',
    'Convert DOCX file to HTML with formatting preserved',
    {
      file_path: z.string().describe('Path to the .docx file'),
      include_styles: z
        .boolean()
        .optional()
        .describe('Include inline styles (default: true)'),
    },
    async ({ file_path, include_styles = true }) => {
      try {
        const absolutePath = path.resolve(file_path)
  
        if (!fs.existsSync(absolutePath)) {
          throw new Error(`File not found: ${absolutePath}`)
        }
  
        const options = include_styles
          ? {}
          : {
              styleMap: [
                "p[style-name='Heading 1'] => h1:fresh",
                "p[style-name='Heading 2'] => h2:fresh",
                "p[style-name='Heading 3'] => h3:fresh",
                "r[style-name='Strong'] => strong",
                "r[style-name='Emphasis'] => em",
              ],
            }
  
        const result = await mammoth.convertToHtml(
          { path: absolutePath },
          options
        )
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  html: result.value,
                  messages: result.messages,
                  warnings: result.messages.filter(
                    (m: any) => m.type === 'warning'
                  ),
                  errors: result.messages.filter((m: any) => m.type === 'error'),
                },
                null,
                2
              ),
            },
          ],
        }
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error converting to HTML: ${(error as Error).message}`,
            },
          ],
          isError: true,
        }
      }
    }
  )