Metadata-Version: 2.4
Name: aspose-html-cloud-mcp
Version: 1.0.0
Summary: MCP server that exposes Aspose.HTML Cloud document conversion (HTML, Markdown, SVG, EPUB ? PDF, DOCX, PNG, etc.) as tools for AI assistants.
Project-URL: Homepage, https://github.com/aspose-html-cloud/Aspose.HTML-Cloud-MCP
Project-URL: Repository, https://github.com/aspose-html-cloud/Aspose.HTML-Cloud-MCP
Project-URL: Issues, https://github.com/aspose-html-cloud/Aspose.HTML-Cloud-MCP/issues
Author-email: Aspose <support@aspose.cloud>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,aspose,claude,conversion,copilot,cursor,html,mcp,model-context-protocol,pdf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Aspose.HTML Cloud MCP Server (Python)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes **Aspose.HTML Cloud** document conversion as tools for AI assistants like Claude Desktop, Cursor, VS Code Copilot, and other MCP-compatible clients.

## What it does

Converts documents between formats via the [Aspose.HTML Cloud API](https://products.aspose.cloud/html/).

| Supported input formats | Supported output formats |
|---|---|
| `html`, `mhtml`, `xhtml`, `epub`, `svg`, `md` | `pdf`, `xps`, `docx`, `doc`, `jpeg`, `png`, `bmp`, `gif`, `tiff`, `webp`, `md`, `mhtml`, `svg` |

**Available tools:**

| Tool | Input source |
|---|---|
| `convert_url_to_format` | Public URL |
| `convert_content_to_format` | Raw HTML / SVG / Markdown string |
| `convert_base64_to_format` | Base64-encoded document |
| `convert_file_to_format` | Local file path |
| `vectorize_image` | Raster image ? SVG vectorization |

**Example prompts:**

> "Convert https://example.com to PDF"

> "Convert this HTML to DOCX: \<html\>\<body\>\<h1\>Hello\</h1\>\</body\>\</html\>"

> "Convert C:\docs\report.html to PNG"

> "Vectorize this PNG image into SVG"

## Prerequisites

- **Python 3.10+**
- A free **Aspose Cloud** account -- sign up at [dashboard.aspose.cloud](https://dashboard.aspose.cloud/) and create an application to get your **Client ID** and **Client Secret**

## Installation

```bash
pip install aspose-html-cloud-mcp
```

Or run directly with [`uvx`](https://docs.astral.sh/uv/) (no install needed):

```bash
uvx aspose-html-cloud-mcp
```

## Configuration with MCP Clients

Credentials are passed via environment variables `ASPOSE_CLIENT_ID` and `ASPOSE_CLIENT_SECRET`.

### Claude Desktop

Edit your Claude Desktop config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "aspose-html-cloud": {
      "command": "uvx",
      "args": ["aspose-html-cloud-mcp"],
      "env": {
        "ASPOSE_CLIENT_ID": "your-client-id",
        "ASPOSE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### VS Code (Copilot)

Add to your `.vscode/settings.json` or user settings:

```json
{
  "mcp": {
    "servers": {
      "aspose-html-cloud": {
        "command": "uvx",
        "args": ["aspose-html-cloud-mcp"],
        "env": {
          "ASPOSE_CLIENT_ID": "your-client-id",
          "ASPOSE_CLIENT_SECRET": "your-client-secret"
        }
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP configuration (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "aspose-html-cloud": {
      "command": "uvx",
      "args": ["aspose-html-cloud-mcp"],
      "env": {
        "ASPOSE_CLIENT_ID": "your-client-id",
        "ASPOSE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### Alternative: Using pip + python

If you installed via `pip install` instead of `uvx`, replace the command:

```json
{
  "command": "aspose-html-cloud-mcp"
}
```

Or:

```json
{
  "command": "python",
  "args": ["-m", "aspose_html_cloud_mcp"]
}
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `ASPOSE_CLIENT_ID` | Yes | Your Aspose Cloud application Client ID |
| `ASPOSE_CLIENT_SECRET` | Yes | Your Aspose Cloud application Client Secret |
| `ASPOSE_HTML_API_URL` | No | Override the API base URL (default: `https://api.aspose.cloud`) |

## Development

```bash
# Clone the repository
git clone https://github.com/aspose-html-cloud/Aspose.HTML-Cloud-MCP.git
cd Aspose.HTML-Cloud-MCP/python

# Create a virtual environment and install in dev mode
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -e .

# Run the server
export ASPOSE_CLIENT_ID="your-client-id"
export ASPOSE_CLIENT_SECRET="your-client-secret"
aspose-html-cloud-mcp
```

## Publishing to PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

The Aspose.HTML Cloud API itself requires a separate subscription -- a free tier is available at [aspose.cloud](https://purchase.aspose.cloud/pricing).
