> [!WARNING]
> **⚠️ OUTDATED REPOSITORY - This repository is no longer maintained**
> 
> A public MCP server is now available and this package is deprecated.  
> Please use the official public server instead: **https://mcp.jsoncut.com/mcp**
> 
> For more information, see: https://docs.jsoncut.com/docs/mcp/overview

---

<p align="center">
  <img src="assets/logo.png" alt="Jsoncut Logo" width="200"/>
</p>

<h1 align="center">Jsoncut MCP Server</h1>

<p align="center">
  <strong>Model Context Protocol server for the Jsoncut API</strong><br>
  Enable AI agents to generate stunning images and videos programmatically
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@jsoncut/mcp-server"><img src="https://img.shields.io/npm/v/@jsoncut/mcp-server.svg" alt="npm version"></a>
  <a href="https://github.com/jsoncut/jsoncut-mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
</p>

---

## 🚀 Features

- 🎨 **Image Generation**: Create JSON configurations for image composition with layers, positioning, and effects
- 🎬 **Video Generation**: Create JSON configurations for video rendering with clips, transitions, and audio
- ✅ **Configuration Validation**: Validate configs against the Jsoncut API before submission
- 📋 **Schema Resources**: JSON schemas automatically available as MCP resources
- 🔑 **Flexible Authentication**: API key via environment variable or .env file

---

## 📦 Quick Start

### Using npx (Recommended for Local)

```bash
export JSONCUT_API_KEY=your_api_key_here
npx -y @jsoncut/mcp-server
```

### Using Remote Server (Recommended)

A public MCP server is available at **`https://mcp.jsoncut.com`**. No installation needed - just configure your MCP client with your API key:

```json
{
  "jsoncut": {
    "url": "https://mcp.jsoncut.com/mcp",
    "headers": {
      "x-api-key": "your_jsoncut_api_key_here"
    }
  }
}
```

### Using Docker Locally (Optional)

You can also run your own local server using Docker:

```bash
# Pull and run from Docker Hub
docker run -d \
  --name jsoncut-mcp \
  -p 3210:3000 \
  centerbit/jsoncut-mcp-server:latest

# Access at: http://localhost:3210/mcp
```

Or use Docker Compose:
```bash
# Start the service
docker-compose up -d

# Access at: http://localhost:3210/mcp
```

📖 **See [DOCKER.md](./DOCKER.md) for complete Docker deployment guide**

### Get Your API Key

