Huoshui File Converter

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 directoryuvx huoshui-file-converter
# Specify working directory (recommended)uvx huoshui-file-converter --dir "/path/to/documents"
# Short formuvx 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 variableexport HUOSHUI_WORKING_DIR="/project/docs"uvx huoshui-file-converter
# Current directory fallbackcd /project/docsuvx huoshui-file-converter

Supported Conversions

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:

Development

Requirements

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

Testing

# Test configurationuvx 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]