huoshui-file-converter

Huoshui File Converter

用于在指定工作目录中转换文档格式的安全 MCP（Model Context Protocol）服务。

功能

• 🔒 沙盒安全：所有操作均限制在已配置的工作目录中
• 📄 格式支持：支持在 Markdown、DOCX、HTML、PDF 和 TXT 之间转换
• 🚀 MCP 集成：全面支持 MCP 协议，包括提示词、资源和工具
• ⚙️ 灵活配置：可通过 CLI 参数、环境变量或当前目录进行配置
• 🔍 智能检测：通过内容分析智能检测文件格式

快速开始

安装

选项 1：从 MCP Registry 安装（推荐）

此服务已发布在 Model Context Protocol Registry 中。使用你的 MCP 客户端进行安装。

mcp-name: io.github.huoshuiai42/huoshui-file-converter

选项 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

支持的转换

源格式	目标格式
Markdown	DOCX、HTML、PDF
DOCX	Markdown、HTML、PDF
HTML	Markdown、DOCX、PDF
TXT	Markdown、DOCX、HTML、PDF

MCP 工具与资源

工具

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

资源

• file_list：浏览目录内容（针对大型目录进行了优化）
  • limit：控制显示的文件数量（默认值：100）
  • supported_only：仅显示可转换的文件
• file_get：获取详细的文件信息
• conversion_capability_list：列出支持的转换

提示词

• role_and_rules：AI 助手行为指南

性能特性

• 快速列出目录：针对大型目录，通过扩展名检测格式
• 智能限制文件数量：默认限制为 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

常见错误及解决方案：

错误	解决方案
未找到目录	创建目录或修正路径
没有写入权限	检查权限（Unix 系统上使用 chmod）
路径位于沙盒之外	仅使用相对路径

开发

要求

• 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 配置示例
• 性能优化指南

许可证

[在此填写许可证]