Get your Jsoncut API key at [jsoncut.com](https://jsoncut.com)

```bash
# Set as environment variable
export JSONCUT_API_KEY=your_api_key_here

# Or create .env file
cp .env.example .env
# Edit .env and add: JSONCUT_API_KEY=your_api_key_here
```

---

## 🎯 MCP Client Configuration

### Remote Server (Recommended)

Use the public server at `https://mcp.jsoncut.com`:

#### Cursor IDE

Open **Cursor Settings** → **Features** → **MCP Servers** → **"+ Add New MCP Server"**

```json
{
  "jsoncut": {
    "url": "https://mcp.jsoncut.com/mcp",
    "headers": {
      "X-API-Key": "your_jsoncut_api_key_here"
    }
  }
}
```

#### Claude Desktop

Add to your `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "jsoncut": {
      "url": "https://mcp.jsoncut.com/mcp",
      "headers": {
        "X-API-Key": "your_jsoncut_api_key_here"
      }
    }
  }
}
```

### Local npx Mode

For local development without network access:

#### Cursor IDE

```json
{
  "jsoncut": {
    "command": "npx",
    "args": ["-y", "@jsoncut/mcp-server"],
    "env": {
      "JSONCUT_API_KEY": "your_api_key_here"
    }
  }
}
```

#### Claude Desktop

```json
{
  "mcpServers": {
    "jsoncut": {
      "command": "npx",
      "args": ["-y", "@jsoncut/mcp-server"],
      "env": {
        "JSONCUT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Local Docker Server

If you're running your own local Docker server:

#### Cursor IDE

```json
{
  "jsoncut": {
    "url": "http://localhost:3210/mcp",
    "headers": {
      "X-API-Key": "your_jsoncut_api_key_here"
    }
  }
}
```

#### Claude Desktop

```json
{
  "mcpServers": {
    "jsoncut": {
      "url": "http://localhost:3210/mcp",
      "headers": {
        "X-API-Key": "your_jsoncut_api_key_here"
      }
    }
  }
}
```

---

## 📚 MCP Resources

The server automatically exposes JSON schemas as MCP resources:

- **`schema://image`** - Complete image generation schema
- **`schema://video`** - Complete video generation schema

AI agents can read these directly without tool calls for fast access to all configuration options.

---

## 🛠️ Available Tools

### `create_image_config`

Create JSON configurations for image generation with a layer-based system.

**Layer Types:**
- **image**: Display images with fit modes (cover, contain, fill, inside, outside)
- **text**: Text with custom fonts, alignment, wrapping, and effects
- **rectangle**: Rectangular shapes with fill, stroke, and rounded corners
- **circle**: Circular and elliptical shapes
- **gradient**: Linear or radial color gradients

**Positioning:**
- Pixel coordinates: `{ x: 100, y: 50 }`
- Position strings: `center`, `top`, `bottom`, `top-left`, `top-right`, etc.
- Position objects: `{ x: 0.5, y: 0.5, originX: "center", originY: "center" }`

**Example:**
```json
{
  "width": 1200,
  "height": 630,
  "layers": [
    {
      "type": "gradient",
      "x": 0, "y": 0, "width": 1200, "height": 630,
      "gradient": {
        "type": "linear",
        "colors": ["#667eea", "#764ba2"],
        "direction": "diagonal"
      }
    },
    {
      "type": "text",
      "text": "Welcome to Jsoncut",
      "position": "center",
      "fontSize": 64,
      "color": "#ffffff"
    }
  ]
}
```

### `create_video_config`

Create JSON configurations for video generation with clips, layers, and transitions.

**Key Features:**
- **Clips**: Sequential video segments with individual layers
- **Layer Types**: video, image, title, subtitle, news-title, audio, gradients, and more
- **Transitions**: 75+ effects (fade, wipe, circle, cube, glitch, zoom, etc.)
- **Audio**: Background music, multiple tracks, normalization, and ducking

**Example:**
```json
{
  "width": 1920,
  "height": 1080,
  "fps": 30,
  "defaults": {
    "duration": 3,
    "transition": { "name": "fade", "duration": 1 }
  },
  "clips": [
    {
      "layers": [
        { "type": "title", "text": "Welcome", "position": "center" }
      ]
    }
  ]
}
```

### `validate_config`

Validate configurations against the Jsoncut API before submission.

**Parameters:**
- `type`: "image" or "video"
- `config`: Configuration object to validate
- `apiKey`: Optional API key (uses environment if not provided)

**Returns:**
- Validation status
- Estimated token cost
- Error details (if any)
- Detected resources with sizes

### `get_image_schema` / `get_video_schema`

Get complete JSON schemas for image or video generation. 

**Note:** Schemas are also available as MCP resources (`schema://image` and `schema://video`) which AI agents can access directly without tool calls.

---

## 📖 Workflow

1. **Create Configuration**: Use `create_image_config` or `create_video_config`
2. **Validate** (optional): Call `validate_config` if you have actual file paths
3. **Submit**: Use the configuration with the Jsoncut API

The schemas are automatically available as MCP resources, so AI agents have instant access to all configuration options.

---

## 📁 File Paths

Use placeholder paths in configurations:

```
/image/2024-01-15/userXXX/photo.jpg
/video/2024-01-15/userXXX/video.mp4
/audio/2024-01-15/userXXX/music.mp3
/font/2024-01-15/userXXX/CustomFont.ttf
```

**Supported formats:**
- Images: png, jpg, jpeg, gif, webp
- Videos: mp4, mov, avi, webm
- Audio: mp3, wav, m4a, aac
- Fonts: ttf, otf, woff, woff2

---

## 🧪 Testing

Use the MCP Inspector for interactive testing:

```bash
export JSONCUT_API_KEY=your_api_key_here
npm run inspector
```

---

## 🔧 Development

### Local Development

```bash
# Clone and install
git clone https://github.com/jsoncut/jsoncut-mcp-server.git
cd jsoncut-mcp-server
npm install

# Build
npm run build

# Watch mode
npm run watch

# Run locally
node dist/index.js
```

### Configuration with Local Build

For Cursor/Claude Desktop, use the local build:

```json
{
  "jsoncut": {
    "command": "node",
    "args": ["/absolute/path/to/jsoncut-mcp-server/dist/index.js"],
    "env": {
      "JSONCUT_API_KEY": "your_api_key_here"
    }
  }
}
```

---

## 📝 Examples

See the `examples/` directory for complete configurations:
- `image-example.json` - Image generation with multiple layer types
- `video-example.json` - Video generation with clips and transitions

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🔗 Links

- **API Documentation**: [docs.jsoncut.com](https://docs.jsoncut.com)
- **Website**: [jsoncut.com](https://jsoncut.com)
- **GitHub**: [github.com/jsoncut/jsoncut-mcp-server](https://github.com/jsoncut/jsoncut-mcp-server)
- **npm**: [@jsoncut/mcp-server](https://www.npmjs.com/package/@jsoncut/mcp-server)
- **Support**: support@jsoncut.com

---

<p align="center">
  Built with the <a href="https://github.com/modelcontextprotocol">Model Context Protocol SDK</a> by Anthropic
</p>

<p align="center">
  Made with ❤️ by the Jsoncut Team
</p>