file-convert-mcp 0.1.2__py3-none-any.whl

file_convert_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""file-convert-mcp - MCP tool for file conversion and file format detection by Convert.Guru"""
+
+__version__ = "0.1.2"

file_convert_mcp/server.py

@@ -0,0 +1,254 @@
+import os
+import sys
+import re
+import magic
+import json
+from typing import Dict, Any
+from fastmcp import FastMCP
+from dotenv import load_dotenv
+import aiohttp
+from starlette.responses import JSONResponse
+import asyncio
+
+# Load environment variables
+load_dotenv()
+
+# Initialize FastMCP
+mcp = FastMCP("file-convert-mcp")
+base_url = 'https://convert.guru'
+MAX_FILE_SIZE = 40 * 1024 * 1024
+api_key = os.getenv("CONVERT_GURU_API_KEY")
+if api_key is None:
+    api_key = ''
+
+@mcp.custom_route("/health", methods=["GET"])
+async def health_check(request):
+    return JSONResponse({"status": "healthy", "service": "mcp-server"})
+
+@mcp.custom_route("/tools", methods=["GET"])
+async def list_tools(request):
+    tools_info = []
+    for tool_name, tool in (await mcp.get_tools()).items():
+        tools_info.append({
+            "name": tool_name,
+            "description": tool.description or "No description available",
+            "async": asyncio.iscoroutinefunction(tool.fn)
+        })
+    
+    return JSONResponse({
+        "tools": tools_info,
+        "total_tools": len(tools_info)
+    })
+
+@mcp.tool()
+async def detect_file_type(file_path: str) -> Dict[str, Any]:
+    """Detect file type by sending the first 200 bytes of the file to Convert.Guru API."""
+    if not file_path:
+        return {"error": "file_path parameter is required"}
+
+    if not os.path.exists(file_path):
+        return {"error": f"File not found (use the absolute file path): {file_path}"}
+
+    if not os.path.isfile(file_path):
+        return {"error": f"Not a file: {file_path}"}
+
+    try:
+        with open(file_path, "rb") as f:
+            first_200_bytes = f.read(200)  # Read only the first 200 bytes
+
+        _, file_extension = os.path.splitext(file_path)
+        file_extension = file_extension.lstrip('.') # Remove dot
+        filename = os.path.basename(file_path)
+        file_size_bytes = os.path.getsize(file_path)
+        size_hex = hex(file_size_bytes)
+        mime_type = magic.Magic(mime=True).from_file(file_path)
+
+        data = [file_extension,size_hex,mime_type,filename]
+        separator = '\xFE'
+        joined_data = separator.join(data)
+        headers = {'cache-control': 'no-cache', 'api-key': api_key}
+
+        data_array = bytearray()
+        for char in joined_data:
+            data_array.append(ord(char) & 0xFF)
+
+        data_array.append(0xFE)
+        data_array.extend(first_200_bytes)
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(base_url + '/api/v1/detect_file_type', data=data_array, headers=headers) as response:
+                if response.status == 200:
+                    content = await response.text()
+                    comment_pattern = re.compile(r'<!--.+-->')
+                    # Remove all occurrences of the pattern from the string
+                    content = comment_pattern.sub('', content)
+                    return {"result": {"file_type_description": content.strip()}}
+                else:
+                    error_text = await response.text()
+                    return {"error": f"API request failed with status {response.status}: {error_text}"}
+
+    except aiohttp.ClientError as e:
+        return {"error": f"Error making API request: {e}"}
+    except Exception as e:
+        return {"error": f"Error processing file: {e}"}
+
+@mcp.tool()
+async def convert_file(file_path: str, ext_out: str) -> Dict[str, Any]:
+    """Convert a file to other format via Convert.Guru API. Pass the file path and output extension."""
+    if not file_path:
+        return {"error": "file_path parameter is required"}
+
+    if not ext_out:
+        return {"error": "ext_out parameter is required"}
+
+    if not os.path.exists(file_path):
+        return {"error": f"File not found (use the absolute file path): {file_path}"}
+
+    if not os.path.isfile(file_path):
+        return {"error": f"Not a file: {file_path}"}
+
+    try:
+        with open(file_path, "rb") as f:
+            chunk = f.read(MAX_FILE_SIZE + 1)
+            if len(chunk) > MAX_FILE_SIZE:
+                return {"error": "File exceeds the maximum upload size of 40 MiB."}
+
+            filename = os.path.basename(file_path)
+
+            data = aiohttp.FormData()
+            data.add_field('file', chunk, filename=filename)
+            headers = {'cache-control': 'no-cache', 'api-key': api_key}
+
+            async with aiohttp.ClientSession() as session:
+                async with session.post(base_url + '/api/v1/upload', data=data, headers=headers) as response:
+                    if response.status == 200:
+                        response_text = await response.text()
+                        try:
+                            # Explicitly parse using json.loads
+                            json_result = json.loads(response_text)
+                            json_payload = {
+                                "filename": json_result['Filename'], "ext_out": ext_out.lower()}
+                            conv_response_text = await post_json(base_url + '/api/v1/convert', json_payload, headers)
+                            try:
+                                # Explicitly parse using json.loads
+                                conv_json_result = json.loads(
+                                    conv_response_text)
+                                
+                                ## check for error in conv_json_result
+                                if conv_json_result.get('error'):
+                                    conv_json_result['error'] = f"File conversion failed: {conv_json_result.get('error')}"
+                                    return conv_json_result
+
+                                file_info = conv_json_result.get('file')
+                                if file_info and 'ext_out' in file_info and 'urls' in file_info and file_info['urls']:
+                                    file_extension = file_info.get('ext_out')
+                                    save_path = file_path + '.converted' + \
+                                        f".{file_extension}"
+                                    saved_paths = []
+                                    for file_url_path in file_info['urls']:
+                                        full_file_url = (base_url + file_url_path
+                                                         if file_url_path.startswith('/') else file_url_path)
+                                        download_result = await download_file(session, full_file_url, save_path)
+                                        if 'error' in download_result:
+                                            download_result['result'] = {"converted_file_paths": saved_paths}
+                                            return download_result
+                                        saved_paths.append(download_result['result']['converted_file_path'])
+                                    return {"result": {
+                                        "converted_file_path": saved_paths[0],
+                                        "converted_file_paths": saved_paths,
+                                    }}
+
+                                else:
+                                    return {"error": f"File URL information not found in the API response.: {conv_response_text}"}
+                            except json.JSONDecodeError:
+                                # If the response is not JSON (convert)
+                                return {"error": f"API convert request failed - response text is not JSON: {conv_response_text}"}
+
+                        except json.JSONDecodeError:
+                            # If the response is not JSON (upload)
+                            return {"error": f"API upload request failed - response text is not JSON: {response_text}"}
+                    else:
+                        error_text = await response.text()
+                        return {"error": f"API request failed with status {response.status}: {error_text}"}
+
+    except aiohttp.ClientError as e:
+        return {"error": f"Error making API request: {e}"}
+    except Exception as e:
+        return {"error": f"Error processing file: {e}"}
+
+async def post_json(url: str, data: dict, headers):
+    """
+    Posts JSON data to a specified URL using aiohttp.
+
+    Args:
+        url: The URL to post the JSON data to.
+        data: A Python dictionary that will be converted to JSON.
+    """
+    cloned_headers = headers.copy()
+    cloned_headers['Content-Type'] = 'application/json'
+    async with aiohttp.ClientSession() as session:
+        try:
+            async with session.post(url, json=data, headers=cloned_headers) as response:
+                response_text = await response.text()
+                status = response.status
+                err = {}
+
+                if status == 200 or status == 400:
+                    return response_text
+                elif status == 524:
+                    err = {"error": f"Error HTTP 524 - operation takes too long to complete, timeout occured."}
+                elif status == 500:
+                    err = {"error": f"Error HTTP 500 - operation takes too long to complete, internal server error."}
+                else:
+                    err = {"error": f"Error HTTP {status})."}
+                
+                return json.dumps(err)
+        except aiohttp.ClientError as e:
+            err = {"error": f"An error occurred during the request (exception): {e}"}
+            return json.dumps(err)
+
+async def download_file(session: aiohttp.ClientSession, url: str, save_path: str) -> Dict[str, Any]:
+    """Downloads a file from a URL and saves it to the specified path."""
+    try:
+        async with session.get(url) as response:
+            if response.status == 200:
+                root, extension = os.path.splitext(save_path)
+                counter = 1
+                while True:
+                    try:
+                        f = open(save_path, 'xb')
+                        break
+                    except FileExistsError:
+                        counter += 1
+                        save_path = f"{root}_{counter}{extension}"
+                try:
+                    with f:
+                        async for chunk in response.content.iter_chunked(8192):
+                            f.write(chunk)
+                except BaseException:
+                    os.remove(save_path)
+                    raise
+                return {"result": {"converted_file_path": save_path}}
+            else:
+                response_text = await response.text()
+                return {"error": f"File download from {url} failed with status {response.status}: {response_text}"}
+    except aiohttp.ClientError as e:
+        return {"error": f"An error occurred during file download from {url}: {e}"}
+
+def main():
+    """Start the installed command and direct script with the same settings."""
+    transport = os.getenv("TRANSPORT", "").upper()
+    if transport == "HTTP":
+        port = os.getenv("PORT", "8000")
+        try:
+            port_int = int(port)
+            mcp.run(transport="http", host="0.0.0.0", port=port_int)
+        except ValueError:
+            print(f"Invalid PORT value: {port}. Using default stdio transport.", file=sys.stderr)
+            mcp.run()
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()

file_convert_mcp-0.1.2.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.5
+Name: file-convert-mcp
+Version: 0.1.2
+Summary: MCP tool for file conversion and file format detection by Convert.Guru
+Project-URL: Homepage, https://convert.guru
+Project-URL: Repository, https://github.com/convertguru/file-convert-mcp
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiohttp
+Requires-Dist: fastmcp<3,>=2.14.7
+Requires-Dist: python-dotenv
+Requires-Dist: python-magic-bin==0.4.14; sys_platform == 'win32'
+Requires-Dist: python-magic; sys_platform != 'win32'
+Requires-Dist: starlette
+Description-Content-Type: text/markdown
+
+# File Convert MCP Server
+[![smithery badge](https://smithery.ai/badge/@convertguru/file-convert-mcp)](https://smithery.ai/server/@convertguru/file-convert-mcp)
+
+A Model Context Protocol (MCP) server for converting files between various formats.
+
+File Convert is an MCP server designed to handle the conversion of a wide array of file formats, including images, office documents, audio, video, text, and data files. It aims to provide seamless transformation into popular formats such as PDF, JPG, MP4, and HTML, among others. This server offers a set of powerful tools to convert diverse file types into easily accessible and widely compatible formats like PDF, JPG, PNG, TXT.
+
+## ✨ Features
+
+- **Intelligent File Type Detection:** Employs a combination of AI, TrID, and magic bytes for accurate file type identification.
+- **Versatile File Conversion:** Supports conversion between numerous file types and the following popular formats:
+    - **Images:** Handles a vast range of formats, including many legacy ones. Converts to PDF, JPG, PNG.
+    - **Office Documents:** Converts to PDF, TXT, HTML.
+    - **Audio/Video:** Converts to MP3, MP4.
+    - **Databases:** Converts to CSV.
+    - **Various Files:** Offers conversion capabilities for other file types as well.
+
+## 🛠️ Requirements
+
+1. **Python:** Version 3.12 or higher is required.
+2. **uv Tool:** Install the [Python uv tool](https://docs.astral.sh/uv/getting-started/installation/) for efficient dependency management and easy execution of the MCP server.
+3. **API Key (Development):** As of May 2025, the MCP is in its testing phase, and **no API key is currently required** for development. For future production use, please [contact the Convert.Guru team](https://convert.guru/contact) to obtain an API key.
+
+## 🚀 Usage with Desktop App
+
+To integrate this server with your desktop application, add the following configuration to your app's server settings. If necessary, adjust the absolute path to the `uv`/`uvx` executables (or `uv.exe`/`uvx.exe` on Windows).
+
+**Using `uvx` (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "file-convert": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/convertguru/file-convert-mcp.git", "file-convert-mcp"],
+      "env": {
+        "CONVERT_GURU_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+**If you have cloned the repository locally (adjust paths as needed):**
+
+```json
+{
+  "mcpServers": {
+    "file-convert": {
+      "command": "/home/User/.local/bin/uv",
+      "args": ["--directory", "/home/User/file-convert-mcp/src/file_convert_mcp", "run", "server.py"],
+      "env": {
+        "CONVERT_GURU_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+**Using local `uvx`:**
+
+```json
+{
+  "mcpServers": {
+    "file-convert": {
+      "command": "uvx",
+      "args": ["--from", "/home/User/file-convert-mcp", "file-convert-mcp"],
+      "env": {
+        "CONVERT_GURU_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+The MCP server supports the following environment variables:
+
+- **`CONVERT_GURU_API_KEY`**: Your Convert.Guru API key (optional for development)
+- **`TRANSPORT`**: Transport method for the MCP server
+  - `"stdio"` (default): Standard input/output transport
+  - `"http"`: HTTP transport (streamable) with REST API endpoints
+- **`PORT`**: Port number for HTTP transport (default: 8000, only used when `TRANSPORT=http`)
+
+When using HTTP transport, the server provides additional endpoints:
+- `GET /health` - Health check endpoint
+- `GET /tools` - List of available MCP tools
+
+Also, see this guide on how to [set up MCP tools in Claude Desktop](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users).
+
+### Installing via Smithery
+
+To install file-convert-mcp for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@convertguru/file-convert-mcp):
+
+```bash
+npx -y @smithery/cli install @convertguru/file-convert-mcp --client claude
+```
+
+## 🛠️ Development
+
+Get started with local development by following these steps:
+
+**1. Clone the repository:**
+
+```bash
+git clone https://github.com/convertguru/file-convert-mcp.git
+```
+
+**2. Fetch and cache Python dependencies (optional, `uvx` handles this automatically):**
+
+```bash
+cd file-convert-mcp
+uv sync
+cd ..
+```
+
+**3. Create .env file with your (optional for now) API key:**
+
+```bash
+echo "CONVERT_GURU_API_KEY=your_api_key_here" > file-convert-mcp/.env
+```
+
+**4. Run the MCP server locally using various `uv` commands:**
+
+```bash
+# Using uvx with .env file from the local directory
+cd file-convert-mcp
+UV_ENV_FILE=.env uvx --from ./file-convert-mcp file-convert-mcp
+
+# OR using uv directly to run the server script
+uv run file-convert-mcp/src/file_convert_mcp/server.py
+
+# OR specifying the directory for uv
+uv --directory file-convert-mcp/src/file_convert_mcp run server.py
+
+# OR navigating into the server directory
+cd file-convert-mcp/src/file_convert_mcp
+uv run server.py
+
+# OR using uvx to fetch the core from the GitHub repository + local .env file
+UV_ENV_FILE=.env uvx --from git+https://github.com/convertguru/file-convert-mcp.git file-convert-mcp
+
+# OR run with HTTP transport on custom port
+TRANSPORT=http PORT=9000 uv run file-convert-mcp/src/file_convert_mcp/server.py
+
+# OR run with stdio transport (default)
+TRANSPORT=stdio uv run file-convert-mcp/src/file_convert_mcp/server.py
+```
+
+**5. Create .env file with your configuration (optional for now):**
+
+```bash
+# Basic configuration
+echo "CONVERT_GURU_API_KEY=your_api_key_here" > file-convert-mcp/.env
+
+# OR with transport configuration
+echo "CONVERT_GURU_API_KEY=your_api_key_here" > file-convert-mcp/.env
+echo "TRANSPORT=http" >> file-convert-mcp/.env
+echo "PORT=8000" >> file-convert-mcp/.env
+```
+
+**6. Modify the server logic if needed:**
+Edit the main server file located at `src/file_convert_mcp/server.py.`
+
+**7. Clearing the `uv` Cache (if needed):**
+If `uv` has cached an older version of the code in `~/.cache/uv`, you might need to clear the cache. Alternatively, use `uv` with the `-n` or `--no-cache` option to bypass it.
+
+## ⚙️ Available Tools
+
+The MCP server provides the following tools:
+
+* `detect_file_type`: Analyzes the first 200 bytes of an uploaded file and uses the Convert.Guru API to determine its type.
+* `convert_file`: Converts a given file to a specified output format. The desired file extension should be passed as the `ext_out` parameter.
+
+Files larger than 40 MiB are rejected before upload. All result files are saved
+beside the input file. Existing files are preserved by adding numbered suffixes.
+The result contains `converted_file_paths` for all downloaded files and retains
+`converted_file_path` for the first file for compatibility. If a later download
+fails, the error response includes the paths already downloaded.
+
+### Local development and checks (shared user installation)
+
+```powershell
+python -m pip install --user pytest build hatchling editables
+python -m pip install --user --no-build-isolation -e .
+python -m pytest -q
+python -m build --no-isolation
+```
+
+These tests use a local API substitute and do not upload files to Convert.Guru.
+They cover the 40 MiB boundary, multiple results, existing files, partial failure,
+native file detection, and the installed STDIO/HTTP command. Large temporary test
+files are removed automatically. Building creates local artifacts in `dist/`;
+it does not publish them.
+
+On Windows, the package uses `python-magic-bin`, which bundles libmagic.
+FastMCP is constrained to the tested 2.x API. If the user Scripts directory is not
+on PATH, launch `file-convert-mcp.exe` using its full path, or run
+`python -m file_convert_mcp.server`.
+
+## 📜 License
+
+Visit us [https://convert.guru](https://convert.guru/)
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for complete details.

file_convert_mcp-0.1.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+file_convert_mcp/__init__.py,sha256=lByJAD0oq9PtxtDVVGK_RCi13uaZ5VDFuQ4xSwoyB4I,122
+file_convert_mcp/server.py,sha256=51O-caBzdPQa67FRELIVGPK21dctWImVcpYYen3dDxI,11498
+file_convert_mcp-0.1.2.dist-info/METADATA,sha256=V5IMSeDYIRvwIOdBzrCX2m8bCdkcNIJR_cfTft8Q2jU,8433
+file_convert_mcp-0.1.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+file_convert_mcp-0.1.2.dist-info/entry_points.txt,sha256=OCX21YgRXluFTDsRq01P5AHAyvU2sH7D9KcfMr7J98U,66
+file_convert_mcp-0.1.2.dist-info/licenses/LICENSE,sha256=pl9FVNBTGggLFoBSc-xb8sIn4i3h_Y6iTTqId29qVhM,1090
+file_convert_mcp-0.1.2.dist-info/RECORD,,

file_convert_mcp-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

file_convert_mcp-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+file-convert-mcp = file_convert_mcp.server:main

file_convert_mcp-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 convert.guru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.