# 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

```bash
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:

```bash
mcp-document-converter
```

### Programmatically

```bash
node src/server.js
```

### With npx

```bash
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
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "test", "version": "1.0.0" }
  }
}
```

### List Tools
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

### Call Tool
```json
{
  "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
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```json
{
  "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:
```bash
npm test
```

### DOCX Conversion Tests
Test document conversion functionality:
```bash
npm run test:docx
```

### Manual Testing
Test the server by sending JSON-RPC messages:
```bash
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.