MCP Document Converter

A lightweight Model Context Protocol (MCP) server that provides DOCX to Markdown conversion and image analysis tools for VS Code Copilot. Focused on document processing without heavy browser automation dependencies.

Installation

npm install -g mcp-document-converter

Features

Document Conversion Tools

• convert_docx_to_markdown - Convert DOCX files to Markdown with formatting preservation
• Extract and save embedded images from documents
• Preserve formatting (bold, italic, headers, lists, etc.)
• Generate clean Markdown output with metadata

Core Capabilities

• Complete formatting preservation (headers, tables, lists, colors)
• Image extraction with proper file naming
• HTML entity escaping for proper markdown display
• JSON-RPC over stdio (standard MCP protocol)
• Compatible with VS Code Copilot and other MCP clients
• Lightweight with minimal dependencies

Image Analysis Tools

• read_image_info - Read image metadata and dimensions
• analyze_images_directory - Analyze all images in a folder
• create_image_viewer - Generate HTML viewer for images

Requirements

• Node.js 14+
• Dependencies: mammoth, turndown, turndown-plugin-gfm

Usage

As a Global Command

After installing globally:

mcp-document-converter

Programmatically

node src/server.js

With npx

npx mcp-browser-opener

The server will listen for JSON-RPC messages on stdin and respond on stdout.

MCP Protocol

The server implements the standard MCP protocol using JSON-RPC over stdio:

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "test", "version": "1.0.0" }
  }
}

List Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Call Tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "open_browser",
    "arguments": {
      "query": "How to use VS Code Copilot"
    }
  }
}

Call browser_input_text Tool

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "browser_input_text",
    "arguments": {
      "url": "https://www.google.com",
      "selector": "textarea[name=\"q\"]",
      "text": "automated search query",
      "submit": true,
      "headless": false,
      "screenshot": true
    }
  }
}

Tool: open_browser

Opens a Chrome browser window with optional URL or search query.

Parameters:

• url (optional): Specific URL to open
• query (optional): Search query for Google search

Example:

{
  "name": "open_browser",
  "arguments": {
    "query": "JavaScript tutorial"
  }
}

Tool: browser_input_text

Controls a headless browser to input text into web forms and elements using Puppeteer.

Parameters:

• url (required): URL to navigate to
• selector (required): CSS selector for the input element (e.g., 'input[name="search"]', '#searchbox')
• text (required): Text to input into the element
• submit (optional): Whether to submit the form after inputting text (default: false)
• headless (optional): Whether to run browser in headless mode (default: true)
• screenshot (optional): Whether to take a screenshot after the action (default: false)

Example:

{
  "name": "browser_input_text",
  "arguments": {
    "url": "https://example.com/form",
    "selector": "#email",
    "text": "test@example.com",
    "submit": false,
    "headless": true,
    "screenshot": true
  }
}

Tool: convert_docx_to_markdown

Converts DOCX documents to Markdown format while preserving formatting and extracting embedded images.

Parameters:

• inputFile (required): Path to the input DOCX file
• outputFile (optional): Path for the output Markdown file (returns content if not specified)
• extractImages (optional): Whether to extract and save images (default: true)
• imageDir (optional): Directory name for extracted images (default: 'images')
• preserveFormatting (optional): Whether to preserve formatting (default: true)

Example:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "convert_docx_to_markdown",
    "arguments": {
      "inputFile": "document.docx",
      "outputFile": "document.md", 
      "extractImages": true,
      "imageDir": "images",
      "preserveFormatting": true
    }
  }
}

Features:

• Preserves text formatting (bold, italic, strikethrough)
• Converts headers, lists, and blockquotes
• Extracts embedded images to separate files
• Generates relative image links in Markdown
• Adds conversion metadata header
• Handles complex document structures

Integration with VS Code Copilot

This server can be configured as an MCP server in VS Code to provide browser automation and document conversion capabilities. Add it to your MCP configuration:

{
  "mcpServers": {
    "browser-opener": {
      "command": "mcp-browser-opener"
    }
  }
}

Development

1. Clone the repository
2. Install dependencies: npm install
3. Run the server: npm start or node src/server.js

Project Structure

• src/ - Source code and toolset modules
• test/ - All test files, sample data, and generated outputs
• test/docx_convertion/ - Sample DOCX files for testing document conversion

Testing

Basic Tests

Run all basic tool tests:

npm test

DOCX Conversion Tests

Test document conversion functionality:

npm run test:docx

Manual Testing

Test the server by sending JSON-RPC messages:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | mcp-browser-opener

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.