KarlBarker/nuxtui-mcp-server

Nuxt UI MCP Server

By xflo.ai

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to Nuxt UI components, documentation, and usage examples. This server enables AI tools like Windsurf, Claude Desktop, Cursor, and other MCP-compatible clients to work seamlessly with Nuxt UI.

⚠️ Security Notice

This is development software intended for internal use and trusted environments only.

⚠️ Known Security Limitations:

• External API requests are not fully validated (SSRF risk)
• Component names are not strictly sanitized (injection risk)
• Error messages may expose internal information
• HTML parsing from external sources without full sanitization
• No rate limiting or request size limits

Recommendations:

• Use only in trusted, internal development environments
• Do not expose this server to public networks
• Consider implementing additional input validation for production use
• Monitor logs for suspicious activity

For production deployments, please implement proper security controls or contact xflo.ai for an enterprise version.

Features

• 📚 Component Documentation: Access detailed documentation for all 50+ Nuxt UI components
• 🔍 Smart Search: Search components by name or description
• 📝 Source Code Access: Retrieve component source code directly from the Nuxt UI repository
• 🎨 Theming Information: Get theming and customization details
• 🚀 Installation Guides: Framework-specific installation instructions for Nuxt and Vue
• 📦 Category Filtering: Browse components by category (forms, navigation, overlays, etc.)
• 💾 Intelligent Caching: Reduces API calls with smart caching
• 🔧 TypeScript Support: Full type safety and IntelliSense

Quick Start

Using npx (Recommended)

The easiest way to use the Nuxt UI MCP server is with npx:

# Basic usage
npx xflo-nuxtui-mcp-server

# With GitHub token for better rate limits (set as env var)
GITHUB_TOKEN=your_token_here npx xflo-nuxtui-mcp-server

Installation in Windsurf

Add this configuration to your ~/.codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "nuxtui": {
      "command": "npx",
      "args": ["-y", "xflo-nuxtui-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"  // Optional
      }
    }
  }
}

Installation in Claude Desktop

Add to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "nuxtui": {
      "command": "npx",
      "args": ["xflo-nuxtui-mcp-server"]
    }
  }
}

Installation in Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-specific):

{
  "mcpServers": {
    "nuxtui": {
      "command": "npx",
      "args": ["-y", "xflo-nuxtui-mcp-server"]
    }
  }
}

Available Tools

The MCP server provides these tools for AI assistants:

1. list_nuxtui_components

Get a list of all available Nuxt UI components.

Parameters:

• category (optional): Filter by category (components, forms, data, feedback, navigation, overlays, layout)

Example usage in AI:

"List all Nuxt UI form components"
"Show me available navigation components in Nuxt UI"

2. get_component_details

Get detailed information about a specific component including props, slots, events, and usage examples.

Parameters:

• name (required): Component name (e.g., 'button', 'modal', 'form')

Example usage in AI:

"Show me details about the Nuxt UI button component"
"What props does the modal component accept?"

3. get_component_source

Retrieve the source code of a Nuxt UI component.

Parameters:

• name (required): Component name
• version (optional): Git branch or tag (default: 'main')

Example usage in AI:

"Show me the source code for the Nuxt UI accordion component"
"Get the button component source from version 3.0.0"

4. search_components

Search for components by keyword in name or description.

Parameters:

• query (required): Search term

Example usage in AI:

"Search for Nuxt UI components related to forms"
"Find components with 'overlay' in their description"

5. get_installation_guide

Get comprehensive installation instructions for Nuxt UI.

Example usage in AI:

"How do I install Nuxt UI?"
"Show me the Vue setup for Nuxt UI"

Local Development

Prerequisites

• Node.js v18 or later
• npm or yarn

Setup

1. Clone the repository:

git clone https://github.com/yourusername/nuxtui-mcp-server.git
cd nuxtui-mcp-server

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Run the server:

npm start

Development Mode

Run in development mode with hot reload:

npm run dev

Testing with MCP Inspector

Use the MCP Inspector for debugging:

npm run inspector

This will provide a URL to access debugging tools in your browser.

Environment Variables

• GITHUB_TOKEN: GitHub Personal Access Token for higher API rate limits (optional but recommended)

Project Structure

nuxtui-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled output
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

How It Works

1. Component Discovery: The server fetches the component list from the Nuxt UI documentation
2. Documentation Parsing: Uses Cheerio to parse HTML documentation for component details
3. Source Code Retrieval: Fetches component source directly from GitHub
4. Intelligent Caching: Caches responses to minimize API calls
5. MCP Protocol: Implements the Model Context Protocol for AI tool communication

Troubleshooting

Rate Limiting

If you encounter GitHub API rate limits:

1. Add a GitHub Personal Access Token to your environment
2. The token increases rate limits from 60 to 5,000 requests per hour

Component Not Found

If a component is not found:

1. Verify the component name matches exactly (case-sensitive)
2. Check if the component exists in the latest Nuxt UI version
3. Try searching with search_components tool

Connection Issues

If the server won't connect:

1. Ensure Node.js v18+ is installed
2. Check your MCP client configuration
3. Use the MCP Inspector to debug

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• Built for the Nuxt UI library by the Nuxt team
• Implements the Model Context Protocol
• Inspired by the shadcn-ui MCP server implementation

Links

• Nuxt UI Documentation
• Nuxt UI GitHub
• Model Context Protocol
• MCP SDK Documentation