Architecture

@forgespace/ui-mcp is a thin protocol adapter. All AI/generation logic lives in @forgespace/siza-gen:

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

Quick Start

# NPX (instant)
npx -y @forgespace/ui-mcp@latest

# Global install
npm install -g @forgespace/ui-mcp && forgespace-ui-mcp

# Docker
docker build -t forgespace-ui-mcp . && docker run --rm -i forgespace-ui-mcp

IDE Integration

Add to your MCP configuration (Claude Code, Windsurf, Cursor, VS Code):

{
  "mcpServers": {
    "forgespace-ui-mcp": {
      "command": "npx",
      "args": ["-y", "@forgespace/ui-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Tools

Tool	Category	Description
`scaffold_full_application`	Code	Full project boilerplate (React/Next.js/Vue/Angular/HTML + Tailwind)
`generate_ui_component`	Code	UI components with style audit, supports shadcn/ui, Radix, Headless UI, Material, PrimeVue
`generate_form`	Code	Production forms with Zod/Yup validation, multi-step flows, accessible markup
`generate_page_template`	Code	Pre-built pages (landing, dashboard, auth, pricing, CRUD)
`generate_prototype`	Design	Interactive HTML prototypes with navigation
`generate_design_image`	Design	SVG/PNG mockups of UI screens
`image_to_component`	Code	Screenshot/wireframe to framework-specific component
`refine_component`	Code	Improve components via natural language feedback
`generate_api_route`	Backend	API routes with validation, auth, and error handling
`generate_backend_module`	Backend	Full feature modules with routes, services, middleware
`scaffold_backend`	Backend	Complete backend projects with auth, DB, monitoring
`generate_from_template_pack`	Code	Multi-page apps from curated packs (SaaS, Landing, AI Chat)
`figma_context_parser`	Context	Read Figma files, extract tokens, map to Tailwind
`figma_push_variables`	Design	Write design tokens back to Figma
`fetch_design_inspiration`	Context	Extract visual metadata from URLs
`analyze_design_references`	Context	Analyze design references, detect patterns
`analyze_design_image`	ML	Analyze design images for training data
`analyze_component_library`	Context	Analyze component library patterns
`audit_accessibility`	Quality	WCAG 2.1 audit with fix suggestions
`submit_feedback`	Quality	Submit feedback to improve future output
`payments_refund`	Backend	Request payment refund with Zod-validated params (payment_id, amount, reason, currency)
`manage_training`	ML	Training data ingestion and fine-tuning

Framework & Library Support

Library	React	Vue	Angular	Svelte	HTML
shadcn/ui	shadcn/ui	shadcn-vue	Tailwind	bits-ui	Tailwind
Radix	@radix-ui/react	@radix-ui/vue	Tailwind	@radix-ui/svelte	Tailwind
Headless UI	@headlessui/react	@headlessui/vue	Tailwind	@headlessui/svelte	Tailwind
Material	@mui/material	Vuetify	@angular/material	@smui/material	Tailwind
PrimeVue	Headless UI	primevue	primeng	Tailwind	Tailwind
none	Tailwind CSS	Tailwind CSS	Tailwind CSS	Tailwind CSS	Tailwind CSS

Brand Identity Integration

All generation tools accept an optional brand_identity parameter — a JSON string from branding-mcp's generate_brand_identity tool. When provided, brand colors, typography, and spacing are injected into the design context.

Environment Variables

Variable	Required	Description
`FIGMA_ACCESS_TOKEN`	Only for Figma tools	Token from Figma Settings
`SENTRY_DSN`	Optional	Sentry DSN for error reporting (uncaught exceptions and unhandled rejections)

Distribution

npm — published as @forgespace/ui-mcp
MCP Registry metadata — repository includes server.json and mcpName metadata for registry submission
Tag release automation — pushing v* runs npm publish with provenance, then publishes the same version to the MCP Registry via GitHub OIDC
Weekly registry ops — .github/workflows/mcp-registry-status.yml refreshes one issue with npm and MCP Registry drift, visibility, and next actions
GitHub — source, issues, releases, and Discussions live under Forge Space

Development

npm install && npm run build
npm test                  # 437 tests, 35 suites
npm run validate          # lint + format + typecheck + test

Community

GitHub Workflow

This repository follows the shared Forge Space GitHub work-management baseline:

Discussions for ideas, RFCs, Q&A, and announcements
Issues for actionable delivery work
Projects for roadmap visibility and cross-repo reporting

See Forge-Space/.github GOVERNANCE.md for the org-wide contract.

Scheduled monitoring runs that execute CodeQL require job-scoped security-events: write permission for SARIF upload.

The scheduled Security Monitoring workflow intentionally skips Codecov upload and relies on local coverage summary generation to reduce false alerting from third-party action download instability.

License

MIT