file-convert-mcp 0.1.2__tar.gz

file_convert_mcp-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

file_convert_mcp-0.1.2/.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv
+uv.lock
+__pycache__/
+.pytest_cache/
+dist/
+*.egg-info/

file_convert_mcp-0.1.2/Dockerfile

@@ -0,0 +1,25 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/build/project-config
+FROM python:3.12-alpine
+
+# Install runtime and build dependencies
+RUN apk add --no-cache file build-base libffi-dev openssl-dev
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml .
+COPY src ./src
+COPY LICENSE README.md ./
+
+# Install package
+RUN pip install --no-cache-dir .
+
+# Expose port 8000 for HTTP transport
+EXPOSE 8000
+
+# Set default environment variables
+ENV TRANSPORT=http
+ENV PORT=8000
+
+# Set default command
+CMD ["file-convert-mcp"]

file_convert_mcp-0.1.2/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.

file_convert_mcp-0.1.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,206 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "file-convert-mcp"
+version = "0.1.2"
+readme = "README.md"
+license = { text = "MIT" }
+description = "MCP tool for file conversion and file format detection by Convert.Guru"
+authors = []
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=2.14.7,<3",
+    "aiohttp",
+    "python-dotenv",
+    "python-magic; sys_platform != 'win32'",
+    "python-magic-bin==0.4.14; sys_platform == 'win32'",
+    "starlette"
+]
+
+[project.urls]
+Homepage = "https://convert.guru"
+Repository = "https://github.com/convertguru/file-convert-mcp"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.scripts]
+file-convert-mcp = "file_convert_mcp.server:main"

file_convert_mcp-0.1.2/smithery.yaml

@@ -0,0 +1,36 @@
+# Smithery configuration file: https://smithery.ai/docs/build/project-config
+
+startCommand:
+  type: stdio
+  configSchema:
+    # JSON Schema defining the configuration options for the MCP.
+    type: object
+    properties:
+      apiKey:
+        type: string
+        default: ""
+        description: Convert.Guru API key (optional for development)
+      transport:
+        type: string
+        enum: ["stdio", "http"]
+        default: "http"
+        description: Transport method for the MCP server
+      port:
+        type: integer
+        default: 8000
+        description: Port number for HTTP transport (optional, only used when transport is http)
+  commandFunction:
+    # A JS function that produces the CLI command based on the given config to start the MCP on stdio.
+    |-
+    (config) => ({ 
+      command: 'file-convert-mcp', 
+      env: { 
+        CONVERT_GURU_API_KEY: config.apiKey,
+        TRANSPORT: (config.transport || "http").toUpperCase(),
+        PORT: config.transport === "http" ? (config.port?.toString() || "8000") : undefined
+      } 
+    })
+  exampleConfig:
+    apiKey: ""
+    transport: "http"
+    port: 8000

file_convert_mcp-0.1.2/src/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-0.1.2/src/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/tests/test_server.py

