Content
# 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:
```bash
# 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`:
```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`
```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):
```json
{
"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:
```bash
git clone https://github.com/yourusername/nuxtui-mcp-server.git
cd nuxtui-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
4. Run the server:
```bash
npm start
```
### Development Mode
Run in development mode with hot reload:
```bash
npm run dev
```
### Testing with MCP Inspector
Use the MCP Inspector for debugging:
```bash
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](https://ui.nuxt.com) library by the Nuxt team
- Implements the [Model Context Protocol](https://modelcontextprotocol.io)
- Inspired by the shadcn-ui MCP server implementation
## Links
- [Nuxt UI Documentation](https://ui.nuxt.com)
- [Nuxt UI GitHub](https://github.com/nuxt/ui)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)
