{
  "markdown": "# 活水 PDF 转换器 (Huoshui PDF Converter)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://github.com/modelcontextprotocol/spec)\n[![PyPI version](https://badge.fury.io/py/huoshui-pdf-converter.svg)](https://pypi.org/project/huoshui-pdf-converter/)\n\nA high-quality, cross-platform PDF ↔ Markdown converter implemented as an MCP (Model Context Protocol) server. Supports bidirectional conversion with full Unicode/CJK character support.\n\n## Features\n\n### Core Capabilities\n\n- **PDF → Markdown**: Extract text and images with layout preservation\n- **Markdown → PDF**: Generate beautiful PDFs with multiple rendering engines\n- **Unicode Support**: Full support for Chinese, Japanese, Korean, and other Unicode characters\n- **Cross-Platform**: Works on Windows, macOS, and Linux\n- **MCP Integration**: Use with Claude Desktop or any MCP-compatible client\n\n### Technical Features\n\n- **Pure Python**: No external system dependencies required\n- **Automatic Font Detection**: Finds and uses system Unicode fonts\n- **Smart Engine Selection**: Automatically switches engines based on content\n- **Comprehensive Error Handling**: Graceful degradation and detailed logging\n- **Async Architecture**: Non-blocking operations for better performance\n\n## Installation\n\n### 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-pdf-converter\n\n### As a Python Package\n\n```bash\npip install huoshui-pdf-converter\n```\n\nOr using `uv` (recommended):\n\n```bash\nuv pip install huoshui-pdf-converter\n```\n\n### As an MCP Server\n\nAdd to your Claude Desktop configuration:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"huoshui-pdf-converter\": {\n      \"command\": \"uvx\",\n      \"args\": [\"huoshui-pdf-converter\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nOr if you prefer to use a specific Python environment:\n\n```json\n{\n  \"mcpServers\": {\n    \"huoshui-pdf-converter\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"huoshui_pdf_converter.server\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n## Usage\n\n### Command Line Interface\n\n```bash\n# Convert PDF to Markdown\nhuoshui-pdf pdf-to-md input.pdf output.md\n\n# Convert Markdown to PDF\nhuoshui-pdf md-to-pdf input.md output.pdf\n\n# With options\nhuoshui-pdf md-to-pdf input.md output.pdf --page-size A4 --margin 2cm --font-size 12\n```\n\n### As a Python Library\n\n```python\nimport asyncio\nfrom huoshui_pdf_converter import PDFToMarkdownConverter, MarkdownToPDFConverter\n\nasync def main():\n    # PDF to Markdown\n    pdf_converter = PDFToMarkdownConverter()\n    result = await pdf_converter.convert(\n        pdf_path=\"input.pdf\",\n        output_path=\"output.md\",\n        extract_images=True,\n        preserve_formatting=True\n    )\n\n    # Markdown to PDF\n    md_converter = MarkdownToPDFConverter()\n    result = await md_converter.convert(\n        markdown_path=\"input.md\",\n        output_path=\"output.pdf\",\n        page_size=\"A4\",\n        margin=\"2cm\",\n        font_size=12\n    )\n\nasyncio.run(main())\n```\n\n### MCP Tools\n\nWhen used as an MCP server, the following tools are available:\n\n1. **pdf_to_markdown**: Convert PDF files to Markdown\n\n   ```json\n   {\n     \"pdf_path\": \"path/to/input.pdf\",\n     \"output_path\": \"path/to/output.md\",\n     \"extract_images\": true,\n     \"preserve_formatting\": true\n   }\n   ```\n\n2. **markdown_to_pdf**: Convert Markdown files to PDF\n\n   ```json\n   {\n     \"markdown_path\": \"path/to/input.md\",\n     \"output_path\": \"path/to/output.pdf\",\n     \"page_size\": \"A4\",\n     \"margin\": \"2cm\",\n     \"font_size\": 12\n   }\n   ```\n\n3. **list_supported_formats**: Get supported formats and engines\n4. **validate_file**: Validate input files before conversion\n\n## Supported Formats\n\n### Input Formats\n\n- **PDF**: All standard PDF files (PDF 1.0 - 1.7)\n- **Markdown**: CommonMark and GitHub Flavored Markdown\n\n### Output Options\n\n- **Page Sizes**: A4, A3, Letter, Legal\n- **Margins**: Customizable (e.g., \"1cm\", \"0.5in\")\n- **Font Sizes**: Any size in points\n- **Images**: PNG, JPEG extraction from PDFs\n\n## Unicode and Font Support\n\nThe converter automatically detects and uses appropriate fonts for different languages:\n\n- **macOS**: Arial Unicode, PingFang SC, STHeiti\n- **Windows**: Microsoft YaHei, SimSun, Arial Unicode MS\n- **Linux**: Noto Sans CJK, Source Han Sans, WenQuanYi\n\n## Architecture\n\n### Conversion Engines\n\n**PDF → Markdown**\n\n- PyMuPDF (MuPDF): High-quality text and image extraction\n\n**Markdown → PDF**\n\n- ReportLab: Best Unicode support, cross-platform compatibility\n- xhtml2pdf: Good HTML/CSS rendering (fallback)\n- fpdf2: Basic PDF generation (last resort)\n\n### Engine Selection Logic\n\n1. Detects CJK characters → Uses ReportLab\n2. Complex formatting → Uses xhtml2pdf\n3. Basic documents → Uses any available engine\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/huoshui-pdf-converter.git\ncd huoshui-pdf-converter\n\n# Install dependencies\nuv pip install -e \".[dev]\"\n\n# Run tests\npython test_converter.py\n```\n\n### Project Structure\n\n```\nhuoshui-pdf-converter/\n├── huoshui_pdf_converter/\n│   ├── __init__.py\n│   ├── server.py           # MCP server implementation\n│   ├── pdf_converter.py    # PDF to Markdown converter\n│   └── markdown_converter.py # Markdown to PDF converter\n├── pyproject.toml\n├── README.md\n├── LICENSE\n└── test_converter.py\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Chinese characters not displaying**:\n\n   - Ensure Arial Unicode or similar fonts are installed\n   - The converter will automatically detect and use appropriate fonts\n\n2. **Import errors**:\n\n   - Install all dependencies: `pip install huoshui-pdf-converter[all]`\n\n3. **MCP connection issues**:\n   - Check Claude Desktop logs\n   - Ensure Python is in your PATH\n\n### Logging\n\nEnable debug logging:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [FastMCP](https://github.com/jlowin/fastmcp) for Model Context Protocol support\n- Uses [PyMuPDF](https://github.com/pymupdf/PyMuPDF) for PDF parsing\n- Uses [ReportLab](https://www.reportlab.com/) for PDF generation\n- Inspired by the need for better PDF ↔ Markdown conversion tools\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/yourusername/huoshui-pdf-converter/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/huoshui-pdf-converter/discussions)\n- **Email**: your.email@example.com\n",
  "bytes": 7256,
  "sha": "960974e6b81874ca2199c47624f6aa6b9d1968f2c84a29d2ec3a4bf0746c7ec0",
  "repo_slug": "huoshuiai42/huoshui-pdf-converter",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_huoshuiai42_huoshui_pdf_conver_af487e3b/readme"
}