Content
# Document Operations MCP Server
[](https://www.npmjs.com/package/doc-ops-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/doc-ops-mcp)
**Language / 语言**: [English](README.md) | [中文](README_zh.md)
> **Document Operations MCP Server** - A universal MCP server for document processing, conversion, and automation. Handle PDF, DOCX, HTML, Markdown, and more through a unified API and toolset.
## Demo
### Video
<https://github.com/user-attachments/assets/43dfeeec-8097-413e-8519-a7de98e31136>
In this demo, we showcase how to:
- Configure doc-ops-mcp in MCP clients
- Convert DOCX documents to PDF format
- Add default watermarks to converted PDF files
## Table of Contents
1. [Quick Start](#1-quick-start)
2. [System Architecture](#2-system-architecture)
3. [Optional Integration](#3-optional-integration)
4. [Features](#4-features)
5. [Open Source Licenses](#5-open-source-licenses)
6. [Future Roadmap](#6-future-roadmap)
7. [Docker Deployment](#7-docker-deployment)
8. [Development Guide](#8-development-guide)
9. [Troubleshooting](#9-troubleshooting)
10. [Contributing](#10-contributing)
## 1. Quick Start
First, add the Document Operations MCP server to your MCP client.
**Standard config** works in most MCP clients:
```json
{
"mcpServers": {
"doc-ops-mcp": {
"command": "npx",
"args": ["-y", "doc-ops-mcp"],
"env": {
"OUTPUT_DIR": "/path/to/your/output/directory",
"CACHE_DIR": "/path/to/your/cache/directory",
}
}
}
}
```
<details>
<summary>Claude Desktop</summary>
Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
</details>
<details>
<summary>VS Code</summary>
Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above.
</details>
<details>
<summary>Cursor</summary>
Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx -y doc-ops-mcp`.
</details>
<details>
<summary>Other MCP Clients</summary>
For other MCP clients, use the standard config above and refer to your client's documentation for MCP server installation.
</details>
### Configuration
The Document Operations MCP server supports configuration through environment variables. These can be provided in the MCP client configuration as part of the `"env"` object:
```json
{
"mcpServers": {
"doc-ops-mcp": {
"command": "npx",
"args": ["-y", "doc-ops-mcp"],
"env": {
"OUTPUT_DIR": "/path/to/your/output/directory",
"CACHE_DIR": "/path/to/your/cache/directory",
"WATERMARK_IMAGE": "/path/to/watermark.png",
"QR_CODE_IMAGE": "/path/to/qrcode.png"
}
}
}
}
```
### Supported Document Operations
| Format | Convert to PDF | Convert to DOCX | Convert to HTML | Convert to Markdown | Content Rewriting | Watermark/QR Code |
|--------|----------------|-----------------|-----------------|---------------------|-------------------|-------------------|
| **PDF** | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
| **DOCX** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| **HTML** | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
| **Markdown** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
**Rewriting Features:**
- **Content Replacement**: Support batch text replacement and regular expression replacement
- **Format Adjustment**: Modify document structure, heading levels, and style formatting
- **Smart Rewriting**: Content optimization while preserving original document format
### Usage Examples
**Format Conversion:**
```
Convert /Users/docs/report.docx to PDF
Convert /Users/docs/article.md to HTML
Convert /Users/docs/presentation.html to DOCX
Convert /Users/docs/readme.md to PDF (with theme styling)
```
**Document Rewriting:**
```
Rewrite company names in /Users/docs/contract.md
Batch replace terminology in /Users/docs/manual.docx
Adjust heading levels in /Users/docs/article.html
Update dates and version numbers in /Users/docs/policy.md
```
**PDF Enhancement:**
```
Add watermark to /Users/docs/document.pdf
Add QR code to /Users/docs/report.pdf
Add company logo watermark to /Users/docs/invoice.pdf
```
### Environment Variables
The server supports environment variables for controlling output paths and PDF enhancement features:
#### Core Directories
- **`OUTPUT_DIR`**: Controls where all generated files are saved (default: `~/Documents`)
- **`CACHE_DIR`**: Directory for temporary and cache files (default: `~/.cache/doc-ops-mcp`)
#### PDF Enhancement Features
- **`WATERMARK_IMAGE`**: Default watermark image path for PDF files
- Automatically added to all PDF conversions
- Supported formats: PNG, JPG
- If not set, default text watermark "doc-ops-mcp" will be used
- **`QR_CODE_IMAGE`**: Default QR code image path for PDF files
- Added to PDFs only when explicitly requested (`addQrCode=true`)
- Supported formats: PNG, JPG
- If not set, QR code functionality will be unavailable
**Output Path Rules:**
1. If `outputPath` is not provided → files saved to `OUTPUT_DIR` with auto-generated names
2. If `outputPath` is relative → resolved relative to `OUTPUT_DIR`
3. If `outputPath` is absolute → used as-is, ignoring `OUTPUT_DIR`
See [OUTPUT_PATH_CONTROL.md](./OUTPUT_PATH_CONTROL.md) for detailed documentation.
## 2. System Architecture
Document Operations MCP Server adopts a pure JavaScript architecture design, providing complete document processing capabilities:
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Client Layer │
│ (Claude Desktop, Cursor, VS Code, etc.) │
└─────────────────────┬───────────────────────────────────────┘
│ JSON-RPC 2.0
┌─────────────────────┴───────────────────────────────────────┐
│ Doc-Ops-MCP Server │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Tool Router │ │ Request │ │ Response │ │
│ │ & Handler │ │ Validator │ │ Formatter │ │
│ └────────┬────────┘ └────────┬────────┘ └──────┬──────┘ │
│ │ │ │ │
│ ┌────────┴────────────────────┴──────────────────┴─────┐ │
│ │ Document Processing Engine │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Document │ │ Format │ │ Style │ │ │
│ │ │ Reader │ │ Converter │ │ Processor │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ PDF │ │ Watermark/ │ │ Conversion │ │ │
│ │ │ Enhancement │ │ QR Code │ │ Planner │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
└────┴───────────────────────────────────────────────────────┴─┘
│
┌───────────────────────────┴─────────────────────────────────┐
│ Core Dependencies Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ pdf-lib │ │word-extractor│ │ marked │ │
│ │ (PDF Tools) │ │(DOCX Reader)│ │ (Markdown) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ cheerio │ │ jszip │ │ docx │ │
│ │(HTML Parser)│ │(ZIP Handler)│ │(DOCX Gen.) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ xml2js │ │Custom OOXML │ │
│ │(XML Parser) │ │ Parser │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Architecture Overview
**Core Features**:
- Pure JavaScript implementation with no external system dependencies
- Complete document reading, conversion, and style processing capabilities
- Built-in PDF watermark and QR code addition functionality
- Intelligent conversion planning and path optimization
**Conversion Flow**:
- **Direct Conversion**: Supports direct conversion between most formats
- **Multi-step Conversion**: Complex conversions achieved through intermediate formats
- **Style Preservation**: Uses OOXML parser to ensure complete style integrity
## 3. Optional Integration
This server can work with `playwright-mcp` for enhanced PDF conversion capabilities. Please refer to the official `playwright-mcp` documentation for detailed configuration.
### 🔧 PDF Conversion Workflow
This server supports complete PDF conversion functionality:
1. **Document Parsing**: Use OOXML parser to ensure complete style preservation
2. **Format Conversion**: Convert documents to high-quality HTML format
3. **PDF Generation**: Built-in converter or optionally work with `playwright-mcp`
4. **Enhancement Processing**: Automatically add watermarks and QR codes (if configured)
### How It Works
This server uses intelligent conversion architecture:
1. **Smart Planning**: `plan_conversion` analyzes conversion requirements and selects optimal paths
2. **Format Conversion**: Use specialized converters to handle various document formats
3. **Style Preservation**: Ensure style integrity through OOXML parser
4. **Enhancement Processing**: Automatically add watermarks, QR codes and other enhancements
5. **Optional Integration**: Support working with `playwright-mcp` for enhanced capabilities
## 4. Features
### MCP Tools
#### Core Document Tools
| Tool Name | Description | Input Parameters | External Dependencies |
|-----------|-------------|------------------|----------------------|
| `read_document` | Read document content | `filePath`: Document path<br>`extractMetadata`: Extract metadata<br>`preserveFormatting`: Preserve formatting | None |
| `write_document` | Write document content | `content`: Document content<br>`outputPath`: Output file path<br>`encoding`: File encoding | None |
| `convert_document` | Smart document conversion | `inputPath`: Input file path<br>`outputPath`: Output file path<br>`preserveFormatting`: Preserve formatting | None |
| `plan_conversion` | Conversion planner | `sourceFormat`: Source format<br>`targetFormat`: Target format<br>`preserveStyles`: Preserve styles<br>`quality`: Conversion quality | None |
##### **read_document**
Read various document formats including PDF, DOCX, DOC, HTML, MD, and more.
**Parameters:**
- `filePath` (string, required) - Document path to read
- `extractMetadata` (boolean, optional) - Extract document metadata, defaults to `false`
- `preserveFormatting` (boolean, optional) - Preserve formatting (HTML output), defaults to `false`
##### **write_document**
Write content to document files in specified formats.
**Parameters:**
- `content` (string, required) - Content to write
- `outputPath` (string, optional) - Output file path (auto-generated if not provided)
- `encoding` (string, optional) - File encoding, defaults to `utf-8`
##### **convert_document**
Convert documents between formats with enhanced style preservation.
**Parameters:**
- `inputPath` (string, required) - Input file path
- `outputPath` (string, optional) - Output file path (auto-generated if not provided)
- `preserveFormatting` (boolean, optional) - Preserve formatting, defaults to `true`
- `useInternalPlaywright` (boolean, optional) - Use built-in Playwright for PDF conversion, defaults to `false`
##### **convert_docx_to_pdf**
Convert DOCX to PDF with automatic watermark addition (if configured).
**Parameters:**
- `docxPath` (string, required) - DOCX file path
- `outputPath` (string, optional) - Output PDF path (auto-generated if not provided)
- `addQrCode` (boolean, optional) - Whether to add QR code, defaults to `false`
- `preserveFormatting` (boolean, optional) - Preserve original formatting, defaults to `true`
- `chineseFont` (string, optional) - Chinese font, defaults to `Microsoft YaHei`
##### **convert_markdown_to_pdf**
Convert Markdown to PDF with automatic watermark addition (if configured).
**Parameters:**
- `markdownPath` (string, required) - Markdown file path
- `outputPath` (string, optional) - Output PDF path (auto-generated if not provided)
- `theme` (string, optional) - Theme style, defaults to `"github"`
- `includeTableOfContents` (boolean, optional) - Include table of contents, defaults to `false`
- `addQrCode` (boolean, optional) - Whether to add QR code, defaults to `false`
##### **convert_markdown_to_html**
Convert Markdown to HTML.
**Parameters:**
- `markdownPath` (string, required) - Markdown file path
- `outputPath` (string, optional) - Output HTML path (auto-generated if not provided)
- `theme` (string, optional) - Theme style, defaults to `"github"`
- `includeTableOfContents` (boolean, optional) - Include table of contents, defaults to `false`
##### **convert_markdown_to_docx**
Convert Markdown to DOCX.
**Parameters:**
- `markdownPath` (string, required) - Markdown file path
- `outputPath` (string, optional) - Output DOCX path (auto-generated if not provided)
##### **convert_html_to_markdown**
Convert HTML to Markdown.
**Parameters:**
- `htmlPath` (string, required) - HTML file path
- `outputPath` (string, optional) - Output Markdown path (auto-generated if not provided)
##### **plan_conversion**
🎯 Smart Conversion Planner - Analyze conversion requirements and generate optimal conversion plans.
**Parameters:**
- `sourceFormat` (string, required) - Source file format (pdf, docx, html, markdown, md, txt, doc)
- `targetFormat` (string, required) - Target file format (pdf, docx, html, markdown, md, txt, doc)
- `sourceFile` (string, optional) - Source file path (for generating specific conversion parameters)
- `preserveStyles` (boolean, optional) - Whether to preserve style formatting, defaults to `true`
- `includeImages` (boolean, optional) - Whether to include images, defaults to `true`
- `theme` (string, optional) - Conversion theme, defaults to `github`
- `quality` (string, optional) - Conversion quality requirement (fast, balanced, high), defaults to `balanced`
##### **process_pdf_post_conversion**
**Parameters:**
- `playwrightPdfPath` (string, required) - Generated PDF file path
- `targetPath` (string, optional) - Target PDF file path (auto-generated if not provided)
- `addWatermark` (boolean, optional) - Whether to add watermark, defaults to `false`
- `addQrCode` (boolean, optional) - Whether to add QR code, defaults to `false`
- `watermarkImage` (string, optional) - Watermark image path
- `qrCodePath` (string, optional) - QR code image path
#### PDF Enhancement Tools
##### **add_watermark**
🎨 PDF Watermark Addition Tool - Add image or text watermarks to PDF documents.
**Parameters:**
- `pdfPath` (string, required) - PDF file path
- `watermarkImage` (string, optional) - Watermark image path (PNG/JPG)
- `watermarkText` (string, optional) - Watermark text content
- `watermarkImageScale` (number, optional) - Image scale ratio, defaults to `0.25`
- `watermarkImageOpacity` (number, optional) - Image opacity, defaults to `0.6`
- `watermarkImagePosition` (string, optional) - Image position, defaults to `fullscreen`
##### **add_qrcode**
📱 PDF QR Code Addition Tool - Add QR codes to PDF documents.
**Parameters:**
- `pdfPath` (string, required) - PDF file path
- `qrCodePath` (string, optional) - QR code image path
- `qrScale` (number, optional) - QR code scale ratio, defaults to `0.15`
- `qrOpacity` (number, optional) - QR code opacity, defaults to `1.0`
- `qrPosition` (string, optional) - QR code position, defaults to `bottom-center`
- `addText` (boolean, optional) - Whether to add explanatory text, defaults to `true`
## System Requirements
### System Requirements
- **Node.js** ≥ 18.0.0
- **Zero external system dependencies** - All processing via npm packages
- **Optional Integration**: playwright-mcp for enhanced PDF conversion
### Core Technology Stack
- **pdf-lib** - PDF operations and enhancement
- **word-extractor** - DOCX document text extraction
- **marked** - Markdown parsing and rendering
- **cheerio** - HTML parsing and manipulation
- **docx** - DOCX document generation
- **jszip** - ZIP file processing
- **xml2js** - XML parsing and conversion
- **Custom OOXML Parser** - Advanced DOCX style preservation
### Installation
```bash
# Global installation
npm install -g doc-ops-mcp
# Or using pnpm
pnpm add -g doc-ops-mcp
# Or using bun
bun add -g doc-ops-mcp
```
### Architecture Components
- **MCP Server Core**: Handles JSON-RPC 2.0 communication and tool registration
- **Smart Router**: Routes requests to optimal processing modules
- **Conversion Engine**: Contains specialized converters for different document types
- **Style Processor**: Ensures style preservation during format conversion
- **Security Module**: Provides path validation and content security handling
## 5. Open Source Licenses
### Project License
- **This Project**: MIT License
- **Compatibility**: Available for commercial and non-commercial use
### Third-Party Dependencies
| Library | Version | License | Purpose |
|---------|---------|---------|----------|
| **pdf-lib** | ^1.17.1 | MIT | PDF document manipulation |
| **word-extractor** | ^1.0.4 | MIT | DOCX document text extraction |
| **marked** | ^15.0.12 | MIT | Markdown parsing and rendering |
| **cheerio** | ^1.0.0-rc.12 | MIT | HTML parsing and manipulation |
| **docx** | ^9.5.1 | Apache-2.0 | DOCX document generation |
| **jszip** | ^3.10.1 | MIT | ZIP file processing |
| **xml2js** | ^0.6.2 | MIT | XML parsing and conversion |
### License Compatibility
- ✅ **Commercial Use**: All dependencies support commercial use
- ✅ **Distribution**: Free to distribute and modify
- ✅ **Patent Protection**: Apache-2.0 provides patent protection
- ⚠️ **Notice**: Original license notices must be retained
## 6. Future Roadmap
### Core Features
- 🔄 **Enhanced Conversion Quality**: Improve style preservation for complex documents
- 📊 **Excel Support**: Complete Excel read/write and conversion functionality
- 🎨 **Template System**: Support for custom document templates
- 🔍 **OCR Integration**: Image text recognition capabilities
### System Improvements
- 🌐 **Multi-language Support**: Internationalization and localization
- 🔐 **Security Enhancements**: Document encryption and access control
- ⚡ **Performance Optimization**: Large file handling and memory optimization
- 🔌 **Plugin System**: Extensible processor architecture
### Version Roadmap
- **v2.0**: Complete Excel support and template system
- **v3.0**: OCR integration and multi-language support
- **v4.0**: Advanced security features and plugin system
## 7. Docker Deployment
### Quick Start
#### Using Pre-built Image
```bash
# Pull the latest image
docker pull docops/doc-ops-mcp:latest
# Run with default configuration
docker run -d \
--name doc-ops-mcp \
-p 3000:3000 \
docops/doc-ops-mcp:latest
```
#### Building from Source
```bash
# Clone the repository
git clone https://github.com/JefferyMunoz/doc-ops-mcp.git
cd doc-ops-mcp
# Build the Docker image
docker build -t doc-ops-mcp .
# Run the container
docker run -d \
--name doc-ops-mcp \
-p 3000:3000 \
-v $(pwd)/documents:/app/documents \
doc-ops-mcp
```
### Docker Compose Deployment
Create a `docker-compose.yml` file:
```yaml
version: '3.8'
services:
doc-ops-mcp:
image: docops/doc-ops-mcp:latest
container_name: doc-ops-mcp
ports:
- "3000:3000"
volumes:
- ./documents:/app/documents
- ./config:/app/config
environment:
- NODE_ENV=production
- PORT=3000
restart: unless-stopped
# Optional: Add Nginx for reverse proxy
nginx:
image: nginx:alpine
container_name: doc-ops-nginx
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- doc-ops-mcp
restart: unless-stopped
```
### Environment Variables
| Variable | Description | Default |
|----------|-------------|----------|
| `PORT` | Server port | `3000` |
| `NODE_ENV` | Environment mode | `production` |
| `LOG_LEVEL` | Logging level | `info` |
| `MAX_FILE_SIZE` | Maximum file size (MB) | `50` |
### Volume Mounts
Mount local directories for persistent storage:
```bash
# Documents directory for file processing
docker run -d \
--name doc-ops-mcp \
-p 3000:3000 \
-v $(pwd)/documents:/app/documents \
-v $(pwd)/output:/app/output \
doc-ops-mcp
```
### Docker Configuration Examples
#### Production Deployment
```bash
# Production setup with Docker Swarm
docker swarm init
docker stack deploy -c docker-compose.yml doc-ops
# Scale the service
docker service scale doc-ops_mcp=3
```
### Health Checks
The container includes built-in health checks:
```bash
# Check container health
docker ps
# View health check logs
docker inspect --format='{{.State.Health.Status}}' doc-ops-mcp
# Manual health check
docker exec doc-ops-mcp curl -f http://localhost:3000/health || exit 1
```
## 8. Development Guide
### Local Development
```bash
# Clone the repository
git clone https://github.com/your-org/doc-ops-mcp.git
cd doc-ops-mcp
# Install dependencies
npm install
# Run in development mode
npm run dev
# Build the project
npm run build
# Run tests
npm test
```
### Project Structure
```
src/
├── index.ts # MCP server entry point
├── tools/ # Tool implementations
│ ├── documentConverter.ts
│ ├── pdfTools.ts
│ └── ...
├── types/ # Type definitions
└── utils/ # Utility functions
```
### Adding New Tools
1. Create a new tool file in `src/tools/`
2. Implement the tool logic
3. Register the tool in `src/index.ts`
4. Add test cases
5. Update documentation
## 9. Troubleshooting
### Common Issues
1. **Port conflicts**: Change the host port in docker-compose.yml
2. **Permission issues**: Ensure volume mounts have correct permissions
3. **Memory issues**: Increase Docker memory allocation
### Debug Mode
```bash
# Run with debug logging
docker run -d \
--name doc-ops-mcp \
-p 3000:3000 \
-e LOG_LEVEL=debug \
doc-ops-mcp
# View logs
docker logs -f doc-ops-mcp
```
## 10. Contributing
### How to Contribute
1. **Fork the Project**
2. **Create a Feature Branch** (`git checkout -b feature/AmazingFeature`)
3. **Commit Your Changes** (`git commit -m 'Add some AmazingFeature'`)
4. **Push to the Branch** (`git push origin feature/AmazingFeature`)
5. **Open a Pull Request**
#### Intellectual Property License
**By submitting a Pull Request, you agree that all contributions submitted through Pull Requests will be licensed under the MIT License.** This means:
- You grant the project maintainers and users the right to use, modify, and distribute your contributions under the MIT License
- You confirm that you have the right to make these contributions
- You understand that your contributions will become part of the open source project
- You waive any claims to exclusive ownership of the contributed code
If you cannot agree to these terms, please do not submit a Pull Request.
### Code Standards
- Use TypeScript
- Follow ESLint configuration
- Add appropriate tests
- Update relevant documentation
### Reporting Issues
- Use [GitHub Issues](https://github.com/your-org/doc-ops-mcp/issues)
- Provide detailed error information and reproduction steps
- Include system environment information
### License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
