🎨 Siza MCP Server

AI-driven UI generation via Model Context Protocol Generate complete applications, components, and designs from natural language

🏆 Badges

🧪 Quality & Testing

🔧 Build & Deployment

🛡️ Security & Standards

🌟 Platform & Integration

📊 Activity & Community

💎 Zero-Cost & Open Source

✨ What It Does

Siza MCP is a powerful Model Context Protocol server that transforms natural language into production-ready UI. From full-stack applications to individual components, interactive prototypes to design mockups — all generated with AI precision.

🚀 Key Capabilities

• 🏗️ Full Application Scaffolding - React, Next.js, Vue, Angular, HTML
• 🎨 Component Generation - Style-aware, framework-specific code
• 📸 Screenshot-to-Code - Convert images to working components
• 🎭 Interactive Prototypes - Clickable HTML prototypes with navigation
• 🖼️ Design Mockups - SVG/PNG UI mockups and wireframes
• ♿ Accessibility Auditing - WCAG 2.1 compliance with fixes
• 🔗 Figma Integration - Bidirectional design token flow
• 🎯 Template Library - Landing pages, dashboards, auth flows

🛠️ Zero-Cost Architecture

✅ 100% Free & Open Source ✅ No API Keys Required ✅ Self-Hosted Only ✅ MIT License ✅ No Cloud Dependencies

Built with the Model Context Protocol TypeScript SDK.

Tools

| # | Tool | Category | Description | | --- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | 1 | scaffold_full_application | Code | Generate full project boilerplate (React/Next.js/Vue/Angular/HTML + Tailwind) | | 2 | generate_ui_component | Code | Create/iterate UI components with style audit + design context. Supports shadcn/ui, Radix UI, Headless UI, Material UI, PrimeVue | | 3 | generate_prototype | Design | Create interactive HTML prototype with screen flows and navigation | | 4 | generate_design_image | Design | Generate SVG/PNG mockup images of UI screens/components | | 5 | fetch_design_inspiration | Context | Extract visual metadata (colors, typography, layout) from URLs | | 6 | analyze_design_references | Context | Analyze design references from URLs and images, detect common patterns | | 7 | figma_context_parser | Context | Read Figma file nodes, extract tokens, map to Tailwind | | 8 | figma_push_variables | Design | Write design tokens back to Figma as Variables | | 9 | image_to_component | Code | Convert screenshot/mockup/wireframe image into framework-specific component code | | 10 | generate_page_template | Code | Generate pre-built page templates (landing, dashboard, auth, pricing, CRUD, etc.) | | 11 | refine_component | Code | Iteratively improve existing components via natural language feedback | | 12 | audit_accessibility | Quality | Audit component code for WCAG 2.1 violations with fix suggestions | | 13 | submit_feedback | Quality | Submit feedback on generated components to improve future output | | 14 | manage_training | ML | Manage training data ingestion and model fine-tuning | | 15 | analyze_component_library | Context | Analyze component library patterns for style-aware generation | | 16 | analyze_design_image | ML | Analyze design images for training data extraction | | 17 | generate_from_template_pack | Code | Generate complete multi-page apps from curated template packs (SaaS, Landing, AI Chat) |

Component Library Support

The generate_ui_component and image_to_component tools accept a component_library parameter to generate framework-specific code using popular UI libraries:

| Library | React | Vue | Angular | Svelte | HTML | | ------------- | --------------------- | ------------------ | -------------------- | --------------------- | ---- | | shadcn | ✅ shadcn/ui | ✅ shadcn-vue | ✅ (Tailwind) | ✅ bits-ui | ✅ | | radix | ✅ @radix-ui/react-* | ✅ @radix-ui/vue | ✅ (Tailwind) | ✅ @radix-ui/svelte | ✅ | | headlessui | ✅ @headlessui/react | ✅ @headlessui/vue | ✅ (Tailwind) | ✅ @headlessui/svelte | ✅ | | material | ✅ @mui/material | ✅ (Vuetify) | ✅ @angular/material | ✅ @smui/material | ✅ | | primevue | ✅ (Headless UI) | ✅ primevue | ✅ primeng | ✅ (Tailwind) | ✅ | | none / omit | ✅ Tailwind CSS | ✅ Tailwind CSS | ✅ Tailwind CSS | ✅ Tailwind CSS | ✅ |

