@moontra/moonui-mcp-server

v6.0.1

Published

21 days ago

Model Context Protocol server for MoonUI component library - AI-native component access with full props/examples/accessibility data

0High
0Medium
0Low

oguzhanayyldz

mcp model-context-protocol moonui ai claude component-library ui-components react

MoonUI MCP Server

Model Context Protocol server for MoonUI component library - AI-native component access with intelligent recommendations.

✨ Features

🎯 Smart Component Suggestions - AI-powered recommendations based on natural language
🔍 200+ Components - Complete MoonUI library coverage with Pro/Free classification
🌍 Turkish Language Support - 100% accurate Turkish-to-English translation
🚀 Lightning Fast - Sub-millisecond query responses (0.7ms average)
🏆 Pro-First Priority - Automatically suggests best components
✅ 100% Test Coverage - 284 comprehensive tests, all passing
📚 Comprehensive Documentation - Complete metadata, examples, and best practices

🎉 What's New in v6.0.0

v6 ships with complete component data — props, code examples, accessibility specs and best practices that previously had to be inferred. Every entry in the registry is now driven by MoonUI's authoritative DocsConfig definitions.

📊 Registry schema v3.0 — installation, usage.basic/pro.code, fullExamples.free/pro, api.components[].props, api.accessibility, api.bestPractices, proFeatures, seo
🛠️ Four granular tools for context-efficient queries — get_props, get_examples, get_accessibility, get_installation
🌐 Hybrid registry loader — opt-in MOONUI_REGISTRY_URL env to pull fresh data from moonui.dev/api/mcp/registry with offline fallback
📈 Coverage at GA — props on 155/179 components (86.6%), accessibility on 124/179 (69.3%)
🧹 No more hardcoded fallbacks — Button/Dialog/Input data now comes from the registry like every other component
🔗 Sub-component → parent linking — data-table-bulk-actions.parentComponent === "data-table"
📦 dataQuality field — every response signals complete | partial | ast-only so LLMs know how trustworthy the data is

Previous: v5.2.1

✅ Perfect Test Coverage: 100% (284/284 tests passing)
🎯 Enhanced Exact Match: 5x stronger scoring
✨ All-Keywords Bonus: 15x boost for multi-word queries
🌍 Improved Turkish translation, better variant detection
⚡ Performance: 0.7ms average response

📦 Installation

NPM Package

npm install -g @moontra/moonui-mcp-server

Usage with Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "moonui": {
      "command": "npx",
      "args": ["-y", "@moontra/moonui-mcp-server@latest"]
    }
  }
}

Usage with Claude Code

# Install Claude Code CLI
npm install -g @anthropic/claude-code

# Add MCP Server
claude code mcp add moonui

Usage with Cursor IDE

Add to Cursor settings (Cmd/Ctrl + , → MCP section):

{
  "mcp.servers": {
    "moonui": {
      "command": "npx",
      "args": ["@moontra/moonui-mcp-server@latest"]
    }
  }
}

Other MCP-Compatible Tools

Works with any MCP-enabled IDE or AI assistant:

✅ Continue.dev
✅ Cody (Sourcegraph)
✅ Zed Editor
✅ All MCP-compatible tools

🛠️ Available Tools

`get_components`

Get list of all MoonUI components organized by category.

// Returns:
{
  free: Component[],      // 8 free components
  pro: Component[],       // 131 pro components
  mixed: Component[],     // 40 mixed components
  categories: string[],   // All categories
  total: 179             // Total components
}

`get_component_info`

Get detailed information about a specific component.

// Input
{ name: "button" }

// Returns
{
  name: "button",
  type: "mixed",
  category: "forms",
  description: "Versatile button component...",
  installation: {
    cli: "npx moonui-cli@latest add button",
    npm: "@moontra/moonui",
    imports: ["Button", "buttonVariants"]
  },
  props: [...],
  variants: [...],
  examples: [...],
  accessibility: {...}
}

`suggest_component`

Get intelligent component suggestions based on natural language description.

// Input
{
  description: "I need a data table with sorting and filtering",
  preferPro: true  // Optional, defaults to true
}

// Returns
{
  suggestions: [
    {
      component: {...},
      score: 98.5,
      matchReasons: ["keyword match", "category match"],
      type: "pro"
    },
    // ... more suggestions
  ],
  query: {
    original: "data table with sorting",
    normalized: "data table sorting",
    language: "en",
    keywords: ["data", "table", "sorting"]
  }
}

