Huoshui File Converter

火水文件转换器

一个在指定工作目录内用于文档格式转换的安全MCP（模型上下文协议）服务器。

特点/功能

• 🔒 表示“锁定”或“安全”的意思。 沙盒安全所有操作均限制在配置的工作目录内
• 📄 代表一张纸或文档的符号，可翻译为“文件”或“纸张”。 格式支持在Markdown、DOCX、HTML、PDF和TXT之间进行转换
• 🚀 表示火箭或快速上升的意象，常用来比喻快速进展、飞速发展或充满活力的事物。 MCP集成全面支持MCP协议，提供提示、资源和工具
• ⚙️ 通常表示“齿轮”或“机械装置”的图标，没有直接的中文翻译，但在中文语境中可以理解为“齿轮标志”或“机械装置符号”。如果是在特定上下文中，如软件界面或机械图纸中，可能需要根据具体情境来解释其含义。 灵活配置命令行参数、环境变量或当前目录
• 🔍（放大镜图标，通常表示搜索、查看细节或调查等意思） 智能检测通过内容分析实现智能文件格式检测

快速入门

安装

选项1：从MCP注册表（推荐）

此服务器已在模型上下文协议注册表中可用。请使用您的MCP客户端进行安装。

MCP名称：io.github.huoshuiai42/huoshui-file-converter（注：MCP在此处可能指模块名称、组件名称或项目名称等，具体含义需根据上下文确定，但直接翻译为“MCP名称”是合理的，因为“mcp”通常不直接对应中文词汇，而是根据其在特定上下文中的含义来翻译）

选项2：使用uvx

uvx huoshui-file-converter

选项3：使用pip

pip install huoshui-file-converter

基本用法

# 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客户端配置

对于 Claude Desktop 或其他 MCP 客户端：

{
  "mcpServers": {
    "huoshui-converter": {
      "command": "uvx",
      "args": ["huoshui-file-converter", "--dir", "/Users/yourname/Documents"]
    }
  }
}

配置选项

优先顺序

1. CLI 参数 （最高优先级）： --dir 或者 -d
2. 环境变量: HUOSHUI_WORKING_DIR
3. 智能默认如果当前目录存在问题，请使用“Documents”文件夹
4. 当前目录 （备用方案）

示例

# 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

支持的转换

MCP 工具与资源

工具

• convert_document在不同格式之间转换文件
• detect_format智能格式检测

资源

• file_list浏览目录内容（针对大目录进行了优化）

- limit控制显示的文件数量（默认：100） - supported_only仅显示可转换文件

• file_get获取详细的文件信息
• conversion_capability_list列出支持的转换

提示

• role_and_rules人工智能助手行为准则

性能特点

• 快速目录列表基于扩展名的大型目录格式检测
• 智能文件限制默认100个文件限制，防止用户界面冻结
• 大文件处理文件大小超过50MB的会被标记并进行特殊处理
• 选择性显示选项：仅显示支持的文件格式
• 内存高效在目录浏览时避免读取文件内容

安全特性

• 路径验证防止目录遍历攻击
• 工作目录限制所有操作均在配置的目录中进行沙盒化处理
• 初创企业验证检查目录是否存在及权限
• 相对路径强制执行拒绝使用绝对路径

命令行选项

$ 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

错误处理

服务器在启动时验证工作目录：

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

常见错误及解决方案：

发展

要求

• Python 3.8及以上版本
• pypandoc
• pandoc（系统依赖）
• LaTeX（用于PDF转换）

测试

# Test configuration
uvx huoshui-file-converter --dir "/tmp/test"

# Check startup messages
# ✅ Working directory configured: /tmp/test
# 📂 Source: CLI argument

文档

• 工作目录配置
• MCP配置示例
• 性能优化指南

许可证

\[此处填写您的许可证\]