@@ -0,0 +1,172 @@
+import asyncio
+import os
+from pathlib import Path
+import socket
+import subprocess
+import sysconfig
+import tempfile
+import time
+from urllib.request import urlopen
+
+from aiohttp import web
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+import magic
+import pytest
+
+from file_convert_mcp import server
+
+
+@pytest.fixture
+def work_dir():
+    # Large boundary-test files live in TEMP and are removed after each test.
+    with tempfile.TemporaryDirectory(prefix="file-convert-mcp-test-", ignore_cleanup_errors=True) as folder:
+        yield Path(folder)
+
+
+async def conversion_case(monkeypatch, source, *, outputs=1, failed_output=None):
+    uploads = []
+
+    async def upload(request):
+        part = await (await request.multipart()).next()
+        size = 0
+        while chunk := await part.read_chunk():
+            size += len(chunk)
+        uploads.append(size)
+        return web.json_response({"Filename": "uploaded.bin"})
+
+    async def convert(request):
+        assert (await request.json())["ext_out"] == "txt"
+        return web.json_response({"file": {
+            "ext_out": "txt", "urls": [f"/result/{n}" for n in range(outputs)]
+        }})
+
+    async def result(request):
+        n = int(request.match_info["n"])
+        if n == failed_output:
+            return web.Response(status=500, text="Test download failure")
+        return web.Response(body=f"Result {n}".encode())
+
+    app = web.Application()
+    app.router.add_post('/api/v1/upload', upload)
+    app.router.add_post('/api/v1/convert', convert)
+    app.router.add_get('/result/{n}', result)
+    runner = web.AppRunner(app)
+    await runner.setup()
+    sock = socket.socket()
+    sock.bind(('127.0.0.1', 0))
+    port = sock.getsockname()[1]
+    await web.SockSite(runner, sock).start()
+    monkeypatch.setattr(server, 'base_url', f'http://127.0.0.1:{port}')
+    try:
+        response = await server.convert_file.fn(str(source), 'TXT')
+        return response, uploads
+    finally:
+        await runner.cleanup()
+
+
+@pytest.mark.parametrize('offset', [-1, 0, 1])
+def test_upload_size_boundary(monkeypatch, work_dir, offset):
+    source = work_dir / 'boundary.bin'
+    size = server.MAX_FILE_SIZE + offset
+    with source.open('wb') as f:
+        f.truncate(size)
+    response, uploads = asyncio.run(conversion_case(monkeypatch, source))
+    if offset > 0:
+        assert '40 MiB' in response['error']
+        assert uploads == []
+    else:
+        assert uploads == [size]
+        assert Path(response['result']['converted_file_path']).read_bytes() == b'Result 0'
+
+
+def test_multiple_results_and_repeated_conversion(monkeypatch, work_dir):
+    source = work_dir / 'input.bin'
+    source.write_bytes(b'input')
+    original = work_dir / 'input.bin.converted.txt'
+    original.write_bytes(b'Keep me')
+    seen = set()
+    for _ in range(2):
+        response, uploads = asyncio.run(conversion_case(monkeypatch, source, outputs=3))
+        paths = response['result']['converted_file_paths']
+        assert response['result']['converted_file_path'] == paths[0]
+        assert len(paths) == 3
+        for n, path in enumerate(paths):
+            assert path not in seen
+            seen.add(path)
+            assert Path(path).read_bytes() == f'Result {n}'.encode()
+        assert uploads == [5]
+    assert original.read_bytes() == b'Keep me'
+    assert source.read_bytes() == b'input'
+
+
+def test_failed_download_reports_completed_files(monkeypatch, work_dir):
+    source = work_dir / 'input.bin'
+    source.write_bytes(b'input')
+    response, _ = asyncio.run(conversion_case(monkeypatch, source, outputs=3, failed_output=1))
+    assert '500' in response['error']
+    paths = response['result']['converted_file_paths']
+    assert len(paths) == 1
+    assert Path(paths[0]).read_bytes() == b'Result 0'
+
+
+def installed_command():
+    scheme = 'nt_user' if os.name == 'nt' else 'posix_user'
+    suffix = '.exe' if os.name == 'nt' else ''
+    command = Path(sysconfig.get_path('scripts', scheme)) / f'file-convert-mcp{suffix}'
+    assert command.is_file(), 'Install the package before running the transport tests.'
+    return str(command)
+
+
+async def check_mcp(transport):
+    async with Client(transport, timeout=10) as client:
+        tools = await client.list_tools()
+        assert {tool.name for tool in tools} == {'detect_file_type', 'convert_file'}
+        # An actual tool call, deliberately rejected before any external API request.
+        response = await client.call_tool('convert_file', {'file_path': '', 'ext_out': 'txt'})
+        assert 'file_path parameter is required' in str(response)
+
+
+@pytest.mark.parametrize('port', [None, 'invalid'])
+def test_installed_stdio_start(work_dir, port):
+    env = dict(os.environ, PYTHONIOENCODING='utf-8', TRANSPORT='stdio')
+    if port:
+        env.update(TRANSPORT='http', PORT=port)
+    transport = StdioTransport(command=installed_command(), args=[], env=env, cwd=str(work_dir))
+    asyncio.run(check_mcp(transport))
+
+
+def test_installed_http_start(work_dir):
+    with socket.socket() as sock:
+        sock.bind(('127.0.0.1', 0))
+        port = sock.getsockname()[1]
+    env = dict(os.environ, PYTHONIOENCODING='utf-8', TRANSPORT='http', PORT=str(port))
+    log_path = work_dir / 'http.log'
+    with log_path.open('w', encoding='utf-8') as log:
+        process = subprocess.Popen(
+            [installed_command()], env=env, cwd=work_dir,
+            stdout=log, stderr=log,
+            creationflags=subprocess.CREATE_NO_WINDOW if os.name == 'nt' else 0,
+        )
+        try:
+            deadline = time.monotonic() + 25
+            while time.monotonic() < deadline:
+                assert process.poll() is None, log_path.read_text(encoding='utf-8')
+                try:
+                    with urlopen(f'http://127.0.0.1:{port}/health', timeout=1) as response:
+                        assert response.status == 200
+                    break
+                except OSError:
+                    time.sleep(0.1)
+            else:
+                pytest.fail(log_path.read_text(encoding='utf-8'))
+            with urlopen(f'http://127.0.0.1:{port}/tools', timeout=2) as response:
+                assert b'convert_file' in response.read()
+            asyncio.run(check_mcp(f'http://127.0.0.1:{port}/mcp'))
+        finally:
+            process.terminate()
+            process.wait(timeout=10)
+
+
+def test_native_file_detection():
+    assert magic.from_buffer(b'%PDF-1.4\n', mime=True) == 'application/pdf'