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

bash

uvx huoshui-file-converter

Option 3: Using pip

Terminal

pip install huoshui-file-converter

Basic Usage

bash

# 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:

config.json

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

Configuration Options

Priority Order

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

Examples

server.ts

# 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

bash

$ 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:

Code

✅ 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

bash

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

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

Documentation

License

[Your license here]