Skip to main content
Glama
huoshuiai42

Huoshui File Converter

by huoshuiai42
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYesFile path (absolute or relative to home directory)
to_formatYesTarget format (docx, markdown, html)

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the converted file is saved in the same directory, which is useful. However, it does not mention error handling, permissions, or the range of supported conversions beyond the three formats listed in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear structure (intro, args, returns). It is efficient but could be slightly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the return value and the location of the new file, which is helpful given no output schema. However, it lacks details on error handling and allowed conversions, which limits completeness for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already provides full descriptions for both parameters (file_path and to_format) with 100% coverage. The description adds no new semantic information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool converts a file to a different format and saves the new file in the same directory, distinguishing it from siblings like detect_format and file_get.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives (detect_format, file_get). The description implies conversion use case but does not provide exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYesFile path (absolute or relative to home directory)

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses content inspection and return dictionary with format key; no annotations needed to supplement, but could mention if there are any limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise and well-structured with Args/Returns sections; every sentence adds value, no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema, description fully explains purpose, inputs, and output; no gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and description repeats the parameter info, adding no new semantic depth beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it detects a file's true format by inspecting contents, distinguishing it from siblings convert_document (converts) and file_get (retrieves).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes when to use it (for reliable format detection) but no explicit when-not or alternatives; adequate but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesFile path (absolute or relative to home directory)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It only states it retrieves file info but doesn't describe what happens on errors, permissions needed, or return format details. The 'Returns' line is vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise with two clear sections: purpose and parameter/return. No unnecessary words, front-loaded with the main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with one parameter and no output schema, the description provides basic information but lacks details on what constitutes 'detailed information', error handling, or any edge cases. It is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the path parameter with a description. The description's Args section duplicates that info without adding new semantics. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves detailed information about a single file. The verb 'Retrieves' and resource 'detailed information about a single file' are specific. Sibling tools are for conversion and format detection, so purpose is distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives or when not to use it. There is no mention of prerequisites or context for choosing this over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.1
    • First observedconvert_document
    • First observeddetect_format
    • First observedfile_get
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers