Fomantic UI MCP Server

A comprehensive Model Context Protocol (MCP) server that provides structured access to Fomantic UI components, themes, documentation, and code generation capabilities. Perfect for AI assistants to help with Fomantic UI development.

✨ Features

• 🔍 Component Discovery: Query available Fomantic UI components with detailed metadata
• 🎨 Theme Management: Access and customize theme variables, colors, and styling
• ⚡ Code Generation: Generate production-ready HTML/CSS snippets for any component
• 📚 Documentation Access: Get contextual documentation, examples, and usage patterns
• 🔎 Smart Search: Full-text search across components, properties, and documentation
• 💾 Caching: Intelligent caching for fast responses and offline capability
• 🧪 Well Tested: Comprehensive test suite with 71+ tests covering all functionality

📦 Installation

NPM Installation (Recommended)

npm install -g fomantic-mcp

From Source

git clone https://github.com/fomantic/mcp-server.git
cd mcp-server
npm install
npm run build
npm link

🚀 Quick Start

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fomantic-ui": {
      "command": "fomantic-mcp",
      "args": []
    }
  }
}

With Claude Code (CLI)

Claude Code has built-in MCP support. Add to your MCP configuration:

# Add to ~/.config/claude-code/mcp.json (Linux/macOS)
# Or %APPDATA%\claude-code\mcp.json (Windows)
{
  "mcpServers": {
    "fomantic-ui": {
      "command": "fomantic-mcp",
      "args": []
    }
  }
}

# Or use the setup command
claude-code mcp add fomantic-ui fomantic-mcp

With Other MCP Clients

# Start the server
fomantic-mcp

# Or run from source
npm start

🎯 Claude Code Integration

Setup Instructions

1. Install the MCP Server:

   npm install -g fomantic-mcp

2. Configure Claude Code:

   # Option 1: Use Claude Code's MCP manager
   claude-code mcp add fomantic-ui fomantic-mcp
   
   # Option 2: Manual configuration
   # Edit ~/.config/claude-code/mcp.json
   {
     "mcpServers": {
       "fomantic-ui": {
         "command": "fomantic-mcp",
         "args": [],
         "env": {
           "LOG_LEVEL": "info"
         }
       }
     }
   }

3. Verify Installation:

   claude-code mcp list
   # Should show: fomantic-ui (running)

Usage in Claude Code

Once configured, you can use the MCP server directly in your Claude Code sessions:

🔧 Generate Components

Ask Claude Code to generate Fomantic UI components:

Claude, create a primary button component for my login form.

Claude Code will use the generate_component tool:

<button class="ui primary button" id="login-btn">Login</button>

🔍 Search Components

Find specific components:

Claude, show me all available input components in Fomantic UI.

Claude Code will search and display:

• Input field variations
• Usage examples
• Properties and options

🎨 Theme Customization

Generate theme overrides:

Claude, create CSS variables for a dark theme with blue primary color.

Output:

:root {
  --primary-color: #007bff;
  --background-color: #1a1a1a;
  --text-color: #ffffff;
}

📚 Get Documentation

Access component documentation:

Claude, explain how to use Fomantic UI dropdowns with JavaScript.

Claude Code will retrieve and explain:

• Component API
• Usage examples
• Best practices
• Common patterns

Advanced Claude Code Usage

🏗️ Full Page Layouts

Claude, create a responsive dashboard layout using Fomantic UI with:
- Header with navigation
- Sidebar with menu
- Main content area
- Footer

📝 Forms with Validation

Claude, build a contact form with validation using Fomantic UI that includes:
- Name, email, subject fields
- Message textarea
- Submit button with loading state
- Client-side validation

🎭 Component Variations

Claude, show me different button styles available in Fomantic UI and generate examples of each.

Configuration Options for Claude Code

You can customize the MCP server behavior in Claude Code:

{
  "mcpServers": {
    "fomantic-ui": {
      "command": "fomantic-mcp",
      "args": [
        "--config", "/path/to/custom-config.json"
      ],
      "env": {
        "LOG_LEVEL": "debug",
        "FOMANTIC_VERSION": "2.9.3",
        "CACHE_DIR": "~/.fomantic-cache"
      },
      "timeout": 30000,
      "restart": "on-failure"
    }
  }
}

Troubleshooting in Claude Code

Check MCP Server Status

claude-code mcp status fomantic-ui

View Logs

claude-code mcp logs fomantic-ui

Restart Server

claude-code mcp restart fomantic-ui

Debug Mode

# Enable debug logging
claude-code mcp set-env fomantic-ui LOG_LEVEL=debug
claude-code mcp restart fomantic-ui

Common Claude Code Prompts

Here are some effective prompts to use with Claude Code:

Component Creation

• "Create a Fomantic UI modal dialog for user confirmation"
• "Generate a responsive card layout with 3 columns"
• "Build a navigation menu with dropdown submenus"

Code Analysis

• "Review this Fomantic UI code and suggest improvements"
• "Convert this Bootstrap component to Fomantic UI"
• "Optimize this form for better accessibility"

Documentation

• "Explain the difference between Semantic UI and Fomantic UI"
• "Show me best practices for Fomantic UI theming"
• "What are the performance implications of using multiple Fomantic modules?"

Claude Code Memory Integration

For enhanced workflow, create a CLAUDE.md file in your project root:

# Project: [Your Project Name] - Fomantic UI

## UI Framework
- Using Fomantic UI 2.9.3
- MCP Server: fomantic-ui configured
- Prefer semantic HTML classes
- Use ui prefix for all components

## Design System
- Primary color: #007bff
- Secondary color: #6c757d  
- Border radius: 4px
- Font: "Lato", sans-serif

## Component Preferences
- Buttons: Use semantic variants (primary, secondary, success)
- Forms: Include validation classes
- Grids: Mobile-first responsive approach
- Modals: Center content, include close button

## Code Style
- Use kebab-case for IDs and classes
- Include ARIA attributes for accessibility
- Minimize inline styles, prefer CSS classes
- Add comments for complex component configurations

## Common Patterns
- Form validation: Use Fomantic's built-in validation
- Loading states: Apply 'loading' class to buttons/segments
- Responsive: Use stackable grids on mobile
- Icons: Prefer semantic icon names over generic ones

This helps Claude Code provide more consistent and project-specific Fomantic UI code generation.

📖 Usage Examples

Component Generation

Generate a primary button:

{
  "tool": "generate_component",
  "arguments": {
    "component": "button",
    "variant": "primary",
    "content": "Click me!",
    "attributes": {
      "id": "my-button",
      "onclick": "handleClick()"
    }
  }
}

Output:

<button class="ui primary button" id="my-button" onclick="handleClick()">Click me!</button>

Search Components

Find all input-related components:

{
  "tool": "search_components", 
  "arguments": {
    "query": "input",
    "category": "elements",
    "limit": 10
  }
}

Theme Customization

Generate theme overrides:

{
  "tool": "create_theme_override",
  "arguments": {
    "variables": {
      "--primary-color": "#007bff",
      "--border-radius": "8px",
      "--font-size": "16px"
    },
    "outputFormat": "css"
  }
}

Output:

:root {
  --primary-color: #007bff;
  --border-radius: 8px; 
  --font-size: 16px;
}

🔧 Configuration

Environment Variables

You can configure the MCP server using these environment variables:

| Variable | Default | Description | |----------|---------|-------------| | LOG_LEVEL | info | Logging level: error, warn, info, debug | | LOG_OUTPUT | both | Log output: console, file, or both | | LOG_DIR | (auto) | Custom log directory path | | NODE_ENV | production | Environment mode |

Examples:

# Debug mode with console-only logging
LOG_LEVEL=debug LOG_OUTPUT=console fomantic-mcp

# Custom log directory
LOG_DIR=/var/log/fomantic-mcp fomantic-mcp

# Development mode
NODE_ENV=development fomantic-mcp

Configuration File

Create a .fomantic-mcp.json configuration file:

{
  "version": "2.9.3",
  "cachePath": "~/.fomantic-mcp/cache",
  "updateInterval": 86400,
  "database": {
    "path": "data/fomantic.db",
    "autoUpdate": true
  },
  "parser": {
    "baseUrl": "https://fomantic-ui.com",
    "timeout": 10000,
    "retries": 3
  },
  "cache": {
    "type": "file",
    "maxSize": 1000,
    "defaultTTL": 3600000
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | version | string | "2.9.0" | Fomantic UI version to target | | cachePath | string | "~/.fomantic-mcp/cache" | Cache directory path | | updateInterval | number | 86400 | Auto-update interval in seconds | | database.path | string | "data/fomantic.db" | SQLite database path | | database.autoUpdate | boolean | true | Enable automatic database updates | | parser.baseUrl | string | "https://fomantic-ui.com" | Documentation base URL | | parser.timeout | number | 10000 | HTTP request timeout in ms | | parser.retries | number | 3 | Number of retry attempts | | cache.type | string | "file" | Cache type ("memory" or "file") | | cache.maxSize | number | 1000 | Maximum cache entries | | cache.defaultTTL | number | 3600000 | Default TTL in milliseconds |

🛠️ MCP Resources

Available Resources

| Resource URI | Description | MIME Type | |--------------|-------------|-----------| | fomantic://components | List all components | application/json | | fomantic://components/{name} | Get component details | application/json | | fomantic://themes/variables | Theme variables | application/json | | fomantic://examples/{component} | Component examples | text/html | | fomantic://cheatsheet | Quick reference guide | text/markdown |

Claude Code Quick Reference

Common MCP resources and tools available in Claude Code:

| What you want | What to ask Claude Code | MCP Resource/Tool Used | |---------------|-------------------------|------------------------| | Generate a button | "Create a primary button" | generate_component | | Find input types | "Show me input variations" | search_components | | Get component docs | "How do I use modals?" | fomantic://components/modal | | Create theme | "Generate dark theme CSS" | create_theme_override | | Build a form | "Create contact form" | generate_component + examples | | Layout help | "Make responsive grid" | fomantic://components/grid |

Resource Examples

// Get all components
await mcp.readResource("fomantic://components");

// Get button component details
await mcp.readResource("fomantic://components/button");

// Get theme variables
await mcp.readResource("fomantic://themes/variables");

🔨 MCP Tools

Core Tools

generate_component

Generate HTML markup for Fomantic UI components.

Parameters:

• component (required): Component name (e.g., "button", "input", "dropdown")
• variant (optional): Component variant (e.g., "primary", "secondary", "large")
• content (optional): Inner content/text
• attributes (optional): HTML attributes object
• includeJS (optional): Include JavaScript initialization
• includeCSS (optional): Include component-specific CSS

Example:

{
  "component": "dropdown",
  "variant": "selection",
  "attributes": {
    "id": "country-select",
    "data-value": "us"
  },
  "includeJS": true
}

search_components

Search for components by name, category, or description.

Parameters:

• query (required): Search query string
• category (optional): Filter by category (elements, collections, views, modules, behaviors)
• limit (optional): Maximum results (default: 10)
• includeExamples (optional): Include examples in results
• includeVariations (optional): Include component variations

create_theme_override

Generate theme customization CSS.

Parameters:

• variables (required): Object of CSS variables to override
• theme (optional): Base theme name (default: "default")
• outputFormat (optional): Output format (css, less, scss)

validate_markup

Validate Fomantic UI HTML structure.

Parameters:

• html (required): HTML markup to validate
• strict (optional): Enable strict validation
• checkAccessibility (optional): Include accessibility checks

Advanced Tools

get_component_api

Get detailed API information for JavaScript components.

generate_form

Generate complete form structures with validation.

create_layout

Generate responsive grid layouts.

optimize_theme

Analyze and optimize theme performance.

🏗️ Development

Prerequisites

• Node.js 18+
• npm 9+
• TypeScript 5.3+

Setup

# Clone repository
git clone https://github.com/fomantic/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

Development Scripts

| Script | Description | |--------|-------------| | npm run build | Build TypeScript to JavaScript | | npm run dev | Watch mode for development | | npm run test | Run all tests | | npm run test:unit | Run unit tests only | | npm run test:integration | Run integration tests | | npm run test:e2e | Run end-to-end tests | | npm run test:coverage | Generate coverage report | | npm run lint | Lint TypeScript code | | npm run format | Format code with Prettier | | npm run setup | Initial setup script |

Project Structure

fomantic-mcp/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # MCP server implementation
│   ├── handlers/                # Request handlers
│   │   ├── resources.ts         # Resource handlers
│   │   └── tools.ts             # Tool implementations
│   ├── parsers/                 # Data parsing modules
│   │   ├── documentation.ts     # Documentation parser
│   │   └── source-code.ts       # Source code parser
│   ├── models/                  # TypeScript interfaces
│   │   ├── component.ts         # Component models
│   │   ├── theme.ts             # Theme models
│   │   └── search.ts            # Search models
│   ├── storage/                 # Data storage layer
│   │   ├── database.ts          # SQLite interface
│   │   └── cache.ts             # Caching implementation
│   ├── generators/              # Code generation
│   │   ├── html.ts              # HTML generator
│   │   └── css.ts               # CSS generator
│   └── utils/                   # Utility functions
├── tests/                       # Test suites
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── e2e/                     # End-to-end tests
├── scripts/                     # Build scripts
└── docs/                        # Documentation

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

Test Coverage

Current test coverage: 71 tests passing

• ✅ Unit Tests: Cache, Database, Parsers, Models
• ✅ Integration Tests: MCP Server, Protocol Compliance
• ✅ End-to-End Tests: Complete Workflows
• ✅ Performance Tests: Load Testing, Concurrency
• ✅ Error Handling: Edge Cases, Recovery

📊 Performance

Benchmarks

• Component Generation: ~5ms per component
• Search: ~10ms for 1000+ components
• Documentation Parsing: ~100ms per component page
• Database Operations: ~1ms per query
• Cache Hit Rate: >95% for repeated requests

Optimization Features

• Intelligent Caching: Multi-level caching (memory + file)
• Lazy Loading: Components loaded on-demand
• Connection Pooling: Efficient database connections
• Request Deduplication: Prevent duplicate network requests
• Background Updates: Automatic data synchronization

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Write tests for new functionality
• Follow TypeScript best practices
• Use Prettier for code formatting
• Add JSDoc comments for public APIs
• Update documentation for new features

🐛 Troubleshooting

Common Issues

Server Won't Start

Global Installation Issues:

# Check if the server is installed globally
npm list -g fomantic-mcp

# Check Node.js version
node --version  # Should be 18+

# Try running with debug logging
LOG_LEVEL=debug fomantic-mcp

# If still failing, try console-only logging
LOG_OUTPUT=console fomantic-mcp

# Reinstall globally if needed
npm uninstall -g fomantic-mcp
npm install -g fomantic-mcp

Local Development Issues:

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Rebuild project
npm run build

Database Errors

# Reset database
rm -rf data/fomantic.db
npm run setup

# Check file permissions
ls -la data/

Network Issues

# Check connectivity
curl -I https://fomantic-ui.com

# Use proxy (if needed)
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

Performance Issues

# Clear cache
rm -rf data/cache/

# Reduce cache size in config
echo '{"cache": {"maxSize": 100}}' > .fomantic-mcp.json

Debug Mode

Enable debug logging:

# Set log level
export LOG_LEVEL=debug

# Run with verbose output
DEBUG=fomantic:* fomantic-mcp

Getting Help

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Email Support

📚 API Reference

Component Model

interface Component {
  id: string;
  name: string;
  category: ComponentCategory;
  description: string;
  version: string;
  properties: Property[];
  methods: Method[];
  events: Event[];
  examples: Example[];
  variations: Variation[];
  dependencies: string[];
  cssClasses: CSSClass[];
  createdAt: Date;
  updatedAt: Date;
}

Theme Model

interface Theme {
  id: string;
  name: string;
  description: string;
  version: string;
  variables: ThemeVariable[];
  overrides: Override[];
  assets: Asset[];
}

Search Model

interface SearchQuery {
  query: string;
  category?: string;
  type?: SearchResultType;
  limit?: number;
  offset?: number;
}

🔐 Security

Security Features

• 🛡️ Input Validation: All inputs validated and sanitized
• 🔒 SQL Injection Protection: Parameterized queries only
• 🚫 XSS Prevention: HTML output escaped by default
• 🔐 Safe Parsing: Sandboxed HTML/CSS parsing
• 📝 Audit Logging: Security events logged

Reporting Security Issues

Please report security vulnerabilities to [email protected].

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Fomantic UI - The amazing UI framework
• Model Context Protocol - The protocol specification
• Claude - AI assistant integration
• TypeScript - Type safety and developer experience
• Vitest - Fast and reliable testing framework

🔗 Related Projects

• Fomantic UI - The main UI framework
• Claude Desktop - AI assistant with MCP support
• MCP SDK - MCP development kit
• Semantic UI React - React integration

Made with ❤️ for the Fomantic UI community

This MCP server makes Fomantic UI development faster, easier, and more enjoyable by bringing intelligent assistance directly to your workflow.