UIWeaver MCP

An AI-powered Model Context Protocol server that runs inside Claude Desktop.
Give it a prompt — get production-ready React + Tailwind UI, 3D components, real 3D model embeds, or a fully integrated frontend ↔ backend codebase.

---

What is UIWeaver?

UIWeaver connects Claude Desktop to Google Gemini and your local filesystem. It is a 9-tool MCP server that can:

• Generate polished React + Tailwind UI from a text description
• Analyze existing components for accessibility and quality issues
• Auto-fix those issues and return a health score
• Scan an existing React/Next.js project and analyze every file
• Preview and apply code changes to your project on disk
• Generate high-detail CSS 3D components (no WebGL — runs on any device)
• Search Sketchfab for real 3D models and return a ready-to-use React embed
• Connect a frontend with dummy data to a real backend API automatically

All of this is triggered by natural language inside Claude Desktop — no manual coding required.

---

Project Structure

UI-Weaver/
├── run_server.py                  ← Entry point Claude Desktop calls
├── requirements.txt               ← Python dependencies
├── .env.example                   ← Template for your API key
├── README.md                      ← This file
│
└── uiweaver_mcp/                  ← Main package
    ├── __init__.py
    ├── server.py                  ← All 9 MCP tools registered here
    ├── config.py                  ← Loads GEMINI_API_KEY from .env
    ├── .env                       ← Your actual API key (never commit this)
    │
    ├── schemas/
    │   └── project.py             ← Component, Page, Project dataclasses
    │
    ├── services/
    │   ├── gemini_service.py      ← Sends prompts to Gemini, parses responses
    │   ├── analysis_service.py    ← Checks components for issues
    │   ├── refinement_service.py  ← Auto-fix loop
    │   ├── file_service.py        ← Read/write/diff files on disk
    │   ├── threed_service.py      ← CSS 3D component generation
    │   ├── model_search_service.py← Sketchfab search + React embed generation
    │   └── integration_service.py ← Frontend ↔ Backend integration
    │
    └── utils/
        └── scoring.py             ← Health score calculator

---

Setup Guide

Prerequisites

Requirement	Version	Notes
Python	3.10+	python.org
Claude Desktop	Latest	claude.ai/download
Gemini API Key	—	Free at aistudio.google.com

---

Step 1 — Clone / download the project

UI-Weaver/

Make sure the folder is at a path with no spaces, or quote it everywhere.

---

Step 2 — Install dependencies

Open a terminal in the UI-Weaver folder:

# Windows
pip install -r requirements.txt

# macOS / Linux
pip3 install -r requirements.txt

Verify the key packages installed:

python -c "import mcp; import google.genai; print('OK')"

---

Step 3 — Add your Gemini API key

1. Get a free key at https://aistudio.google.com/app/apikey
2. Copy .env.example to uiweaver_mcp/.env
3. Open uiweaver_mcp/.env and replace the placeholder:

GEMINI_API_KEY=AIzaSy...your_real_key_here

---

Step 4 — Register UIWeaver in Claude Desktop

Open (or create) this file:

• Windows: C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Paste this (update the paths to match your system):

{
  "mcpServers": {
    "UIWeaver": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python310\\python.exe",
      "args": ["C:\\Users\\<you>\\Documents\\UI-Weaver\\run_server.py"],
      "env": {
        "GEMINI_API_KEY": "AIzaSy...your_real_key_here"
      }
    }
  }
}

macOS / Linux — use forward slashes and the output of which python3:

{
  "mcpServers": {
    "UIWeaver": {
      "command": "/usr/bin/python3",
      "args": ["/Users/<you>/Documents/UI-Weaver/run_server.py"],
      "env": { "GEMINI_API_KEY": "AIzaSy..." }
    }
  }
}

---

Step 5 — Restart Claude Desktop

Fully quit and reopen Claude Desktop. Open a new conversation and look for the hammer icon (🔨) in the bottom of the chat input. Click it — you should see UIWeaver listed with 9 tools.

---

Verify everything works

In Claude Desktop, type exactly:

Use generate_ui_tool to make a simple button component

If it responds with a React component with Tailwind classes, everything is working.

---

The 9 Tools — Reference + Example Prompts

---

1. generate_ui_tool

What it does: Generates a complete React + Tailwind CSS project from a text description. Produces proper TypeScript functional components with interfaces, JSX, Tailwind classes, accessibility attributes — ready to paste into any Next.js or Vite project.

Key behavior:

