Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tele-ai--doc-ops-mcp/badge.svg)](/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

i

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)

  1. # Document Operations MCP Server
  2. [![npm version](https://img.shields.io/npm/v/doc-ops-mcp.svg)](https://www.npmjs.com/package/doc-ops-mcp)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Downloads](https://img.shields.io/npm/dm/doc-ops-mcp.svg)](https://www.npmjs.com/package/doc-ops-mcp)
  5. **Language / 语言**: [English](README.md) | [中文](README_zh.md)
  6. > **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.
  7. ## Demo
  8. ### Video
  9. <https://github.com/user-attachments/assets/43dfeeec-8097-413e-8519-a7de98e31136>
  10. In this demo, we showcase how to:
  11. - Configure doc-ops-mcp in MCP clients
  12. - Convert DOCX documents to PDF format
  13. - Add default watermarks to converted PDF files
  14. ## Table of Contents
  15. 1. [Quick Start](#1-quick-start)
  16. 2. [System Architecture](#2-system-architecture)
  17. 3. [Optional Integration](#3-optional-integration)
  18. 4. [Features](#4-features)
  19. 5. [Open Source Licenses](#5-open-source-licenses)
  20. 6. [Future Roadmap](#6-future-roadmap)
  21. 7. [Docker Deployment](#7-docker-deployment)
  22. 8. [Development Guide](#8-development-guide)
  23. 9. [Troubleshooting](#9-troubleshooting)
  24. 10. [Contributing](#10-contributing)
  25. ## 1. Quick Start
  26. First, add the Document Operations MCP server to your MCP client.
  27. **Standard config** works in most MCP clients:
  28. ```json
  29. {
  30. "mcpServers": {
  31. "doc-ops-mcp": {
  32. "command": "npx",
  33. "args": ["-y", "doc-ops-mcp"],
  34. "env": {
  35. "OUTPUT_DIR": "/path/to/your/output/directory",
  36. "CACHE_DIR": "/path/to/your/cache/directory",
  37. }
  38. }
  39. }
  40. }
  41. ```
  42. <details>
  43. <summary>Claude Desktop</summary>
  44. Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
  45. </details>
  46. <details>
  47. <summary>VS Code</summary>
  48. Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above.
  49. </details>
  50. <details>
  51. <summary>Cursor</summary>
  52. Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx -y doc-ops-mcp`.
  53. </details>
  54. <details>
  55. <summary>Other MCP Clients</summary>
  56. For other MCP clients, use the standard config above and refer to your client's documentation for MCP server installation.
  57. </details>
  58. ### Configuration
  59. 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:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "doc-ops-mcp": {
  64. "command": "npx",
  65. "args": ["-y", "doc-ops-mcp"],
  66. "env": {
  67. "OUTPUT_DIR": "/path/to/your/output/directory",
  68. "CACHE_DIR": "/path/to/your/cache/directory",
  69. "WATERMARK_IMAGE": "/path/to/watermark.png",
  70. "QR_CODE_IMAGE": "/path/to/qrcode.png"
  71. }
  72. }
  73. }
  74. }
  75. ```
  76. ### Supported Document Operations
  77. | Format | Convert to PDF | Convert to DOCX | Convert to HTML | Convert to Markdown | Content Rewriting | Watermark/QR Code |
  78. |--------|----------------|-----------------|-----------------|---------------------|-------------------|-------------------|
  79. | **PDF** | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
  80. | **DOCX** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
  81. | **HTML** | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
  82. | **Markdown** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
  83. **Rewriting Features:**
  84. - **Content Replacement**: Support batch text replacement and regular expression replacement
  85. - **Format Adjustment**: Modify document structure, heading levels, and style formatting
  86. - **Smart Rewriting**: Content optimization while preserving original document format
  87. ### Usage Examples
  88. **Format Conversion:**
  89. ```
  90. Convert /Users/docs/report.docx to PDF
  91. Convert /Users/docs/article.md to HTML
  92. Convert /Users/docs/presentation.html to DOCX
  93. Convert /Users/docs/readme.md to PDF (with theme styling)
  94. ```
  95. **Document Rewriting:**
  96. ```
  97. Rewrite company names in /Users/docs/contract.md
  98. Batch replace terminology in /Users/docs/manual.docx
  99. Adjust heading levels in /Users/docs/article.html
  100. Update dates and version numbers in /Users/docs/policy.md
  101. ```
  102. **PDF Enhancement:**
  103. ```
  104. Add watermark to /Users/docs/document.pdf
  105. Add QR code to /Users/docs/report.pdf
  106. Add company logo watermark to /Users/docs/invoice.pdf
  107. ```
  108. ### Environment Variables
  109. The server supports environment variables for controlling output paths and PDF enhancement features:
  110. #### Core Directories
  111. - **`OUTPUT_DIR`**: Controls where all generated files are saved (default: `~/Documents`)
  112. - **`CACHE_DIR`**: Directory for temporary and cache files (default: `~/.cache/doc-ops-mcp`)
  113. #### PDF Enhancement Features
  114. - **`WATERMARK_IMAGE`**: Default watermark image path for PDF files
  115. - Automatically added to all PDF conversions
  116. - Supported formats: PNG, JPG
  117. - If not set, default text watermark "doc-ops-mcp" will be used
  118. - **`QR_CODE_IMAGE`**: Default QR code image path for PDF files
  119. - Added to PDFs only when explicitly requested (`addQrCode=true`)
  120. - Supported formats: PNG, JPG
  121. - If not set, QR code functionality will be unavailable
  122. **Output Path Rules:**
  123. 1. If `outputPath` is not provided → files saved to `OUTPUT_DIR` with auto-generated names
  124. 2. If `outputPath` is relative → resolved relative to `OUTPUT_DIR`
  125. 3. If `outputPath` is absolute → used as-is, ignoring `OUTPUT_DIR`
  126. See [OUTPUT_PATH_CONTROL.md](./OUTPUT_PATH_CONTROL.md) for detailed documentation.
  127. ## 2. System Architecture
  128. Document Operations MCP Server adopts a pure JavaScript architecture design, providing complete document processing capabilities:
  129. ```
  130. ┌─────────────────────────────────────────────────────────────┐
  131. │ MCP Client Layer │
  132. │ (Claude Desktop, Cursor, VS Code, etc.) │
  133. └─────────────────────┬───────────────────────────────────────┘
  134. │ JSON-RPC 2.0
  135. ┌─────────────────────┴───────────────────────────────────────┐
  136. │ Doc-Ops-MCP Server │
  137. │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
  138. │ │ Tool Router │ │ Request │ │ Response │ │
  139. │ │ & Handler │ │ Validator │ │ Formatter │ │
  140. │ └────────┬────────┘ └────────┬────────┘ └──────┬──────┘ │
  141. │ │ │ │ │
  142. │ ┌────────┴────────────────────┴──────────────────┴─────┐ │
  143. │ │ Document Processing Engine │ │
  144. │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
  145. │ │ │ Document │ │ Format │ │ Style │ │ │
  146. │ │ │ Reader │ │ Converter │ │ Processor │ │ │
  147. │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
  148. │ │ │ │
  149. │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
  150. │ │ │ PDF │ │ Watermark/ │ │ Conversion │ │ │
  151. │ │ │ Enhancement │ │ QR Code │ │ Planner │ │ │
  152. │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
  153. └────┴───────────────────────────────────────────────────────┴─┘
  154. │
  155. ┌───────────────────────────┴─────────────────────────────────┐
  156. │ Core Dependencies Layer │
  157. │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
  158. │ │ pdf-lib │ │word-extractor│ │ marked │ │
  159. │ │ (PDF Tools) │ │(DOCX Reader)│ │ (Markdown) │ │
  160. │ └─────────────┘ └─────────────┘ └─────────────┘ │
  161. │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
  162. │ │ cheerio │ │ jszip │ │ docx │ │
  163. │ │(HTML Parser)│ │(ZIP Handler)│ │(DOCX Gen.) │ │
  164. │ └─────────────┘ └─────────────┘ └─────────────┘ │
  165. │ ┌─────────────┐ ┌─────────────┐ │
  166. │ │ xml2js │ │Custom OOXML │ │
  167. │ │(XML Parser) │ │ Parser │ │
  168. │ └─────────────┘ └─────────────┘ │
  169. └─────────────────────────────────────────────────────────────┘
  170. ```
  171. ### Architecture Overview
  172. **Core Features**:
  173. - Pure JavaScript implementation with no external system dependencies
  174. - Complete document reading, conversion, and style processing capabilities
  175. - Built-in PDF watermark and QR code addition functionality
  176. - Intelligent conversion planning and path optimization
  177. **Conversion Flow**:
  178. - **Direct Conversion**: Supports direct conversion between most formats
  179. - **Multi-step Conversion**: Complex conversions achieved through intermediate formats
  180. - **Style Preservation**: Uses OOXML parser to ensure complete style integrity
  181. ## 3. Optional Integration
  182. This server can work with `playwright-mcp` for enhanced PDF conversion capabilities. Please refer to the official `playwright-mcp` documentation for detailed configuration.
  183. ### 🔧 PDF Conversion Workflow
  184. This server supports complete PDF conversion functionality:
  185. 1. **Document Parsing**: Use OOXML parser to ensure complete style preservation
  186. 2. **Format Conversion**: Convert documents to high-quality HTML format
  187. 3. **PDF Generation**: Built-in converter or optionally work with `playwright-mcp`
  188. 4. **Enhancement Processing**: Automatically add watermarks and QR codes (if configured)
  189. ### How It Works
  190. This server uses intelligent conversion architecture:
  191. 1. **Smart Planning**: `plan_conversion` analyzes conversion requirements and selects optimal paths
  192. 2. **Format Conversion**: Use specialized converters to handle various document formats
  193. 3. **Style Preservation**: Ensure style integrity through OOXML parser
  194. 4. **Enhancement Processing**: Automatically add watermarks, QR codes and other enhancements
  195. 5. **Optional Integration**: Support working with `playwright-mcp` for enhanced capabilities
  196. ## 4. Features
  197. ### MCP Tools
  198. #### Core Document Tools
  199. | Tool Name | Description | Input Parameters | External Dependencies |
  200. |-----------|-------------|------------------|----------------------|
  201. | `read_document` | Read document content | `filePath`: Document path<br>`extractMetadata`: Extract metadata<br>`preserveFormatting`: Preserve formatting | None |
  202. | `write_document` | Write document content | `content`: Document content<br>`outputPath`: Output file path<br>`encoding`: File encoding | None |
  203. | `convert_document` | Smart document conversion | `inputPath`: Input file path<br>`outputPath`: Output file path<br>`preserveFormatting`: Preserve formatting | None |
  204. | `plan_conversion` | Conversion planner | `sourceFormat`: Source format<br>`targetFormat`: Target format<br>`preserveStyles`: Preserve styles<br>`quality`: Conversion quality | None |
  205. ##### **read_document**
  206. Read various document formats including PDF, DOCX, DOC, HTML, MD, and more.
  207. **Parameters:**
  208. - `filePath` (string, required) - Document path to read
  209. - `extractMetadata` (boolean, optional) - Extract document metadata, defaults to `false`
  210. - `preserveFormatting` (boolean, optional) - Preserve formatting (HTML output), defaults to `false`
  211. ##### **write_document**
  212. Write content to document files in specified formats.
  213. **Parameters:**
  214. - `content` (string, required) - Content to write
  215. - `outputPath` (string, optional) - Output file path (auto-generated if not provided)
  216. - `encoding` (string, optional) - File encoding, defaults to `utf-8`
  217. ##### **convert_document**
  218. Convert documents between formats with enhanced style preservation.
  219. **Parameters:**
  220. - `inputPath` (string, required) - Input file path
  221. - `outputPath` (string, optional) - Output file path (auto-generated if not provided)
  222. - `preserveFormatting` (boolean, optional) - Preserve formatting, defaults to `true`
  223. - `useInternalPlaywright` (boolean, optional) - Use built-in Playwright for PDF conversion, defaults to `false`
  224. ##### **convert_docx_to_pdf**
  225. Convert DOCX to PDF with automatic watermark addition (if configured).
  226. **Parameters:**
  227. - `docxPath` (string, required) - DOCX file path
  228. - `outputPath` (string, optional) - Output PDF path (auto-generated if not provided)
  229. - `addQrCode` (boolean, optional) - Whether to add QR code, defaults to `false`
  230. - `preserveFormatting` (boolean, optional) - Preserve original formatting, defaults to `true`
  231. - `chineseFont` (string, optional) - Chinese font, defaults to `Microsoft YaHei`
  232. ##### **convert_markdown_to_pdf**
  233. Convert Markdown to PDF with automatic watermark addition (if configured).
  234. **Parameters:**
  235. - `markdownPath` (string, required) - Markdown file path
  236. - `outputPath` (string, optional) - Output PDF path (auto-generated if not provided)
  237. - `theme` (string, optional) - Theme style, defaults to `"github"`
  238. - `includeTableOfContents` (boolean, optional) - Include table of contents, defaults to `false`
  239. - `addQrCode` (boolean, optional) - Whether to add QR code, defaults to `false`
  240. ##### **convert_markdown_to_html**
  241. Convert Markdown to HTML.
  242. **Parameters:**
  243. - `markdownPath` (string, required) - Markdown file path
  244. - `outputPath` (string, optional) - Output HTML path (auto-generated if not provided)
  245. - `theme` (string, optional) - Theme style, defaults to `"github"`
  246. - `includeTableOfContents` (boolean, optional) - Include table of contents, defaults to `false`
  247. ##### **convert_markdown_to_docx**
  248. Convert Markdown to DOCX.
  249. **Parameters:**
  250. - `markdownPath` (string, required) - Markdown file path
  251. - `outputPath` (string, optional) - Output DOCX path (auto-generated if not provided)
  252. ##### **convert_html_to_markdown**
  253. Convert HTML to Markdown.
  254. **Parameters:**
  255. - `htmlPath` (string, required) - HTML file path
  256. - `outputPath` (string, optional) - Output Markdown path (auto-generated if not provided)
  257. ##### **plan_conversion**
  258. 🎯 Smart Conversion Planner - Analyze conversion requirements and generate optimal conversion plans.
  259. **Parameters:**
  260. - `sourceFormat` (string, required) - Source file format (pdf, docx, html, markdown, md, txt, doc)
  261. - `targetFormat` (string, required) - Target file format (pdf, docx, html, markdown, md, txt, doc)
  262. - `sourceFile` (string, optional) - Source file path (for generating specific conversion parameters)
  263. - `preserveStyles` (boolean, optional) - Whether to preserve style formatting, defaults to `true`
  264. - `includeImages` (boolean, optional) - Whether to include images, defaults to `true`
  265. - `theme` (string, optional) - Conversion theme, defaults to `github`
  266. - `quality` (string, optional) - Conversion quality requirement (fast, balanced, high), defaults to `balanced`
  267. ##### **process_pdf_post_conversion**
  268. **Parameters:**
  269. - `playwrightPdfPath` (string, required) - Generated PDF file path
  270. - `targetPath` (string, optional) - Target PDF file path (auto-generated if not provided)
  271. - `addWatermark` (boolean, optional) - Whether to add watermark, defaults to `false`
  272. - `addQrCode` (boolean, optional) - Whether to add QR code, defaults to `false`
  273. - `watermarkImage` (string, optional) - Watermark image path
  274. - `qrCodePath` (string, optional) - QR code image path
  275. #### PDF Enhancement Tools
  276. ##### **add_watermark**
  277. 🎨 PDF Watermark Addition Tool - Add image or text watermarks to PDF documents.
  278. **Parameters:**
  279. - `pdfPath` (string, required) - PDF file path
  280. - `watermarkImage` (string, optional) - Watermark image path (PNG/JPG)
  281. - `watermarkText` (string, optional) - Watermark text content
  282. - `watermarkImageScale` (number, optional) - Image scale ratio, defaults to `0.25`
  283. - `watermarkImageOpacity` (number, optional) - Image opacity, defaults to `0.6`
  284. - `watermarkImagePosition` (string, optional) - Image position, defaults to `fullscreen`
  285. ##### **add_qrcode**
  286. 📱 PDF QR Code Addition Tool - Add QR codes to PDF documents.
  287. **Parameters:**
  288. - `pdfPath` (string, required) - PDF file path
  289. - `qrCodePath` (string, optional) - QR code image path
  290. - `qrScale` (number, optional) - QR code scale ratio, defaults to `0.15`
  291. - `qrOpacity` (number, optional) - QR code opacity, defaults to `1.0`
  292. - `qrPosition` (string, optional) - QR code position, defaults to `bottom-center`
  293. - `addText` (boolean, optional) - Whether to add explanatory text, defaults to `true`
  294. ## System Requirements
  295. ### System Requirements
  296. - **Node.js** ≥ 18.0.0
  297. - **Zero external system dependencies** - All processing via npm packages
  298. - **Optional Integration**: playwright-mcp for enhanced PDF conversion
  299. ### Core Technology Stack
  300. - **pdf-lib** - PDF operations and enhancement
  301. - **word-extractor** - DOCX document text extraction
  302. - **marked** - Markdown parsing and rendering
  303. - **cheerio** - HTML parsing and manipulation
  304. - **docx** - DOCX document generation
  305. - **jszip** - ZIP file processing
  306. - **xml2js** - XML parsing and conversion
  307. - **Custom OOXML Parser** - Advanced DOCX style preservation
  308. ### Installation
  309. ```bash
  310. # Global installation
  311. npm install -g doc-ops-mcp
  312. # Or using pnpm
  313. pnpm add -g doc-ops-mcp
  314. # Or using bun
  315. bun add -g doc-ops-mcp
  316. ```
  317. ### Architecture Components
  318. - **MCP Server Core**: Handles JSON-RPC 2.0 communication and tool registration
  319. - **Smart Router**: Routes requests to optimal processing modules
  320. - **Conversion Engine**: Contains specialized converters for different document types
  321. - **Style Processor**: Ensures style preservation during format conversion
  322. - **Security Module**: Provides path validation and content security handling
  323. ## 5. Open Source Licenses
  324. ### Project License
  325. - **This Project**: MIT License
  326. - **Compatibility**: Available for commercial and non-commercial use
  327. ### Third-Party Dependencies
  328. | Library | Version | License | Purpose |
  329. |---------|---------|---------|----------|
  330. | **pdf-lib** | ^1.17.1 | MIT | PDF document manipulation |
  331. | **word-extractor** | ^1.0.4 | MIT | DOCX document text extraction |
  332. | **marked** | ^15.0.12 | MIT | Markdown parsing and rendering |
  333. | **cheerio** | ^1.0.0-rc.12 | MIT | HTML parsing and manipulation |
  334. | **docx** | ^9.5.1 | Apache-2.0 | DOCX document generation |
  335. | **jszip** | ^3.10.1 | MIT | ZIP file processing |
  336. | **xml2js** | ^0.6.2 | MIT | XML parsing and conversion |
  337. ### License Compatibility
  338. - ✅ **Commercial Use**: All dependencies support commercial use
  339. - ✅ **Distribution**: Free to distribute and modify
  340. - ✅ **Patent Protection**: Apache-2.0 provides patent protection
  341. - ⚠️ **Notice**: Original license notices must be retained
  342. ## 6. Future Roadmap
  343. ### Core Features
  344. - 🔄 **Enhanced Conversion Quality**: Improve style preservation for complex documents
  345. - 📊 **Excel Support**: Complete Excel read/write and conversion functionality
  346. - 🎨 **Template System**: Support for custom document templates
  347. - 🔍 **OCR Integration**: Image text recognition capabilities
  348. ### System Improvements
  349. - 🌐 **Multi-language Support**: Internationalization and localization
  350. - 🔐 **Security Enhancements**: Document encryption and access control
  351. - ⚡ **Performance Optimization**: Large file handling and memory optimization
  352. - 🔌 **Plugin System**: Extensible processor architecture
  353. ### Version Roadmap
  354. - **v2.0**: Complete Excel support and template system
  355. - **v3.0**: OCR integration and multi-language support
  356. - **v4.0**: Advanced security features and plugin system
  357. ## 7. Docker Deployment
  358. ### Quick Start
  359. #### Using Pre-built Image
  360. ```bash
  361. # Pull the latest image
  362. docker pull docops/doc-ops-mcp:latest
  363. # Run with default configuration
  364. docker run -d \
  365. --name doc-ops-mcp \
  366. -p 3000:3000 \
  367. docops/doc-ops-mcp:latest
  368. ```
  369. #### Building from Source
  370. ```bash
  371. # Clone the repository
  372. git clone https://github.com/JefferyMunoz/doc-ops-mcp.git
  373. cd doc-ops-mcp
  374. # Build the Docker image
  375. docker build -t doc-ops-mcp .
  376. # Run the container
  377. docker run -d \
  378. --name doc-ops-mcp \
  379. -p 3000:3000 \
  380. -v $(pwd)/documents:/app/documents \
  381. doc-ops-mcp
  382. ```
  383. ### Docker Compose Deployment
  384. Create a `docker-compose.yml` file:
  385. ```yaml
  386. version: '3.8'
  387. services:
  388. doc-ops-mcp:
  389. image: docops/doc-ops-mcp:latest
  390. container_name: doc-ops-mcp
  391. ports:
  392. - "3000:3000"
  393. volumes:
  394. - ./documents:/app/documents
  395. - ./config:/app/config
  396. environment:
  397. - NODE_ENV=production
  398. - PORT=3000
  399. restart: unless-stopped
  400. # Optional: Add Nginx for reverse proxy
  401. nginx:
  402. image: nginx:alpine
  403. container_name: doc-ops-nginx
  404. ports:
  405. - "80:80"
  406. volumes:
  407. - ./nginx.conf:/etc/nginx/nginx.conf:ro
  408. depends_on:
  409. - doc-ops-mcp
  410. restart: unless-stopped
  411. ```
  412. ### Environment Variables
  413. | Variable | Description | Default |
  414. |----------|-------------|----------|
  415. | `PORT` | Server port | `3000` |
  416. | `NODE_ENV` | Environment mode | `production` |
  417. | `LOG_LEVEL` | Logging level | `info` |
  418. | `MAX_FILE_SIZE` | Maximum file size (MB) | `50` |
  419. ### Volume Mounts
  420. Mount local directories for persistent storage:
  421. ```bash
  422. # Documents directory for file processing
  423. docker run -d \
  424. --name doc-ops-mcp \
  425. -p 3000:3000 \
  426. -v $(pwd)/documents:/app/documents \
  427. -v $(pwd)/output:/app/output \
  428. doc-ops-mcp
  429. ```
  430. ### Docker Configuration Examples
  431. #### Production Deployment
  432. ```bash
  433. # Production setup with Docker Swarm
  434. docker swarm init
  435. docker stack deploy -c docker-compose.yml doc-ops
  436. # Scale the service
  437. docker service scale doc-ops_mcp=3
  438. ```
  439. ### Health Checks
  440. The container includes built-in health checks:
  441. ```bash
  442. # Check container health
  443. docker ps
  444. # View health check logs
  445. docker inspect --format='{{.State.Health.Status}}' doc-ops-mcp
  446. # Manual health check
  447. docker exec doc-ops-mcp curl -f http://localhost:3000/health || exit 1
  448. ```
  449. ## 8. Development Guide
  450. ### Local Development
  451. ```bash
  452. # Clone the repository
  453. git clone https://github.com/your-org/doc-ops-mcp.git
  454. cd doc-ops-mcp
  455. # Install dependencies
  456. npm install
  457. # Run in development mode
  458. npm run dev
  459. # Build the project
  460. npm run build
  461. # Run tests
  462. npm test
  463. ```
  464. ### Project Structure
  465. ```
  466. src/
  467. ├── index.ts # MCP server entry point
  468. ├── tools/ # Tool implementations
  469. │ ├── documentConverter.ts
  470. │ ├── pdfTools.ts
  471. │ └── ...
  472. ├── types/ # Type definitions
  473. └── utils/ # Utility functions
  474. ```
  475. ### Adding New Tools
  476. 1. Create a new tool file in `src/tools/`
  477. 2. Implement the tool logic
  478. 3. Register the tool in `src/index.ts`
  479. 4. Add test cases
  480. 5. Update documentation
  481. ## 9. Troubleshooting
  482. ### Common Issues
  483. 1. **Port conflicts**: Change the host port in docker-compose.yml
  484. 2. **Permission issues**: Ensure volume mounts have correct permissions
  485. 3. **Memory issues**: Increase Docker memory allocation
  486. ### Debug Mode
  487. ```bash
  488. # Run with debug logging
  489. docker run -d \
  490. --name doc-ops-mcp \
  491. -p 3000:3000 \
  492. -e LOG_LEVEL=debug \
  493. doc-ops-mcp
  494. # View logs
  495. docker logs -f doc-ops-mcp
  496. ```
  497. ## 10. Contributing
  498. ### How to Contribute
  499. 1. **Fork the Project**
  500. 2. **Create a Feature Branch** (`git checkout -b feature/AmazingFeature`)
  501. 3. **Commit Your Changes** (`git commit -m 'Add some AmazingFeature'`)
  502. 4. **Push to the Branch** (`git push origin feature/AmazingFeature`)
  503. 5. **Open a Pull Request**
  504. #### Intellectual Property License
  505. **By submitting a Pull Request, you agree that all contributions submitted through Pull Requests will be licensed under the MIT License.** This means:
  506. - You grant the project maintainers and users the right to use, modify, and distribute your contributions under the MIT License
  507. - You confirm that you have the right to make these contributions
  508. - You understand that your contributions will become part of the open source project
  509. - You waive any claims to exclusive ownership of the contributed code
  510. If you cannot agree to these terms, please do not submit a Pull Request.
  511. ### Code Standards
  512. - Use TypeScript
  513. - Follow ESLint configuration
  514. - Add appropriate tests
  515. - Update relevant documentation
  516. ### Reporting Issues
  517. - Use [GitHub Issues](https://github.com/your-org/doc-ops-mcp/issues)
  518. - Provide detailed error information and reproduction steps
  519. - Include system environment information
  520. ### License
  521. 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 in

Free to use. If it’s helped, pass it on.