tremor-ui-mcp-server/UPDATING_COMPONENTS.md

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

# 🔄 Updating Components Guide

This guide explains how to update the Tremor UI MCP Server with new components, blocks, and templates.

## 🚀 Quick Methods

### 1. **Automatic Updates (Recommended)**

The server automatically fetches new components from the Tremor GitHub repository:

```bash
# Just restart the server - cache refreshes every 30 minutes
npx @tremor-ui/mcp-server --github-api-key your_token
```

### 2. **Force Cache Refresh**

```bash
# The server will automatically reload components on restart
# Kill the current server process and restart it
```

## 🛠️ Manual Component Addition

### Step 1: Generate Example Config

```bash
# Generate example component configuration
npm run update-components example-component > new-component.json

# For blocks
npm run update-components example-block > new-block.json

# For templates  
npm run update-components example-template > new-template.json
```

### Step 2: Edit Configuration

Edit the generated JSON file with your component details:

```json
{
  "name": "ScatterChart",
  "description": "A scatter plot chart for correlation analysis",
  "category": "Charts",
  "props": [
    {
      "name": "data",
      "type": "Array<object>",
      "required": true,
      "description": "Chart data array"
    },
    {
      "name": "x",
      "type": "string", 
      "required": true,
      "description": "X-axis data key"
    },
    {
      "name": "y",
      "type": "string",
      "required": true,
      "description": "Y-axis data key"
    }
  ],
  "dependencies": ["@tremor/react", "react"]
}
```

### Step 3: Add to Server

```bash
# Add the new component
npm run update-components add-component new-component.json

# Add a new block
npm run update-components add-block new-block.json

# Add a new template
npm run update-components add-template new-template.json
```

### Step 4: Rebuild and Test

```bash
# Rebuild the server
npm run build

# Test the new component
npm run test:server

# Or test manually
echo '{"method": "tools/call", "params": {"name": "get_component", "arguments": {"componentName": "ScatterChart"}}}' | node dist/index.js
```

## 📝 Manual Editing

You can also manually edit `src/services/tremor.ts`:

### Adding New Components

Find the `getPredefinedComponents()` method and add your component:

```typescript
private getPredefinedComponents(): Record<string, TremorComponent> {
  return {
    // ... existing components ...
    
    'ScatterChart': {
      name: 'ScatterChart',
      description: 'A scatter plot chart for correlation analysis',
      category: 'Charts',
      props: [
        { name: 'data', type: 'Array<object>', required: true, description: 'Chart data array' },
        { name: 'x', type: 'string', required: true, description: 'X-axis data key' },
        { name: 'y', type: 'string', required: true, description: 'Y-axis data key' },
        { name: 'size', type: 'string', required: false, description: 'Size data key for bubble sizing' },
        { name: 'colors', type: 'string[]', required: false, description: 'Colors for data points' }
      ],
      dependencies: ['@tremor/react', 'react']
    },
    
    // Add more components here...
  };
}
```

### Adding New Blocks

Find the `getPredefinedBlocks()` method:

```typescript
private getPredefinedBlocks(): Record<string, TremorBlock> {
  return {
    // ... existing blocks ...
    
    'metrics-overview': {
      name: 'metrics-overview',
      title: 'Metrics Overview',
      description: 'A comprehensive metrics dashboard with KPI cards and trends',
      category: 'Analytics',
      source: 'https://tremor.so/blocks/metrics-overview',
      dependencies: ['@tremor/react', 'react', 'tailwindcss'],
      files: [
        {
          name: 'metrics-overview.tsx',
          content: '// Metrics overview component implementation',
          path: 'components/metrics-overview.tsx'
        }
      ]
    }
  };
}
```

### Adding New Templates

Find the `getPredefinedTemplates()` method:

```typescript
private getPredefinedTemplates(): Record<string, TremorTemplate> {
  return {
    // ... existing templates ...
    
    'marketing-dashboard': {
      name: 'marketing-dashboard',
      title: 'Marketing Dashboard Template',
      description: 'Complete marketing analytics with campaign performance and lead tracking',
      category: 'Marketing',
      source: 'https://tremor.so/templates/marketing-dashboard',
      dependencies: ['@tremor/react', 'react', 'next.js', 'tailwindcss'],
      files: [
        {
          name: 'page.tsx',
          content: '// Marketing dashboard page implementation',
          path: 'app/marketing/page.tsx'
        }
      ]
    }
  };
}
```