Each generator produces a component file plus a test file (React also generates a Storybook story).

Resource

| URI | Description | | ------------------------------ | ----------------------------------------------------------------------- | | application://current-styles | Current IDesignContext as JSON — session-scoped style source of truth |

🚀 Quick Start

Option 1: NPX (Instant Setup) ⚡

npx -y siza-mcp@latest

Option 2: Global Install 📦

npm install -g siza-mcp
siza-mcp

Option 3: Docker 🐳

docker build -t siza-mcp .
docker run --rm -i siza-mcp

---

🔧 IDE Integration

Add to your IDE's MCP configuration (Windsurf, Cursor, etc.):

{
  "mcpServers": {
    "siza-mcp": {
      "command": "npx",
      "args": ["-y", "siza-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_token_here",
        "NODE_ENV": "production"
      }
    }
  }
}

💡 Tip: Use Docker for production, NPX for quick testing

Option 1: Docker (Production Ready)

Add to your IDE's MCP configuration:

{
  "mcpServers": {
    "siza-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "FIGMA_ACCESS_TOKEN",
        "siza-mcp:latest"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Option 2: NPX (Quick Setup)

{
  "mcpServers": {
    "siza-mcp": {
      "command": "npx",
      "args": ["-y", "siza-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_figma_token_here",
        "NODE_ENV": "production"
      }
    }
  }
}

📖 Full Setup Guide: See MCP_SETUP_GUIDE.md for detailed configuration options.

Option 3: Local Development

# Run the automated setup script
./setup-ide.sh

# Edit environment variables
nano .env

Option 4: Manual Setup

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your values
# Add your FIGMA_ACCESS_TOKEN

# Build
npm run build

# Run (stdio transport)
node dist/index.js

Development

# Watch mode
npm run dev

# Run tests
npm test

# Run tests in watch mode (only changed files)
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Clean build artifacts
npm run clean

# Validate all checks (lint, format, typecheck, test)
npm run validate

# Docker commands
npm run docker:build
npm run docker:run

MCP Integration

Siza MCP server can be integrated with any MCP-compatible IDE using standard Docker or NPX commands.

🎯 Quick Setup (No Clone Required)

Docker Integration (Recommended)

1. Build Docker image once:

   docker pull siza-mcp:latest
   # Or build from source: docker build -t siza-mcp:latest .
   

2. Add to your IDE's MCP configuration:

   {
     "mcpServers": {
       "siza-mcp": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "-e",
           "FIGMA_ACCESS_TOKEN",
           "siza-mcp:latest"
         ],
         "env": {
           "NODE_ENV": "production"
         }
       }
     }
   }
   

NPX Integration (Easiest)

Add to your IDE's MCP configuration:

{
  "mcpServers": {
    "siza-mcp": {
      "command": "npx",
      "args": ["-y", "siza-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_figma_token_here",
        "NODE_ENV": "production"
      }
    }
  }
}

🔧 IDE-Specific Setup

Windsurf

1. Open /Users/lucassantana/.codeium/windsurf/mcp_config.json
2. Add one of the configurations above
3. Restart Windsurf
4. Tools appear automatically in the interface

Cursor IDE

1. Open .cursorrules or MCP settings
2. Add the configuration
3. Restart Cursor

VS Code (with MCP extension)

1. Open MCP settings
2. Add the configuration
3. Reload VS Code

📋 Available Tools After Setup

Once connected, you'll have access to all 13 MCP tools:

• generate_ui_component - Create React/Vue/Angular components
• scaffold_full_application - Generate full applications
• analyze_design_image_for_training - Analyze UI designs
• figma_context_parser - Extract Figma design tokens
• image_to_component - Convert screenshots to code
• And 9+ more tools

🔐 Authentication

Set your Figma token in the MCP configuration:

"env": {
  "FIGMA_ACCESS_TOKEN": "figd_your_token_here"
}

📖 Complete Guide: See MCP_SETUP_GUIDE.md for detailed instructions.

IDE Setup

🚀 Automated Setup

Run the automated setup script for complete IDE configuration:

./setup-ide.sh

This script:

• ✅ Creates .env from .env.example
• ✅ Installs VS Code extensions (if available)
• ✅ Installs Node.js dependencies
• ✅ Builds the project
• ✅ Tests environment variables

📚 Manual IDE Configuration

VS Code

