doc-ops-mcp
MCP server for seamless document format conversion and processing
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Tele-AI/doc-ops-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Tele-AI/doc-ops-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/tele-ai--doc-ops-mcp)HTML
<a href="/listings/tele-ai--doc-ops-mcp"><img src="/api/listings/tele-ai--doc-ops-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
First, add the Document Operations MCP server to your MCP client.
**Standard config** works in most MCP clients:
{
"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:
{
"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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 679 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.