# Lovable MCP Server

![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

An MCP (Model Context Protocol) server for the [Lovable Build with URL API](https://docs.lovable.dev). Generate shareable URLs that programmatically create applications in Lovable.

## Overview
This server allows you to programmatically create and interact with Lovable applications by generating "Build with URL" links. By connecting this MCP server with an AI assistant (like Claude), the AI can build full, running applications from a simple text prompt.

## Features & Tools

### 1. `lovable_generate_build_url`
Generate a shareable Lovable Build URL from a prompt and optional reference images.

**Parameters:**
- `prompt` (string, required): Description of the app to build (max 50,000 chars)
- `images` (string[], optional): Up to 10 publicly accessible image URLs (JPEG/PNG/WebP)
- `autosubmit` (boolean, optional): Auto-start building when URL is opened (default: `true`)
- `response_format` ("markdown" | "json"): Output format (default: "markdown")

### 2. `lovable_validate_build_url`
Validate and parse an existing Lovable Build URL, checking for issues.

**Parameters:**
- `url` (string, required): The Lovable Build URL to validate
- `response_format` ("markdown" | "json"): Output format (default: "markdown")

### 3. `lovable_build_prompt`
Compose an optimized prompt from structured requirements and return it as a Build URL.

**Parameters:**
- `app_type` (string, required): Type of application (e.g., "todo app", "dashboard")
- `features` (string[], optional): Features to include
- `style` (string, optional): Visual style or theme
- `tech_preferences` (string, optional): Technology preferences
- `additional_context` (string, optional): Additional requirements
- `response_format` ("markdown" | "json"): Output format (default: "markdown")

## Setup & Installation

1. Make sure you have Node.js and npm installed.
2. Clone or download this repository.
3. Install dependencies:

```bash
npm install
```

4. Build the TypeScript code:

```bash
npm run build
```

## Usage

### Local Usage (stdio)
By default, the server runs using the `stdio` transport. This is ideal for local integrations, such as adding the server as an MCP to the Claude Desktop app.

```bash
npm start
```

### Remote Usage (HTTP)
You can optionally run this server with an HTTP streaming transport on a given port.

```bash
TRANSPORT=http PORT=3000 npm start
```

## Integration Guides

### Claude Desktop Configuration
To add this server to the Claude desktop app, add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lovable": {
      "command": "node",
      "args": ["/path/to/lovable-mcp-server/dist/index.js"]
    }
  }
}
```

*Note: Replace `/path/to/lovable-mcp-server/dist/index.js` with the absolute path to your local built index.js.*

### Claude Code Configuration
If you're using the Claude Code CLI:

```bash
claude mcp add lovable node /path/to/lovable-mcp-server/dist/index.js
```

## Examples

### Generating a Build URL
```
Tool: lovable_generate_build_url
Input: { "prompt": "Create a todo app with categories and dark mode" }
```

### Building from structured requirements
```
Tool: lovable_build_prompt
Input: {
  "app_type": "dashboard",
  "features": ["charts", "KPI cards", "data tables"],
  "style": "modern",
  "tech_preferences": "use shadcn/ui"
}
```

### Validating an existing URL
```
Tool: lovable_validate_build_url
Input: { "url": "https://lovable.dev/?autosubmit=true#prompt=Create%20a%20todo%20app" }
```

## License
MIT