huoshui-file-converter

Huoshui File Converter

指定した作業ディレクトリ内でドキュメント形式を変換する、安全な MCP（Model Context Protocol）サーバーです。

特長

• 🔒 サンドボックスセキュリティ：すべての操作を設定済みの作業ディレクトリ内に制限します
• 📄 形式のサポート：Markdown、DOCX、HTML、PDF、TXT 間で変換できます
• 🚀 MCP 統合：プロンプト、リソース、ツールを含む MCP プロトコルを完全にサポートします
• ⚙️ 柔軟な設定：CLI 引数、環境変数、またはカレントディレクトリを使用できます
• 🔍 スマート検出：コンテンツ分析によってファイル形式をインテリジェントに検出します

クイックスタート

インストール

オプション 1：MCP Registry から（推奨）

このサーバーは Model Context Protocol Registry で利用できます。MCP クライアントを使ってインストールしてください。

mcp-name: io.github.huoshuiai42/huoshui-file-converter

オプション 2：uvx を使用

uvx huoshui-file-converter

オプション 3：pip を使用

pip install huoshui-file-converter

基本的な使い方

# Use current directory
uvx huoshui-file-converter

# Specify working directory (recommended)
uvx huoshui-file-converter --dir "/path/to/documents"

# Short form
uvx huoshui-file-converter -d "~/Documents"

MCP クライアントの設定

Claude Desktop またはその他の MCP クライアントの場合：

{
  "mcpServers": {
    "huoshui-converter": {
      "command": "uvx",
      "args": ["huoshui-file-converter", "--dir", "/Users/yourname/Documents"]
    }
  }
}

設定オプション

優先順位

1. CLI 引数（最優先）：--dir または -d
2. 環境変数：HUOSHUI_WORKING_DIR
3. スマートデフォルト：カレントディレクトリに問題がある場合は Documents フォルダー
4. カレントディレクトリ（フォールバック）

例

# CLI argument (best for MCP clients)
uvx huoshui-file-converter --dir "/project/docs"

# Environment variable
export HUOSHUI_WORKING_DIR="/project/docs"
uvx huoshui-file-converter

# Current directory fallback
cd /project/docs
uvx huoshui-file-converter

対応する変換

変換元	変換先
Markdown	DOCX、HTML、PDF
DOCX	Markdown、HTML、PDF
HTML	Markdown、DOCX、PDF
TXT	Markdown、DOCX、HTML、PDF

MCP ツールとリソース

ツール

• convert_document：形式間でファイルを変換します
• detect_format：ファイル形式をインテリジェントに検出します

リソース

• file_list：ディレクトリの内容を表示します（大規模なディレクトリに最適化されています）
  • limit：表示するファイル数を指定します（デフォルト：100）
  • supported_only：変換可能なファイルのみを表示します
• file_get：ファイルの詳細情報を取得します
• conversion_capability_list：対応する変換形式を一覧表示します

プロンプト

• role_and_rules：AI アシスタントの動作ガイドライン

パフォーマンス機能

• 高速なディレクトリ一覧表示：大規模なディレクトリでは拡張子に基づいて形式を検出します
• スマートなファイル数制限：デフォルトのファイル数を 100 件に制限し、UI のフリーズを防ぎます
• 大容量ファイルの処理：50 MB を超えるファイルには印を付け、特別に処理します
• 選択的な表示：対応するファイル形式のみを表示するオプションがあります
• メモリ効率：ディレクトリの閲覧中にファイルの内容を読み込まないため、メモリを効率的に使用します

セキュリティ機能

• パスの検証：ディレクトリトラバーサル攻撃を防止します
• 作業ディレクトリの制限：すべての操作を設定済みのディレクトリ内にサンドボックス化します
• 起動時の検証：ディレクトリの存在とアクセス権を確認します
• 相対パスの強制：絶対パスは拒否されます

コマンドラインオプション

$ uvx huoshui-file-converter --help

usage: huoshui-file-converter [-h] [--dir PATH] [--version]

Huoshui Document Converter - MCP Server for file conversion within a working directory

options:
  -h, --help         show this help message and exit
  --dir PATH, -d PATH
                     Working directory for file operations (default: current directory or HUOSHUI_WORKING_DIR env var)
  --version, -v      show program's version number and exit

Examples:
  uvx huoshui-file-converter                    # Use current directory
  uvx huoshui-file-converter --dir /docs        # Use specific directory
  uvx huoshui-file-converter -d ./project       # Use relative directory

Configuration Priority:
  1. CLI argument (--dir/-d)
  2. Environment variable (HUOSHUI_WORKING_DIR)
  3. Current working directory

エラー処理

サーバーは起動時に作業ディレクトリを検証します。

✅ Working directory configured: /Users/name/Documents
📂 Source: CLI argument

一般的なエラーと解決方法：

エラー	解決方法
ディレクトリが見つからない	ディレクトリを作成するか、パスを修正します
書き込み権限がない	権限を確認します（Unix では chmod）
サンドボックス外のパス	相対パスのみを使用します

開発

要件

• Python 3.8+
• pypandoc
• pandoc（システム依存関係）
• LaTeX（PDF 変換用）

テスト

# Test configuration
uvx huoshui-file-converter --dir "/tmp/test"

# Check startup messages
# ✅ Working directory configured: /tmp/test
# 📂 Source: CLI argument

ドキュメント

• 作業ディレクトリの設定
• MCP 設定例
• パフォーマンス最適化ガイド

ライセンス

[ライセンスをここに記載]