Doc Ops Mcp

ドキュメント操作 MCP サーバー

言語 / 语言: English | 中文

ドキュメント操作 MCP サーバー - ドキュメントの処理、変換、自動化に対応する汎用 MCP サーバーです。統一された API とツールセットを通じて、PDF、DOCX、HTML、Markdown などを扱えます。

デモ

動画

https://github.com/user-attachments/assets/43dfeeec-8097-413e-8519-a7de98e31136

このデモでは、次の方法を紹介します。

• MCP クライアントで doc-ops-mcp を設定する
• DOCX ドキュメントを PDF 形式に変換する
• 変換した PDF ファイルにデフォルトの透かしを追加する

目次

1. クイックスタート
2. システムアーキテクチャ
3. オプションの統合
4. 機能
5. オープンソースライセンス
6. 今後のロードマップ
7. Docker のデプロイ
8. 開発ガイド
9. トラブルシューティング
10. 貢献

1. クイックスタート

まず、Document Operations MCP サーバーを MCP クライアントに追加します。

ほとんどの MCP クライアントでは、標準設定を使用できます。

{
  "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",
      }
    }
  }
}

Claude Desktop

MCP のインストールガイドに従い、上記の標準設定を使用してください。

VS Code

MCP のインストールガイドに従い、上記の標準設定を使用してください。

Cursor

Cursor Settings -> MCP -> Add new MCP Server に移動します。任意の名前を設定し、タイプに command を選択して、コマンド npx -y doc-ops-mcp を指定してください。

その他の MCP クライアント

その他の MCP クライアントでは、上記の標準設定を使用し、MCP サーバーのインストール方法についてはお使いのクライアントのドキュメントを参照してください。

設定

Document Operations MCP サーバーは、環境変数による設定に対応しています。これらは、MCP クライアントの設定で "env" オブジェクトの一部として指定できます。

{
  "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"
      }
    }
  }
}

対応するドキュメント操作

形式	PDF に変換	DOCX に変換	HTML に変換	Markdown に変換	コンテンツの書き換え	透かし／QR コード
PDF	✅	❌	❌	❌	❌	✅
DOCX	✅	✅	✅	✅	✅	❌
HTML	✅	❌	✅	✅	✅	❌
Markdown	✅	✅	✅	✅	✅	❌

書き換え機能：

• コンテンツの置換：テキストの一括置換と正規表現による置換に対応
• 書式の調整：ドキュメントの構造、見出しレベル、スタイルの書式を変更
• スマートな書き換え：元のドキュメント形式を保ちながらコンテンツを最適化

使用例

形式の変換：

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)

ドキュメントの書き換え：

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 の拡張：

Add watermark to /Users/docs/document.pdf
Add QR code to /Users/docs/report.pdf
Add company logo watermark to /Users/docs/invoice.pdf

環境変数

サーバーでは、出力先と PDF 拡張機能を制御するための環境変数に対応しています。

コアディレクトリ

• OUTPUT_DIR：生成されたすべてのファイルの保存先を指定します（デフォルト：~/Documents）
• CACHE_DIR：一時ファイルとキャッシュファイルのディレクトリです（デフォルト：~/.cache/doc-ops-mcp）

PDF の拡張機能

• WATERMARK_IMAGE：PDF ファイルのデフォルトの透かし画像パス
  • すべての PDF 変換に自動的に追加されます
  • 対応形式：PNG、JPG
  • 設定されていない場合は、デフォルトのテキスト透かし「doc-ops-mcp」が使用されます
• QR_CODE_IMAGE：PDF ファイルのデフォルトの QR コード画像パス
  • 明示的に要求された場合（addQrCode=true）にのみ PDF に追加されます
  • 対応形式：PNG、JPG
  • 設定されていない場合、QR コード機能は利用できません

出力パスのルール：

1. outputPath が指定されていない場合 → ファイルは自動生成された名前で OUTPUT_DIR に保存されます
2. outputPath が相対パスの場合 → OUTPUT_DIR を基準に解決されます
3. outputPath が絶対パスの場合 → OUTPUT_DIR を無視して、そのまま使用されます

詳細なドキュメントについては、OUTPUT_PATH_CONTROL.md を参照してください。

2. システムアーキテクチャ

Document Operations MCP Server は、純粋な JavaScript アーキテクチャを採用し、完全なドキュメント処理機能を提供します。

┌─────────────────────────────────────────────────────────────┐
│                    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    │                           │
│  └─────────────┘  └─────────────┘                           │
└─────────────────────────────────────────────────────────────┘

アーキテクチャの概要

主な機能：