## 🔧 Advanced Configuration

### Custom Categories

Add new categories by updating the `extractCategory()` method:

```typescript
private extractCategory(path: string): string {
  if (path.includes('chart')) return 'Charts';
  if (path.includes('input')) return 'Input';
  if (path.includes('layout')) return 'Layout';
  if (path.includes('text')) return 'Text';
  if (path.includes('display')) return 'Display';
  if (path.includes('navigation')) return 'Navigation';  // New category
  if (path.includes('feedback')) return 'Feedback';      // New category
  return 'General';
}
```

### Adjusting Cache Timeout

To make the server check for updates more frequently:

```typescript
// In src/services/tremor.ts
private readonly cacheTimeout = 10 * 60 * 1000; // 10 minutes instead of 30
```

### Enhanced GitHub Integration

To fetch components from multiple repositories or branches:

```typescript
// In src/services/github.ts
private readonly repos = [
  { owner: 'tremorlabs', repo: 'tremor', branch: 'main' },
  { owner: 'tremorlabs', repo: 'tremor-raw', branch: 'main' }
];
```

## 🧪 Testing New Components

### 1. Unit Tests

Add tests for new components in `tests/tremor.test.ts`:

```typescript
describe('New Components', () => {
  it('should return ScatterChart component', async () => {
    const component = await service.getComponent('ScatterChart');
    expect(component).toBeDefined();
    expect(component?.name).toBe('ScatterChart');
    expect(component?.category).toBe('Charts');
  });
});
```

### 2. Integration Testing

```bash
# Test with the MCP server
npm run test:server

# Test specific component
echo '{"method": "tools/call", "params": {"name": "get_component", "arguments": {"componentName": "ScatterChart"}}}' | node dist/index.js
```

### 3. AI Assistant Testing

Configure your AI assistant and test with prompts like:

```
"Show me the new ScatterChart component from Tremor UI"
"Generate a demo using the ScatterChart component"
"List all chart components including the new ones"
```

## 📚 Component Properties Reference

### Required Properties

```typescript
interface TremorComponent {
  name: string;           // Component name (e.g., "AreaChart")
  description: string;    // Brief description
  category: string;       // Component category
  props?: ComponentProp[]; // Component props
  dependencies?: string[]; // Required packages
  source?: string;        // Source code
  demo?: string;          // Demo code
}
```

### Component Props

```typescript
interface ComponentProp {
  name: string;          // Prop name
  type: string;          // TypeScript type
  required: boolean;     // Is required?
  description: string;   // Prop description
  defaultValue?: string; // Default value
}
```

## 🚀 Best Practices

### 1. **Component Naming**
- Use PascalCase (e.g., `AreaChart`, `ProgressBar`)
- Be descriptive and consistent with Tremor UI naming

### 2. **Categories**
- Use existing categories when possible
- Keep categories broad but meaningful
- Common categories: `Charts`, `Layout`, `Input`, `Display`, `Text`

### 3. **Props Documentation**
- Provide clear, concise descriptions
- Use proper TypeScript types
- Mark required props correctly

### 4. **Dependencies**
- Always include `@tremor/react` and `react`
- Add specific dependencies as needed
- Keep the list minimal

### 5. **Testing**
- Test each new component thoroughly
- Verify demo code generation works
- Check with actual AI assistants

## 🔄 Update Workflow

1. **Check for Updates**: Monitor Tremor UI releases and documentation
2. **Generate Config**: Use the helper script to create component configs
3. **Add Components**: Use the update script or manual editing
4. **Test**: Run the test suite and verify functionality
5. **Build**: Rebuild the server
6. **Deploy**: Restart the MCP server with new components

## 🆘 Troubleshooting

### Component Not Showing Up
- Check component name spelling
- Verify the component was added to the correct method
- Restart the MCP server
- Clear cache by restarting

### Demo Generation Issues
- Verify prop types are correct
- Check required props are properly marked
- Test demo generation manually

### Build Errors
- Check TypeScript syntax
- Verify all imports and dependencies
- Run `npm run lint` to check for issues

---

**📝 Remember**: After adding new components, always rebuild the server with `npm run build` and restart the MCP server to see changes!