# 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]
Raw data
{
"_id": null,
"home_page": null,
"name": "huoshui-file-converter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Huoshui AI <contact@huoshui.ai>",
"keywords": "conversion, document, docx, file-converter, format-conversion, html, markdown, mcp, pandoc",
"author": null,
"author_email": "Huoshui AI <contact@huoshui.ai>",
"download_url": "https://files.pythonhosted.org/packages/86/d7/59f07ca46732f9deedade13a301d2c98e0094be658e53a78d81e5ef4794f/huoshui_file_converter-0.1.1.tar.gz",
"platform": null,
"description": "# Huoshui File Converter\n\nA secure MCP (Model Context Protocol) server for document format conversion within a specified working directory.\n\n## Features\n\n- \ud83d\udd12 **Sandbox Security**: All operations restricted to a configured working directory\n- \ud83d\udcc4 **Format Support**: Convert between Markdown, DOCX, HTML, PDF, and TXT\n- \ud83d\ude80 **MCP Integration**: Full MCP protocol support with prompts, resources, and tools\n- \u2699\ufe0f **Flexible Configuration**: CLI arguments, environment variables, or current directory\n- \ud83d\udd0d **Smart Detection**: Intelligent file format detection by content analysis\n\n## Quick Start\n\n### Installation\n\nOption 1: From MCP Registry (Recommended)\n\nThis server is available in the Model Context Protocol Registry. Install it using your MCP client.\n\nmcp-name: io.github.huoshuiai42/huoshui-file-converter\n\nOption 2: Using uvx\n\n```bash\nuvx huoshui-file-converter\n```\n\nOption 3: Using pip\n\n```bash\npip install huoshui-file-converter\n```\n\n### Basic Usage\n\n```bash\n# Use current directory\nuvx huoshui-file-converter\n\n# Specify working directory (recommended)\nuvx huoshui-file-converter --dir \"/path/to/documents\"\n\n# Short form\nuvx huoshui-file-converter -d \"~/Documents\"\n```\n\n### MCP Client Configuration\n\nFor Claude Desktop or other MCP clients:\n\n```json\n{\n \"mcpServers\": {\n \"huoshui-converter\": {\n \"command\": \"uvx\",\n \"args\": [\"huoshui-file-converter\", \"--dir\", \"/Users/yourname/Documents\"]\n }\n }\n}\n```\n\n## Configuration Options\n\n### Priority Order\n\n1. **CLI Argument** (highest priority): `--dir` or `-d`\n2. **Environment Variable**: `HUOSHUI_WORKING_DIR`\n3. **Smart Default**: Documents folder if current directory is problematic\n4. **Current Directory** (fallback)\n\n### Examples\n\n```bash\n# CLI argument (best for MCP clients)\nuvx huoshui-file-converter --dir \"/project/docs\"\n\n# Environment variable\nexport HUOSHUI_WORKING_DIR=\"/project/docs\"\nuvx huoshui-file-converter\n\n# Current directory fallback\ncd /project/docs\nuvx huoshui-file-converter\n```\n\n## Supported Conversions\n\n| From | To |\n| -------- | ------------------------- |\n| Markdown | DOCX, HTML, PDF |\n| DOCX | Markdown, HTML, PDF |\n| HTML | Markdown, DOCX, PDF |\n| TXT | Markdown, DOCX, HTML, PDF |\n\n## MCP Tools & Resources\n\n### Tools\n\n- `convert_document`: Convert files between formats\n- `detect_format`: Intelligent format detection\n\n### Resources\n\n- `file_list`: Browse directory contents (optimized for large directories)\n - `limit`: Control number of files shown (default: 100)\n - `supported_only`: Show only convertible files\n- `file_get`: Get detailed file information\n- `conversion_capability_list`: List supported conversions\n\n### Prompts\n\n- `role_and_rules`: AI assistant behavior guidelines\n\n## Performance Features\n\n- **Fast Directory Listing**: Extension-based format detection for large directories\n- **Smart File Limits**: Default 100-file limit prevents UI freezing\n- **Large File Handling**: Files >50MB are marked and handled specially\n- **Selective Display**: Option to show only supported file formats\n- **Memory Efficient**: Avoids reading file contents during directory browsing\n\n## Security Features\n\n- **Path Validation**: Prevents directory traversal attacks\n- **Working Directory Restriction**: All operations sandboxed to configured directory\n- **Startup Validation**: Checks directory existence and permissions\n- **Relative Path Enforcement**: Absolute paths are rejected\n\n## Command Line Options\n\n```bash\n$ uvx huoshui-file-converter --help\n\nusage: huoshui-file-converter [-h] [--dir PATH] [--version]\n\nHuoshui Document Converter - MCP Server for file conversion within a working directory\n\noptions:\n -h, --help show this help message and exit\n --dir PATH, -d PATH\n Working directory for file operations (default: current directory or HUOSHUI_WORKING_DIR env var)\n --version, -v show program's version number and exit\n\nExamples:\n uvx huoshui-file-converter # Use current directory\n uvx huoshui-file-converter --dir /docs # Use specific directory\n uvx huoshui-file-converter -d ./project # Use relative directory\n\nConfiguration Priority:\n 1. CLI argument (--dir/-d)\n 2. Environment variable (HUOSHUI_WORKING_DIR)\n 3. Current working directory\n```\n\n## Error Handling\n\nThe server validates the working directory on startup:\n\n```\n\u2705 Working directory configured: /Users/name/Documents\n\ud83d\udcc2 Source: CLI argument\n```\n\nCommon errors and solutions:\n\n| Error | Solution |\n| -------------------- | ----------------------------------- |\n| Directory not found | Create directory or fix path |\n| No write access | Check permissions (`chmod` on Unix) |\n| Path outside sandbox | Use relative paths only |\n\n## Development\n\n### Requirements\n\n- Python 3.8+\n- pypandoc\n- pandoc (system dependency)\n- LaTeX (for PDF conversion)\n\n### Testing\n\n```bash\n# Test configuration\nuvx huoshui-file-converter --dir \"/tmp/test\"\n\n# Check startup messages\n# \u2705 Working directory configured: /tmp/test\n# \ud83d\udcc2 Source: CLI argument\n```\n\n## Documentation\n\n- [Working Directory Configuration](docs/working_directory_config.md)\n- [MCP Configuration Examples](docs/mcp_configuration_examples.md)\n- [Performance Optimization Guide](docs/performance_optimization.md)\n\n## License\n\n[Your license here]\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A secure MCP server for document format conversion using pypandoc",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/huoshuiai/huoshui-file-converter",
"Issues": "https://github.com/huoshuiai/huoshui-file-converter/issues",
"Repository": "https://github.com/huoshuiai/huoshui-file-converter"
},
"split_keywords": [
"conversion",
" document",
" docx",
" file-converter",
" format-conversion",
" html",
" markdown",
" mcp",
" pandoc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a9e73229596bd74f7f250dbcdcb5d45326de291eed1f94012f083e893e295b00",
"md5": "c16b0d4ed72f67d2d2858571ded6d268",
"sha256": "ef93bec7747ae6d6474eb4c09d212df43d8e706ca7f71d137944fa30f37d77d0"
},
"downloads": -1,
"filename": "huoshui_file_converter-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c16b0d4ed72f67d2d2858571ded6d268",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 12073,
"upload_time": "2025-09-10T00:38:47",
"upload_time_iso_8601": "2025-09-10T00:38:47.816370Z",
"url": "https://files.pythonhosted.org/packages/a9/e7/3229596bd74f7f250dbcdcb5d45326de291eed1f94012f083e893e295b00/huoshui_file_converter-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "86d759f07ca46732f9deedade13a301d2c98e0094be658e53a78d81e5ef4794f",
"md5": "0319acc0d3be7f444f022e32c7f799a2",
"sha256": "c4fe6a57f122455e7ae11047956d9b28fe5f851b79e5cf93187978bb303b5f28"
},
"downloads": -1,
"filename": "huoshui_file_converter-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "0319acc0d3be7f444f022e32c7f799a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 16019963,
"upload_time": "2025-09-10T00:39:00",
"upload_time_iso_8601": "2025-09-10T00:39:00.814702Z",
"url": "https://files.pythonhosted.org/packages/86/d7/59f07ca46732f9deedade13a301d2c98e0094be658e53a78d81e5ef4794f/huoshui_file_converter-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 00:39:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "huoshuiai",
"github_project": "huoshui-file-converter",
"github_not_found": true,
"lcname": "huoshui-file-converter"
}
JSON
