io.github.huoshuiai42/huoshui-file-converter
An MCP server that provides document format conversion
Open source Open in the app JSON README (API)
About
An MCP server that provides document format conversion
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- huoshuiai42
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Last push
- 2025-09-10T00:41:57Z
- Repository state
- parado
- Language
- Python
- Added
- 2026-08-29 04:00:08
- Updated
- 2026-08-29 04:00:08
- Origin id
io.github.huoshuiai42/huoshui-file-converter
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 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:
```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 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:
```
✅ 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
- [Working Directory Configuration](docs/working_directory_config.md)
- [MCP Configuration Examples](docs/mcp_configuration_examples.md)
- [Performance Optimization Guide](docs/performance_optimization.md)
## License
[Your license here]