• 外部システムへの依存がない、純粋な JavaScript による実装
• ドキュメントの読み取り、変換、スタイル処理を網羅する機能
• PDF の透かしと QR コードの追加機能を内蔵
• インテリジェントな変換計画とパスの最適化

変換フロー：

• 直接変換：ほとんどの形式間で直接変換できます
• 複数ステップ変換：中間形式を使用して複雑な変換を実現します
• スタイルの保持：OOXML パーサーを使用して、スタイルの完全性を確保します

3. オプションの連携

このサーバーは、PDF 変換機能を強化するために playwright-mcp と連携できます。詳細な設定については、playwright-mcp の公式ドキュメントを参照してください。

🔧 PDF 変換ワークフロー

このサーバーは、完全な PDF 変換機能をサポートしています。

1. ドキュメントの解析：OOXML パーサーを使用して、スタイルを完全に保持します
2. 形式の変換：ドキュメントを高品質な HTML 形式に変換します
3. PDF の生成：内蔵のコンバーターを使用するか、オプションで playwright-mcp と連携します
4. 拡張処理：設定されている場合、透かしと QR コードを自動的に追加します

動作の仕組み

このサーバーは、インテリジェントな変換アーキテクチャを採用しています。

1. スマートな計画：plan_conversion が変換要件を分析し、最適な経路を選択します
2. 形式の変換：専用のコンバーターを使用して、さまざまなドキュメント形式を処理します
3. スタイルの保持：OOXML パーサーを通じてスタイルの完全性を確保します
4. 拡張処理：透かし、QR コードなどの拡張要素を自動的に追加します
5. オプションの連携：機能を強化するために playwright-mcp との連携をサポートします

4. 機能

MCP ツール

ドキュメントの主要ツール

ツール名	説明	入力パラメーター	外部依存関係
read_document	ドキュメントの内容を読み取ります	filePath：ドキュメントのパス extractMetadata：メタデータを抽出 preserveFormatting：書式を保持	なし
write_document	ドキュメントの内容を書き込みます	content：ドキュメントの内容 outputPath：出力ファイルのパス encoding：ファイルのエンコーディング	なし
convert_document	ドキュメントをスマートに変換します	inputPath：入力ファイルのパス outputPath：出力ファイルのパス preserveFormatting：書式を保持	なし
plan_conversion	変換プランナー	sourceFormat：ソース形式 targetFormat：ターゲット形式 preserveStyles：スタイルを保持 quality：変換品質	なし

read_document

PDF、DOCX、DOC、HTML、MD など、さまざまなドキュメント形式を読み取ります。

パラメーター：

• filePath（string、必須） - 読み取るドキュメントのパス
• extractMetadata（boolean、任意） - ドキュメントのメタデータを抽出します。デフォルトは false です
• preserveFormatting（boolean、任意） - 書式を保持します（HTML 出力）。デフォルトは false です

write_document

指定した形式でドキュメントファイルにコンテンツを書き込みます。

パラメーター：

• content（string、必須） - 書き込むコンテンツ
• outputPath（string、任意） - 出力ファイルのパス（指定しない場合は自動生成）
• encoding（string、任意） - ファイルのエンコーディング。デフォルトはutf-8

convert_document

スタイルの保持を強化しながら、ドキュメントを形式間で変換します。

パラメーター：

• inputPath（string、必須） - 入力ファイルのパス
• outputPath（string、任意） - 出力ファイルのパス（指定しない場合は自動生成）
• preserveFormatting（boolean、任意） - 書式を保持するかどうか。デフォルトはtrue
• useInternalPlaywright（boolean、任意） - PDF 変換に組み込みの Playwright を使用するかどうか。デフォルトはfalse

convert_docx_to_pdf

DOCX を PDF に変換し、（設定されている場合は）自動的に透かしを追加します。

パラメーター：

• docxPath（string、必須） - DOCX ファイルのパス
• outputPath（string、任意） - 出力 PDF のパス（指定しない場合は自動生成）
• addQrCode（boolean、任意） - QR コードを追加するかどうか。デフォルトはfalse
• preserveFormatting（boolean、任意） - 元の書式を保持するかどうか。デフォルトはtrue
• chineseFont（string、任意） - 中国語フォント。デフォルトはMicrosoft YaHei

convert_markdown_to_pdf

Markdown を PDF に変換し、（設定されている場合は）自動的に透かしを追加します。

パラメーター：

• markdownPath（string、必須） - Markdown ファイルのパス
• outputPath（string、任意） - 出力 PDF のパス（指定しない場合は自動生成）
• theme（string、任意） - テーマのスタイル。デフォルトは"github"
• includeTableOfContents（boolean、任意） - 目次を含めるかどうか。デフォルトはfalse
• addQrCode（boolean、任意） - QR コードを追加するかどうか。デフォルトはfalse

convert_markdown_to_html

Markdown を HTML に変換します。

パラメーター：

• markdownPath（string、必須） - Markdown ファイルのパス
• outputPath（string、任意） - 出力 HTML のパス（指定しない場合は自動生成）
• theme（string、任意） - テーマのスタイル。デフォルトは"github"
• includeTableOfContents（boolean、任意） - 目次を含めるかどうか。デフォルトはfalse

convert_markdown_to_docx

Markdown を DOCX に変換します。

パラメーター：

• markdownPath（string、必須） - Markdown ファイルのパス
• outputPath（string、任意） - 出力 DOCX のパス（指定しない場合は自動生成）

convert_html_to_markdown

HTML を Markdown に変換します。

パラメーター：

• htmlPath（string、必須） - HTML ファイルのパス
• outputPath（string、任意） - 出力 Markdown のパス（指定しない場合は自動生成）

plan_conversion

🎯 スマート変換プランナー - 変換要件を分析し、最適な変換プランを生成します。

パラメーター：

• sourceFormat（string、必須） - ソースファイルの形式（pdf、docx、html、markdown、md、txt、doc）
• targetFormat（string、必須） - ターゲットファイルの形式（pdf、docx、html、markdown、md、txt、doc）
• sourceFile（string、任意） - ソースファイルのパス（具体的な変換パラメーターを生成する場合に使用）
• preserveStyles（boolean、任意） - スタイルの書式を保持するかどうか。デフォルトはtrue
• includeImages（boolean、任意） - 画像を含めるかどうか。デフォルトはtrue
• theme（string、任意） - 変換テーマ。デフォルトはgithub
• quality（string、任意） - 変換品質の要件（fast、balanced、high）。デフォルトはbalanced

process_pdf_post_conversion

パラメーター：

• playwrightPdfPath（string、必須） - 生成された PDF ファイルのパス
• targetPath（string、任意） - ターゲット PDF ファイルのパス（指定しない場合は自動生成）
• addWatermark（boolean、任意） - 透かしを追加するかどうか。デフォルトはfalse
• addQrCode（boolean、任意） - QR コードを追加するかどうか。デフォルトはfalse
• watermarkImage（string、任意） - 透かし画像のパス
• qrCodePath（string、任意） - QR コード画像のパス

PDF 拡張ツール

add_watermark

🎨 PDF 透かし追加ツール - PDF ドキュメントに画像またはテキストの透かしを追加します。

パラメーター：

• pdfPath (string, required) - PDF ファイルのパス
• watermarkImage (string, optional) - 透かし画像のパス（PNG/JPG）
• watermarkText (string, optional) - 透かしテキストの内容
• watermarkImageScale (number, optional) - 画像の拡大縮小率。デフォルトは 0.25 です
• watermarkImageOpacity (number, optional) - 画像の不透明度。デフォルトは 0.6 です
• watermarkImagePosition (string, optional) - 画像の位置。デフォルトは fullscreen です

add_qrcode

📱 PDF QR コード追加ツール - PDF ドキュメントに QR コードを追加します。

パラメーター：

• pdfPath (string, required) - PDF ファイルのパス
• qrCodePath (string, optional) - QR コード画像のパス
• qrScale (number, optional) - QR コードの拡大縮小率。デフォルトは 0.15 です
• qrOpacity (number, optional) - QR コードの不透明度。デフォルトは 1.0 です
• qrPosition (string, optional) - QR コードの位置。デフォルトは bottom-center です
• addText (boolean, optional) - 説明テキストを追加するかどうか。デフォルトは true です

システム要件

システム要件

• Node.js ≥ 18.0.0
• 外部システム依存関係なし - すべての処理は npm パッケージを通じて実行されます
• オプションの連携：PDF 変換を強化する playwright-mcp

コア技術スタック

• pdf-lib - PDF の操作と機能強化
• word-extractor - DOCX ドキュメントからのテキスト抽出
• marked - Markdown の解析とレンダリング
• cheerio - HTML の解析と操作
• docx - DOCX ドキュメントの生成
• jszip - ZIP ファイルの処理
• xml2js - XML の解析と変換
• カスタム OOXML パーサー - 高度な DOCX スタイルの保持

インストール

# 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

アーキテクチャコンポーネント

• MCP サーバーコア：JSON-RPC 2.0 通信とツール登録を処理します
• スマートルーター：リクエストを最適な処理モジュールに振り分けます
• 変換エンジン：さまざまなドキュメント形式に対応する専用コンバーターを備えています
• スタイルプロセッサー：形式変換時のスタイル保持を確実にします
• セキュリティモジュール：パスの検証とコンテンツのセキュリティ処理を提供します