`get_docs`

Access comprehensive MoonUI documentation.

// Input
{
  topic: "installation" | "authentication" | "usage" | "theming" | "cli" | "troubleshooting",
  subtopic?: string  // Optional specific subtopic
}

// Returns detailed documentation with examples

`search_docs`

Search documentation for specific information.

// Input
{ query: "dark mode configuration" }

// Returns relevant documentation sections

`get_server_info`

Get server version and runtime information.

// Returns (v6.0.0)
{
  server: { version: "6.0.0", ... },
  registry: {
    schemaVersion: "3.0",
    source: "embedded" | "remote" | "remote-cache" | "remote-fallback",
    components: 179,
    coverage: { docsConfigCoverage: 0.69, uncoveredComponents: [...] },
    dataAvailability: {
      withProps: { count: 155, ratio: 0.866 },
      withExamples: { count: 125, ratio: 0.698 },
      withAccessibility: { count: 124, ratio: 0.693 },
      withBestPractices: { count: 124, ratio: 0.693 }
    }
  }
}

`clear_cache`

Clear MCP server cache for fresh data.

// Input
{ type?: "all" | "components" | "search" }  // Default: "all"

🆕 Granular tools (v6.0)

These return slices of the registry entry. Use them when you only need one part — keeps LLM context bloat down on large components like data-table.

`get_props(name, subComponent?)`

// Input
{ name: "data-table", subComponent: "BulkAction" }

// Returns
{
  component: "data-table",
  subComponent: "BulkAction",
  dataQuality: "complete",
  count: 5,
  props: [
    { name: "label", type: "string", required: true, default: "-", description: "..." },
    ...
  ]
}

`get_examples(name, variant?)`

// Input
{ name: "button", variant: "free" }   // "free" | "pro" | "all" (default)

// Returns
{
  component: "button",
  variant: "free",
  counts: { free: 10, pro: 6 },
  dataQuality: "complete",
  examples: {
    free: [{ title: "Basic Variants", description: "...", code: "<Button>...</Button>", fullWidth: false }, ...]
  }
}

`get_accessibility(name)`

// Input
{ name: "dialog" }

// Returns
{
  component: "dialog",
  accessibility: {
    keyboard: [{ keys: "Escape", description: "Close dialog" }, ...],
    aria: ["aria-labelledby", "aria-describedby", "role=\"dialog\""],
    screenReader: ["Focus is trapped within the dialog", ...]
  }
}

`get_installation(name)`

// Input
{ name: "button" }

// Returns
{
  component: "button",
  package: "@moontra/moonui",
  installation: {
    cli: "moonui add button",
    npm: "@moontra/moonui (free), @moontra/moonui-pro (pro)",
    imports: ["Button", "buttonVariants"],
    dependencies: ["@radix-ui/react-slot", "class-variance-authority"],
    manualSetup: "import * as React from \"react\"\nimport { Slot } ..."  // Full source
  }
}

⚙️ Configuration (v6.0+)

Hybrid registry — fetch fresh data from moonui.dev

By default the server uses the registry bundled inside the npm tarball — fast, offline-friendly, version-pinned. Opt into live fetching from moonui.dev/api/mcp/registry to always have the latest component data without republishing.

{
  "mcpServers": {
    "moonui": {
      "command": "npx",
      "args": ["-y", "@moontra/moonui-mcp-server@latest"],
      "env": {
        "MOONUI_REMOTE_REGISTRY": "true"
      }
    }
  }
}

| Env var | Effect | |---|---| | MOONUI_REMOTE_REGISTRY=true | Fetch from https://moonui.dev/api/mcp/registry | | MOONUI_REGISTRY_URL=https://... | Fetch from a custom URL (overrides above) |

Behaviour:

3-second fetch timeout
1-hour cache in os.tmpdir() to avoid per-spawn HTTP roundtrips
Embedded fallback if the network is unavailable

Check which source served you via get_server_info().registry.source — values are embedded, remote, remote-cache or remote-fallback.

🔁 Upgrading from v5

v6 is additive — existing get_component_info callers see all the same fields plus the new DocsConfig-derived ones. Action items:

Pin? Move to @latest — npx @moontra/moonui-mcp-server@latest picks up v6 automatically. If you pinned @5.2.3, switch to @latest or @6 to get the richer responses.
dataQuality lets you gate — Components without a DocsConfig return "ast-only". Skip expensive prompts for those if you want.
Legacy tag — @moontra/moonui-mcp-server@legacy will continue to resolve to v5.x for the foreseeable future.

