# WebForge MCP Server

[![npm version](https://badge.fury.io/js/%40joytorm%2Fwebforge-mcp.svg)](https://badge.fury.io/js/%40joytorm%2Fwebforge-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Model Context Protocol (MCP) server for WebForge - Create and manage websites for local businesses through any MCP-compatible IDE.

## Features

- 🎨 **100 Design Styles** - Access to professionally crafted design styles
- 🎭 **40 Color Palettes** - Curated color schemes for different business types  
- 🤖 **Smart Recommendations** - AI-powered style+palette combinations based on business type
- 📊 **Project Management** - Create and manage website projects
- 🔄 **Compatibility Matrix** - Intelligent scoring system for design combinations
- 🔧 **MCP Protocol** - Works with Claude Code, Cursor, Google Antigravity, and other MCP clients

## Compatible IDEs

### Claude Code
```bash
npm install -g @joytorm/webforge-mcp
```

Add to your Claude configuration:
```json
{
  "mcpServers": {
    "webforge": {
      "command": "webforge-mcp",
      "args": []
    }
  }
}
```

### Cursor
1. Install the package: `npm install -g @joytorm/webforge-mcp`
2. Add to Cursor's MCP settings:
   ```json
   {
     "webforge": {
       "command": "webforge-mcp"
     }
   }
   ```

### Google Antigravity
1. Install: `npm install -g @joytorm/webforge-mcp`
2. Configure in Antigravity's MCP servers section:
   ```json
   {
     "name": "webforge",
     "command": "webforge-mcp",
     "transport": "stdio"
   }
   ```

## Prerequisites

### 1. Supabase Setup

You need to create the required database tables in your Supabase instance. Execute this SQL in your Supabase SQL Editor:

```sql
-- WebForge MCP Database Setup
-- Execute this SQL in the Supabase SQL Editor

-- 1. Create design_styles table
CREATE TABLE IF NOT EXISTS design_styles (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    industry TEXT NOT NULL,
    style_dna JSONB NOT NULL,
    dos TEXT[] NOT NULL DEFAULT '{}',
    donts TEXT[] NOT NULL DEFAULT '{}',
    tokens TEXT NOT NULL,
    raw_length INTEGER NOT NULL DEFAULT 0,
    businesses TEXT[] NOT NULL DEFAULT '{}',
    category TEXT NOT NULL,
    category_label TEXT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::TEXT, NOW()) NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::TEXT, NOW()) NOT NULL
);

-- 2. Create design_palettes table  
CREATE TABLE IF NOT EXISTS design_palettes (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    mood TEXT[] NOT NULL DEFAULT '{}',
    industries TEXT[] NOT NULL DEFAULT '{}',
    category TEXT NOT NULL,
    primary_light TEXT NOT NULL,
    primary_dark TEXT NOT NULL,
    accent_light TEXT NOT NULL,
    heading_font TEXT NOT NULL,
    body_font TEXT NOT NULL,
    border_radius TEXT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::TEXT, NOW()) NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::TEXT, NOW()) NOT NULL
);

-- 3. Create style_palette_compatibility table
CREATE TABLE IF NOT EXISTS style_palette_compatibility (
    style_id TEXT NOT NULL REFERENCES design_styles(id) ON DELETE CASCADE,
    palette_id TEXT NOT NULL REFERENCES design_palettes(id) ON DELETE CASCADE,
    score INTEGER NOT NULL CHECK (score >= 1 AND score <= 5),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::TEXT, NOW()) NOT NULL,
    PRIMARY KEY (style_id, palette_id)
);

-- 4. Create indexes for better performance
CREATE INDEX IF NOT EXISTS idx_design_styles_category ON design_styles(category);
CREATE INDEX IF NOT EXISTS idx_design_styles_industry ON design_styles(industry);
CREATE INDEX IF NOT EXISTS idx_design_styles_businesses ON design_styles USING GIN(businesses);
CREATE INDEX IF NOT EXISTS idx_design_palettes_category ON design_palettes(category);
CREATE INDEX IF NOT EXISTS idx_design_palettes_mood ON design_palettes USING GIN(mood);
CREATE INDEX IF NOT EXISTS idx_design_palettes_industries ON design_palettes USING GIN(industries);
CREATE INDEX IF NOT EXISTS idx_compatibility_style_score ON style_palette_compatibility(style_id, score DESC);
CREATE INDEX IF NOT EXISTS idx_compatibility_palette_score ON style_palette_compatibility(palette_id, score DESC);
CREATE INDEX IF NOT EXISTS idx_compatibility_score ON style_palette_compatibility(score DESC);

-- 5. Enable Row Level Security
ALTER TABLE design_styles ENABLE ROW LEVEL SECURITY;
ALTER TABLE design_palettes ENABLE ROW LEVEL SECURITY;
ALTER TABLE style_palette_compatibility ENABLE ROW LEVEL SECURITY;

-- 6. Create RLS policies for read access
DROP POLICY IF EXISTS "Allow read access to design_styles" ON design_styles;
CREATE POLICY "Allow read access to design_styles" ON design_styles FOR SELECT USING (true);

DROP POLICY IF EXISTS "Allow read access to design_palettes" ON design_palettes;
CREATE POLICY "Allow read access to design_palettes" ON design_palettes FOR SELECT USING (true);

DROP POLICY IF EXISTS "Allow read access to style_palette_compatibility" ON style_palette_compatibility;
CREATE POLICY "Allow read access to style_palette_compatibility" ON style_palette_compatibility FOR SELECT USING (true);

-- 7. Create trigger function for updated_at
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = TIMEZONE('utc'::TEXT, NOW());
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- 8. Create triggers for automatic updated_at
DROP TRIGGER IF EXISTS update_design_styles_updated_at ON design_styles;
CREATE TRIGGER update_design_styles_updated_at
    BEFORE UPDATE ON design_styles
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

DROP TRIGGER IF EXISTS update_design_palettes_updated_at ON design_palettes;
CREATE TRIGGER update_design_palettes_updated_at
    BEFORE UPDATE ON design_palettes
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();
```

### 2. Seed the Database

After creating the tables, run the seeding script to populate them with WebForge's design data:

```bash
npm run seed
```

## Installation

### Global Installation (Recommended)
```bash
npm install -g @joytorm/webforge-mcp
```

### Local Development
```bash
git clone https://github.com/joytorm/webforge-mcp.git
cd webforge-mcp
npm install
npm run build
npm link
```

## Available Tools

### Design Discovery
- `webforge_list_styles` - List all 100 available design styles
- `webforge_list_palettes` - List all 40 available color palettes  
- `webforge_recommend_design` - Get top 5 style+palette recommendations for a business type

### Design Details
- `webforge_get_style_details` - Get complete style information including CSS tokens
- `webforge_get_palette_details` - Get complete palette information including all colors

### Project Management
- `webforge_create_project` - Create a new website project
- `webforge_list_projects` - List existing projects with filtering
- `webforge_get_project` - Get detailed project information
- `webforge_update_project` - Update project settings

## Usage Examples

### Get Design Recommendations
```javascript
// Ask for recommendations for a restaurant
await webforge_recommend_design({ business_type: "restaurant" })
```

### Create a New Project
```javascript
// Create a project for a dental clinic
await webforge_create_project({
  name: "Smile Dental Clinic",
  business_type: "dental clinic", 
  description: "Modern dental practice website",
  style_id: "S15", // Optional: assign a style
  palette_id: "P08" // Optional: assign a palette
})
```

### Get Style Details
```javascript
// Get complete details for a specific style
await webforge_get_style_details({ style_id: "S01" })
```

## Environment Variables

The MCP server connects to the WebForge Supabase instance automatically. No additional environment configuration is required.

- **Supabase URL**: `https://supabase.optihost.pro`
- **Authentication**: Handled automatically via service keys

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production  
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format
```

## API Reference

### Recommendation Engine

The recommendation system uses a compatibility matrix that scores style+palette combinations from 1-5 based on:

- **Industry alignment** - How well the style fits the business type
- **Visual harmony** - Color theory and design compatibility  
- **Brand perception** - Mood and professional appropriateness
- **User experience** - Usability for the target audience

### Style Categories

- **Minimalist** - Clean, modern designs with lots of whitespace
- **Creative** - Bold, artistic layouts with unique elements
- **Professional** - Traditional business-focused designs
- **E-commerce** - Product-focused layouts with strong CTAs
- **Local Business** - Community-oriented designs with local appeal

### Palette Moods

- **Professional** - Conservative colors for business credibility
- **Friendly** - Warm, welcoming colors for service businesses  
- **Modern** - Contemporary color schemes for tech/startups
- **Elegant** - Sophisticated palettes for premium brands
- **Energetic** - Vibrant colors for fitness/entertainment

## Contributing

1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## License

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

## Support

- **GitHub Issues**: [https://github.com/joytorm/webforge-mcp/issues](https://github.com/joytorm/webforge-mcp/issues)
- **Email**: [contact@joytorm.com](mailto:contact@joytorm.com)
- **Documentation**: [WebForge MCP Docs](https://github.com/joytorm/webforge-mcp)

---

**Built with ❤️ by the Joytorm team**