• Runs 2 refinement iterations automatically
• Returns a health score (0–100) based on accessibility and code quality
• Each component starts with import React and uses export default function

Example prompts:

Use generate_ui_tool to create a SaaS pricing page with three tiers 
(Starter $9/mo, Pro $29/mo, Enterprise custom), a feature comparison 
table below, and a FAQ section. Dark navy background, violet accent.

Use generate_ui_tool to build a job board listing page with filters 
on the left sidebar (role type, location, salary range), job cards 
in the main area showing company logo placeholder, title, location, 
salary, and an Apply button. Clean minimal design.

Use generate_ui_tool to make a user profile settings page with tabs 
for General, Security, Notifications, and Billing. Each tab has a 
form with save button. Slate background, white cards.

Output shape:

{
  "title": "...",
  "health_score": 94,
  "components": [
    { "name": "PricingCard", "code": "import React..." }
  ],
  "pages": [...],
  "styles": { "primaryColor": "#7c3aed" }
}

---

2. analyze_ui_tool

What it does: Takes a single component's code as a string and returns a list of issues with severity levels, plus a health score.

Issue types detected:

Type	Severity	Trigger
Missing aria attribute	High	No aria- attribute found
Component too large	Medium	Code > 2000 characters
No Tailwind classes	Low	No className or tailwind keyword

Example prompts:

Use analyze_ui_tool on this component code:
[paste your component code here]

I have a React button component — use analyze_ui_tool to check it 
for accessibility issues. Here's the code: [paste code]

Output shape:

{
  "health_score": 70,
  "issues": [
    { "type": "missing_aria", "severity": "high", "component": "Button", "description": "..." }
  ]
}

---

3. refine_ui_tool

What it does: Takes component code, runs analysis, auto-fixes every issue it finds, and returns the improved code. Loops up to 3 times until no issues remain or iterations are exhausted.

Auto-fixes applied:

• Injects aria-label="auto-fixed" into the first JSX tag if aria is missing
• Truncates code that exceeds safe length limits

Example prompts:

Use refine_ui_tool to fix this component: [paste code]

My Navbar component has accessibility issues. Use refine_ui_tool 
to auto-fix it: [paste code]

Output shape:

{
  "health_score": 100,
  "iterations": 2,
  "issues_remaining": 0,
  "components": [
    { "name": "Navbar", "code": "import React..." }
  ]
}

---

4. scan_project

What it does: Walks an entire React/Next.js project folder, reads every .tsx/.jsx/.ts/.js file (skipping node_modules, .next, dist), runs analysis on each one, and returns a full health report.

Example prompts:

Use scan_project on C:\Users\Arin\my-nextjs-app to give me a 
health report of all my components

Scan my frontend project at /Users/arin/projects/dashboard using 
scan_project and tell me which files have the most issues

Output shape:

{
  "folder": "...",
  "total_files": 24,
  "health_score": 81,
  "total_issues": 7,
  "files": [
    { "name": "Sidebar.tsx", "path": "src/components/Sidebar.tsx", "issues": [...] }
  ]
}

---

5. preview_changes

What it does: Shows a line-by-line diff of what would change in a specific file without writing anything to disk. Always use this before apply_changes.

Example prompts:

Use preview_changes on my project at C:\my-app, component name 
"Sidebar", with this new code: [paste updated code]

Before writing anything, use preview_changes to show me the diff 
for Header.tsx in C:\projects\my-site with this updated version: 
[paste code]

Output shape:

{
  "status": "update",
  "file": "src/components/Sidebar.tsx",
  "full_path": "C:/my-app/src/components/Sidebar.tsx",
  "diff": "+ import { useState } from 'react';\n- const items = [{id:1...}]...",
  "original_size": 1240,
  "new_size": 890
}

---

6. apply_changes

What it does: Writes updated component code to disk. Creates directories if they don't exist. Always run preview_changes first.

Example prompts:

The diff looks good. Use apply_changes to write it — 
full_file_path is C:\my-app\src\components\Sidebar.tsx, 
here's the new code: [paste code]

Apply the changes using apply_changes to 
C:\projects\dashboard\src\pages\index.tsx with this code: [paste]

Output shape:

{
  "status": "success",
  "file": "C:/my-app/src/components/Sidebar.tsx",
  "bytes_written": 3241,
  "message": "File written successfully"
}

---

7. generate_3d_tool

What it does: Generates a high-detail CSS 3D React component using perspective, transform-style: preserve-3d, and translateZ. No Three.js, no WebGL — runs at 60fps on integrated graphics and budget laptops.

