magicconvert_mcp_server

# MagicConvert MCP Server > 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: ```bash pip install magicconvert ``` Install the MCP server package: ```bash pip install magicconvert-mcp-server ``` --- ### Run with `uvx` (Recommended) Add the server in your MCP configuration (`mcp.yaml` or `.mcp/config.json`): ```json { "mcpServers": { "magicconvert": { "command": "uvx magicconvert-mcp-server" } } } ``` Then run the server: ```bash 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. ```json { "file_path": "/path/to/your/file.pdf" } ``` --- ### 2. `convert_base64_file_to_markdown` **Description**: Accepts a base64 encoded file (from uploads) and converts it. ```json { "base64_data": "base64string==", "filename": "document.pdf" } ``` --- ### 3. `convert_url_to_markdown` **Description**: Downloads a webpage or document from a URL and converts it. ```json { "url": "https://example.com/article" } ``` --- ### 4. `convert_text_to_markdown` **Description**: Converts raw text content into Markdown. Supports plain text, HTML, and CSV. ```json { "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 ```python 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: ```bash export LOGLEVEL=DEBUG ``` --- ## 🧪 Development & Testing Clone the repository and run: ```bash python -m magicconvert_mcp_server ``` To run with stdio transport (MCP): ```bash 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](./LICENSE) for details. --- ## 🔗 Links - PyPI: [magicconvert-mcp-server](https://pypi.org/project/magicconvert-mcp-server/) - Core Library: [MagicConvert](https://pypi.org/project/magicconvert/) - MCP Protocol: [mcp-spec](https://github.com/microsoft/mcp)