Skip to main content
Glama
Huoshui File Converter

Huoshui File Converter

by huoshuiai42

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

Related MCP server: doc-ops-mcp

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

License

[Your license here]

Available Tools

3 tools
convert_documentA

Converts a specified file to a different format. The new file is saved in the same directory as the original.

Args: file_path: File path (absolute or relative to home directory) to_format: The target format to convert the file into

Returns: Dictionary with new_file_path key containing the absolute path of converted file

Inputs: file_path (required), to_format (required).

detect_formatA

Intelligently detects a file's true format by inspecting its contents, which is more reliable than trusting a file extension.

Args: file_path: File path (absolute or relative to home directory)

Returns: Dictionary with format key containing the detected file format

Inputs: file_path (required).

file_getB

Retrieves detailed information about a single file.

Args: path: File path (absolute or relative to home directory)

Returns: File resource with detailed information

Inputs: path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: file conversion, format detection, and file info retrieval. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: convert_document, detect_format, file_get.

    Tool Count5/5

    With 3 tools, the surface is well-scoped for a file conversion utility. Each tool earns its place without being overly sparse.

    Completeness4/5

    Covers core conversion workflow (detect + convert + info). Minor omissions like listing supported formats or batch conversion, but sufficient for common tasks.

    Related MCP Connectors

    Related MCP Servers