`reload_registry`

Reload component registry from disk (useful after component updates).

🌍 Language Support

Turkish Language (100% Accuracy)

The MCP server provides perfect Turkish-to-English translation:

// Turkish queries automatically translated
"buton" → "button"
"veri tablosu" → "data table"
"tarih seçici" → "date picker"
"form girişi" → "form input"

// Multi-word phrases supported
"tarih picker" → "date-picker"  // Edge case handling (v5.2.1)
"açılır menü" → "dropdown-menu"

Test Coverage: 100% (20/20 Turkish translation tests passing)

🏆 Pro-First Policy

Default Behavior

By default, the MCP server prioritizes Pro components for better user experience:

Query: "table"
→ Returns: Pro/Mixed "table" component (3x score boost)

Query: "data table with sorting"
→ Returns: Pro "data-table" component (highest features)

Free Component Requests

Explicitly request free components:

Query: "free button" | "ücretsiz kart" | "bedava tablo"
→ Returns: Free version (no Pro boost)

⚡ Performance

Response Time Benchmarks

| Metric | Target | v5.2.1 | Status | |--------|--------|--------|--------| | Average Query | < 1ms | 0.7ms | ✅ Excellent | | 95th Percentile | < 2ms | 1.2ms | ✅ | | 99th Percentile | < 5ms | 2.5ms | ✅ | | Registry Load | < 100ms | 45ms | ✅ |

Cache Strategy

Production: 24-hour cache for optimal performance
Development: 1-hour cache for faster updates
Manual Control: clear_cache and reload_registry tools available

🧪 Quality Assurance

Test Coverage (v5.2.1)

Total Tests: 284
Passed: 284 (100%)
Failed: 0 (0%)
Average Score: 100/100
Average Time: 0.7ms

Test Categories

| Category | Coverage | Tests | Status | |----------|----------|-------|--------| | Turkish Translation | 100% | 20/20 | ✅ | | Pro-First Priority | 100% | 25/25 | ✅ | | Form Queries | 100% | 15/15 | ✅ | | Category Coverage | 100% | 23/23 | ✅ | | Edge Cases | 100% | 15/15 | ✅ | | Individual Components | 100% | 179/179 | ✅ |

Overall Grade: A+ (Production Ready)

📖 Philosophy

This MCP server enables AI assistants to understand and work with MoonUI components intelligently:

Semantic Understanding: Natural language queries to component matching
Context-Aware: Pro-first recommendations based on best practices
Performance-First: Sub-millisecond responses for seamless AI interaction
Quality-Driven: 100% test coverage ensures reliability
User-Focused: Simple setup, powerful capabilities

🔗 Resources

Documentation: https://moonui.dev/docs/mcp-server
NPM Package: https://npmjs.com/package/@moontra/moonui-mcp-server
GitHub Issues: https://github.com/moonui/mcp-server/issues
Discord Community: https://discord.gg/moonui
MCP Protocol: https://modelcontextprotocol.io

📊 Component Statistics

Free Components: 8 (core functionality)
Pro Components: 131 (premium features)
Mixed Components: 40 (free + pro versions)
Total: 179 components
Categories: Forms, Overlay, Feedback, Data Display, Navigation, Layout, Media, Charts

🚀 Version History

v5.2.1 (Current) - October 7, 2025

✅ 100% test coverage achieved (284/284 tests)
🎯 Enhanced exact match scoring (10x → 50x)
✨ New all-keywords-match bonus (15x)
🌍 Improved Turkish translation edge cases
🔍 Multi-word component variant detection fix
⚡ Performance improvement (0.8ms → 0.7ms avg)

v5.0 - Major Update

89/100 score, 83% pass rate
75% Turkish support
Pro-first policy introduced

v4.5 - Initial Release

60/100 score, 42% pass rate
Basic component recommendation
No Turkish support

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines and Quality Standards.

Development

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

# Install dependencies
npm install

# Build registry
npm run build:registry

# Run tests
npx tsx test-comprehensive.ts

# Build package
npx tsup

# Publish (maintainers only)
npm publish

Maintaining Quality

Please read MCP-SERVER-STANDARDS.md before contributing. Key requirements:

✅ Maintain 100% test coverage
✅ Sub-millisecond performance
✅ Follow semantic versioning
✅ Document all changes

Built with ❤️ by the MoonUI Team

Enabling AI assistants to build better UIs with MoonUI components