Magicconvert

A Model Context Protocol (MCP) server that provides robust and extensible file, URL, and text conversion capabilities using the MagicConvert library. Outputs are delivered in clean, structured Markdown format.

---

🌟 Features

• ✅ Document Conversion:

  • Word .docx
  • PDF .pdf
  • PowerPoint .pptx
  • Excel .xlsx
  • CSV .csv

• 🖼️ Image OCR:

  • JPEG .jpg, .jpeg
  • PNG .png
  • TIFF .tiff
  • BMP .bmp

• 🌐 Web Content to Markdown:

  • URLs (http://, https://)
  • HTML Files .html, .htm

• ✍️ Text Conversion:

  • Plain text
  • HTML
  • CSV

• 🧩 Flexible Input Options:

  • Local file paths
  • Base64 encoded uploads
  • Direct URLs
  • Raw text input

• 🧼 Clean Output:

  • Well-structured, readable Markdown output

• 🔁 Temporary File Handling:

  • Secure and automatic temp file creation and cleanup

---

🚀 Installation

Prerequisites

Install the core library:

pip install magicconvert

Install the MCP server package:

pip install magicconvert-mcp-server

---

Run with uvx (Recommended)

Add the server in your MCP configuration (mcp.yaml or .mcp/config.json):

{
  "mcpServers": {
    "magicconvert": {
      "command": "uvx magicconvert-mcp-server"
    }
  }
}

Then run the server:

uvx magicconvert-mcp-server

---

🛠️ Supported Tools

The server exposes the following tools via MCP:

1. convert_file_to_markdown

Description: Converts a file from the local file system to Markdown.

{
  "file_path": "/path/to/your/file.pdf"
}

---

2. convert_base64_file_to_markdown

Description: Accepts a base64 encoded file (from uploads) and converts it.

{
  "base64_data": "base64string==",
  "filename": "document.pdf"
}

---

3. convert_url_to_markdown

Description: Downloads a webpage or document from a URL and converts it.

{
  "url": "https://example.com/article"
}

---

4. convert_text_to_markdown

Description: Converts raw text content into Markdown. Supports plain text, HTML, and CSV.

{
  "text_content": "<p>Hello</p>",
  "format_type": "html"
}

Accepted format_type values:

• plain (default)
• html
• csv

---

5. get_supported_formats

Description: Returns a Markdown-formatted list of supported input types and features.

No parameters required.

---

📦 Example Usage

from mcp.client import Client

client = Client()

response = client.call_tool("magicconvert", "convert_file_to_markdown", {
    "file_path": "example.pdf"
})

print(response[0].text)

---

🔒 Temporary File Management

All temporary files created (e.g., for base64 or text inputs) are:

• Stored in a platform-safe temporary directory (e.g., /tmp, %TEMP%)
• Cleaned up automatically after conversion
• Validated for path safety

---

⚙️ Logging

The server logs messages to the mcp_magicconvert_server logger.

To enable debug logging, set the environment variable:

export LOGLEVEL=DEBUG

---

🧪 Development & Testing

Clone the repository and run:

python -m magicconvert_mcp_server

To run with stdio transport (MCP):

uvx magicconvert-mcp-server

To test via CLI, MCP-compatible clients like mcp[cli] are recommended.

---

📚 Advanced: MCP Integration

This library is designed for use in MCP-compatible environments, such as:

• OpenAI's API calling tools
• LangChain or LlamaIndex with MCP extensions
• Custom MCP client implementations

---

🧠 Internals Overview

The server defines:

• A MagicConvertProcessor that wraps around the core MagicConvert logic
• Full support for async base64 decoding using aiofiles
• Smart MIME inference via filenames and extensions
• A modular Server class using the mcp framework with defined tool interfaces

---

📄 License

MIT License. See LICENSE for details.

---

🔗 Links

• PyPI: magicconvert-mcp-server
• Core Library: MagicConvert
• MCP Protocol: mcp-spec