🎨 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

Architecture

Siza MCP is a thin MCP protocol adapter that delegates all AI/generation logic to @forgespace/siza-gen:

siza-mcp (~355 KB)                 @forgespace/siza-gen (~1.8 MB)
├── src/index.ts (MCP server)      ├── ml/        (embeddings, quality, training)
├── tools/     (21 tool defs)      ├── generators/ (react, vue, angular, svelte, html)
├── services/  (figma, analysis)   ├── registry/   (502 snippets, compositions, packs)
├── resources/ (2 MCP resources)   ├── feedback/   (self-learning, pattern promotion)
└── lib/       (browser, image)    ├── quality/    (anti-generic rules, diversity)
                                   └── artifacts/  (store, learning loop)

✨ What It Does

Siza MCP is a 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)
18	generate_api_route	Backend	Generate production-ready API routes with validation, auth, and error handling
19	generate_backend_module	Backend	Generate complete backend feature modules with routes, services, and middleware
20	scaffold_backend	Backend	Generate full backend project scaffolds with auth, database, monitoring, and caching

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 20 MCP tools:

• generate_ui_component - Create React/Vue/Angular components
• scaffold_full_application - Generate full applications
• generate_api_route - Generate production-ready API routes
• generate_backend_module - Generate backend feature modules
• scaffold_backend - Generate complete backend projects
• figma_context_parser - Extract Figma design tokens
• image_to_component - Convert screenshots to code
• And 13+ 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: 82%+ (67 test suites, 1192 tests)

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

Coverage Status

• 1192+ tests passing across 67 test suites
• 82%+ statement coverage
• Component library integration fully tested
• Accessibility features comprehensively tested
• Quality validation for 450+ component snippets

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

• ✅ 20 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