Markdownify MCP Server - UTF-8 Enhanced

This is an enhanced version of the original Markdownify MCP project, with improved UTF-8 encoding support and optimized handling of multilingual content.

中文文档

Enhancements

• Added comprehensive UTF-8 encoding support
• Optimized handling of multilingual content
• Fixed encoding issues on Windows systems
• Improved error handling mechanisms

Key Differences from Original Project

1. Enhanced Encoding Support:

2. Improved Error Handling:

3. Extended Functionality:

4. Performance Optimizations:

5. Better Development Experience:

Features

Supports converting various file types to Markdown:

• PDF files
• Images (with metadata)
• Audio (with transcription)
• Word documents (DOCX)
• Excel spreadsheets (XLSX)
• PowerPoint presentations (PPTX)
• Web content:
  • YouTube video transcripts
  • Search results
  • General web pages
• Existing Markdown files

Quick Start

1. Clone this repository:

git clone https://github.com/JDJR2024/markdownify-mcp-utf8.git
   cd markdownify-mcp-utf8

2. Install dependencies:

pnpm install

Note: This will also install `uv` and related Python dependencies.

3. Build the project:

pnpm run build

4. Start the server:

pnpm start

Requirements

• Node.js 16.0 or higher
• Python 3.8 or higher
• pnpm package manager
• Git

Detailed Installation Guide

1. Environment Setup

1. Install Node.js:

2. Install pnpm:

npm install -g pnpm
   pnpm --version

3. Install Python:

4. (Windows Only) Configure UTF-8 Support:

# Set system-wide UTF-8
   setx PYTHONIOENCODING UTF-8
   # Set current session UTF-8
   set PYTHONIOENCODING=UTF-8
   # Enable UTF-8 in command prompt
   chcp 65001

2. Project Setup

1. Clone the repository:

git clone https://github.com/JDJR2024/markdownify-mcp-utf8.git
   cd markdownify-mcp-utf8

2. Create and activate Python virtual environment:

# Windows
   python -m venv .venv
   .venv\Scripts\activate

   # Linux/macOS
   python3 -m venv .venv
   source .venv/bin/activate

3. Install project dependencies:

# Install Node.js dependencies
   pnpm install

   # Install Python dependencies (will be handled by setup.sh)
   ./setup.sh

4. Build the project:

pnpm run build

3. Verification

1. Start the server:

pnpm start

2. Test the installation:

# Convert a web page
   python convert_utf8.py "https://example.com"

   # Convert a local file
   python convert_utf8.py "path/to/your/file.docx"

Usage Guide

Basic Usage

1. Converting Web Pages:

python convert_utf8.py "https://example.com"

The converted markdown will be saved as `converted_result.md`

2. Converting Local Files:

# Convert DOCX
   python convert_utf8.py "document.docx"

   # Convert PDF
   python convert_utf8.py "document.pdf"

   # Convert PowerPoint
   python convert_utf8.py "presentation.pptx"

   # Convert Excel
   python convert_utf8.py "spreadsheet.xlsx"

3. Converting YouTube Videos:

python convert_utf8.py "https://www.youtube.com/watch?v=VIDEO_ID"

Advanced Usage

1. Environment Variables:

# Set custom UV path
   export UV_PATH="/custom/path/to/uv"

   # Set custom output directory
   export MARKDOWN_OUTPUT_DIR="/custom/output/path"

2. Batch Processing:

Create a batch file (e.g., `convert_batch.txt`) with URLs or file paths:

https://example1.com
   https://example2.com
   file1.docx
   file2.pdf

Then run:

while read -r line; do python convert_utf8.py "$line"; done < convert_batch.txt

Troubleshooting

1. Common Issues:

2. Debugging:

# Enable debug output
   export DEBUG=true
   python convert_utf8.py "your_file.docx"

Usage

Command Line

Convert web page to Markdown:

python convert_utf8.py "https://example.com"

Convert local file:

python convert_utf8.py "path/to/your/file.docx"

Desktop App Integration

To integrate this server with a desktop app, add the following to your app's server configuration:

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{ABSOLUTE_PATH}/dist/index.js"
      ],
      "env": {
        "UV_PATH": "/path/to/uv"
      }
    }
  }
}

Troubleshooting

1. Encoding Issues

2. Permission Issues

Acknowledgments

This project is based on the original work by Zach Caceres. Thanks to the original author for their outstanding contribution.

License

This project continues to be licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Before submitting a Pull Request, please:

1. Ensure your code follows the project's coding standards

2. Add necessary tests and documentation

3. Update relevant sections in the README

Contact

For issues or suggestions:

1. Submit an Issue: https://github.com/JDJR2024/markdownify-mcp-utf8/issues

2. Create a Pull Request: https://github.com/JDJR2024/markdownify-mcp-utf8/pulls

3. Email: jdidndosmmxmx@gmail.com