• Extensions: TypeScript, ESLint, Prettier, REST Client
• Debug Configuration: .vscode/launch.json (auto-loads .env)
• Tasks: Build and start tasks configured
• Settings: Environment file auto-loading enabled

Cursor IDE

• Environment: .cursorrules configured for Siza MCP
• Auto-loading: .env file automatically detected
• Development: Optimized for MCP server development

Windsurf IDE

• Configuration: .windsurf/ directory with MCP development rules
• Environment: .env file automatically loaded
• Integration: Seamless MCP tool development

🔧 Environment Variables

Create .env file with your configuration:

# Required for Figma integration
FIGMA_ACCESS_TOKEN=your_figma_access_token_here

# Optional configuration
NODE_ENV=development
LOG_LEVEL=debug

📖 Detailed Instructions: See IDE-SETUP.md for comprehensive IDE configuration guide.

Test Coverage

Current test coverage: 77.39% (39 test suites, 550 tests)

• Statements: 77.39%
• Branches: 70.77%
• Functions: 78.72%
• Lines: 77.39%

Coverage thresholds are enforced via Jest configuration. All tests must pass and maintain coverage levels before merging.

Coverage Status

• ✅ All 550 tests passing
• ⚠️ Coverage below threshold (target: 84%)
• 📊 39 test suites covering all tools and core functionality
• 🎯 Component library integration fully tested
• ♿ Accessibility features comprehensively tested

Docker

docker build -t siza-mcp .
docker run -i siza-mcp

Environment Variables

| Variable | Required | Description | | -------------------- | -------------------- | ------------------------------------------------- | | FIGMA_ACCESS_TOKEN | Only for Figma tools | Personal access token from Figma account settings |

Figma Integration Status

✅ Implemented Features

• figma_context_parser: Read Figma files, extract design tokens, map to Tailwind CSS
• figma_push_variables: Write design tokens back to Figma as Variables
• Bidirectional token flow: Siza ↔ Figma

🔧 Setup Requirements

1. Get Figma access token from Figma Account Settings
2. Set FIGMA_ACCESS_TOKEN environment variable
3. Use file key from Figma URL: figma.com/file/<file_key>/...

📋 Usage Examples

# Parse Figma design tokens (JSON-RPC)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "figma_context_parser", "arguments": {"file_key": "ABC123"}}}' | node dist/index.js

# Push variables to Figma (JSON-RPC)
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "figma_push_variables", "arguments": {"file_key": "ABC123", "variables": [{"name": "primary-color", "value": "#3b82f6"}]}}}' | node dist/index.js

Production Deployment

🚀 Production Ready Features

• ✅ 12 MCP tools fully operational
• ✅ Component library integration (shadcn/ui, Radix UI, Headless UI, Material UI)
• ✅ Accessibility compliance (WCAG 2.1 AA/AAA)
• ✅ Responsive design generation
• ✅ Zero-cost architecture (self-hosted)

📦 Docker Deployment

# Build production image
docker build -t siza-mcp:latest .

# Run production server
docker run -d \
  --name siza-mcp \
  -p 8026:8026 \
  -e FIGMA_ACCESS_TOKEN=your_token_here \
  siza-mcp:latest

🔗 Integration Examples

• mcp-gateway: Add to your Docker Compose setup
• Claude Desktop: Connect via stdio transport
• Custom MCP clients: Use SSE or stdio transport

🚀 Deployment

Automated Deployment

Siza MCP uses GitHub Actions for automated deployment with comprehensive validation:

# Trigger deployment via GitHub Actions
1. Go to: https://github.com/LucasSantana-Dev/siza-mcp/actions
2. Click "Deploy" workflow
3. Choose version type (patch/minor/major)
4. Set dry_run to false for production deployment
5. Click "Run workflow"

Features:

• ✅ Full validation (lint, test, build, security audit)
• ✅ Multi-platform Docker builds (amd64/arm64)
• ✅ Automatic npm publishing with provenance
• ✅ GitHub release creation
• ✅ Semantic versioning
• ✅ Rollback capabilities

Quick Setup

Run the setup script to configure deployment:

./scripts/setup-deployment.sh

This script helps configure:

• GitHub secrets (NPM_TOKEN, DOCKER_USERNAME, DOCKER_PASSWORD)
• Branch protection rules
• Local validation

Manual Deployment

For local testing or emergency deployments:

# Update version
npm version patch  # or minor/major