Available 3D techniques:

Technique	Description
tilt-card	Card tilts in 3D as the mouse moves over it
flip-card	Hover/click reveals the back face
depth-layers	Multiple translateZ layers create parallax depth
floating	Element bobs in 3D space with a CSS keyframe loop
isometric	CSS-only isometric cube with shaded faces
depth-extrusion	Stacked box-shadow values simulate 3D extrusion

Example prompts:

Use generate_3d_tool to make an interactive tilt card showing 
monthly revenue $48,291 with a floating +12% growth badge. 
Dark slate background, violet glow accent.

Use generate_3d_tool to create a 3D flip card — front shows 
a team member photo placeholder, name, and role. Back shows 
their 3 skills and a "Contact" button. Dark glassmorphism style.

Use generate_3d_tool to build an isometric stats display with 
3 cubes showing Users, Revenue, and Uptime metrics. Each cube 
has a different height based on the value. Emerald and amber theme.

Use generate_3d_tool to make a floating product card for wireless 
headphones. The card levitates, has depth layers showing the product 
details, with a subtle glow shadow underneath.

Output shape:

{
  "title": "Revenue Tilt Card",
  "technique": "tilt-card",
  "dependencies": ["react"],
  "performance": "60fps on integrated graphics",
  "quality_report": { "health_score": 100, "issues": [] },
  "components": [
    { "name": "RevenueTiltCard", "code": "import React, { useState }..." }
  ],
  "usage": "<RevenueTiltCard />"
}

---

8. search_and_embed_3d

What it does: Searches Sketchfab's public database of millions of free 3D models, finds the best match, and generates two ready-to-use React components for it.

Two component options generated:

Option	How it works	Setup needed
iframe_embed	Embeds Sketchfab's viewer — works immediately	Nothing
model_viewer	Google's <model-viewer> — just the model, no Sketchfab UI	Download .glb + npm install @google/model-viewer

Example prompts:

Use search_and_embed_3d to find a 3D model of a raspberry pi board

Use search_and_embed_3d to find a wooden office chair 3D model

Use search_and_embed_3d to find an astronaut helmet 3D model, pick=1

Use search_and_embed_3d for a sports car model — I want to embed 
it on a product landing page

Output shape:

{
  "model_found": {
    "name": "Raspberry Pi cam v2.1",
    "author": "F2A",
    "license": "CC Attribution",
    "likes": 85,
    "sketchfab_page": "https://sketchfab.com/...",
    "download_page": "https://sketchfab.com/...#download"
  },
  "components": {
    "iframe_embed": { "code": "import React..." },
    "model_viewer":  { "code": "import React...", "setup_steps": [...] }
  },
  "recommendation": "Start with iframe_embed..."
}

Tip: If the first result isn't what you want, add pick=1 or pick=2 to get the next result.

---

9. integrate_frontend_backend

What it does: The most powerful tool. Give it:

1. Your frontend folder (React/Next.js with hardcoded dummy data)
2. Your backend folder (Express/FastAPI/Flask/Django)
3. Your API spec (plain text or OpenAPI JSON)

It auto-detects backend routes, finds every frontend file with dummy/hardcoded data, and uses Gemini to rewrite each file — replacing fake data with real fetch() calls, adding TypeScript interfaces, loading skeletons, and error handling.

Backend frameworks supported: Express, Fastify, FastAPI, Flask, Django

Dummy data patterns it detects:

• const items = [{id: 1, name: "John"}, ...]
• useState([{...hardcoded objects...}])
• Strings containing placeholder, dummy, mock, fake
• Comments like // TODO: replace with API call

Transformations applied per file:

• Replaces hardcoded arrays with useState<Type[]>([])
• Adds useEffect with fetch() to the correct endpoint
• Adds const [loading, setLoading] = useState(true)
• Adds const [error, setError] = useState<string | null>(null)
• Adds loading skeleton (animated pulse)
• Adds error banner
• Adds TypeScript interfaces matching API response shapes
• Uses process.env.NEXT_PUBLIC_API_URL as base URL

Recommended workflow — always dry run first:

Step 1 — Dry run (default):

Use integrate_frontend_backend with:
  frontend_folder = C:\my-app\frontend
  backend_folder  = C:\my-app\backend
  api_spec        = "GET /api/users → returns [{id, name, email, role}]
                     POST /api/users → body {name, email}, returns created user
                     DELETE /api/users/:id → returns {success: true}
                     GET /api/products → returns [{id, title, price, stock}]"

