magicconvert-mcp-server 1.1.6
MCP Server for MagicConvert - Convert various file formats to Markdown
License: MIT
Requires Python: >=3.10
Keywords: conversion, docx, markdown, mcp, ocr, pdf, 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)