tremor-ui-mcp-server/README.md

A Model Context Protocol (MCP) server providing AI assistants with access to Tremor UI components, blocks, and templates for React dashboard development

# Tremor UI MCP Server

A Model Context Protocol (MCP) server providing AI assistants with access to Tremor UI components, blocks, and templates for React dashboard development.

## Overview

The Tremor UI MCP Server enables AI assistants to access and provide information about:
- **Components**: 35+ Tremor UI components with props, examples, and metadata
- **Blocks**: Pre-built dashboard sections and layouts
- **Templates**: Complete dashboard templates and applications

Built on top of the Model Context Protocol, this server integrates with AI assistants like Claude, Continue.dev, and others to provide contextual information about Tremor UI development.

## Features

- 🎯 **Complete Component Library**: Access to all Tremor UI components with detailed information
- 📊 **Dashboard Blocks**: Pre-built sections for rapid dashboard development
- 🏗️ **Templates**: Full application templates with best practices
- 🔄 **Live Data**: Fetches latest information from the Tremor repository
- ⚡ **Fast & Cached**: Intelligent caching for optimal performance
- 🔐 **GitHub Integration**: Optional GitHub API token for enhanced rate limits

## Quick Start

### Running with npx (Recommended)

### Running Locally (Development)

```bash
# Clone or navigate to the project
cd tremor-ui-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
node dist/index.js --github-api-key your_token_here

# Or using npm script
npm start
```

### Running with npx (After Publishing)

```bash
# Basic usage (rate limited to 60 requests/hour)
npx tremor-ui-mcp-server

# With GitHub token for better rate limits (5000 requests/hour)
npx tremor-ui-mcp-server --github-api-key ghp_your_token_here

# Short form
npx tremor-ui-mcp-server -g ghp_your_token_here

# Using environment variable
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
npx tremor-ui-mcp-server
```

### Command Line Options

```
tremor-ui-mcp-server [options]

Options:
  --github-api-key, -g <token>    GitHub Personal Access Token
  --help, -h                      Show help message
  --version, -v                   Show version information

Environment Variables:
  GITHUB_PERSONAL_ACCESS_TOKEN    Alternative way to provide GitHub token

Examples:
  npx @tremor-ui/mcp-server --help
  npx @tremor-ui/mcp-server --version
  npx @tremor-ui/mcp-server -g ghp_1234567890abcdef
  GITHUB_PERSONAL_ACCESS_TOKEN=ghp_token npx @tremor-ui/mcp-server
```

## MCP Client Configuration

### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "tremor-ui": {
      "command": "node",
      "args": ["path/to/tremor-ui-mcp-server/dist/index.js", "--github-api-key", "ghp_your_token_here"]
    }
  }
}
```

Or using environment variables:

```json
{
  "mcpServers": {
    "tremor-ui": {
      "command": "node",
      "args": ["path/to/tremor-ui-mcp-server/dist/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

Or if published to npm:

```json
{
  "mcpServers": {
    "tremor-ui": {
      "command": "npx",
      "args": ["tremor-ui-mcp-server", "--github-api-key", "ghp_your_token_here"]
    }
  }
}
```

### Cursor (Workspace Configuration)

Create a `.cursorrules` file in your workspace:

```json
{
  "mcpServers": {
    "tremor-ui": {
      "command": "npx",
      "args": ["@tremor-ui/mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

### Cursor (Global Configuration)

Add to your global Cursor settings:

```json
{
  "mcpServers": {
    "tremor-ui": {
      "command": "npx",
      "args": ["@tremor-ui/mcp-server", "--github-api-key", "ghp_your_token_here"]
    }
  }
}
```

### VS Code: Continue Extension

Add to your Continue configuration:

```json
{
  "continue.server": {
    "mcpServers": {
      "tremor-ui": {
        "command": "npx",
        "args": ["@tremor-ui/mcp-server", "--github-api-key", "ghp_your_token_here"]
      }
    }
  }
}
```

### VS Code: Claude Extension

Add to your Claude extension settings:

```json
{
  "claude.mcpServers": {
    "tremor-ui": {
      "command": "npx",
      "args": ["@tremor-ui/mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

### Continue.dev

Add to your Continue.dev configuration:

```json
{
  "name": "tremor-ui",
  "command": "npx",
  "args": ["@tremor-ui/mcp-server", "--github-api-key", "ghp_your_token_here"]
}
```

## Available Tools

The Tremor UI MCP Server provides the following tools for AI assistants:

### Component Tools

#### `get_component`
Get component source code and detailed information.

**Arguments:**
- `componentName` (string): The name of the component (e.g., "AreaChart", "Card", "Badge")

**Example:**
```json
{
  "tool": "get_component",
  "arguments": { "componentName": "AreaChart" }
}
```

#### `get_component_demo`
Get component usage examples and demo code.

**Arguments:**
- `componentName` (string): The name of the component

**Example:**
```json
{
  "tool": "get_component_demo",
  "arguments": { "componentName": "AreaChart" }
}
```

#### `list_components`
List all available Tremor UI components.

**Arguments:** None

**Example:**
```json
{
  "tool": "list_components",
  "arguments": {}
}
```

#### `get_component_metadata`
Get component dependencies, props, and metadata.

**Arguments:**
- `componentName` (string): The name of the component

**Example:**
```json
{
  "tool": "get_component_metadata",
  "arguments": { "componentName": "AreaChart" }
}
```

### Block Tools

#### `get_block`
Get complete block implementations.

**Arguments:**
- `blockName` (string): The name of the block (e.g., "dashboard-overview", "kpi-cards")

**Example:**
```json
{
  "tool": "get_block",
  "arguments": { "blockName": "dashboard-overview" }
}
```

#### `list_blocks`
List all available blocks with categories.

**Arguments:** None

**Example:**
```json
{
  "tool": "list_blocks",
  "arguments": {}
}
```

### Template Tools

#### `get_template`
Get complete template implementations.

**Arguments:**
- `templateName` (string): The name of the template (e.g., "sales-dashboard", "financial-overview")

**Example:**
```json
{
  "tool": "get_template",
  "arguments": { "templateName": "sales-dashboard" }
}
```

#### `list_templates`
List all available templates.

**Arguments:** None

**Example:**
```json
{
  "tool": "list_templates",
  "arguments": {}
}
```

### Repository Tools

#### `get_directory_structure`
Explore the Tremor UI repository structure.

**Arguments:** None

**Example:**
```json
{
  "tool": "get_directory_structure",
  "arguments": {}
}
```

## Available Components

The server provides access to 35+ Tremor UI components across categories:

### Charts
- **AreaChart**: Responsive area chart for time-series data
- **BarChart**: Bar chart for categorical data visualization
- **LineChart**: Line chart for trend visualization
- **DonutChart**: Circular chart for parts of a whole

### Layout
- **Card**: Container component with padding and shadow
- **Grid**: Grid layout system
- **Flex**: Flexible layout component

### Text & Display
- **Metric**: Display large numbers or KPIs
- **Text**: Typography component
- **Title**: Heading component
- **Badge**: Status indicators and labels
- **Callout**: Highlight important information

### Input & Interaction
- **ProgressBar**: Progress indicator
- **Button**: Interactive button component
- **Select**: Dropdown selection
- **DatePicker**: Date selection component

### Data Display
- **Table**: Data table component
- **List**: List component
- **Tracker**: Progress tracking component

## Troubleshooting

### Command Not Found

Ensure Node.js 18+ and npx are installed:

```bash
node --version  # Should be 18+
npx --version   # Should work
```

### Rate Limit Exceeded

Add a GitHub API token:

```bash
npx @tremor-ui/mcp-server --github-api-key ghp_your_token_here
```

### Network/Proxy Issues

Configure proxy settings:

```bash
export HTTP_PROXY=http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080
npx @tremor-ui/mcp-server
```

### Debug Mode

Enable verbose logging:

```bash
DEBUG=* npx @tremor-ui/mcp-server --github-api-key ghp_your_token
```

## Development

### Prerequisites

- Node.js 18+
- npm or yarn
- GitHub Personal Access Token (optional, for development)

### Setup

```bash
git clone https://github.com/your-username/tremor-ui-mcp-server.git
cd tremor-ui-mcp-server
npm install
```

### Build

```bash
npm run build
```

### Development

```bash
npm run dev
```

### Testing

```bash
npm test
```

### Local Testing with MCP Clients

```bash
# Build the project
npm run build

# Test with Claude Desktop
echo '{"method": "tools/list", "params": {}}' | node dist/index.js
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Tremor](https://tremor.so/) - The amazing React UI library for dashboards
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol that powers this integration
- [Anthropic](https://anthropic.com/) - For Claude and MCP development
- [Vercel](https://vercel.com/) - For acquiring and supporting Tremor

## Related Projects

- [Tremor UI](https://github.com/tremorlabs/tremor) - The main Tremor UI library
- [Shadcn UI MCP Server](https://github.com/jpisnice/shadcn-ui-mcp-server) - Inspiration for this project
- [MCP Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server examples

---

**Made with ❤️ for the Tremor and AI community**