<div align="center">
  <img src="https://api.smartrayon.eu/public/logo.png" alt="SmartConvert Logo" width="120"  style="border-radius: 20px; margin-bottom: 20px;">
  <h1>SmartConvert x402</h1>
  <p><b>The 1st Image Optimization Engine for the Agentic Web</b></p>

  [![Smithery Badge](https://smithery.ai/badge/smartunityia/conversion)](https://smithery.ai/servers/smartunityia/conversion)
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  [![Base](https://img.shields.io/badge/Network-Base-blue)](https://base.org)
  [![USDC](https://img.shields.io/badge/Payment-USDC-green)](https://circle.com/usdc)
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)

  <p>
    <a href="https://api.smartrayon.eu/site">🌍 <b>Official Landing Page</b></a> • 
    <a href="https://api.smartrayon.eu/api-docs">📖 <b>Swagger API Docs</b></a>
  </p>

  <p><i>Empower your AI agents with professional image conversion & programmatic M2M payments via x402.</i></p>
</div>

---

## 🚀 Overview

**SmartConvert x402** is a high-performance Model Context Protocol (MCP) server designed for the autonomous agent economy. It provides a plug-and-play solution for AI assistants (like Claude, Cursor, or AutoGPT) to optimize images while handling payments natively using **USDC on Base**.

### Why it's a Game Changer:
- **For AI Agents**: Zero-friction image processing. No API keys to manage per user—the agent pays its own way using the x402 protocol.
- **For Developers**: Build apps that monetize themselves instantly. Every byte processed generates revenue directly to your wallet.
- **Privacy First**: High-speed processing using `Sharp` (Node.js) with support for WebP, AVIF, PNG, JPEG, and SVG.

---

## 🛠 MCP Capabilities

Once connected to your AI assistant, SmartConvert exposes the following tools and intelligence:

### 🧰 Tools
- **`convert_image_to_webp`**: High-speed conversion to WebP or AVIF. Triggers the x402 payment lifecycle automatically.

### 🧠 Prompts (Agentic Intelligence)
- **`format_advisor`**: An expert assistant that guides the agent on choosing between WebP (speed) or AVIF (quality) based on constraints.
- **`image_optimization_agent`**: A pre-configured system prompt to turn any LLM into an autonomous image processing master.
- **`x402_payment_help`**: Interactive guide to help users and agents understand the payment flow.

### 📊 Resources
- `image-api://metrics`: Real-time transparency on billing and usage.
- `image-api://instructions`: Embedded documentation for the x402 standard.
- `image-api://spec`: Full OpenAPI definition for deep integration.

---

## 💸 The x402 Payment Flow

SmartConvert implements the **HTTP 402 Payment Required** standard, specifically designed for Machine-to-Machine (M2M) communications.

```mermaid
sequenceDiagram
    participant Agent as AI Agent (Cursor/Claude)
    participant API as SmartConvert API
    participant SDK as x402 EVM SDK (Base)

    Agent->>API: POST /convert (No signature)
    API-->>Agent: 402 Payment Required + Payment Details
    Note over Agent: Agent detects x402 protocol
    Agent->>SDK: Sign USDC TransferWithAuthorization
    SDK-->>Agent: Cryptographic Payload (Base64)
    Agent->>API: POST /convert + payment-signature
    API-->>Agent: 200 OK + Optimized Image
```

---

## ⚡ Quick Start

### For Users (Claude Desktop / Cursor)
Simply add the following to your configuration:

```json
{
  "mcpServers": {
    "smartconvert": {
      "url": "https://api.smartrayon.eu/mcp"
    }
  }
}
```

### For Developers (Self-Hosting & Monetization)
1. **Clone & Config**: `cp .env.example .env`
2. **Setup Wallet**: Enter your `WALLET_RECEIVER_ADDRESS` and Coinbase CDP credentials.
3. **Deploy with Docker**:
```bash
docker compose up -d --build
```

---

## 🔧 Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | API Port | `6722` |
| `WALLET_RECEIVER_ADDRESS` | Where USDC payments are sent | - |
| `CDP_API_KEY_ID` | Coinbase CDP Key ID | - |
| `X402_USE_TESTNET` | Toggle Base Sepolia vs Mainnet | `true` |

---

## 🤝 Contributing

We are building the economic primitives of the Agentic Web. Contributions are encouraged!
- **Core**: TypeScript / Node.js
- **Image Engine**: Sharp
- **Transport**: MCP Streamable HTTP (SSE)

---

<p align="center">
  Developed with ❤️ by <b>SmartUnityIA</b><br>
  <i>Empowering the machine economy, one byte at a time.</i>
</p>