@tekton-ui/mcp-server
Advanced tools
Tekton MCP Server with Claude Code integration and timestamp-based preview system
Tekton MCP Server v2.0.0 - stdio-based MCP protocol implementation for Claude Code.
MCP (Model Context Protocol) server enabling AI-driven blueprint generation, theme preview, and production code export for the Tekton design system.
SPEC: SPEC-MCP-002 v2.0.0 - stdio-based MCP Standard
pnpm install
The MCP server supports optional API key authentication to enable access to premium themes.
# Required for premium theme access
TEKTON_API_KEY=tk_live_xxx...
# Optional: API endpoint (defaults to https://tekton-ui.com)
TEKTON_API_URL=https://tekton-ui.com # or http://localhost:3000 for dev
All Themes (Requires valid API key and license):
classic-magazine - Classic magazine styleequinox-fitness - Fitness & wellnessminimal-workspace - Minimal workspaceneutral-humanism - Neutral humanismround-minimal - Round minimalsquare-minimalism - Square minimalismNote: All 6 themes require authentication. No free themes are available.
Without API Key:
With Valid API Key:
With Invalid API Key:
init Commandνλ‘μ νΈμ Tekton UIλ₯Ό ν μ€λ‘ μ€μ ν©λλ€.
npx @tekton-ui/mcp-server init
μλμΌλ‘ μνλλ μμ :
@tekton-ui/ui, tailwindcss-animate (ν¨ν€μ§ 맀λμ μλ κ°μ§: pnpm/yarn/bun/npm)tailwind.config.tsμ content κ²½λ‘ λ° animate νλ¬κ·ΈμΈ μΆκ°globals.cssμ @import '@tekton-ui/ui/styles' μΆκ°.mcp.jsonμ tekton μλ² λ±λ‘ (νλ‘μ νΈ λ£¨νΈ)TEKTON-GUIDE.md νλ‘μ νΈ λ£¨νΈμ μμ±CLAUDE.md λ° AGENTS.mdμ Tekton μν¬νλ‘μ° μΉμ
μΆκ°μ€μ μλ£ ν Claude Codeλ₯Ό μ¬μμνλ©΄, AIμκ² "λ‘κ·ΈμΈ νλ©΄ λ§λ€μ΄μ€"μ κ°μ΄ μμ°μ΄λ‘ νλ©΄ μμ±μ μμ²ν μ μμ΅λλ€.
| Command | Description |
|---|---|
npx @tekton-ui/mcp-server | MCP stdio μλ² μμ |
npx @tekton-ui/mcp-server init | νλ‘μ νΈ μ΄κΈ° μ€μ |
tekton-mcp login | λΈλΌμ°μ OAuth λ‘κ·ΈμΈ |
tekton-mcp logout | λ‘κ·Έμμ |
tekton-mcp status | μΈμ¦ μν νμΈ |
pnpm install
pnpm build
pnpm inspect
# Opens browser at http://localhost:6274
See Claude Code Integration Guide for complete setup instructions.
Quick Config (νλ‘μ νΈ λ£¨νΈ .mcp.json):
{
"mcpServers": {
"tekton": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@tekton-ui/mcp-server"]
}
}
}
Tool: generate-blueprint
Description: Generate a UI blueprint from natural language description
Input:
{
"description": "User profile dashboard with avatar, bio, settings link",
"layout": "sidebar-left",
"themeId": "calm-wellness",
"componentHints": ["Card", "Avatar", "Button"]
}
Output (Data-Only, v2.0.0):
{
"success": true,
"blueprint": {
"id": "bp-1738123456789-abc123",
"name": "User profile dashboard",
"themeId": "calm-wellness",
"layout": "sidebar-left",
"components": [...],
"timestamp": 1738123456789
}
}
Note: previewUrl field removed in v2.0.0 (use SPEC-PLAYGROUND-001 for visual preview)
Tool: preview-theme
Description: Preview a Tekton theme and retrieve its design tokens
Input:
{
"themeId": "premium-editorial"
}
Output (Data-Only, v2.0.0):
{
"success": true,
"theme": {
"id": "premium-editorial",
"name": "Premium Editorial",
"description": "Elegant magazine-style UI",
"cssVariables": {
"--color-primary": "oklch(0.2 0 0)",
"--color-secondary": "oklch(0.98 0 0)",
"--font-family": "Georgia",
"--border-radius": "0"
}
}
}
Note: previewUrl field removed in v2.0.0
Tool: export-screen
Description: Export a blueprint to production-ready code (TSX/JSX/Vue)
Input (v2.0.0: accepts blueprint object):
{
"blueprint": {
"id": "bp-1738123456789-abc123",
"name": "User Dashboard",
"themeId": "calm-wellness",
"layout": "sidebar-left",
"components": [],
"timestamp": 1738123456789
},
"format": "tsx"
}
Output (Data-Only, v2.0.0):
{
"success": true,
"code": "import React from 'react';\n\nexport default function UserDashboard() { ... }"
}
Note: filePath field removed in v2.0.0. Claude Code handles file writes.
Tool: list-themes
Description: List all available themes from .moai/themes/generated/
Input:
{}
Output:
{
"success": true,
"themes": [
{
"id": "calm-wellness",
"name": "Calm Wellness",
"description": "Serene wellness applications",
"brandTone": "calm",
"schemaVersion": "2.1"
}
],
"count": 13
}
Tool: generate_screen
Description: Generate production-ready code from JSON screen definition
Input:
{
"screenDefinition": {
"id": "user-dashboard",
"shell": "shell.web.dashboard",
"page": "page.dashboard",
"sections": [
{
"id": "header",
"token": "section.container",
"components": [
{
"type": "Heading",
"props": { "level": 1, "children": "Dashboard" }
}
]
}
]
},
"outputFormat": "react",
"options": {
"typescript": true,
"cssFramework": "styled-components"
}
}
Output:
{
"success": true,
"code": "import React from 'react';\nimport styled from 'styled-components';\n\n...",
"cssVariables": ":root { --shell-header-height: 64px; ... }"
}
Output Formats:
css-in-js: Styled-components or Emotiontailwind: Tailwind CSS classesreact: Pure React component with CSS variablesTool: validate_screen
Description: Validate JSON screen definition with helpful feedback
Input:
{
"screenDefinition": {
"id": "test-screen",
"shell": "shell.web.app",
"page": "page.detail",
"sections": []
},
"strictMode": false
}
Output:
{
"success": true,
"valid": true,
"errors": [],
"warnings": ["Optional field 'meta' not provided"],
"suggestions": [
{
"field": "shell",
"message": "Shell token must match pattern",
"suggestion": "Use format: shell.{platform}.{name}"
}
]
}
Tool: list_tokens
Description: List available layout tokens from SPEC-LAYOUT-001
Input:
{
"tokenType": "shell",
"filter": "dashboard"
}
Output:
{
"success": true,
"shells": [
{
"id": "shell.web.dashboard",
"name": "Web Dashboard Shell",
"description": "Dashboard application shell with header and sidebar",
"platform": "web"
}
],
"metadata": {
"total": 1,
"filtered": 1
}
}
Token Types:
shell: Shell layout tokens (shell.web., shell.mobile.)page: Page layout tokens (page.dashboard, page.detail, etc.)section: Section pattern tokens (section.grid-4, section.hero, etc.)all: All token typesTool: list-components
Description: List all available UI components from @tekton/ui component catalog
Input:
{
"category": "core",
"search": "button"
}
Parameters:
category (optional): Filter by category - 'core' | 'complex' | 'advanced' | 'all' (default: 'all')search (optional): Search components by name or descriptionOutput:
{
"success": true,
"components": [
{
"id": "button",
"name": "Button",
"category": "core",
"description": "Interactive button with variants",
"variantsCount": 6,
"hasSubComponents": false,
"tier": 1
}
],
"count": 15,
"categories": {
"core": 15,
"complex": 10,
"advanced": 5
}
}
Component Categories:
Total Components: 30+
Tool: preview-component
Description: Get detailed information about a specific UI component including props, variants, sub-components, and usage examples
Input:
{
"componentId": "button",
"includeExamples": true,
"includeDependencies": true
}
Parameters:
componentId (required): Component ID (lowercase with hyphens, e.g., 'button', 'card', 'dialog')includeExamples (optional): Include usage examples (default: true)includeDependencies (optional): Include dependency information (default: true)Output:
{
"success": true,
"component": {
"id": "button",
"name": "Button",
"category": "core",
"description": "Interactive button with variants",
"tier": 1,
"props": [
{
"name": "variant",
"type": "'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'",
"required": false,
"defaultValue": "'default'",
"description": "Visual style variant"
},
{
"name": "size",
"type": "'default' | 'sm' | 'lg' | 'icon'",
"required": false,
"defaultValue": "'default'",
"description": "Button size"
}
],
"variants": [
{
"name": "variant",
"value": "default",
"description": "Default blue button"
},
{
"name": "variant",
"value": "destructive",
"description": "Red destructive action"
}
],
"importStatement": "import { Button } from '@tekton/ui';",
"dependencies": {
"internal": [],
"external": ["@radix-ui/react-slot"]
},
"examples": [
{
"title": "Basic Usage",
"code": "import { Button } from '@tekton/ui';\n\n<Button variant=\"default\">Click me</Button>",
"description": "Simple button with default variant"
}
],
"accessibility": "Supports keyboard navigation and ARIA attributes"
}
}
Error Handling: When component not found, returns error with list of available components
Tool: list-screen-templates
Description: List all available screen templates from the Tekton template registry
Input:
{
"category": "auth",
"search": "login"
}
Parameters:
category (optional): Filter by category - 'auth' | 'dashboard' | 'form' | 'marketing' | 'feedback' | 'all' (default: 'all')search (optional): Search templates by name or descriptionOutput:
{
"success": true,
"templates": [
{
"id": "auth.login",
"name": "Login",
"category": "auth",
"description": "User authentication login screen",
"requiredComponentsCount": 5,
"layoutType": "centered",
"version": "1.0.0",
"tags": ["authentication", "form"]
}
],
"count": 4,
"categories": {
"auth": 4,
"dashboard": 1,
"form": 0,
"marketing": 3,
"feedback": 5
}
}
Template Categories:
Total Templates: 13
The MCP server provides 2 built-in prompts that work across all MCP clients:
Purpose: Complete onboarding guide for Tekton UI
Content:
When to use: First-time users, onboarding, workflow overview
Purpose: Detailed 4-step production workflow
Content:
When to use: Production screen generation, workflow clarification
Note: These prompts are platform-agnostic and work with Claude Code, OpenAI Codex, Cursor, Windsurf, and any MCP-compatible client.
Total Prompts: 2
Tool: preview-screen-template
Description: Get detailed information about a specific screen template including skeleton structure, layout configuration, and customization boundaries
Input:
{
"templateId": "auth.login",
"includeLayoutTokens": true
}
Parameters:
templateId (required): Template ID in format category.name (e.g., 'auth.login', 'feedback.loading')includeLayoutTokens (optional): Include responsive layout tokens (default: true)Output:
{
"success": true,
"template": {
"id": "auth.login",
"name": "Login",
"category": "auth",
"description": "User authentication login screen",
"version": "1.0.0",
"skeleton": {
"shell": "centered-card",
"page": "auth-page",
"sections": [
{
"id": "header",
"name": "Header",
"slot": "logo",
"required": true
},
{
"id": "form",
"name": "Form",
"slot": "main",
"required": true
}
]
},
"layout": {
"type": "centered",
"responsive": {
"mobile": {
"padding": "1rem",
"gap": "1rem",
"columns": 1
},
"tablet": {
"padding": "2rem",
"gap": "1.5rem",
"columns": 1
},
"desktop": {
"padding": "2rem",
"gap": "2rem",
"columns": 1
}
}
},
"customizable": {
"texts": ["title", "subtitle", "button_label"],
"optional": ["social_login", "remember_me"],
"slots": ["logo", "footer", "socialLogin"]
},
"requiredComponents": ["Input", "Button", "Card", "Form", "Label"],
"importStatement": "import { LoginTemplate } from '@tekton/ui';",
"exampleProps": {
"texts": {
"title": "Welcome Back",
"subtitle": "Sign in to your account"
},
"options": {
"social_login": true,
"remember_me": true
}
},
"created": "2026-01-15",
"updated": "2026-01-20",
"tags": ["authentication", "form"]
}
}
Error Handling: When template not found, returns error with list of available templates
Use Cases:
Blueprint & Theme Workflows:
User: "Create a user dashboard with profile card using calm-wellness theme"
β Claude Code calls generate-blueprint
β Blueprint JSON returned
User: "Show me the premium-editorial theme"
β Claude Code calls preview-theme
β Theme metadata and CSS variables returned
User: "Export that dashboard as TypeScript React"
β Claude Code calls export-screen
β TSX code returned (ready to copy/paste)
Screen Generation Workflows:
User: "Generate a dashboard screen using shell.web.dashboard and page.dashboard"
β Claude Code calls generate_screen
β Production-ready React code with CSS variables returned
User: "What layout tokens are available for sections?"
β Claude Code calls list_tokens with tokenType='section'
β List of section tokens (grid-2, grid-3, hero, etc.) returned
Component Discovery Workflows (SPEC-MCP-003):
User: "What UI components are available?"
β Claude Code calls list-components
β List of 30+ components categorized by tier returned
User: "Show me details about the Button component"
β Claude Code calls preview-component with componentId='button'
β Props, variants, examples, and dependencies returned
User: "I need a dialog component. What are the props?"
β Claude Code calls preview-component with componentId='dialog'
β Complete Dialog component specification with sub-components returned
Template Discovery Workflows (SPEC-MCP-003):
User: "What screen templates are available for authentication?"
β Claude Code calls list-screen-templates with category='auth'
β 4 auth templates (login, signup, forgot-password, verification) returned
User: "Show me the login template structure"
β Claude Code calls preview-screen-template with templateId='auth.login'
β Skeleton, layout, customization boundaries, and required components returned
User: "What can I customize in the loading template?"
β Claude Code calls preview-screen-template with templateId='feedback.loading'
β Customizable texts, slots, and optional features returned
See Claude Code Integration Guide for complete examples.
packages/mcp-server/
βββ src/
β βββ index.ts # stdio MCP server entry point (13 tools)
β βββ tools/ # MCP tool implementations
β β βββ generate-blueprint.ts # Blueprint generation
β β βββ preview-theme.ts # Theme preview
β β βββ list-themes.ts # Theme listing
β β βββ list-icon-libraries.ts # Icon library listing
β β βββ preview-icon-library.ts # Icon library preview
β β βββ export-screen.ts # Blueprint export
β β βββ generate-screen.ts # Screen code generation (SPEC-LAYOUT-002)
β β βββ validate-screen.ts # Screen validation (SPEC-LAYOUT-002)
β β βββ list-tokens.ts # Layout token listing (SPEC-LAYOUT-002)
β β βββ list-components.ts # Component listing (SPEC-MCP-003)
β β βββ preview-component.ts # Component preview (SPEC-MCP-003)
β β βββ list-screen-templates.ts # Template listing (SPEC-MCP-003)
β β βββ preview-screen-template.ts # Template preview (SPEC-MCP-003)
β βββ data/ # Static data registries (SPEC-MCP-003)
β β βββ component-registry.ts # Component metadata registry
β β βββ component-metadata.json # Static component metadata
β βββ storage/ # Blueprint storage
β β βββ blueprint-storage.ts
β β βββ timestamp-manager.ts
β βββ schemas/ # Zod validation
β β βββ mcp-schemas.ts
β βββ utils/ # Helper functions
β βββ error-handler.ts
β βββ logger.ts # stderr-only logging
βββ __tests__/ # Test suites
βββ tools/ # Tool tests
β βββ generate-blueprint.test.ts
β βββ preview-theme.test.ts
β βββ export-screen.test.ts
β βββ screen-tools.test.ts # SPEC-LAYOUT-002 Phase 4 tests
β βββ list-components.test.ts # SPEC-MCP-003 tests
β βββ preview-component.test.ts # SPEC-MCP-003 tests
β βββ list-screen-templates.test.ts # SPEC-MCP-003 tests
β βββ preview-screen-template.test.ts # SPEC-MCP-003 tests
βββ mcp-protocol/ # JSON-RPC validation
βββ storage/ # Storage tests
βββ utils/ # Utility tests
Key Changes in v2.0.0:
classic-magazine - Classic magazine styleequinox-fitness - Fitness & wellnessminimal-workspace - Minimal workspaceneutral-humanism - Neutral humanismround-minimal - Round minimalsquare-minimalism - Square minimalismCSS Format: All color values use OKLCH format for perceptual uniformity
Authentication: All themes require valid API key and license
| Metric | Target | Current | Status |
|---|---|---|---|
| Test Coverage | β₯ 85% | 94.39% | β |
| TypeScript Errors | 0 | 0 | β |
| Critical Vulnerabilities | 0 | 0 | β |
| Tool Response Time | < 500ms | < 100ms | β |
| Server Startup | < 1s | < 500ms | β |
Test Results:
All MCP tools reuse @tekton/core functions:
Blueprint & Theme Tools:
loadTheme() - Theme loadinglistThemes() - Theme enumerationcreateBlueprint() - Blueprint creationvalidateBlueprint() - Schema validationgenerateCSSVariables() - CSS variable extractionrender() - Code generationScreen Generation Tools (SPEC-LAYOUT-002):
validateScreenDefinition() - Screen validationresolveScreen() - Layout and component resolutiongenerateStyledComponents() - CSS-in-JS generationgenerateTailwindClasses() - Tailwind CSS generationgenerateReactComponent() - React component generationgetAllShellTokens() - Shell token listinggetAllPageLayoutTokens() - Page token listinggetAllSectionPatternTokens() - Section token listingComponent & Template Discovery (SPEC-MCP-003):
templateRegistry from @tekton/ui - Template metadata and searchZero code duplication - Single source of truth maintained.
# Install dependencies
pnpm install
# Build (TypeScript β dist/)
pnpm build
# Run tests
pnpm test
# Test with coverage
pnpm test:coverage
# Watch mode
pnpm dev
# Lint
pnpm lint
# Start MCP server (stdio)
pnpm start
# MCP Inspector (browser-based testing)
pnpm inspect
# Automated MCP protocol validation
node validate-mcp.mjs
# Manual testing with MCP Inspector
pnpm inspect
Breaking Changes:
previewUrl field removed from generate-blueprint and preview-theme outputsfilePath field removed from export-screen outputexport-screenexport-screen now accepts blueprint object instead of blueprintIdWhy?
Visual Preview: Use SPEC-PLAYGROUND-001 for React-based rendering
Contributions welcome! Please ensure:
pnpm test)pnpm test:coverage)pnpm build)node validate-mcp.mjs)MIT
Version: 3.0.0 (stdio-based MCP standard + Component & Template Discovery) Last Updated: 2026-02-01 SPEC: SPEC-MCP-002 v2.0.0, SPEC-LAYOUT-002 Phase 4, SPEC-MCP-003 v1.0.0 Total Tools: 13 (9 existing + 4 new discovery tools)
FAQs
Tekton MCP Server with Claude Code integration and timestamp-based preview system
The npm package @tekton-ui/mcp-server receives a total of 2 weekly downloads. As such, @tekton-ui/mcp-server popularity was classified as not popular.
We found that @tekton-ui/mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Β It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.