# Full validation
npm run validate:all

# Build and publish
npm run build
npm publish --access public

# Create Git tag
git push origin main --follow-tags

Docker Deployment

# Build and push multi-platform image
docker buildx build --platform linux/amd64,linux/arm64 \
  --push -t lucassantana/siza-mcp:latest .

# Pull and run
docker pull lucassantana/siza-mcp:latest
docker run -d --name siza-mcp \
  -e FIGMA_ACCESS_TOKEN=your_token \
  lucassantana/siza-mcp:latest

📖 Full deployment guide: See docs/DEPLOYMENT.md

Project Structure

siza-mcp/
├── package.json
├── tsconfig.json
├── Dockerfile
├── src/
│   ├── index.ts                        # McpServer + stdio transport
│   ├── tools/
│   │   ├── scaffold-full-application.ts
│   │   ├── generate-ui-component.ts
│   │   ├── generate-prototype.ts
│   │   ├── generate-design-image.ts
│   │   ├── fetch-design-inspiration.ts
│   │   ├── analyze-design-references.ts
│   │   ├── figma-context-parser.ts
│   │   ├── figma-push-variables.ts
│   │   ├── image-to-component.ts
│   │   ├── generate-page-template.ts
│   │   ├── refine-component.ts
│   │   └── audit-accessibility.ts
│   ├── resources/
│   │   └── current-styles.ts
│   ├── lib/
│   │   ├── types.ts
│   │   ├── design-context.ts
│   │   ├── style-audit.ts
│   │   ├── figma-client.ts
│   │   ├── design-extractor.ts
│   │   ├── browser-scraper.ts
│   │   ├── image-analyzer.ts
│   │   ├── pattern-detector.ts
│   │   ├── tailwind-mapper.ts
│   │   ├── image-renderer.ts
│   │   ├── prototype-builder.ts
│   │   ├── design-references/
│   │   │   ├── index.ts
│   │   │   ├── font-pairings.ts
│   │   │   ├── color-systems.ts
│   │   │   ├── inspiration-sources.ts
│   │   │   └── ...
│   │   └── templates/
│   │       ├── react.ts
│   │       ├── nextjs.ts
│   │       ├── vue.ts
│   │       ├── angular.ts
│   │       ├── html.ts
│   │       └── prototype-shell.ts
│   └── __tests__/
│       ├── *.unit.test.ts              # Unit tests for lib modules
│       ├── *.integration.test.ts       # Integration tests
│       ├── tools/                      # Tool-specific tests
│       │   └── *.unit.test.ts
│       └── resources/                  # Resource tests
│           └── *.unit.test.ts

mcp-gateway Integration

To add Siza to your mcp-gateway Docker Compose setup:

1. docker-compose.yml: Add a siza service on port 8026.
2. scripts/gateways.txt: Add siza|http://siza:8026/sse|SSE.
3. .env.example: Add UIFORGE_PORT=8026 and FIGMA_ACCESS_TOKEN=.

Architecture

• Transport: stdio (gateway wraps via mcpgateway.translate → SSE)
• Templates: Embedded TS template functions per framework
• Image generation: satori (JSX → SVG) + @resvg/resvg-js (SVG → PNG)
• Style consistency: In-memory IDesignContext store exposed via application://current-styles
• Figma write-back: Variables REST API for design tokens (only supported write path)

ML & Specialist Agents

Five specialist agents powered by RAG (Retrieval-Augmented Generation) over external datasets. All features degrade gracefully when no training data exists.

Data Ingestion

npx tsx src/scripts/ingest-training-data.ts --source all   # Ingest all sources
npx tsx src/scripts/ingest-training-data.ts --stats         # Show embedding counts
npx tsx src/scripts/ingest-training-data.ts --test-query "accessible modal"

Sources: shadcn/ui (MIT), axe-core (MPL 2.0), Material Design 3 (Apache 2.0), GitHub Primer (MIT), WAI-ARIA APG (W3C).

Training Data Generation

npx tsx src/scripts/generate-training-data.ts              # Generate all adapters
npx tsx src/scripts/generate-training-data.ts --stats      # Show training data counts

Cross-Repo Knowledge Sync

npx tsx src/scripts/sync-knowledge.ts                      # Export to mcp-gateway JSONL
npx tsx src/scripts/sync-knowledge.ts --dry-run            # Preview without writing

License

MIT