5. オープンソースライセンス

プロジェクトライセンス

• 本プロジェクト：MIT ライセンス
• 互換性：商用利用および非商用利用が可能です

サードパーティ依存関係

ライブラリ	バージョン	ライセンス	用途
pdf-lib	^1.17.1	MIT	PDF ドキュメントの操作
word-extractor	^1.0.4	MIT	DOCX ドキュメントからのテキスト抽出
marked	^15.0.12	MIT	Markdown の解析とレンダリング
cheerio	^1.0.0-rc.12	MIT	HTML の解析と操作
docx	^9.5.1	Apache-2.0	DOCX ドキュメントの生成
jszip	^3.10.1	MIT	ZIP ファイルの処理
xml2js	^0.6.2	MIT	XML の解析と変換

ライセンスの互換性

• ✅ 商用利用：すべての依存関係は商用利用に対応しています
• ✅ 配布：自由に配布および変更できます
• ✅ 特許保護：Apache-2.0 は特許保護を提供します
• ⚠️ 通知：元のライセンス表示を保持する必要があります

6. 今後のロードマップ

コア機能

• 🔄 変換品質の向上：複雑なドキュメントのスタイル保持を改善します
• 📊 Excel サポート：Excel の読み書きと変換機能を完成させます
• 🎨 テンプレートシステム：カスタムドキュメントテンプレートに対応します
• 🔍 OCR 連携：画像内テキストの認識機能

システムの改善

• 🌐 多言語サポート：国際化とローカライズ
• 🔐 セキュリティの強化：ドキュメントの暗号化とアクセス制御
• ⚡ パフォーマンスの最適化：大容量ファイルの処理とメモリの最適化
• 🔌 プラグインシステム：拡張可能なプロセッサーアーキテクチャ

バージョンロードマップ

• v2.0：Excel サポートとテンプレートシステムを完成させます
• v3.0：OCR 連携と多言語サポート
• v4.0：高度なセキュリティ機能とプラグインシステム

7. Docker デプロイ

クイックスタート

ビルド済みイメージを使用

# 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

ソースからのビルド

# 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 によるデプロイ

docker-compose.yml ファイルを作成します。

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

環境変数

変数	説明	デフォルト
PORT	サーバーのポート	3000
NODE_ENV	環境モード	production
LOG_LEVEL	ログレベル	info
MAX_FILE_SIZE	最大ファイルサイズ（MB）	50

ボリュームマウント

永続ストレージとしてローカルディレクトリをマウントします。

# 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 設定例

本番環境へのデプロイ

# 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

ヘルスチェック

コンテナにはヘルスチェック機能が組み込まれています。

# 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. 開発ガイド

ローカル開発

# 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

プロジェクト構成

src/
├── index.ts          # MCP server entry point
├── tools/            # Tool implementations
│   ├── documentConverter.ts
│   ├── pdfTools.ts
│   └── ...
├── types/            # Type definitions
└── utils/            # Utility functions

新しいツールの追加

1. src/tools/ に新しいツールファイルを作成します
2. ツールのロジックを実装します
3. src/index.ts にツールを登録します
4. テストケースを追加します
5. ドキュメントを更新します

9. トラブルシューティング

よくある問題

1. ポートの競合：docker-compose.yml のホストポートを変更してください
2. 権限の問題：ボリュームマウントに適切な権限が設定されていることを確認してください
3. メモリの問題：Docker のメモリ割り当てを増やしてください

デバッグモード

# 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. コントリビューション

コントリビューションの方法

1. プロジェクトをフォークする
2. 機能ブランチを作成する（git checkout -b feature/AmazingFeature）
3. 変更をコミットする（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュする（git push origin feature/AmazingFeature）
5. プルリクエストを作成する

知的財産ライセンス

プルリクエストを送信することで、プルリクエストを通じて提出されたすべてのコントリビューションが MIT License の下でライセンスされることに同意したものとみなされます。 これは、以下を意味します。

• プロジェクトのメンテナーとユーザーに対し、MIT License の下でコントリビューションを使用、変更、配布する権利を付与します
• これらのコントリビューションを行う権利があることを確認します
• コントリビューションがオープンソースプロジェクトの一部となることを理解します
• コントリビューションしたコードに対する独占所有権の主張を放棄します

これらの条件に同意できない場合は、プルリクエストを送信しないでください。

コード規約

• TypeScript を使用します
• ESLint の設定に従います
• 適切なテストを追加します
• 関連するドキュメントを更新します

問題の報告

• GitHub Issues を使用します
• エラーの詳細情報と再現手順を記載します
• システム環境の情報を含めます

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。