Step 2 — Review the diffs in the response. Each file shows exactly what lines change.

Step 3 — Apply when satisfied:

Use integrate_frontend_backend with the same folders and spec 
but apply=true

With OpenAPI JSON:

Use integrate_frontend_backend. frontend_folder = C:\my-app\frontend, 
backend_folder = C:\my-app\backend, api_spec = [paste your full 
OpenAPI/Swagger JSON here]

With a separate output folder (keeps originals untouched):

Use integrate_frontend_backend with apply=true and 
output_folder = C:\my-app\frontend-integrated

Output shape:

{
  "status": "dry_run",
  "summary": {
    "backend_framework": "fastapi",
    "routes_found": 12,
    "files_with_dummy_data": 5,
    "files_integrated": 5,
    "errors": []
  },
  "backend_routes": [
    { "method": "GET", "path": "/api/users", "file": "routers/users.py" }
  ],
  "integrations": [
    {
      "file": "src/pages/users.tsx",
      "changes_summary": [
        "Replaced hardcoded users array with useState<User[]>([])",
        "Added useEffect fetching GET /api/users",
        "Added User TypeScript interface",
        "Added loading skeleton",
        "Added error banner"
      ],
      "api_calls_added": [
        { "method": "GET", "endpoint": "/api/users", "trigger": "on component mount" }
      ],
      "env_vars_needed": ["NEXT_PUBLIC_API_URL=http://localhost:8000"],
      "diff": "+ const [users, setUsers] = useState<User[]>([]);\n- const users = [{id:1..."
    }
  ]
}

---

Typical Workflows

Build a new UI from scratch

1. Use generate_ui_tool to create [your UI description]
2. Use refine_ui_tool on any component that needs improvement
3. Use apply_changes to write the components to your project

Audit an existing project

1. Use scan_project on [your project folder]
2. For each file with issues, use refine_ui_tool to fix it
3. Use preview_changes to review → apply_changes to write

Add a 3D section to a landing page

1. Use generate_3d_tool to create [your 3D component description]
2. Use apply_changes to write it to your components folder
3. Import it into your page

Embed a product's real 3D model

1. Use search_and_embed_3d to find [product name] 3D model
2. Use the iframe_embed component immediately, or:
3. Download the .glb → use the model_viewer component for production

Connect dummy frontend to real backend

1. Use integrate_frontend_backend (dry run) to preview all changes
2. Review all diffs carefully
3. Use integrate_frontend_backend with apply=true to write
4. Add the .env vars listed in the output
5. Restart your dev server and test in the browser

---

Troubleshooting

UIWeaver doesn't appear in Claude Desktop

1. Open claude_desktop_config.json and check for JSON syntax errors (missing comma, extra bracket)
2. Make sure python.exe path is correct — run it in a terminal to verify
3. Fully quit Claude Desktop (system tray → Quit, not just close window) and reopen
4. In a terminal, run python run_server.py directly — if it errors, fix that first

"No module named 'uiweaver_mcp'" error

The run_server.py wrapper handles this automatically by adding the project root to sys.path. If you see this error, make sure Claude Desktop is calling run_server.py — not server.py directly.

"GEMINI_API_KEY not set" error

Check two places:

• uiweaver_mcp/.env has GEMINI_API_KEY=your_key
• claude_desktop_config.json "env" block also has the key

Either location works. The env block in the config takes priority.

Gemini returns HTML instead of React components

In your Claude prompt, be explicit: say "Use generate_ui_tool" and include "React component" in your description. Example:

Use generate_ui_tool to create a React component for a login form

scan_project finds no files

Make sure the folder path uses forward slashes or escaped backslashes, and that the path points to the project root (the folder containing src/ or pages/), not a subfolder.

integrate_frontend_backend finds no dummy data

The scanner looks for specific patterns. If your data doesn't match, manually identify the files and use generate_ui_tool + apply_changes to rewrite them manually.

---

Tech Stack

Layer	Technology
MCP Framework	mcp 1.6.0 (FastMCP, stdio transport)
AI Model	Google Gemini 2.0 Flash
Language	Python 3.10+
Claude Desktop	MCP client (calls UIWeaver's tools)
3D Models	Sketchfab public API + Google model-viewer
Output format	React + TypeScript + Tailwind CSS

---

License

MIT — use it, fork it, build on it.

---

Built with UIWeaver itself.