Huoshui File Converter

io.github.huoshuiai42Published by GitHub account huoshuiai42v1.0.0Updated Oct 24, 2026

An MCP server that provides document format conversion

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & Storage

Overview

AI-generated overview

A local MCP server that lets an assistant convert documents between Markdown, DOCX, HTML, PDF and TXT inside a configured working directory.

What you can do
Convert documents between Markdown, DOCX, HTML, PDF and TXT, with TXT and HTML able to reach any of the other formats and PDF as a target only. Detect a file's format by content analysis rather than extension alone. Browse the working directory with a file limit and an option to show only convertible files. Get detailed information about a single file. List the supported conversion pairs.
When to use it
Useful when an assistant needs to turn notes, reports or web content into another document format, or to inspect which files in a folder can be converted, without leaving the chat client.
Requirements
Runs locally as a Python package (Python 3.8+) via uvx or pip. Needs pandoc as a system dependency and LaTeX for PDF output. A working directory is set by the --dir/-d argument or the HUOSHUI_WORKING_DIR environment variable, falling back to the current directory.
Before you install
Conversion writes new files into the configured working directory, so point it at a folder where that is acceptable. All operations are restricted to that directory and absolute paths are rejected. PDF conversion depends on an external LaTeX installation.

Installation

In SourceWeft

  1. Open Huoshui File Converter in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
pip install huoshui-file-converter

Basic Usage

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

json
{  "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

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

FromTo
MarkdownDOCX, HTML, PDF
DOCXMarkdown, HTML, PDF
HTMLMarkdown, DOCX, PDF
TXTMarkdown, 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:

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

Common errors and solutions:

ErrorSolution
Directory not foundCreate directory or fix path
No write accessCheck permissions (chmod on Unix)
Path outside sandboxUse relative paths only

Development

Requirements

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

Testing

bash
# Test configurationuvx huoshui-file-converter --dir "/tmp/test"
# Check startup messages# ✅ Working directory configured: /tmp/test# 📂 Source: CLI argument

Documentation

License

[Your license here]

Source: README.md at commit ba6cd8b

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.