Huoshui File Converter

A secure MCP (Model Context Protocol) server for document format conversion within a specified working directory.

Features

• 🔒 Sandbox Security: All operations restricted to a configured working directory
• 📄 Format Support: Convert between Markdown, DOCX, HTML, PDF, and TXT
• 🚀 MCP Integration: Full MCP protocol support with prompts, resources, and tools
• ⚙️ Flexible Configuration: CLI arguments, environment variables, or current directory
• 🔍 Smart Detection: Intelligent file format detection by content analysis

Quick Start

Installation

Option 1: From MCP Registry (Recommended)

This server is available in the Model Context Protocol Registry. Install it using your MCP client.

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

Option 2: Using uvx

uvx huoshui-file-converter

Option 3: Using pip

pip install huoshui-file-converter

Basic Usage

# 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 Client Configuration

For Claude Desktop or other MCP clients:

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

Configuration Options

Priority Order

1. CLI Argument (highest priority): --dir or -d
2. Environment Variable: HUOSHUI_WORKING_DIR
3. Smart Default: Documents folder if current directory is problematic
4. Current Directory (fallback)

Examples

# 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

Supported Conversions

From	To
Markdown	DOCX, HTML, PDF
DOCX	Markdown, HTML, PDF
HTML	Markdown, DOCX, PDF
TXT	Markdown, DOCX, HTML, PDF

MCP Tools & Resources

Tools

• convert_document: Convert files between formats
• detect_format: Intelligent format detection

Resources

• file_list: Browse directory contents (optimized for large directories)
  • limit: Control number of files shown (default: 100)
  • supported_only: Show only convertible files
• file_get: Get detailed file information
• conversion_capability_list: List supported conversions

Prompts

• role_and_rules: AI assistant behavior guidelines

Performance Features

• Fast Directory Listing: Extension-based format detection for large directories
• Smart File Limits: Default 100-file limit prevents UI freezing
• Large File Handling: Files >50MB are marked and handled specially
• Selective Display: Option to show only supported file formats
• Memory Efficient: Avoids reading file contents during directory browsing

Security Features

• Path Validation: Prevents directory traversal attacks
• Working Directory Restriction: All operations sandboxed to configured directory
• Startup Validation: Checks directory existence and permissions
• Relative Path Enforcement: Absolute paths are rejected

Command Line Options

$ 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

Error Handling

The server validates the working directory on startup:

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

Common errors and solutions:

Error	Solution
Directory not found	Create directory or fix path
No write access	Check permissions (chmod on Unix)
Path outside sandbox	Use relative paths only

Development

Requirements

• Python 3.8+
• pypandoc
• pandoc (system dependency)
• LaTeX (for PDF conversion)

Testing

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

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

Documentation

• Working Directory Configuration
• MCP Configuration Examples
• Performance Optimization Guide

License

[Your license here]